完善企微开通与部署端口契约（07-26-internal-ops-recovery-baseline）

2026-07-26 23:44:44 +08:00
@@ -59,3 +59,68 @@ isolated drill
 ## 外部门禁

 以下事项不因本地演练通过而自动获批：读取真实运行环境、复制真实备份、建立异机定时任务、停机、恢复真实库/附件、部署和公网 `/ready`。进入这些步骤前再次列出目标、只读/写入范围和回滚方式并取得明确批准。
+
+## 企微 HR 双 Secret 数据流
+
+```text
+通讯录 Secret -> user/list_id -> userid 集合
+自建应用 Secret -> user/get + department/list + hr/get_staff_info
+                 -> normalize -> 脱敏 dry-run -> 既有 HR 同步写入
+```
+
+- 保留 `WECOM_CONTACT_SECRET` 与 `WECOM_AGENT_SECRET` 的现有配置名和 token 来源审计，不增加第三套 Secret。
+- `listContactMembers` 分离列表 token 与详情 token；默认详情 token 等于列表 token 以保持内部调用兼容，但正式聚合入口明确传入自建应用 token。
+- 指定 userid 与全量 userid 两条路径使用同一详情 token 合同；部门列表也使用自建应用 token。
+- `/user/get` 失败仍沿用最小 userid 回退，HR 信息可补足资料；真实 dry-run 必须以归一化后的必填字段和冲突检查作为写入门，不因 API `errcode=0` 自动放行。
+
+## 真实职责写入门
+
+- 先读取全量候选并在内存中按目标姓名匹配，只输出两个匹配计数、身份哈希是否不同、缺失字段数和计划动作数量。
+- 只有两个匹配计数均为 1、企微身份不同、均为 active、必填资料完整且手机号/邮箱不冲突时，才进入 apply。
+- 员工和企微绑定通过既有 HR master sync 服务创建或更新；随后通过既有角色写入语义分别设置 `employee + finance` 和 `employee + ceo`。
+- 角色变更递增 `token_version`、撤销活动会话并写 `SYSTEM_USER_ROLES_SET` 审计；最终只核对数量、角色集合、不同 employee id、审计存在和付款业务零写入。
+- 任一门禁失败即停止，不进行部分角色写入；如员工同步已经成功而角色阶段失败，保留同步审计并立即报告，不用删除真实员工记录进行破坏性回滚。
+
+## 企微本人敏感信息授权边界
+
+- `/user/get` 和人事助手批量读取继续只负责 userid、姓名、部门等可读字段；不得把批量缺字段误判为企微完全不支持手机号和邮箱。
+- 2022-06-20 后新建自建应用的敏感字段走独立 OAuth 数据流：管理员在应用详情选择字段，成员以 `snsapi_privateinfo` 手工确认，`getuserinfo` 返回短时 `user_ticket`，服务端立即调用 `/cgi-bin/auth/getuserdetail`。
+- `user_ticket`、授权 code 和完整敏感响应不得写日志、任务证据或审计 extra；只保存业务所需的规范化手机号/邮箱及字段存在性审计。
+- 普通 `snsapi_base` 登录与敏感资料授权分开，避免每次登录引入手工授权；用户已批准未绑定的 active 可见成员通过独立入口自助创建仅授予 `employee` 的 OA 账号。
+
+### OAuth 开通数据流
+
+```text
+GET /auth/wecom/login?mode=onboard
+  -> feature flag + state(mode=onboard)
+  -> authorize(scope=snsapi_privateinfo)
+  -> getuserinfo(code) -> userid + user_ticket
+  -> getuserdetail(user_ticket) -> mobile + email|biz_mail
+  -> user/get + department/list -> name + active + department
+  -> unique precheck -> transaction(employee + employee role + binding + audit)
+  -> authenticated session
+```
+
+- `mode=login|bind` 保持既有 `snsapi_base` 和行为；新增 `mode=onboard` 才使用 `snsapi_privateinfo`。
+- `getuserinfo` 只把 `user_ticket` 传给同一请求中的详情交换函数，诊断信息只记录字段是否存在。
+- 详情中的 userid 必须与身份接口 userid 一致；邮箱优先使用成员授权的个人邮箱，无个人邮箱时使用企业邮箱，二者都缺失则停止。
+- 联系人详情必须证明成员 active，并提供姓名、部门；手机号/邮箱与不同 OA 员工冲突时停止，不自动合并。
+- 已有绑定员工只补齐经授权的规范化资料且不改角色；新员工在单事务内创建 employee、`employee` 角色、企微绑定和脱敏审计。任何一步失败均不留下部分账号。
+- 自助开通不替代管理员职责分配；`finance`、`ceo` 仍沿用角色接口的 token version、会话撤销和审计合同。
+
+## 部署目录统一设计约束
+
+- 现场是混合部署，不能把“统一目录”处理成普通 rsync：必须以当前活动 PostgreSQL 数据和附件挂载为唯一数据事实源。
+- 在停机切换前固定记录活动容器、数据挂载、环境文件摘要、端口、Caddy 路由和回滚镜像；不得打印环境变量内容。
+- 当前部署脚本固定探测宿主端口，而现场通过另一宿主端口提供 OA；脚本必须从已验证的 Compose/env 配置解析实际端口，不能硬编码。
+- 两套目录的 Compose 容器名和环境文件不同。切换前必须先选择唯一目录并证明其 DB/附件目标就是当前活动数据；不得让 Compose 创建第二套空数据库后误判部署成功。
+- 统一后应由同一目录负责 source sync、Compose、环境文件和运维 timer，并让 `/ready`、前端 marker 和容器环境同时暴露同一短构建标识。
+- 任一迁移状态、数据挂载、端口或公网构建标识不匹配时，立即切回旧容器和 Caddy 目标；不执行数据库 reset 或数据目录覆盖。
+
+### 生产统一顺序
+
+1. 使用已完成的成对异机备份作为灾难回滚点，并记录活动数据挂载、环境摘要、容器镜像和 Caddy 端口。
+2. 本地先修复 Compose 可配置回环端口及部署脚本动态端口探测，通过全部门禁并提交、发布批准提交。
+3. 停机后把非活动的既定部署目录改名保留，将活动数据目录和环境文件迁入既定目录；同一文件系统优先原子改名，不复制运行中的 PostgreSQL 文件。
+4. 用新 Compose 重建 db/init/server，应用已提交 migrations；旧容器和旧目录在验收前保留，不清理。
+5. 公网构建标识、数据计数、角色、企微入口和关键只读检查通过后更新运维 timer；失败则停止新容器并恢复旧目录/容器和原 Caddy 目标。
@@ -12,12 +12,24 @@
 - [x] 在单独授权后完成真实运行来源、职责分离、异机副本和 `/ready` 的只读核查，并如实记录 `NO_GO` 缺口。
 - [x] 经明确授权完成提交发布和真实 DB＋附件＋manifest 成对异机备份，两端完整性复验通过。
 - [ ] 经后续明确授权完成真实职责分配、部署/迁移和真实格式影子恢复后复验。
