﻿========================================
  违章推送设置说明（微信 / 钉钉 / 短信）
========================================


【一句话】
  一条违章进了台账，系统可以自动把消息发到
  项目部微信群、钉钉群，或者直接发短信到管理员手机。
  位置：电脑端「账号与接入」→ 最下面「违章推送」。


========================================
  一、三条路怎么选（先看这张表）
========================================

  方式          花钱   开通难度        适合
  ----------    ----   ------------    ----------------------
  企业微信机器人  免费   5 分钟，最简单   有企业微信的（推荐）
  钉钉机器人      免费   5 分钟          用钉钉的
  短信            收费   要报备 1~3 天    要求"必须到手机短信"

  三个可以同时配，一条违章会同时发到所有启用的通道。

  说明：
  · 企业微信 / 钉钉发的是群消息，项目部一群人能同时看到，
    还能在群里直接讨论、@人。
  · 短信是发到个人手机，最硬，但运营商要审模板，还要按条计费。
    一般建议"群里发日常，短信只发一类（最严重）"。

  系统支持的消息通道：
    企业微信群机器人 / 钉钉群机器人 / 自定义 HTTP 接口 /
    短信（阿里云，或任意 HTTP 短信网关）


========================================
  二、企业微信机器人（推荐，5 分钟）
========================================

  1) 电脑版企业微信，打开「项目部安全群」
     （必须是内部群，外部群不支持机器人）
  2) 群右上角「…」→ 点「消息推送」（老版本叫「群机器人」）
  3) 点「添加」，起个名字，比如"违章告警"
  4) 添加完点开它，复制「Webhook 地址」，形如：
     https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx
  5) 回到本系统「账号与接入」→「违章推送」→「＋ 添加通道」
       · 名称：项目部安全群
       · 类型：企业微信机器人
       · 地址：粘贴刚才复制的 Webhook
       · 手机号：不用填
     保存
  6) 点「发送测试」。群里出现一条红标题的测试消息就成了。

  注意：
  · 这个 Webhook 地址就是密码，谁拿到都能往群里发消息，
    别发到公开群里、别贴到网上。
  · 企业微信限制每个机器人 20 条/分钟，本系统按 18 条/分钟
    自我限流，超了直接丢弃并记日志，不会堆积。


========================================
  三、钉钉机器人
========================================

  1) 钉钉群 → 右上角「群设置」→「机器人」→「添加机器人」
  2) 选「自定义」→ 起名 → 安全设置里选一种：
       · 加签（推荐）：会给你一串 SEC 开头的密钥
       · 自定义关键词：填「违章」（消息里必须含这两个字）
  3) 复制 Webhook 地址
  4) 回到本系统添加通道：
       · 类型：钉钉机器人
       · 地址：Webhook
       · 密钥：选"加签"时，把 SEC 开头那串粘这里
     保存 → 发送测试

  如果选了「自定义关键词」而没加签，密钥留空即可。
  本系统发出的消息标题固定含"违章告警"，关键词填「违章」就能过。


========================================
  四、短信（收费，要报备）
========================================

  【方式 A：阿里云短信】

  1) 登录阿里云 →「短信服务」→ 开通（免费开通，按条计费）
  2) 申请签名：控制台 → 国内消息 → 签名管理 → 添加签名
       · 一般用公司名或项目名，需要营业执照，审核 1~2 个工作日
  3) 申请模板：模板管理 → 添加模板，内容大致这样写：
       「${project}发生${type}违章，时间${time}，位置${location}，
         请及时处理。」
       变量名必须是 type / level / time / project / location / note
       这六个之一，多余的可以不写。审核同样 1~2 个工作日
  4) 创建 AccessKey：右上角头像 → AccessKey 管理 → 创建
       · 会得到 AccessKeyId 和 AccessKeySecret，Secret 只显示一次
  5) 回到本系统添加通道：
       · 类型：短信 · 阿里云
       · 手机号：接收人号码，多个用逗号隔开
       · AccessKeyId / AccessKeySecret：粘贴
       · 短信签名：填第 2 步审核通过的那个签名，一字不差
       · 模板 CODE：填第 3 步的 SMS_xxxxxxx
     保存 → 发送测试

  【方式 B：任意 HTTP 短信网关】

  有些短信服务商、短信猫设备给的是"一个网址就能发"的接口，
  形如：

    http://网关地址/send?mobile={phone}&content={text}

  添加通道时：
    · 类型：短信 · HTTP 网关
    · 地址：把上面的网址粘进来，手机号用 {phone}，内容用 {text}
    · 手机号：要发的号码，多个用逗号隔开

  系统会把 {phone} 换成一个个号码、{text} 换成消息正文，
  逐个号码调用一次。返回 2xx 视为成功。


