完善企微开通与部署端口契约（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 目标。