+- [x] 修复企微 HR 双 Secret 分工：通讯录 token 只列 userid，自建应用 token 读取详情、部门和 HR 信息。
+- [x] 补充单元测试并运行后端语法、聚焦测试、Prisma 与 Trellis 门禁。
+- [x] 在真实环境执行两名目标成员的脱敏 dry-run；两人均唯一、不同身份且 active，但批量链路均缺手机和邮箱，已按门禁停止真实写入。
+- [ ] 复用既有 HR 同步与角色语义写入 `employee + finance`、`employee + ceo`，复核会话失效、审计和 maker-checker，不部署、不迁移。
+- [x] 增加默认关闭的一次性企微敏感资料授权入口，保持普通登录静默；实现 `user_ticket -> getuserdetail`、active/字段/唯一性门禁和仅 `employee` 自助开通。
+- [x] 补齐 OAuth 路由、服务、配置契约和单元测试，证明票据/原始敏感响应不进入日志、Cookie、数据库或审计。
+- [ ] 修复部署脚本的现场端口解析，确定唯一部署目录，并在活动 DB/附件挂载、环境摘要和旧镜像回滚点全部确认后才执行获批切换。
+- [ ] 部署后验证唯一 Compose 来源、构建标识、迁移状态、Caddy 公网 `/ready` 和前端 marker；不因服务可访问而忽略来源漂移。
+- [ ] 用户在企微应用详情选择手机、邮箱、企业邮箱敏感字段；部署开关开启后，两名目标分别通过一次性链接本人确认授权。
+- [ ] 两人自助开通成功后写入获批 `finance` / `ceo` 职责，复核不同身份、maker-checker、会话撤销、审计和付款零写入。

 ## 推荐文件边界

 - 复用并按需修改：`scripts/backup-db.sh`、`scripts/backup-storage.sh`、`scripts/restore-db.sh`、`scripts/restore-storage.sh`。
 - 最多新增两个小脚本：一个成对备份入口、一个 QA-only 隔离演练入口；不创建通用备份框架。
 - 更新现有 `deploy/trialrun/runbook.md`、`deploy/trialrun/checklist.md` 和 `.trellis/spec/hyb-oa/deployment-trialrun.md`，不新建常驻平行业务文档。
