wangsli/hyb-oa
1
0
派生 0
代码 工单 合并请求 工作流 8 软件包 项目 发布 百科 活动

WARCH2 增加企微审批历史只读查询

浏览代码
这个提交包含在：
wangsli
2026-05-20 10:23:23 +08:00
父节点 7a32399ca9
当前提交 123ebc9c95
共修改 23 个文件，包含 1358 行新增和 36 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
docs/企微优先开发路线图.md
+22 -10
查看文件
@@ -2,10 +2,10 @@
**文档状态**：当前开发路线图事实源。
**分类**：开发治理 / 路线图。
**适用时间**：WDRG / WCP1 / WHMSLIVE / WOUA / WAPI / WRRA / WOUA-FIX / WRV1 / WRA1 / WMSG1 / WAPC1 / WAPC2 / WPROC1 / WPROC2 / WAPC2F / WAPC2FLIVE / WCBK1 / WEGOV1 / WACP3 / WACP3R / WREAD1 / WREAD1F / WADM1 / WARCH1 之后。
**关联 Issue**：`WDRG,WCP1,WHMS,WHMSLIVE,WOUA,WAPI,WRRA,WOUAFIX,WRV1,WRA1,WMSG1,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WACP3,WACP3R,WREAD1,WREAD1F,WADM1,WARCH1`。
**最近审计**：2026-05-19。
**不得误读**：本文只控制后续开发节奏、阶段顺序和门禁。WHMSLIVE 后只代表企微 HR 主数据镜像已部署并受控验证；WAPI 后进一步固定企微 API/Secret 口径并转为运行优先；WRRA 后明确 `PASS_WITH_FINDINGS` 只代表只读对账成功且存在差异，不代表企微考勤/审批镜像、OA 应急接管、恢复回写或 RuleOps 已完成运行时实现。WMSG1 只证明企业微信应用消息可达和 Deeplink 可回到 OA；WAPC1 只固化审批配置准备清单；WAPC2 只新增请假/补卡模板详情和低风险 `sp_no` 审批详情只读 POC，不代表真实回调或镜像能力已完成。WPROC1 后，WAPC2 不直接放行深度镜像，必须先完成自动样件、回调、补偿拉取和镜像数据模型设计门禁。WPROC2 只新增可执行 process gate。WAPC2FLIVE 已创建 OA-POC 请假/补卡测试模板和低风险测试审批单，并自动复跑 WAPC2 得到 `PASS_APPROVAL_POC`。WCBK1 已完成真实回调 URL 验证和一条现有 OA-POC 测试审批单事件确认，公网报告为 `PASS_CALLBACK_EVENT_CONFIRMED`；WEGOV1 后路线明确为“企微成熟功能优先上线，OA 做自建留存、审计、入口、消息和应急兜底”。WACP3R 已将补偿拉取复跑修正为自动按 `SMOKE002` creator 发现 OA-POC 请假/补卡模板，公网报告 `/app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T115944Z/summary.json` 为 `PASS_WITH_FINDINGS`。WREAD1F 新样例后，审批人真机确认请假和补卡消息卡片、列表、详情页均可看清；远端人工结果报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` 为 `PASS_READABLE`。但同意按钮单击即通过仍是操作风险，需在 WARCH1 的留存、审计、提示或操作规程中继续处理。WADM1 只完成自建留存/镜像数据模型设计；WARCH1 只实现请假/补卡最小审批历史留存、回调事件入库、补偿拉取入库和 QA-only 离线读取证明，不代表完整镜像、外出/加班、应急接管、恢复回写或 RuleOps 已完成。
**适用时间**：WDRG / WCP1 / WHMSLIVE / WOUA / WAPI / WRRA / WOUA-FIX / WRV1 / WRA1 / WMSG1 / WAPC1 / WAPC2 / WPROC1 / WPROC2 / WAPC2F / WAPC2FLIVE / WCBK1 / WEGOV1 / WACP3 / WACP3R / WREAD1 / WREAD1F / WADM1 / WARCH1 / WARCH2 之后。
**关联 Issue**：`WDRG,WCP1,WHMS,WHMSLIVE,WOUA,WAPI,WRRA,WOUAFIX,WRV1,WRA1,WMSG1,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WACP3,WACP3R,WREAD1,WREAD1F,WADM1,WARCH1,WARCH2`。
**最近审计**：2026-05-20。
**不得误读**：本文只控制后续开发节奏、阶段顺序和门禁。WHMSLIVE 后只代表企微 HR 主数据镜像已部署并受控验证；WAPI 后进一步固定企微 API/Secret 口径并转为运行优先；WRRA 后明确 `PASS_WITH_FINDINGS` 只代表只读对账成功且存在差异，不代表企微考勤/审批镜像、OA 应急接管、恢复回写或 RuleOps 已完成运行时实现。WMSG1 只证明企业微信应用消息可达和 Deeplink 可回到 OA；WAPC1 只固化审批配置准备清单；WAPC2 只新增请假/补卡模板详情和低风险 `sp_no` 审批详情只读 POC，不代表真实回调或镜像能力已完成。WPROC1 后，WAPC2 不直接放行深度镜像，必须先完成自动样件、回调、补偿拉取和镜像数据模型设计门禁。WPROC2 只新增可执行 process gate。WAPC2FLIVE 已创建 OA-POC 请假/补卡测试模板和低风险测试审批单，并自动复跑 WAPC2 得到 `PASS_APPROVAL_POC`。WCBK1 已完成真实回调 URL 验证和一条现有 OA-POC 测试审批单事件确认，公网报告为 `PASS_CALLBACK_EVENT_CONFIRMED`；WEGOV1 后路线明确为“企微成熟功能优先上线，OA 做自建留存、审计、入口、消息和应急兜底”。WACP3R 已将补偿拉取复跑修正为自动按 `SMOKE002` creator 发现 OA-POC 请假/补卡模板，公网报告 `/app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T115944Z/summary.json` 为 `PASS_WITH_FINDINGS`。WREAD1F 新样例后，审批人真机确认请假和补卡消息卡片、列表、详情页均可看清；远端人工结果报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` 为 `PASS_READABLE`。但同意按钮单击即通过仍是操作风险，需在 WARCH1/WARCH2 的留存、审计、提示或操作规程中继续处理。WADM1 只完成自建留存/镜像数据模型设计；WARCH1 只实现请假/补卡最小审批历史留存、回调事件入库、补偿拉取入库和 QA-only 离线读取证明；WARCH2 只提供 OA DB 只读查询 API 和 PC/移动历史页，不调用企微 API、不读取企微 Secret、不代表完整镜像、外出/加班、应急接管、恢复回写或 RuleOps 已完成。
## 1. 路线图原则
@@ -48,6 +48,7 @@
| `WREAD1/WREAD1F` | 请假/补卡真机确认已通过 | 新增 QA-only `npm run check:wecom-approval-readability-gate`，只读汇总 OA-POC 请假/补卡证据并输出人工确认清单。WREAD1F 重新生成新样例后，审批人真机确认请假和补卡均可看清；远端报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` 为 `PASS_READABLE`。风险记录：驳回有二次确认，但同意单击即通过，后续 WADM1/WARCH1 需纳入提示、审计或操作规程。 |
| `WADM1` | 自建留存/镜像模型设计已固化 | docs-only 固定 OA 留存域数据模型：企微审批主表、参与人/节点/动作、字段摘要、附件摘要、回调事件、补偿拉取 run/item、对账 finding、打卡/人事快照边界、隐私保留、权限和 WARCH1 最小实现切片。WADM1 解决 WACP3R “回调证据文件未持久化”的模型设计缺口，但不创建迁移、不写入业务数据、不放行完整镜像。 |
| `WARCH1` | 最小审批历史留存已实现并公网验证 | 新增 `WecomApprovalArchive` 等审批留存表、回调事件表、补偿拉取 run/item/finding 表；回调 POST 默认写 OA DB，失败返回非 200 让企微重试；补偿 runner 支持 `--persist-to-db` + `WECOM_ARCHIVE_WRITE=1` 双开关写 OA 留存；新增 `npm run check:wecom-approval-archive` 离线读取 OA DB 历史摘要。公网报告 `/app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T160306Z/summary.json` 与 `/app/artifacts/qa-flow/wecom-approval-archive-20260519T160330Z/summary.json` 均为 `PASS_WITH_FINDINGS`：请假/补卡 2 条历史可离线读取，finding 是 WARCH1 前旧回调未入 DB 的历史 gap，已作为对账 finding 留存。范围仅请假/补卡，不写企微、不做完整镜像、不做应急接管或恢复回写。 |
| `WARCH2` | 已部署并公网只读验证 | 新增只读 `GET /api/wecom/approval-archive` 和 `GET /api/wecom/approval-archive/:id`，以及 PC/移动共用历史页 `/wecom-approval-archive`、`/mobile/wecom-approval-archive`。查询只读 OA DB，不调用企微 API、不读取企微 Secret；权限固定为本人相关、直属下属和 HR/admin/* 全量，`leave.view_all` / `attendance.view_all` 不单独代表全量企微归档权限；申请人未映射、callback-only、外部-only 记录只允许 HR/admin/* 查看。页面文案固定“企业微信主办，OA 自建留存”“仅已归档记录”，不提供审批动作。公网 `SYNC_ENV=0` 部署已完成，`/ready` 正常，新 API 未登录返回 401；远端离线归档报告 `/app/artifacts/qa-flow/wecom-approval-archive-20260520T013610Z/summary.json` 为 `PASS_WITH_FINDINGS`，可读 2 条请假/补卡历史，finding 仍是 WARCH1 前旧回调未入库历史 gap。 |
## 3. 阶段路线
@@ -65,10 +66,11 @@
| 10 | `WREAD1 企微审批可读性与误审批防护门禁` | 真机确认请假、补卡、外出、加班在企微里是否看得清再批，评估快捷同意/驳回误操作风险。 | WACP3 完成或并行准备低风险样例；审批模板可在企微手机端由代表审批人查看。 | 请假/补卡已由 WREAD1F 真机确认 `PASS_READABLE`；驳回有二次确认，同意单击即通过，后续作为操作风险进入 WADM1/WARCH1 设计。外出/加班仍需后续样例或处理决策；不可读模板不得进入正式镜像。 |
| 11 | `WADM1 自建留存/镜像数据模型设计` | 先设计 OA 留存字段、状态机、幂等键、索引、隐私保留、审计和迁移回滚方案。 | WACP3 证明补偿拉取可用；WREAD1 明确模板可读性或回退策略。 | 已完成 docs-only 设计：模型覆盖审批、打卡、人事关键快照、回调事件和补偿拉取记录；只允许在单独 WARCH1 合同批准后进入 schema 或业务代码实现。 |
| 12 | `WARCH1 最小自建历史留存实现` | 先保存企微审批最小历史，满足企微 API 不可用时可查看已保存请假/补卡摘要。 | WADM1 完成并批准 schema/接口实现。 | 已新增 OA DB 审批留存、回调事件、补偿 run/item/finding、双开关补偿入库和离线读取 runner；公网已持久化现有请假/补卡详情并离线读取 2 条已通过历史。报告和日志只输出脱敏前缀；不保存 Secret、token、EncodingAESKey、原始密文或无治理原始 payload。 |
| 13 | `wecom_attendance_approval_mirror_v1` | 企微打卡、请假、补卡、外出、加班、假期余额和审批历史镜像到 OA。 | WARCH1 稳定；外出/加班模板和打卡细项明确；运行优先门禁和用户一致性仍满足。 | OA 可查询企微 HR/考勤镜像、附件摘要、审批历史、考勤解释和审计；不把 OA 主办高敏审批迁到企微。 |
| 14 | `oa_hr_emergency_mode_v1` | 企业微信不可用时，由管理员人工开启 OA HR/考勤应急接管。 | 自建历史留存和镜像数据可支撑对账；OA 应急入口、权限和审计方案明确。 | 管理员可填写原因、范围、预计结束时间和责任人后开启/关闭；应急单据带 `EMERGENCY` 标记。 |
| 15 | `wecom_recovery_writeback_v1` | 企微恢复后，OA 应急数据先 dry-run，再回写企微。 | 应急接管模式完成；企微写回接口、冲突规则和回滚策略已单独批准。 | 系统生成成功、失败、跳过和冲突清单；无冲突项可自动回写，冲突进入人工确认。 |
| 16 | `wecom_ruleops_v1` | AI 草拟企微规则、生成差异报告和 dry-run，人工确认后写入企微。 | 前述同步/回写链路稳定；企微规则 API 能力和权限已验证。 | 每次写入保存前后快照、确认人、API `errcode`、失败原因、回滚建议和审计记录。 |
| 13 | `WARCH2 正式只读历史查询` | 把 WARCH1 runner 级离线证明升级为正式 OA API 和 PC/移动历史页。 | WARCH1 已持久化请假/补卡历史；权限与脱敏合同批准。 | 已完成：查询 API、PC/移动页面、`SYNC_ENV=0` 公网部署、`/ready`、未登录 401、离线归档 runner 均通过。V1 仍只覆盖请假/补卡，不调用企微 API，不提供审批动作。 |
| 14 | `wecom_attendance_approval_mirror_v1` | 企微打卡、请假、补卡、外出、加班、假期余额和审批历史镜像到 OA。 | WARCH2 公网验证完成；外出/加班模板和打卡细项明确；运行优先门禁和用户一致性仍满足。 | OA 可查询企微 HR/考勤镜像、附件摘要、审批历史、考勤解释和审计；不把 OA 主办高敏审批迁到企微。 |
| 15 | `oa_hr_emergency_mode_v1` | 企业微信不可用时，由管理员人工开启 OA HR/考勤应急接管。 | 自建历史留存和镜像数据可支撑对账；OA 应急入口、权限和审计方案明确。 | 管理员可填写原因、范围、预计结束时间和责任人后开启/关闭；应急单据带 `EMERGENCY` 标记。 |
| 16 | `wecom_recovery_writeback_v1` | 企微恢复后，OA 应急数据先 dry-run，再回写企微。 | 应急接管模式完成；企微写回接口、冲突规则和回滚策略已单独批准。 | 系统生成成功、失败、跳过和冲突清单；无冲突项可自动回写，冲突进入人工确认。 |
| 17 | `wecom_ruleops_v1` | AI 草拟企微规则、生成差异报告和 dry-run，人工确认后写入企微。 | 前述同步/回写链路稳定；企微规则 API 能力和权限已验证。 | 每次写入保存前后快照、确认人、API `errcode`、失败原因、回滚建议和审计记录。 |
## 4. 每阶段固定门禁
@@ -292,7 +294,7 @@ WARCH1 最小实现切片：
1. 新增只写不读的审批留存、回调事件、补偿拉取和对账 finding 表，migration 可回滚。
2. 修改 WCBK1 回调路径和 WACP3 补偿 runner，把请假/补卡的规范化详情幂等写入 OA DB。
3. 增加 QA-only backfill/verify runner：断开企微 API 时仍能从 OA DB 读取已保存的请假/补卡历史摘要。
4. 再做只读查询 API 或管理页入口；不在 WARCH1 内开启完整镜像增强、外出/加班正式样例、应急接管、恢复回写或 RuleOps。
4. 再做只读查询 API 或管理页入口；不在 WARCH1 内开启完整镜像增强、外出/加班正式样例、应急接管、恢复回写或 RuleOps。该正式查询切片已由 WARCH2 承接。
WARCH1 已按独立 Issue CSV 进入最小实现。当前实现边界：
@@ -301,4 +303,14 @@ WARCH1 已按独立 Issue CSV 进入最小实现。当前实现边界：
- `npm run check:wecom-approval-compensation-poc` 默认仍只读不写库；只有同时传 `--persist-to-db` 且进程环境 `WECOM_ARCHIVE_WRITE=1` 时，才把现有请假/补卡补偿详情写入 OA 自建留存表。该路径不写企微、不创建模板、不提交审批。
- `npm run check:wecom-approval-archive -- --offline --format=json` 是 QA-only 离线证明：不调用企微 API，只从 OA DB 读取已保存历史摘要，并只输出脱敏 `sp_no`、template、userid 前缀、计数、字段类型和 finding 类型。
- 公网验证已执行 `SYNC_ENV=0` 部署并应用 migration；补偿持久化报告 `/app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T160306Z/summary.json` 为 `PASS_WITH_FINDINGS`，`archivePersistence.status=OK`、`storedCount=2`；离线读取报告 `/app/artifacts/qa-flow/wecom-approval-archive-20260519T160330Z/summary.json` 为 `PASS_WITH_FINDINGS`，可读 2 条已通过历史。finding 是 WARCH1 前旧回调未持久化到 DB 的历史 gap，已记录为 `callback_missing_for_pulled_detail`，不是当前写入链路阻断。
- WARCH1 仍不新增正式管理页，不开发外出/加班，不开启 `wecom_attendance_approval_mirror_v1`、`oa_hr_emergency_mode_v1`、`wecom_recovery_writeback_v1` 或 `wecom_ruleops_v1`。
- WARCH1 仍不新增正式管理页，不开发外出/加班，不开启 `wecom_attendance_approval_mirror_v1`、`oa_hr_emergency_mode_v1`、`wecom_recovery_writeback_v1` 或 `wecom_ruleops_v1`。WARCH2 已在此基础上实现并部署正式只读查询 API 和 PC/移动历史页。
### 6.2 WARCH2 正式只读查询边界
WARCH2 把 WARCH1 的离线 runner 证明升级为 OA 内可查历史，但仍是只读留存查询，不是审批镜像或应急办理：
- API：`GET /api/wecom/approval-archive` 和 `GET /api/wecom/approval-archive/:id` 只读 OA DB；不调用企微 API、不获取 access token、不读取 `WECOM_AGENT_SECRET`、`WECOM_CALLBACK_TOKEN` 或 `WECOM_CALLBACK_ENCODING_AES_KEY`。
- 权限：普通员工只看本人作为申请人、参与人或动作处理人的已归档历史；主管可看直属下属申请和本人相关记录；HR/admin/* 可看全量。`leave.view_all` / `attendance.view_all` 只满足入口权限，不单独代表全量企微归档权限。
- 未映射边界：callback-only、申请人未映射、参与人未映射或仅外部 userid 的记录默认只允许 HR/admin/* 查看；普通员工和主管不得靠参与人/动作关系看到申请人未映射记录。
- 脱敏：API 和页面只返回脱敏 `sp_no` / template 前缀、字段名/字段类型/敏感级别、动作类型/时间/来源和 finding 摘要；不返回完整外部键、手机号、邮箱、原因全文、附件、评论、原始 XML、密文、token 或 Secret。
- 页面：PC `/wecom-approval-archive` 与移动 `/mobile/wecom-approval-archive` 固定文案“企业微信主办，OA 自建留存”“仅已归档记录”，入口在备用模块或考勤历史语境，不进入 `/workflow/tasks` 待办语境，不展示审批按钮或 pending 待办暗示。