========================================
  五、推送规则（为什么有时候只收到一条）
========================================

  【门槛】
    只推一类（最严重）—— 只有 6 分/500 元那档才发
    一类 + 二类      —— 默认，覆盖未戴帽、未穿背心等
    全部违章         —— 连吸烟这种口头警告也发

  【60 秒去重】
    无人机一次归档会抽出几百帧，同一件事会连着报几十条。
    同「项目 + 违章类型 + 等级」60 秒内只发一条，
    手机上不会刷屏，台账里该有的记录一条不少。

  【限流】
    每个通道最多 18 条/分钟（官方上限 20，留余量）。
    超出的直接丢弃，并在"最近发送记录"里写明原因。

  【测试】
    点「发送测试」会立刻往所有启用的通道发一条示例消息，
    内容固定是"未戴安全帽 · 一类 · 塔基警戒圈"，不用等真违章。

  【看结果】
    每行通道后面有"最近发送"，显示时间 + 成功/失败原因；
    卡片底部有"最近发送记录"，保留最近 60 条，
    失败信息会原样显示，比如 key 失效、网络超时、errcode 93000。


========================================
  六、常见问题
========================================

  Q: 点了测试，群里没反应？
  A: 先看「最近发送」那列写了什么。
     · "errcode 93000" = Webhook 地址不对或机器人已被移出群
     · "key been removed" = 机器人被删了，重新建一个
     · "超时" = 这台电脑上不了外网。企业微信和钉钉都需要联网，
       纯内部局域网发不出去，这种情况只能用局域网内的
       HTTP 网关（见方式 B）

  Q: 短信一直收不到？
  A: 按顺序查这四件事：
     1) 短信签名、模板 CODE 是否审核通过（没通过调不动）
     2) 模板变量名是否写了 type/time/project/location 这些
     3) 阿里云账号余额是否为 0（欠费直接失败）
     4) "最近发送"里的错误码，阿里云的错误码网上能查到含义

  Q: 能不能只发给某一个人？
  A: 企业微信/钉钉是"发到群"，谁在群里谁看到。
     要发给个人就用短信通道，手机号只填那一个人。
     或者单独建一个只有管理员的群，机器人加到那个群。

  Q: 换电脑后推送配置还在吗？
  A: 在。配置存在 data/db.json 里，和项目、台账一起。
     升级时只覆盖程序文件、不覆盖 data 目录，配置就不会丢。

  Q: 推送会不会影响识别速度？
  A: 不会。推送是"发出去就不管"的后台动作，带 8 秒超时，
     发不出去也不影响违章记录入库。


========================================
  七、安全提醒
========================================

  · Webhook 地址、AccessKeySecret 等同于密码，不要截图外发、
    不要写进微信群公告。
  · 系统里保存后不再显示明文密钥，只显示"已设置"；
    要换密钥就重新填一次。
  · 建议单独建一个"违章告警"群，只拉管理和安全员，
    不要拉全员，避免处罚信息扩散。
  · 短信只推一类违章，控制费用，也避免骚扰。


========================================
  八、负责人手机上一定能收到（v2.9.2）
========================================

  【不配任何东西也能收到：App 内提醒】
    项目负责人手机装了本系统的 App，打开就在后台轮询：
      · 一有违章，顶部滑下红色提醒条 + 震动，8 秒内到；
      · 点「知道了」才消失，20 秒没人管会自动收起来；
      · 不花钱、不用企业微信、不用报备短信模板。
    适合：负责人天天在现场、手机常备在手上的场景。

  【要求"锁屏也能弹"：企业微信群机器人】
    负责人的手机装企业微信，进「违章告警」群即可（不用装本系统）。
    这个群机器人是免费、免报备的，5 分钟能配完，锁屏、静音也能看到横幅。

  【项目负责人手机号自动进短信收件人】
    电脑端「项目管理」→ 编辑项目 → 填「负责人手机」。
    之后这个项目出的违章，发短信时会自动把这个号码加进收件人，
    不用在「违章推送」里再手工维护一遍号码。

  【三类触发动作，效果一样】
    · 手机「回传」页：选违章类型 → 上传 → 自动生成违章记录并推送
    · 手机「直播」页：点「抓拍违章」
    · 电脑「素材归档」：AI 判定违规并落盘

  【电脑端也要有声音画面提醒】
    「账号与接入」→「电脑端提醒」：
      · 右下角弹卡片（带缩略图，点一下就跳到对应页面）
      · 提示音：普通回传「叮咚」，违章是专门警报音
      · 系统桌面通知：点「测试一下」时点允许，网页最小化也收得到
    违章还会在页面顶部出红色横幅，不点「知道了」不消失，
    值班的人离开一下回来也不会漏。