+- 优先修改 `server/src/routes/wecomAuth.js` 并抽取小型企微本人授权/员工开通服务；不把 HR 批同步服务改成通用身份平台。
+- 更新现有 `docs/企微API能力目录.md` 和 `.trellis/spec/hyb-oa/wecom-boundary.md`，记录批量读取与本人 OAuth 的稳定边界。

 ## 验证命令

@@ -28,6 +40,18 @@
 - `node scripts/qa/check-trellis-governance.mjs`
 - `node scripts/qa/check-sensitive-content.mjs`
 - `git diff --check`
+- `cd server && node --check src/services/integrations/wecomHrMaster.js`
+- `cd server && npm test -- --run tests/unit/wecomHrMaster.service.test.js`
+- `cd server && npm run prisma:validate`
+- `cd server && npm test -- --run tests/unit/routes/wecomAuth.test.js tests/unit/wecomHrMaster.service.test.js`
+- `cd server && npm test -- --run tests/unit/routes/wecomAuth.test.js tests/unit/wecomHrMaster.service.test.js tests/unit/wecomOAuthOnboarding.service.test.js`
+- `bash -n deploy/trialrun/deploy.sh`
+
+## 本轮本地验证证据（2026-07-26）
+
+- 后端全量 Vitest：162 个测试文件、1000 个测试通过；安全补修后企微聚焦回归为 3 个文件、30 个测试通过。
+- `prisma validate`、四个企微改动文件 `node --check`、部署环境契约和部署脚本语法均通过。
+- 本地实现没有开启 `WECOM_OAUTH_ONBOARDING_ENABLED`，没有部署、迁移、写真实员工/角色或修改企微后台权限。

 ## 回滚点

@@ -35,3 +59,6 @@
 - DB/附件安全门禁与现有操作冲突：先修 runbook 和调用方，不放宽默认门禁。
 - 动态演练环境不可用：记录缺失依赖并停止，不使用真实数据替代。
 - 任何命令解析到生产、远程或含真实数据的目标：立即停止并请求明确授权。
+- 真实 dry-run 任一目标非唯一、身份相同、字段缺失或存在唯一约束冲突：停止 apply，不尝试猜测身份。
+- 员工同步后角色写入失败：不删除真实员工或企微绑定；记录脱敏结果并停止，待修复后幂等重试角色阶段。
+- 现场 Compose 解析出第二套 DB/附件目标、意外容器名或非活动端口：停止部署，不创建或迁移数据。
@@ -19,6 +19,10 @@
 - 使用一次性 PostgreSQL 目标和临时附件目录完成合成数据恢复演练及负向测试。
 - 更新现有试运行 runbook、checklist 和部署规约，明确影子恢复与真实恢复边界。
 - 规划并保留真实运行 commit、访问边界、角色职责、异机副本及恢复后 `/ready` 的外部授权门；未授权前不执行这些动作。
