企业微信模块（活动 / 通知 / 通讯录）- 前端联调方案

涉及页面

• 活动管理（列表 + 新建/编辑弹窗）
• 活动详情（含报名记录列表、报名统计、二维码展示）
• 通知管理（列表 + 新建/编辑弹窗）
• 成员选择器（推送时挑选部门/成员，数据来自企业微信通讯录）
• 活动报名落地页（**不需要前端开发**，由后端直接渲染 HTML，见文末说明）

本次新增能力

API

所有接口前缀 /admin-api。

活动管理

活动分页请求参数：

创建/修改请求参数：

活动响应新增字段：

推送与二维码

推送请求参数：

推送响应：

{ "code": 0, "data": { "success": true, "errCode": 0, "message": "推送成功" } }

二维码接口： 直接返回 image/png 字节流，不是 JSON。
页面里把这个 URL 当图片地址用即可（如 <img :src="...">），需要带令牌时自行拼查询参数。

报名记录

分页请求参数： activityId、name（模糊）、mobile（模糊）、status

响应字段： id、activityId、activityTitle、wxUserId、name、mobile、deptName、status、statusName、signupTime、checkInTime、remark

公开接口（免登录，前端**不需要**调用）

提交报名请求参数：

报名统计与附件

统计响应：

{
  "activityId": 1, "activityTitle": "2026春季团建活动",
  "signupLimit": 50, "totalSignup": 1,
  "signedUpCount": 1, "checkedInCount": 0, "canceledCount": 0,
  "remaining": 49, "signupPercent": 2, "checkInPercent": 0,
  "deptStats":      [{ "name": "技术部", "count": 3 }],
  "dateStats":      [{ "name": "2026-09-29", "count": 1 }],
  "sourceStats":    [{ "name": "企业微信身份", "count": 0 }, { "name": "表单填写", "count": 1 }]
}

remaining / signupPercent 在活动**不限名额**（signupLimit=0）时为 null，前端要显示"不限"。
统计**不含已取消**的报名，所以 totalSignup ≠ 报名记录总条数。

通知管理

通知与活动的差异：

企业微信通讯录

成员响应字段： userId（推送时填这个）、name、mobile、email、avatar、position、gender、status、departmentIds、departmentNames

这几个接口是**实时调用企业微信**的，企业微信对通讯录接口有频率限制。前端请做缓存（如打开选择器时拉一次），**不要**在搜索框里每输入一个字符就请求一次。

业务流程与数据带入

1. 新建活动 → 保存为**草稿**，此时扫码报名会提示「报名已结束」
2. 点「发布」→ 状态变「已发布」，此时二维码和报名页才可用
3. 点「推送」→ 成员企业微信收到卡片消息，标题为活动标题，正文含**活动时间 / 地点 / 报名截止 / 名额**，按钮「立即报名」直达报名页
4. 成员点按钮或扫码 → 打开报名页 →（可选）填姓名和手机号 + 传附件 → 提交
5. 报名成功 → 活动 signupCount 自动 +1
6. 后台在活动详情的报名记录列表里可看到该成员，可执行「取消报名」「签到」

数据带入关系：

字段展示规则

业务规则说明

注意事项

• 二维码接口返回的是图片二进制，不是 JSON，不要用普通 request 封装去取，直接用图片 URL。
• signupLimit 必填，不限要传 0 而不是留空，否则会校验失败。
• 推送范围选「指定部门/成员」时 pushTarget 不能为空，否则报「推送目标不能为空」。
• 推送是**同步**调用企业微信接口，成员多时可能耗时 1~3 秒，前端按钮要有 loading。
• 活动 content 字段在报名页是**按纯文本渲染**的（做了 HTML 转义防 XSS）。如果活动详情需要富文本排版，需要另行接入富文本白名单过滤，当前版本不支持。
• 报名页地址依赖后端配置 wx.cp.signup-url-prefix（当前为 http://wcf.viphk.nnhk.cc）。该地址必须是**成员手机能访问到的外网地址**，否则二维码扫出来打不开。
• 报名记录里的 wxUserId 只有在**企业微信内打开报名页且带上了参数**时才有值；普通浏览器扫码报名时为空，此时按手机号去重。
• 权限标识需要在「系统管理 → 菜单管理」里配置好，否则接口会返回 403。
• 推送目标用的是 userId（成员账号，如 LiuYi），不是姓名、也不是手机号。 从通讯录接口取 userId 填进 pushTarget。
• 附件上传走 system 模块的公共上传接口：报名页先调 POST /admin-api/system/storage-blob/public-upload（表单字段名 files）拿到 blobId，再把 blobIds 随报名提交，由**服务端**完成与报名记录的绑定。管理后台查附件用 /wxcp/activity/signup/attachments。
• 报名的 recordType 固定为 wxcp_activity_signup，已注册进 system 模块的 StorageRecordTypeEnum 白名单。以后新增别的附件关联类型，必须同步注册，否则绑定会报「无效的记录类型」。
• 活动封面的 recordType 为 wxcp_activity，同样已注册进白名单。封面**不再有 coverUrl 字段**，POST/PUT /wxcp/activity/create|update 提交 blobIds，GET 读 attachmentList。
• 封面图在报名页显示时会去掉协议和域名。附件地址里的域名取自 yudao.storage.domain（一般是内网地址），而手机扫码是从公网域名打开页面的，直连内网地址加载不出图片，所以后端只保留 /admin-api/... 路径交给同源代理。**如果部署时管理后台与报名页不同源，这个处理需要重新评估。**
• 表单里的封面用 ImageUpload 组件（maxNumber: 1）时，组件返回的是**单值而不是数组**，提交前必须包成数组（blobIds 后端签名是 List<Long>）。
• 通讯录接口**实时调企业微信**，有频率限制，前端务必缓存，不要随输入实时请求。
• 通知正文超过 600 字会**自动截断**（企业微信文本消息有长度上限），截断提示会写在消息末尾。

关于报名落地页

报名页 GET /admin-api/wxcp/activity/signup-page?id=xxx 由**后端直接渲染 HTML**（含内联样式和少量 JS），前端**无需开发**。

这样做的原因：二维码必须指向一个成员手机能直接打开的页面，而后端渲染可以立即跑通「推送 → 扫码 → 报名」闭环，不必等前端排期。若后续希望改为前端 SPA 页面，把二维码内容改成前端路由地址即可，后端接口（/wxcp/activity/signup）不用动。

该页面的路径刻意放在 /admin-api 下（而非 /app-api），因为前端 Vite 开发代理只转发 /admin-api，放 /app-api 会导致扫码后请求打到前端静态服务返回 404。