WAPI 固化企微 API 能力目录与读取口径

docs/管理员手册.md

@@ -1,6 +1,6 @@
 # hyb-oa 管理员手册（10 人以下团队版）
 
-**当前状态（2026-05-18 / WHMSLIVE）**：R7E、PRELAUNCH、CASHIER-VOUCHER-V1、LAUNCH-DEPLOY-FINANCE、FIN-PROD-ENABLE、ACCOUNTING-HANDOFF-V1、ATTV1、HR-WECOM-DIRECTORY-V1、HRWD-CONTACT-LIVE-TEST、DBWFOC、WFDG、WDRG、WCPC、WHMSLIVE 均已收口；SYSTEM-COMPLETE-GATE 结论为 `GO_TO_USE`。WCP1 历史结论为 `PAUSE_FOR_CONFIG`，WCPC 已使用既有在职测试号 `SMOKE002/测试员工`（报告只记录 `oa_smoke***`）复跑通过，结论为 `GO_TO_HR_MASTER_SYNC`。WHMS 已实现并部署验证 `wecom_hr_master_sync_v1`：企微/人事助手 HR 主数据可 dry-run/apply 到 OA 员工镜像、账号、角色、绑定和审计；默认和最终均为 `force_off`，公网 `SMOKE002` 因企微侧缺手机号、邮箱和部门按 `missing_required_field` 跳过，未对真实员工执行生产批量 apply。后续“路线图门禁 + 单功能 Issue CSV”的开发节奏保持不变：下一阶段为 `wecom_attendance_approval_mirror_v1`，必须另建合同；HR/考勤员工日常审批优先复用企业微信，OA 做按域镜像、人工接管、恢复回写、财务闭环和审计中台；采购、费用、合同、项目、报销、付款、AP、代账交接和高敏附件继续 OA 主办，企业微信只做脱敏提醒和 OA deeplink。公网 `payment_batch_v1=force_on`，`erp_sync=force_off`。公司当前无 ERP/独立财务系统，且 ERP 未来不接入 OA；财务闭环以 OA 内审批、台账、付款批次、银行对公付款回单和月度代账交接为准。
+**当前状态（2026-05-18 / WAPI）**：R7E、PRELAUNCH、CASHIER-VOUCHER-V1、LAUNCH-DEPLOY-FINANCE、FIN-PROD-ENABLE、ACCOUNTING-HANDOFF-V1、ATTV1、HR-WECOM-DIRECTORY-V1、HRWD-CONTACT-LIVE-TEST、DBWFOC、WFDG、WDRG、WCPC、WHMSLIVE 均已收口；SYSTEM-COMPLETE-GATE 结论为 `GO_TO_USE`。WCP1 历史结论为 `PAUSE_FOR_CONFIG`，WCPC 已使用既有在职测试号 `SMOKE002/测试员工`（报告只记录 `oa_smoke***`）复跑通过，结论为 `GO_TO_HR_MASTER_SYNC`。WHMS 已实现并部署验证 `wecom_hr_master_sync_v1`：企微/人事助手 HR 主数据可 dry-run/apply 到 OA 员工镜像、账号、角色、绑定和审计；默认和最终均为 `force_off`，公网 `SMOKE002` 因企微侧缺手机号、邮箱和部门按 `missing_required_field` 跳过，未对真实员工执行生产批量 apply。WAPI 后固定企微 API 能力目录和 Secret 矩阵：通讯录使用 `WECOM_CONTACT_SECRET`，人事助手/打卡/消息/OAuth 使用 `WECOM_AGENT_SECRET`，运行时代码不得靠多个 Secret 试错；WOUA 已按新口径复跑为 `PASS_WITH_FINDINGS`，说明 OA/企微用户仍不一致，下一步先处理用户差异或确定 WHMS 批量同步窗口；`wecom_attendance_approval_mirror_v1` 暂缓到审批模板、测试 `sp_no` 和真实回调配置明确后。采购、费用、合同、项目、报销、付款、AP、代账交接和高敏附件继续 OA 主办，企业微信只做脱敏提醒和 OA deeplink。公网 `payment_batch_v1=force_on`，`erp_sync=force_off`。公司当前无 ERP/独立财务系统，且 ERP 未来不接入 OA；财务闭环以 OA 内审批、台账、付款批次、银行对公付款回单和月度代账交接为准。
 
 ## 1. 适用范围
 - 适用于 `small_team_internal` 工作区模式。
@@ -443,7 +443,7 @@ WHMS 管理操作口径：
    - `APP_ORIGIN=https://oa.example.com`
    - `COOKIE_SECURE=true`
    - `PUBLIC_SECURITY_HARDENING_ENABLED=true`
-3. 若启用企业微信入口，补齐：`WECOM_*` 与 `WECOM_ALLOWED_RETURN_HOSTS`。若启用 OA 驱动企业微信通讯录同步，还需补齐 `WECOM_CONTACT_SYNC_ENABLED=true`、`WECOM_CONTACT_SECRET`、`WECOM_CONTACT_DEFAULT_DEPARTMENT_ID`，并确认该 Secret 具备通讯录写权限。若启用企微打卡同步，确认 `海音达工作台` 已被授权调用打卡 API；`WECOM_CHECKIN_SECRET` 留空时复用 `WECOM_AGENT_SECRET`，单独考勤同步应用才需要填写独立 Secret。若启用企微 HR 主数据镜像，确认 `WECOM_HR_MASTER_SYNC_ENABLED=true` 且人事助手 Secret 或已授权工作台应用 Secret 可读取通讯录和花名册；正式批量 apply 仍由 `wecom_hr_master_sync_v1` feature flag 和单独批准控制。
+3. 若启用企业微信入口，补齐：`WECOM_*` 与 `WECOM_ALLOWED_RETURN_HOSTS`。若启用 OA 驱动企业微信通讯录同步，还需补齐 `WECOM_CONTACT_SYNC_ENABLED=true`、`WECOM_CONTACT_SECRET`、`WECOM_CONTACT_DEFAULT_DEPARTMENT_ID`，并确认该 Secret 具备通讯录写权限。若启用企微打卡同步，确认 `海音达工作台` 已被授权调用打卡 API；`WECOM_CHECKIN_SECRET` 留空时复用 `WECOM_AGENT_SECRET`，单独考勤同步应用才需要填写独立 Secret。若启用企微 HR 主数据镜像，按 WAPI 口径确认通讯录读取使用 `WECOM_CONTACT_SECRET`、人事助手/花名册读取使用 `WECOM_AGENT_SECRET`；正式批量 apply 仍由 `wecom_hr_master_sync_v1` feature flag 和单独批准控制。
 4. 将 `OPENAPI_DOCS_ENABLED` 保持为 `false`，不要在公网生产暴露文档入口。
 5. 定期检查审计日志中的登录失败、Refresh 来源不匹配与涉密资料查看记录。
 6. 准备独立 smoke 账号，不使用老板、管理员或真实员工日常账号跑自动化；smoke 账号的角色和直属上级应按正式审批链配置。