+- 经用户逐项授权后，修正企微通讯录与人事助手的双 Secret 读取分工，并用脱敏 dry-run 唯一确认两名既有企微成员。
+- 唯一匹配且必填资料、冲突检查通过后，将两名成员同步为 OA 员工，并分别配置 `employee + finance` 与 `employee + ceo`，形成不同自然人的付款制单/复核职责。
+- 增加独立的一次性企微敏感资料授权入口：普通登录继续使用 `snsapi_base`，首次开通使用 `snsapi_privateinfo`；未绑定的在职可见成员授权成功后只自动获得 `employee` 角色。
+- 修复部署脚本与现场端口、目录、容器和构建标识契约，统一真实运行来源；切换前保留活动数据、环境文件和旧容器回滚点。

 ## Requirements

@@ -31,6 +35,15 @@
 - 恢复演练至少证明：DB 标记数据恢复、附件内容哈希一致、损坏备份被拒绝、错误确认值被拒绝、非空附件目标被拒绝。
 - 更新现有 runbook/checklist，使正常备份、影子演练、真实恢复三种场景不再共用含糊命令；保持现有本地存储默认，不启用 MinIO。
 - 将真实内部实例核查列为后续同任务外部门禁：运行 commit/访问方式/TLS、真实职责分配、异机副本和恢复后 `/ready` 均需另行批准和脱敏留证。
+- 企微通讯录 Secret 只用于 `/user/list_id`；自建应用 Secret 用于 `/user/get`、`/department/list` 和获授权的人事助手 `/hr/get_staff_info`，不得回退到已废弃的人事助手 Secret。
+- 真实同步前只输出匹配数量、身份是否不同、缺失字段数、冲突数和计划创建/更新数，不输出姓名、userid、手机号、邮箱、部门原文或原始 payload。
+- 真实写入必须复用现有员工同步、角色、会话撤销和审计语义；财务处理人与 CEO 复核人必须是两个不同企微身份，且不得把 `admin` 当作普通业务复核角色。
+- 敏感资料授权必须显式受 `WECOM_OAUTH_ONBOARDING_ENABLED` 控制，默认关闭；成员必须在应用可见范围、企微状态 active，并实际同意手机号及邮箱或企业邮箱授权。
+- `user_ticket` 只在服务端内存中用于一次 `getuserdetail` 调用，不写日志、Cookie、数据库、审计或错误详情；授权 code 和原始敏感响应同样不得持久化。
+- 自助开通按企微 userid、手机号和邮箱做唯一性检查；新账号只创建 `employee` 角色，随机不可知密码并要求改密，不自动授予财务、CEO、管理员或审批角色。
+- 普通 `snsapi_base` 登录、已绑定账号登录和现有绑定流程保持兼容，不因资料授权功能改成每次手工确认。
+- 生产统一以仓库既定部署目录和 Compose 契约为目标，但活动 PostgreSQL 与附件数据是唯一数据事实源；停机切换不得复制运行中的 PostgreSQL 文件、启动第二套空库或覆盖环境变量。
+- 部署健康检查必须从 Compose 解析实际宿主端口，并校验后端 `/ready`、前端 marker 与批准提交一致；应用已提交的 Prisma migrations 但禁止 reset 或改写历史。

 ## Acceptance Criteria

@@ -41,13 +54,21 @@
 - [x] runbook/checklist 明确影子演练命令、生产停止条件、DB + 附件配对要求和异机副本要求。
 - [x] 相关 shell 语法、QA 脚本、Trellis 治理、敏感扫描和 `git diff --check` 通过。
 - [ ] 在获得单独授权后，确认真实运行 commit、访问边界、职责分离、异机备份及恢复后 `/ready`；未授权前保持未勾选且不宣称正式可用。
