写字楼租赁家具资产管理系统 · 企业微信对接

0方案总览

四条链路，共用一套鉴权与事件底座。先看全局结构，再逐条拆。

1前置准备与配置清单

这些必须在写代码之前做完，缺一项后面全部跑不通。

1.1 企微管理后台操作清单

1.2 需要落库的凭据（写进 wecom_config）

2链路一：免登 + 通讯录同步

2.1 免登流程（H5 静默授权）

目标是「从企微工作台点开应用 = 已登录」，全程无输入、无跳登录页。

关键接口与参数

手动授权的 URL 拼装（用于非工作台入口，如分享出去的链接）

https://open.weixin.qq.com/connect/oauth2/authorize
  ?appid={CorpID}                 // 注意：企业微信网页授权用 CorpID，不是 AgentID
  &redirect_uri={URLEncode(回调地址)}
  &response_type=code
  &scope=snsapi_base              // 静默授权，只拿 userid；要手机号用 snsapi_privateinfo
  &state={业务侧防重放串}
  &agentid={AgentID}              // 这个参数不能省，决定用哪个应用的授权
  #wechat_redirect                // 井号必须带上

2.2 通讯录同步

两种方式，建议都要

字段映射

3链路二：消息推送 + 待办

3.1 触发点矩阵

这张表是消息链路的需求正文，模板已在 wecom_message_template 里预置好 14 条，改文案不需要发版。

3.2 发送接口与报文

POST https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=ACCESS_TOKEN
Content-Type: application/json

{
  "touser": "zhangsan|lisi",          // 多个用 | 分隔
  "msgtype": "textcard",
  "agentid": 1000002,
  "textcard": {
    "title": "资产调拨单待审批",             // ≤128 字节
    "description": "调拨单号：TF-20261016-0001\n资产组：305单元标准办公套\n迁移路径：A栋305 → B栋208",
    "url": "https://asset.xxx.com/transfer/detail?id=128",
    "btntxt": "去审批"
  },
  "enable_id_trans": 0,                  // 不开 userid 转 openid
  "enable_duplicate_check": 1,           // 企微侧去重，强烈建议开
  "duplicate_check_interval": 1800        // 去重窗口，最小 1800 秒
}

返回 {"errcode":0,"errmsg":"ok","msgid":"..."}，把 msgid 写回 wecom_message_log 作为送达凭据。

3.3 可靠性设计（这块不做，上线必挨骂）

常见错误码处置

3.4 待办（todo）与消息的差别

消息推了就推了，待办是「必须点掉」的——它会挂在企微「待办」列表里，完成前一直提醒。凡是需要「某人必须处理」的，都应该同时下待办，对应模板里的 todo_flag=1。

• 下发待办：msgtype=todo，需应用具备待办权限
• 本地业务处理完（如盘点已审核），要把对应待办置为已完成：更新 wecom_todo_ref.todo_status=1，并按 todo_msgid 调企微接口同步关闭
• 否则会出现「单据早办完了，待办还挂着红点」——这是体验最伤人的一类小 bug

4链路三：审批流对接

4.1 两种模式，选哪个

4.2 发起审批与状态回调

4.3 状态机映射（核心，必须逐个对齐）

4.4 定时补偿

回调会丢（超时 3 次即弃），所以必须有一个补偿任务：

• 扫 wecom_approval_ref 中 wecom_status=1（审批中）且 apply_time 超过 30 分钟的记录
• 主动调 POST /cgi-bin/oa/getapprovaldetail（body: {"sp_no":"..."}）拉最新状态
• 若状态已变，按 4.3 的映射表补做变更，并标记 sync_source=2 定时补偿查询
• 频率：每 10 分钟一次即可；记录超过 7 天仍是审批中的，说明流程卡住，要提醒催办

5链路四：H5 工作台应用

5.1 页面清单

5.2 JS-SDK 接入

签名（服务端算，前端只拿结果）

// 1) 取 jsapi_ticket（用应用的 access_token），有效期 7200s，必须缓存
GET /cgi-bin/get_jsapi_ticket?access_token=ACCESS_TOKEN

// 2) 拼接并 sha1
string1 = "jsapi_ticket=" + ticket
        + "&noncestr="    + nonceStr
        + "&timestamp="   + timestamp
        + "&url="         + 当前页面完整URL（不含 # 及其后片段）

signature = sha1(string1)