+- [x] 双 Secret 调用测试证明成员 ID 由通讯录 token 读取，成员详情、部门和 HR 资料由自建应用 token 读取。
+- [ ] 真实脱敏 dry-run 证明两个目标各唯一匹配、身份不同、必填资料和唯一约束无阻塞。
+- [ ] 获批写入后，两名活跃员工分别具有 `employee + finance` 与 `employee + ceo`，企微绑定不同，角色审计存在且未产生付款业务写入。
+- [x] 普通企微登录仍生成 `snsapi_base`，一次性开通入口生成 `snsapi_privateinfo`；缺少开关、`user_ticket`、成员授权字段、active 状态或唯一性时均拒绝创建（本地 synthetic 验证）。
+- [ ] 一次性授权通过 `getuserdetail` 获取成员同意的手机和邮箱，自动创建或补齐 OA 员工与企微绑定；新建账号角色严格等于 `employee`，日志和审计不含票据或完整敏感响应。
+- [ ] 部署目录、Compose、环境文件、运维 timer 和活动容器来源统一；活动 DB/附件连续，远端 migrations 与批准提交一致，公网 `/ready` 和前端 marker 返回同一短构建标识。
+- [ ] 两名目标成员分别完成一次本人授权后，账号唯一、企微绑定不同，再由管理员写入 `employee + finance` 与 `employee + ceo`；maker-checker、会话撤销和角色审计通过。

 ## Out of Scope

- 不连接生产数据库，不读取真实附件，不执行远程恢复、部署或公网检查。
- 不修改 Prisma schema、业务 API、权限模型、审批链或付款状态机。
+- 不读取真实附件正文，不执行生产恢复、数据库 reset、迁移历史改写或付款/报销业务写入。
+- 不修改 Prisma schema、公开业务 API、权限模型、审批链或付款状态机；仅修复既有 HR 同步服务的凭证分工，并通过既有角色模型写入获批职责。
 - 不引入 MinIO、云备份 SDK、全量灾备平台、自动跨地域复制或 24×7 值守。
 - 不在仓库提交备份文件、恢复数据、环境变量、凭证、真实账号或完整本地路径。
+- 不发送企微消息、不创建企微审批模板、不把手机号/邮箱改为可空、不写占位假数据，也不将敏感授权变成普通登录的强制步骤。
 - 不在本任务完成企微调休、导航、报销或模块退役；它们属于后续批次。

 ## Test Plan
@@ -59,11 +80,20 @@
 - `node scripts/qa/check-trellis-governance.mjs`
 - `node scripts/qa/check-sensitive-content.mjs`
 - `git diff --check`
+- `cd server && node --check src/services/integrations/wecomHrMaster.js`
+- `cd server && npm test -- --run tests/unit/wecomHrMaster.service.test.js`
+- `cd server && npm run prisma:validate`
+- `cd server && npm test -- --run tests/unit/routes/wecomAuth.test.js tests/unit/wecomHrMaster.service.test.js`
+- `bash -n deploy/trialrun/deploy.sh`
+- `node deploy/trialrun/validate-env-contract.js`
+- 获批部署窗口内执行迁移状态、Compose 数据挂载、`/ready`、前端 marker、Caddy 公网路由和回滚容器只读复验。

 ## Key Decision

 先改进可恢复性和防误操作，再接触真实环境。默认工作流只支持影子恢复；真实恢复不是普通脚本路径，而是需要停机、负责人确认、成对备份、回滚点和独立授权的事故操作。

+企微敏感字段采用“日常静默登录 + 一次性本人授权开通”的双入口。批量同步不猜测敏感资料，不修改全局员工字段可空性；自助开通只授予 `employee`，业务角色继续由管理员审计写入。
+
 ## Local Evidence

 - 已使用一次性 PostgreSQL 16 容器和合成附件完成多轮往返演练，最近一次本地参考 RTO 为 6 秒。
@@ -77,9 +107,9 @@
 - 真实角色只有一个活跃账号，财务和付款复核候选均为 0，不满足 maker-checker。
 - 只读核查时的历史 DB/附件备份约 55 天未更新、无 manifest，且与运行数据位于同一设备；获批后已生成新的 DB＋附件＋manifest 完整批次并复制到独立主机，两端校验一致。
 - 当前代码已在获批后以普通快进方式发布到 upstream，来源门禁为 `PASS`；尚未执行角色修改、部署、迁移或真实格式影子恢复，因此最后一项验收继续保持未勾选。
-
-## Notes
-
- Keep `prd.md` focused on requirements, constraints, and acceptance criteria.
- Lightweight tasks can remain PRD-only.
- For complex tasks, add `design.md` for technical design and `implement.md` for execution planning before `task.py start`.
+- 当前 OA 是宿主机 Caddy、容器化 server/frontend、独立 PostgreSQL 容器和宿主附件挂载组成的混合部署；公网 OA 路由确实进入 server 容器。
+- 服务器存在两套无 Git 元数据的部署目录：运行容器来源与日常运维任务指向不同目录，Compose 和环境文件也不一致；运行代码与本机当前代码不一致且缺少构建标识。
+- 现场端口与当前部署脚本的固定健康检查端口不一致；未统一活动数据目录、容器名、端口和环境文件前，不得直接运行现有部署脚本。
+- 企微结构化探测证明 6 名成员的批量详情接口均成功并返回部门，但手机号、邮箱和企业邮箱可读数量均为 0；HR 接口均成功但没有 `staff_info`。官方文档确认这不代表字段不可获取：2022-06-20 后新建自建应用应由管理员在应用详情选择敏感字段，再由成员通过 `snsapi_privateinfo` 手工授权，并用 `user_ticket` 调 `/cgi-bin/auth/getuserdetail` 获取本人手机号、邮箱或企业邮箱。
+- 当前 OA OAuth 只使用 `snsapi_base`，且没有调用 `/cgi-bin/auth/getuserdetail`，因此现有登录链路不能采集敏感字段。两名目标各唯一匹配且身份不同，但批量 dry-run 均缺 `phone`、`email`，真实写入已按门禁停止。
+- 本轮已在本地实现默认关闭的一次性 `onboard` 入口；普通登录继续静默。全量后端门禁与安全补修后的企微聚焦回归结果记录在 `implement.md`。该证据不代表功能已部署，也不代表企微后台敏感字段已由管理员选择。
@@ -81,3 +81,13 @@
 - 运行主机没有宿主 Node.js，因此为成对备份入口增加 Python 3 manifest 等价回退；无 Node 路径已通过完整合成恢复演练，本地参考 RTO 仍为 6 秒。
 - 运行中的 PostgreSQL 容器参数与部署目录环境文件存在漂移；本次只在运行容器参数与活动服务数据库连接相互匹配后执行备份，未修改环境文件。
 - 本次未执行恢复、部署、迁移、角色修改、企微写入或业务写入；真实格式影子恢复和恢复后 `/ready` 仍无证据。
+
+## 后续获批调查：部署拓扑与企微字段可用性
+
+- 当前 OA 公网路由由宿主反向代理进入 server 容器；后端和前端构建位于同一应用镜像，数据库位于独立容器，附件由宿主目录挂载。
+- 运行容器来源目录与日常运维任务目录不同；两套目录都没有 Git 元数据，源文件相同但 Compose 与环境文件摘要不同。运行代码与本机当前代码不一致，`/ready` 无构建标识。
+- 仓库部署脚本的固定宿主健康检查端口与现场实际端口不一致。直接同步并执行现有 Compose 可能产生不同容器名或第二套数据目标，故未执行部署、重启、迁移或目录改写。
+- 使用修正后的双 Secret 读取链路做结构化探测：成员详情 6/6 成功、部门 6/6 可读，手机号/邮箱/企业邮箱均 0/6 可读；HR 详情 6/6 返回成功但 `staff_info` 为 0/6。该结果只证明批量读取链路拿不到敏感字段。
+- 企微官方文档复核：2022-06-20 后新建的自建应用不再通过 `/user/get` 返回手机、邮箱和企业邮箱；管理员需在应用详情选择敏感字段，成员使用 `snsapi_privateinfo` 手工授权，`/cgi-bin/auth/getuserinfo` 才返回 30 分钟有效的 `user_ticket`，随后 `/cgi-bin/auth/getuserdetail` 可返回成员同意的手机号、邮箱和企业邮箱。
+- 当前 OA `server/src/routes/wecomAuth.js` 固定使用 `snsapi_base`，只调用 `getuserinfo` 获取 userid，不调用 `getuserdetail`；因此现状是项目尚未接入官方敏感信息授权链路，而不是企微没有该能力。
+- 两名目标成员的脱敏结果为匹配计数 `[1,1]`、身份不同、均 active、数据库匹配 `[0,0]`、计划动作均为 create；两人均缺 `phone` 与 `email`，因此没有员工、角色、会话、付款或其他业务写入。