// 3) 前端注入配置
wx.config({
  beta: true,                 // 企业微信必须传 true
  debug: false,
  appId: CORPID,              // 注意：企业微信传的是企业 CorpID，不是 AgentID
  timestamp: timestamp,
  nonceStr: nonceStr,
  signature: signature,
  jsApiList: ["chooseImage", "getLocalImgData", "uploadImage",
              "previewImage", "getLocation", "scanQRCode"]
});

拍照与上传（两个真实大坑）

wx.chooseImage({
  count: 9,
  sizeType: ["compressed"],           // 必须压缩，原图 base64 会爆内存
  sourceType: ["camera", "album"],
  success: function(res){
    var localIds = res.localIds;
    wx.getLocalImgData({
      localId: localIds[0],
      success: function(r){
        var base64 = r.localData;

        // ⚠ 坑一：iOS 返回值带 "data:image/jpeg;base64," 前缀，Android 不带
        base64 = base64.replace(/^data:image\/\w+;base64,/, "");

        // ⚠ 坑二：别把 base64 塞进 JSON 字段传，走 multipart/form-data
        上传到业务服务器(base64);
      }
    });
  }
});

5.3 弱网离线拍照（PRD 2.9 硬性要求）

写字楼地下车库、空置楼层信号差是常态，必须支持离线拍摄后补传。

1. 拍照后先生成客户端唯一标识 client_uuid（UUID v4），图片存 IndexedDB，同时写一条 upload_status=0 待上传 的本地队列记录
2. 检测到网络恢复（online 事件 + 定时探测）后，逐张以 multipart 补传
3. 服务端以 client_uuid 做幂等（uk_client_uuid 唯一索引），重复补传不会产生重复记录
4. 补传成功置 upload_status=1，失败置 2 并累计 retry_count，超过 5 次提示用户手动重试
5. IndexedDB 中的图片在处理完成后清理，避免撑爆手机存储

6数据库改造

改动全部收在独立脚本 wecom_integration_ddl.sql 里，不修改家具资产库原有字段语义，可重复执行。

6.1 新增表（10 张）

6.2 既有表改造（字段级）

6.3 配套视图（5 个）

6.4 幂等改造手法

MySQL 原生不支持 ADD COLUMN IF NOT EXISTS，脚本里内置了两个辅助过程，基于 information_schema 判存后再执行动态 DDL：

CALL sp_add_column_if_absent('sys_user', 'wecom_userid',
  'VARCHAR(64) DEFAULT NULL COMMENT ''企微成员userid,唯一''');
CALL sp_add_index_if_absent('sys_user', 'uk_wecom_userid', '`wecom_userid`', 1);

因此 整份脚本可以重复执行，不用担心「字段已存在」报错中断后续语句。

7安全、容错与上线

7.1 回调加解密（必须自己实现，别抄错）

• URL 验证阶段：企微发 GET 请求带 msg_signature / timestamp / nonce / echostr，需解密 echostr 并原样返回明文，否则保存不了回调地址
• 消息阶段：POST XML 中含 <Encrypt> 密文
• 验签：sha1(sort(Token, timestamp, nonce, Encrypt))，与 msg_signature 比对
• 解密：AES-256-CBC；密钥 = Base64Decode(EncodingAESKey + "=")，IV 取密钥前 16 字节
• 明文结构：16字节随机串 + 4字节消息长度(网络字节序) + 消息体 + receiveid
• 务必校验 receiveid 等于自己的 CorpID，防伪造请求

7.2 降级策略（企微挂了系统不能挂）

核心原则：企业微信是「入口与触达层」，不是业务依赖。任何时刻把 base.enable 置 0，系统都应能凭 PC 端完整跑完家具资产管理全流程。

7.3 上线步骤

7.4 验收清单

1. 企微工作台点开应用，无需任何输入即进入工作台首页，且能看到自己的待办
2. 新入职员工在企微被加入对应部门后，无需人工操作即可正常使用并拥有正确的楼栋数据权限
3. 手机断网状态下拍摄 5 张家具照片，恢复网络后全部自动补传且无重复
4. iOS 与 Android 两端拍照上传均成功（base64 前缀差异已兼容）
5. 盘点任务下发后 10 秒内，物业管家企微收到消息与待办，点击直达对应任务页
6. 低置信识别结果触发待复核提醒，且复核前该盘点单无法提交审核（PRD 四.3 硬约束）
7. 调拨单在企微审批通过后，系统台账位置已自动更新，且变更留痕完整
8. 审批「通过后撤销」时，台账位置正确回滚到原房间
9. 同一单据重复推送不会产生多条消息（幂等生效）
10. 企微接口整体不可用时，PC 端可完成全部业务操作（降级可用）

7.5 风险清单

8交付物清单