WADM1 设计企微自建留存数据模型
这个提交包含在：
文件差异因一行或多行过长而隐藏
@@ -62,6 +62,7 @@ DCL7 已删除本文件中 R70-R91 的长流水历史，避免旧环境、旧开
|
||||
- 2026-05-19 WREAD1 新增企微审批可读性与误审批防护门禁：新增 `server/src/scripts/check-wecom-approval-readability-gate.js` / `npm run check:wecom-approval-readability-gate`，只读汇总 OA-POC 请假/补卡证据并输出真机确认清单。本轮以 `SYNC_ENV=0` 部署，不同步本地 env；部署后先只读复跑 WACP3R 自动发现模板并生成 `/app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T125515Z/summary.json`，再执行 WREAD1，报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T125532Z/summary.json` 为 `PAUSED_MANUAL_CONFIRMATION`。本轮未新建企微模板或审批单，未写 OA/企微数据；下一步需要审批人真机分别确认请假/补卡消息卡片、列表、详情页和快捷同意/驳回误点风险。
|
||||
- 2026-05-19 WREAD1F 按用户选择重新生成新样例：复用 `check:wecom-approval-fixtures` 远端 dry-run，`SMOKE002 -> SMOKE101` 预检通过。第一次 live 因企微模板名按日期重复返回 `301086`，未创建模板或审批单；随后将 OA-POC 模板名修正为带时间戳的唯一名称，focused vitest 17 tests 通过并以 `SYNC_ENV=0` 重新部署。第二次 live 报告 `/app/artifacts/qa-flow/wecom-approval-fixtures-20260519T131958Z/summary.json` 为 `PASS_FIXTURE_CREATED`，已创建新的请假/补卡 OA-POC 测试模板和两条低风险测试审批单，自动复跑 WAPC2 为 `PASS_APPROVAL_POC`。随后只读复跑 WACP3R `/app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T132031Z/summary.json` 为 `PASS_WITH_FINDINGS`，并生成 WREAD1 报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T132054Z/summary.json`，结论仍为 `PAUSED_MANUAL_CONFIRMATION`，等待审批人真机确认。
|
||||
- 2026-05-19 WREAD1 人工真机确认收口：用户确认请假和补卡在企业微信消息卡片、列表、详情页均可以看清；驳回有二次确认，但同意按钮单击即通过；当前暂无额外字段补充建议。已用 `check:wecom-approval-readability-gate` 录入人工结果，远端报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` 为 `PASS_READABLE`，下一阶段允许进入 `WADM1 自建留存/镜像数据模型设计`。同意单击风险需在后续提示、审计留存或操作规程中处理；本轮未写 OA/企微业务数据，未创建新样例。
|
||||
- 2026-05-19 WADM1 完成企微自建留存/镜像数据模型设计：本轮只更新 Issue CSV 和事实源，不改 Prisma schema、不写业务代码、不部署、不写 OA/企微业务数据。设计固定 `WecomApprovalArchive`、参与人/动作/字段摘要、附件摘要、回调事件、补偿拉取 run/item、对账 finding、打卡/人事快照复用边界、隐私保留、权限和迁移回滚策略。WACP3R “回调证据文件未持久化”的 finding 进入 WARCH1 入库实现；同意单击即通过进入 WARCH1 历史留存、审批轨迹和操作规程提示。下一阶段为 `WARCH1 最小自建历史留存实现`，仍不能直接进入完整审批镜像、应急接管、恢复回写或 RuleOps。
|
||||
|
||||
## 关键证据索引
|
||||
|
||||
@@ -121,6 +122,7 @@ DCL7 已删除本文件中 R70-R91 的长流水历史，避免旧环境、旧开
|
||||
| WACP3/WACP3R | 已实现并公网只读复跑：新增补偿拉取 runner 和 `getapprovalinfo` 只读封装；WACP3R 不再要求人工填写模板 ID，改为按 `SMOKE002` creator 自动发现 OA-POC 请假/补卡模板并复跑。远端报告 `/app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T115944Z/summary.json` 为 `PASS_WITH_FINDINGS`：请假/补卡各拉到 1 条详情，finding 为回调证据文件未持久化，未写 OA/企微数据 | `issues/2026-05-19_19-03-06-wecom-approval-compensation-pull-poc-v1.csv`、`issues/2026-05-19_19-42-22-wecom-approval-compensation-config-rerun-v1.csv`、`/app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T115944Z/summary.json` |
|
||||
| WREAD1 | 已完成人工真机确认：请假/补卡消息卡片、列表、详情页均可看清，远端人工结果为 `PASS_READABLE`；风险记录为驳回有二次确认、同意单击即通过，后续进入 WADM1/WARCH1 的提示、审计留存或操作规程设计 | `issues/2026-05-19_20-39-40-wecom-approval-readability-gate-v1.csv`、`/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` |
|
||||
| WREAD1F | 已按用户选择生成新真机样例：修正 OA-POC 模板唯一命名后，公网 live 创建新的请假/补卡测试模板和两条低风险审批单；新样例支撑 WREAD1 人工确认并收口为 `PASS_READABLE` | `issues/2026-05-19_21-15-47-wecom-readability-fresh-fixture-v1.csv`、`/app/artifacts/qa-flow/wecom-approval-fixtures-20260519T131958Z/summary.json`、`/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` |
|
||||
| WADM1 | 已完成 docs-only 数据模型设计：固定企微审批留存、回调事件、补偿拉取、对账 finding、打卡/人事快照边界、隐私权限和 WARCH1 最小实现切片；不改 schema、不部署、不写业务数据 | `issues/2026-05-19_21-55-33-wecom-archive-mirror-data-model-design-v1.csv` |
|
||||
|
||||
## 当前门禁
|
||||
|
||||
|
||||
+12
-2
@@ -2,8 +2,8 @@
|
||||
|
||||
**文档状态**：当前企微 API 调研与本项目使用事实源。
|
||||
**分类**：集成事实源 / API 能力目录。
|
||||
**适用时间**：WAPI / WAPC1 / WAPC2 / WPROC1 / WPROC2 / WAPC2F / WAPC2FLIVE / WCBK1 / WEGOV1 / WACP3 / WACP3R 之后。
|
||||
**关联 Issue**：`WAPI,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WACP3,WACP3R`。
|
||||
**适用时间**：WAPI / WAPC1 / WAPC2 / WPROC1 / WPROC2 / WAPC2F / WAPC2FLIVE / WCBK1 / WEGOV1 / WACP3 / WACP3R / WREAD1 / WADM1 之后。
|
||||
**关联 Issue**：`WAPI,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WACP3,WACP3R,WREAD1,WADM1`。
|
||||
**最近核对**：2026-05-19。
|
||||
**不得误读**：本文只记录本项目会用到的企业微信官方 API 摘要、链接和项目决策，不复制官方文档全文，不保存 Secret、access token、完整 userid、手机号、邮箱或企微原始 payload。官方文档和企业微信后台权限配置始终是最终依据。
|
||||
|
||||
@@ -111,6 +111,16 @@ WPROC1 将 WAPC2 之后的审批路线固定为：
|
||||
- `WADM1` 必须先设计自建留存和镜像字段、状态机、幂等键、索引、隐私保留和迁移回滚方案，再进入 schema 或业务代码实现。
|
||||
- `WARCH1` 必须先实现最小自建历史留存，让 OA 在企微 API 不可用时仍可查看已保存历史，再进入完整镜像增强。
|
||||
|
||||
### 6.1 WADM1 数据留存与 API 结果边界
|
||||
|
||||
WADM1 将已验证的审批能力固定为“可读可留存”的设计输入，但不新增企微 API：
|
||||
|
||||
- 模板详情、审批详情、审批状态回调和批量获取审批单号仍全部固定使用 `WECOM_AGENT_SECRET` 或自建应用回调 Token/EncodingAESKey；不得改为多 Secret 试错。
|
||||
- `getapprovaldetail` 和回调解密结果进入 OA DB 前必须先规范化，保存业务必要字段、完整 `sp_no`、完整 `template_id`、企微 userid、`approval_archive_id` 和摘要 digest；报告和日志只输出脱敏前缀。
|
||||
- WACP3R 的 `PASS_WITH_FINDINGS` 表明补偿拉取可用，但当前回调证据文件未持久化。WARCH1 必须把回调事件、补偿拉取 run/item 和对账 finding 入库，才能支撑跨部署比对。
|
||||
- 不保存原始 XML、密文、access token、Secret、Token、EncodingAESKey 或无治理原始 payload。若后续业务要求保存原始 payload，必须另开加密存储和访问审计合同。
|
||||
- 请假/补卡已通过 WREAD1 真机可读性；外出/加班仍需后续样例或处理决策，不能因接口相同而自动放行。
|
||||
|
||||
## 7. 运行优先结论
|
||||
|
||||
- 近期优先利用：企业微信工作台入口、OAuth/免登、绑定、个人应用消息、OA deeplink、通讯录 userid 清单、可选成员详情、人事助手花名册读取、打卡记录和打卡规则读取。
|
||||
|
||||
+61
-4
@@ -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 真机确认之后。
|
||||
**关联 Issue**：`WDRG,WCP1,WHMS,WHMSLIVE,WOUA,WAPI,WRRA,WOUAFIX,WRV1,WRA1,WMSG1,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WACP3,WACP3R,WREAD1,WREAD1F`。
|
||||
**适用时间**：WDRG / WCP1 / WHMSLIVE / WOUA / WAPI / WRRA / WOUA-FIX / WRV1 / WRA1 / WMSG1 / WAPC1 / WAPC2 / WPROC1 / WPROC2 / WAPC2F / WAPC2FLIVE / WCBK1 / WEGOV1 / WACP3 / WACP3R / WREAD1 / WREAD1F / WADM1 之后。
|
||||
**关联 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`。
|
||||
**最近审计**：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`。但同意按钮单击即通过仍是操作风险，需在 WADM1/WARCH1 的留存、审计、提示或操作规程中继续处理；该结论不代表自建留存模型、最小历史留存或 `wecom_attendance_approval_mirror_v1` 已完成。
|
||||
**不得误读**：本文只控制后续开发节奏、阶段顺序和门禁。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`。但同意按钮单击即通过仍是操作风险，需在 WADM1/WARCH1 的留存、审计、提示或操作规程中继续处理。WADM1 只完成自建留存/镜像数据模型设计，不创建 Prisma migration、不写业务代码、不部署；它不代表最小历史留存、完整镜像、应急接管、恢复回写或 RuleOps 已完成。
|
||||
|
||||
## 1. 路线图原则
|
||||
|
||||
@@ -46,6 +46,7 @@
|
||||
| `WEGOV1` | 路线和治理已调整 | 明确混合架构：企微成熟功能优先上线，OA 做自建数据留存、审计、入口、消息和应急兜底；固化受控测试域、自动化优先和人工边界；后续顺序调整为 WACP3、WREAD1、WADM1、WARCH1 后再评估深度镜像。 |
|
||||
| `WACP3/WACP3R` | 已实现并公网只读复跑，有 findings | 新增 QA-only `npm run check:wecom-approval-compensation-poc` 和 `POST /cgi-bin/oa/getapprovalinfo` 只读封装，固定 `WECOM_AGENT_SECRET`。WACP3R 改为按 `SMOKE002` creator 自动发现 OA-POC 请假/补卡模板 ID，再按模板过滤拉审批单号并用 `getapprovaldetail` 拉详情；公网报告 `/app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T115944Z/summary.json` 为 `PASS_WITH_FINDINGS`：请假/补卡各拉到 1 条详情，发现回调证据文件未持久化导致当前无法跨部署比对历史回调。未写 OA/企微数据，未保存完整模板 ID。 |
|
||||
| `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 “回调证据文件未持久化”的模型设计缺口，但不创建迁移、不写入业务数据、不放行完整镜像。 |
|
||||
|
||||
## 3. 阶段路线
|
||||
|
||||
@@ -61,7 +62,7 @@
|
||||
| 8 | `WEGOV1 企微主办治理与自建留存路线修正` | 固化混合主办边界、OA 自建留存策略、受控测试域和后续顺序。 | WCBK1 已确认真实回调事件；用户选择优先利用企微成熟功能并要求 OA 保存关键历史。 | docs-only 收口；文档明确企微主办域、OA 主办域、OA 留存域、OA 应急域、自动化与人工边界。 |
|
||||
| 9 | `WACP3 补偿拉取 POC` | 证明按时间窗口批量获取审批单号并可拉取审批详情，作为回调丢失补偿。 | WEGOV1 完成；WAPC2/WAPC2FLIVE/WCBK1 已提供低风险样例、详情读取和真实事件证据；官方 API 和权限明确。 | WACP3R 已自动发现 OA-POC 请假/补卡模板并复跑到 `PASS_WITH_FINDINGS`：补偿拉取和详情读取可用；findings 为当前回调证据文件未持久化，需在 WADM1/WARCH1 设计留存模型时解决。 |
|
||||
| 10 | `WREAD1 企微审批可读性与误审批防护门禁` | 真机确认请假、补卡、外出、加班在企微里是否看得清再批，评估快捷同意/驳回误操作风险。 | WACP3 完成或并行准备低风险样例；审批模板可在企微手机端由代表审批人查看。 | 请假/补卡已由 WREAD1F 真机确认 `PASS_READABLE`；驳回有二次确认，同意单击即通过，后续作为操作风险进入 WADM1/WARCH1 设计。外出/加班仍需后续样例或处理决策；不可读模板不得进入正式镜像。 |
|
||||
| 11 | `WADM1 自建留存/镜像数据模型设计` | 先设计 OA 留存字段、状态机、幂等键、索引、隐私保留、审计和迁移回滚方案。 | WACP3 证明补偿拉取可用；WREAD1 明确模板可读性或回退策略。 | 模型覆盖审批、打卡、人事关键快照、回调事件和补偿拉取记录；设计经 Issue CSV 固化后才允许 schema 或业务代码实现。 |
|
||||
| 11 | `WADM1 自建留存/镜像数据模型设计` | 先设计 OA 留存字段、状态机、幂等键、索引、隐私保留、审计和迁移回滚方案。 | WACP3 证明补偿拉取可用；WREAD1 明确模板可读性或回退策略。 | 已完成 docs-only 设计：模型覆盖审批、打卡、人事关键快照、回调事件和补偿拉取记录；只允许在单独 WARCH1 合同批准后进入 schema 或业务代码实现。 |
|
||||
| 12 | `WARCH1 最小自建历史留存实现` | 只读保存企微审批、打卡、人事关键快照，先满足企微不可用时可查看历史。 | WADM1 完成并批准 schema/接口实现。 | OA 可查看已保存历史摘要和完整外部关联键；报告和日志只输出脱敏前缀；不保存 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` 标记。 |
|
||||
@@ -237,3 +238,59 @@ WAPC2 通过后，下一步不是直接进入 `wecom_attendance_approval_mirror_
|
||||
8. `WARCH1 最小自建历史留存实现`：先只读保存企微审批、打卡和人事关键快照，保证企微不可用时可查看历史。
|
||||
|
||||
上述门禁完成前，不拆 `wecom_attendance_approval_mirror_v1`。
|
||||
|
||||
## 13. WADM1 自建留存/镜像数据模型设计
|
||||
|
||||
WADM1 是 `WARCH1` 前的设计门禁，只定义数据模型、状态机、幂等键、隐私和迁移回滚策略，不创建 Prisma migration、不改业务代码、不部署。
|
||||
|
||||
模型按四域边界拆分：
|
||||
|
||||
| 模型域 | 设计对象 | WARCH1 V1 取舍 |
|
||||
| --- | --- | --- |
|
||||
| 企微审批留存 | `WecomApprovalArchive` 主表、`WecomApprovalParticipant` 参与人/节点快照、`WecomApprovalAction` 审批动作、`WecomApprovalFieldSummary` 字段摘要、`WecomApprovalAttachmentSummary` 附件摘要 | 先覆盖请假和补卡；保存完整 `sp_no`、`template_id`、申请/审批人外部键到受权限保护的 OA DB；报告和日志只输出脱敏前缀。 |
|
||||
| 回调与补偿证据 | `WecomApprovalCallbackEvent`、`WecomApprovalCompensationRun`、`WecomApprovalCompensationItem`、`WecomApprovalReconcileFinding` | 解决 WACP3R finding：回调证据不能再只落到易丢失文件；DB 内保存完整 `sp_no`/`template_id`/`approval_archive_id` 用于稳定关联，日志和报告只输出脱敏前缀；未来回调和补偿拉取均入库后再比对漏回调、重复回调和状态不一致。 |
|
||||
| 打卡与人事快照 | 复用 `WecomCheckinSyncRun`、`WecomCheckinRecord`、`WecomHrMasterSyncRun`、`WecomHrMasterSyncItem`、`WecomIdentityBinding`，后续按缺口补规则快照、假期余额摘要或花名册快照 | WARCH1 不重造企微打卡风控；先保存已可读摘要和必要快照，排班、日报、月报、假期余额细项按后续 POC 再扩展。 |
|
||||
| OA 应急衔接 | 应急单据与企微镜像单据通过外部键、状态和恢复队列关联 | WADM1 只预留字段和状态，不开启 `oa_hr_emergency_mode_v1`，不做恢复回写。 |
|
||||
|
||||
审批留存主表建议字段：
|
||||
|
||||
- 业务键：`sp_no` 唯一、`template_id`、`template_type`（`leave`、`missed_punch`、后续 `outing`、`overtime`）、`corp_id_hash` 或租户标识、企微状态码和 OA 规范化状态。
|
||||
- 人员键：申请人 OA `employee_id`、申请人企微 userid、审批人/抄送人企微 userid、通过 `WecomIdentityBinding` 映射到 OA 员工；映射失败时保留外部键并标记 `unmatched_user`。
|
||||
- 时间键：申请时间、提交时间、最后状态时间、完成时间、最近回调时间、最近补偿拉取时间。
|
||||
- 来源键：`last_source` 为 `callback`、`compensation_pull`、`manual_import` 或 `synthetic_fixture`；`source_priority` 规则为回调和补偿互补，不以文件报告替代数据库事实。
|
||||
- 风险键：`readability_status`、`single_tap_approve_risk`、`template_adjustment_required`、`external_config_status`。
|
||||
|
||||
审批状态机建议规范化为：`pending`、`approved`、`rejected`、`revoked`、`terminated`、`changed`、`unknown`、`sync_failed`。企微原始状态码只作为枚举/字符串字段保存，不保存原始 payload；状态推进采用“同一 `sp_no` 幂等 upsert + 最新状态时间优先 + 保留全部动作历史”的规则。回调和补偿状态冲突时不覆盖为成功，而是生成 `WecomApprovalReconcileFinding`，等待后续 runner 或人工解释。
|
||||
|
||||
回调和补偿合并语义：
|
||||
|
||||
- `getapprovaldetail` 详情快照作为业务状态最终校准来源；回调作为低延迟事件来源。两者都必须持久化，不能以 runner 文件报告替代数据库事实。
|
||||
- 主表保存 `status_observed_at`、`last_source` 和 `last_detail_digest`；只有更晚的事件时间或变化的详情 digest 才能推进主状态。
|
||||
- 较旧的 `pending`、`unknown` 或失败事件不得覆盖较新的终态；不同终态冲突写入 `WecomApprovalReconcileFinding(status_mismatch)`，不静默改成成功。
|
||||
- 回调重试以事件幂等键 upsert 并累加重试计数；补偿拉取以 `run_id + sp_no` 唯一，详情 digest 未变化时不重复写动作。
|
||||
- DB 业务表保存完整外部键，默认 UI、导出、日志、报告、文档和 Issue 只显示脱敏前缀。
|
||||
|
||||
幂等键建议：
|
||||
|
||||
- 审批主表：`sp_no` 唯一。
|
||||
- 回调事件：`sha256(corp + event_type + sp_no + template_id + normalized_status + node_user + event_time + normalized_digest)`；保存 digest，不保存原始 XML、密文或原始 payload。
|
||||
- 补偿拉取 run：`source + start_time + end_time + template_filter + cursor`。
|
||||
- 补偿 item：`run_id + sp_no` 唯一，并记录详情拉取状态和错误分类。
|
||||
- 审批动作：`sp_no + action_type + operator_userid + action_time + node_index`。
|
||||
|
||||
隐私和保留策略：
|
||||
|
||||
- OA DB 可保存完整外部关联键和业务必要字段，用于补偿、历史查看、恢复和审计；日志、报告、Issue CSV 和文档只保存脱敏前缀。
|
||||
- 表单字段默认只保存规范化业务字段和摘要。请假/补卡至少保存申请类型、时间范围、时长或补卡时间、原因摘要、审批状态和审批历史；不保存无治理的整包 payload。
|
||||
- 附件 V1 只保存数量、类型和外部引用摘要；不下载采购、合同、报销、发票、银行回单或高敏附件。
|
||||
- 原始 XML、密文、Token、EncodingAESKey、access token、Secret 和完整回调密文永不入库。若后续确需原始 payload，必须另开加密存储、字段级访问审计和保留期限合同。
|
||||
- 普通员工只能查看本人历史；审批人查看自己处理链路；HR/管理员按部门或系统权限查看；导出默认脱敏。
|
||||
|
||||
WARCH1 最小实现切片：
|
||||
|
||||
1. 新增只写不读的审批留存、回调事件、补偿拉取和对账 finding 表，migration 可回滚。
|
||||
2. 修改 WCBK1 回调路径和 WACP3 补偿 runner，把请假/补卡的规范化详情幂等写入 OA DB。
|
||||
3. 增加 QA-only backfill/verify runner：断开企微 API 时仍能从 OA DB 读取已保存的请假/补卡历史摘要。
|
||||
4. 再做只读查询 API 或管理页入口；不在 WARCH1 内开启完整镜像增强、外出/加班正式样例、应急接管、恢复回写或 RuleOps。
|
||||
|
||||
WARCH1 实施前必须另建 Issue CSV，并在方案中列出 Prisma 表、索引、迁移回滚、权限、脱敏输出和 replay 策略。
|
||||
|
||||
+1
-1
@@ -146,7 +146,7 @@ WPROC2 后，三层门禁先由可执行 process gate 承接：
|
||||
|
||||
- 真实回调先证明 URL 验证、验签、解密、幂等和重复投递。
|
||||
- 补偿拉取先证明按时间窗口拿到审批单号并可拉取审批详情。
|
||||
- 镜像表先设计字段、状态机、幂等键、索引和隐私保留边界。
|
||||
- 镜像表先设计字段、状态机、幂等键、索引和隐私保留边界；WADM1 已固定审批留存、回调事件、补偿拉取、对账 finding、打卡/人事快照边界和 WARCH1 最小实现切片。
|
||||
- 应急接管和恢复回写必须等镜像稳定后再做。
|
||||
|
||||
## 3. 开发边界
|
||||
|
||||
+13
-12
文件差异因一行或多行过长而隐藏
+2
-1
@@ -20,7 +20,7 @@
|
||||
|
||||
## 最近事实源链
|
||||
|
||||
R6 -> PC6 -> PA6 -> FL6 -> AP6 -> RI6 -> LP6 -> ME6/QG6 -> DG7/MRF7 -> MIA7 -> MIF7/MIF7T(公网部署与带凭据公网复检已收口) -> DG8 -> DG9 -> R7E -> FBA -> QAOPS9/P2D -> P2-ORG -> P2-FIN-DECISION -> P2-FIN-V1 -> P2-OCR-SAMPLE -> P2Q -> P2AUTO -> P2AF -> P2-FIN-LIVE-DECISION -> P2-FIN-LIVE -> PRELAUNCH -> CASHIER-VOUCHER-V1 -> LAUNCH-DEPLOY-FINANCE -> FIN-PROD-ENABLE -> ACCOUNTING-HANDOFF-V1 -> SYSTEM-COMPLETE-GATE -> LAUNCH-OPS-V1 -> REQ-COMPLETE-AUDIT -> ATTV1 -> LAUNCH-AUTO-OPS-V1 -> AUTO-REMAINING-CLOSEOUT -> HR-WECOM-DIRECTORY-V1 -> HRWD-CONTACT-LIVE-TEST -> WCFB -> WFOC -> DBWFOC -> WFDG -> WDRG -> WCP1 -> WCPC -> WHMS -> WHMSLIVE -> WOUA -> WAPI -> WRRA -> WOUA-FIX -> WRV1 -> WRA1 -> WMSG1 -> WAPC1 -> WAPC2 -> WPROC1 -> WPROC2 -> WAPC2F dry-run -> WAPC2FLIVE -> WCBK1 -> WEGOV1 -> WACP3/WACP3R -> WREAD1 自动汇总 -> WREAD1F 新样例 -> WREAD1 真机确认。
|
||||
R6 -> PC6 -> PA6 -> FL6 -> AP6 -> RI6 -> LP6 -> ME6/QG6 -> DG7/MRF7 -> MIA7 -> MIF7/MIF7T(公网部署与带凭据公网复检已收口) -> DG8 -> DG9 -> R7E -> FBA -> QAOPS9/P2D -> P2-ORG -> P2-FIN-DECISION -> P2-FIN-V1 -> P2-OCR-SAMPLE -> P2Q -> P2AUTO -> P2AF -> P2-FIN-LIVE-DECISION -> P2-FIN-LIVE -> PRELAUNCH -> CASHIER-VOUCHER-V1 -> LAUNCH-DEPLOY-FINANCE -> FIN-PROD-ENABLE -> ACCOUNTING-HANDOFF-V1 -> SYSTEM-COMPLETE-GATE -> LAUNCH-OPS-V1 -> REQ-COMPLETE-AUDIT -> ATTV1 -> LAUNCH-AUTO-OPS-V1 -> AUTO-REMAINING-CLOSEOUT -> HR-WECOM-DIRECTORY-V1 -> HRWD-CONTACT-LIVE-TEST -> WCFB -> WFOC -> DBWFOC -> WFDG -> WDRG -> WCP1 -> WCPC -> WHMS -> WHMSLIVE -> WOUA -> WAPI -> WRRA -> WOUA-FIX -> WRV1 -> WRA1 -> WMSG1 -> WAPC1 -> WAPC2 -> WPROC1 -> WPROC2 -> WAPC2F dry-run -> WAPC2FLIVE -> WCBK1 -> WEGOV1 -> WACP3/WACP3R -> WREAD1 自动汇总 -> WREAD1F 新样例 -> WREAD1 真机确认 -> WADM1 自建留存模型设计。
|
||||
|
||||
- R6、PC6、PA6、FL6、AP6、RI6、LP6 已完成并部署。
|
||||
- ME6 自动化、公网视觉矩阵和 `ME6-3` 代表性企业微信真机门禁已完成。
|
||||
@@ -145,6 +145,7 @@ R6 -> PC6 -> PA6 -> FL6 -> AP6 -> RI6 -> LP6 -> ME6/QG6 -> DG7/MRF7 -> MIA7 -> M
|
||||
| `WACP3/WACP3R` | `issues/2026-05-19_19-03-06-wecom-approval-compensation-pull-poc-v1.csv`、`issues/2026-05-19_19-42-22-wecom-approval-compensation-config-rerun-v1.csv` | 当前补偿拉取 POC：runner 已部署并自动发现模板复跑 | 新增 `check:wecom-approval-compensation-poc`，固定 `WECOM_AGENT_SECRET` 只读调用 `getapprovalinfo` 和 `getapprovaldetail`；WACP3R 按 `SMOKE002` creator 自动发现 OA-POC 请假/补卡模板，远端报告为 `PASS_WITH_FINDINGS`，finding 为回调证据文件未持久化 | 不新增公开 API/schema/UI；不写 OA/企微数据；不保存完整模板 ID；不无过滤拉取高风险审批详情；不进入深度镜像 |
|
||||
| `WREAD1` | `issues/2026-05-19_20-39-40-wecom-approval-readability-gate-v1.csv` | 当前可读性门禁：请假/补卡真机确认已通过 | 新增 `check:wecom-approval-readability-gate`，只读汇总请假/补卡 OA-POC 证据；用户确认两类模板消息卡片、列表和详情页均可看清，远端报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` 为 `PASS_READABLE` | 不新增公开 API/schema/UI；不写 OA/企微业务数据；同意单击即通过作为操作风险进入 WADM1/WARCH1；仍不得跳过自建留存模型和最小历史留存直接做深度镜像 |
|
||||
| `WREAD1F` | `issues/2026-05-19_21-15-47-wecom-readability-fresh-fixture-v1.csv` | 当前真机确认补充：已生成新 OA-POC 样例并支撑 WREAD1 收口 | 用户选择重新生成后，修正模板名唯一性并公网 live 创建新的请假/补卡测试模板和两条审批单；报告 `/app/artifacts/qa-flow/wecom-approval-fixtures-20260519T131958Z/summary.json` 为 `PASS_FIXTURE_CREATED`，最终 WREAD1 人工报告为 `PASS_READABLE` | 写入仅限 OA-POC 测试模板和低风险审批单；不写 OA 业务表；不进入镜像；新样例保留审计 |
|
||||
| `WADM1` | `issues/2026-05-19_21-55-33-wecom-archive-mirror-data-model-design-v1.csv` | 当前模型设计：企微自建留存/镜像数据模型已固化 | 固定审批留存、回调事件、补偿拉取、对账 finding、打卡/人事快照边界、隐私权限和 WARCH1 最小实现切片 | docs-only；不改 Prisma schema、不部署、不写 OA/企微业务数据；下一阶段 WARCH1 仍需单独 Issue CSV 和方案批准 |
|
||||
|
||||
旧 Issue CSV 不删除、不批量回写、不移动到归档目录。若新治理流替代旧合同，只在新 CSV 的 `Notes` 或本索引说明 supersedes，旧文件保留历史审计语义。
|
||||
|
||||
|
||||
+10
-3
@@ -1,6 +1,6 @@
|
||||
# hyb-oa 管理员手册（10 人以下团队版）
|
||||
|
||||
**当前状态（2026-05-19 / WREAD1 真机确认）**：R7E、PRELAUNCH、财务闭环、ATTV1、HR-WECOM-DIRECTORY-V1、WAPI、WOUA-FIX、WRV1/WRA1、WMSG1、WAPC1/WAPC2、WPROC1/WPROC2、WAPC2F dry-run、WAPC2FLIVE、WCBK1、WEGOV1、WACP3/WACP3R 和 WREAD1/WREAD1F 均已收口；SYSTEM-COMPLETE-GATE 结论为 `GO_TO_USE`。WAPI 后固定企微 API 能力目录和 Secret 矩阵：通讯录使用 `WECOM_CONTACT_SECRET`，人事助手/打卡/消息/OAuth/审批读取使用 `WECOM_AGENT_SECRET`，运行时代码不得靠多个 Secret 试错。WAPC2FLIVE 已创建 OA-POC 请假/补卡测试模板和低风险测试审批单，报告 `/app/artifacts/qa-flow/wecom-approval-fixtures-20260519T053400Z/summary.json` 为 `PASS_FIXTURE_CREATED`，自动复跑 WAPC2 为 `PASS_APPROVAL_POC`；测试模板和审批记录保留审计，不自动删除。WCBK1 已部署只读回调端点和 runner，远端完成回调 URL 验证并收到一条由 `SMOKE101` 同意现有 OA-POC 补卡测试单触发的真实审批状态事件，报告 `/app/artifacts/qa-flow/wecom-approval-callback-poc-20260519T092648Z/summary.json` 为 `PASS_CALLBACK_EVENT_CONFIRMED`。WACP3R 已新增自动发现模板 ID 路径并公网只读复跑，报告 `/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`。后续仍需 WADM1 自建留存/镜像数据模型设计和 WARCH1 最小历史留存，不能直接进入 `wecom_attendance_approval_mirror_v1`；同意单击即通过需在后续提示、审计或操作规程中处理。采购、费用、合同、项目、报销、付款、AP、代账交接和高敏附件继续 OA 主办，企业微信只做脱敏提醒和 OA deeplink。公网 `payment_batch_v1=force_on`，`erp_sync=force_off`。公司当前无 ERP/独立财务系统，且 ERP 未来不接入 OA；财务闭环以 OA 内审批、台账、付款批次、银行对公付款回单和月度代账交接为准。
|
||||
**当前状态（2026-05-19 / WADM1 设计后）**：R7E、PRELAUNCH、财务闭环、ATTV1、HR-WECOM-DIRECTORY-V1、WAPI、WOUA-FIX、WRV1/WRA1、WMSG1、WAPC1/WAPC2、WPROC1/WPROC2、WAPC2F dry-run、WAPC2FLIVE、WCBK1、WEGOV1、WACP3/WACP3R、WREAD1/WREAD1F 和 WADM1 均已收口；SYSTEM-COMPLETE-GATE 结论为 `GO_TO_USE`。WAPI 后固定企微 API 能力目录和 Secret 矩阵：通讯录使用 `WECOM_CONTACT_SECRET`，人事助手/打卡/消息/OAuth/审批读取使用 `WECOM_AGENT_SECRET`，运行时代码不得靠多个 Secret 试错。WAPC2FLIVE 已创建 OA-POC 请假/补卡测试模板和低风险测试审批单，报告 `/app/artifacts/qa-flow/wecom-approval-fixtures-20260519T053400Z/summary.json` 为 `PASS_FIXTURE_CREATED`，自动复跑 WAPC2 为 `PASS_APPROVAL_POC`；测试模板和审批记录保留审计，不自动删除。WCBK1 已部署只读回调端点和 runner，远端完成回调 URL 验证并收到一条由 `SMOKE101` 同意现有 OA-POC 补卡测试单触发的真实审批状态事件，报告 `/app/artifacts/qa-flow/wecom-approval-callback-poc-20260519T092648Z/summary.json` 为 `PASS_CALLBACK_EVENT_CONFIRMED`。WACP3R 已新增自动发现模板 ID 路径并公网只读复跑，报告 `/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`。WADM1 已完成自建留存/镜像数据模型设计，明确回调事件和补偿拉取证据必须入库解决跨部署丢失问题；后续仍需 WARCH1 最小历史留存实现，不能直接进入 `wecom_attendance_approval_mirror_v1`。同意单击即通过需在后续提示、审计或操作规程中处理。采购、费用、合同、项目、报销、付款、AP、代账交接和高敏附件继续 OA 主办，企业微信只做脱敏提醒和 OA deeplink。公网 `payment_batch_v1=force_on`，`erp_sync=force_off`。公司当前无 ERP/独立财务系统，且 ERP 未来不接入 OA；财务闭环以 OA 内审批、台账、付款批次、银行对公付款回单和月度代账交接为准。
|
||||
|
||||
## 1. 适用范围
|
||||
- 适用于 `small_team_internal` 工作区模式。
|
||||
@@ -178,6 +178,13 @@ ORDER BY e.employee_no;
|
||||
6. 采购、费用、合同、项目、报销、付款、AP、代账交接和高敏附件继续 OA 主办；采购单附件、合同正文、报价、供应商资料、发票、银行回单和代账资料不进入企业微信原生审批或企业微信附件。
|
||||
7. OA 主办审批仍可向企业微信个人应用发送脱敏消息；消息点击后通过免登录或账号绑定回到 OA 目标审批页，审批动作仍在 OA 完成。
|
||||
|
||||
WADM1 后的管理员关注点：
|
||||
|
||||
1. 后续 WARCH1 只做最小历史留存：先保存请假/补卡审批历史、回调事件、补偿拉取记录和必要员工映射，保证企微 API 不可用时仍可查看已保存历史。
|
||||
2. 回调 Token、EncodingAESKey、Secret 和 access token 只配置在部署环境，不写入文档、Issue、聊天或报告。
|
||||
3. OA 数据库可保存完整 `sp_no`、`template_id` 和企微 userid 以便补偿和审计；对外报告、日志和导出默认脱敏。
|
||||
4. 同意单击即通过是企业微信端交互特性，管理员应通过操作规程要求审批人先看详情再同意；OA 后续通过历史留存、审批轨迹和补偿对账提供追溯。
|
||||
|
||||
企微不可用时：
|
||||
|
||||
1. 管理员人工判断故障后开启 `oa_hr_emergency_mode_v1`，不得因短时 API 异常完全自动切换。
|
||||
@@ -198,7 +205,7 @@ WCP1/WCPC/WHMS 后续推进：
|
||||
2. WCP1 历史结论为 `PAUSE_FOR_CONFIG`；WCPC 已用既有在职测试号完成远端只读复跑，报告 `/tmp/wecom-capability-poc-wcpc-smoke002/summary.json`，结论 `GO_TO_HR_MASTER_SYNC`。
|
||||
3. WCPC 已证明 HR 主数据镜像准入项可用：通讯录成员读取、人事助手花名册读取、打卡短窗口记录/规则读取和假期余额读取均达到可复用状态；审批模板、审批实例和回调配置仍是后续考勤/审批镜像前置项。
|
||||
4. WHMS 已实现并部署验证 `wecom_hr_master_sync_v1`，包括同步批次、逐员工结果、dry-run/apply、People 管理入口和 QA-only runner；公网验证后最终保持 `force_off`。
|
||||
5. 正式开发仍按 `wecom_hr_master_sync_v1` -> `runtime_first_wecom_enablement` -> `WOUA-FIX / WECOM-RUNTIME-READY-V1` -> `WAPC1 审批配置准备` -> `WAPC2 请假/补卡只读 POC` -> `WAPC2F 自动生成 POC 样件` -> `WAPC2FLIVE live 创建与 WAPC2 自动复跑` -> `WCBK1 回调只读 POC` -> `WEGOV1 企微主办治理与自建留存路线修正` -> `WACP3/WACP3R 补偿拉取 POC` -> `WREAD1 审批可读性与误审批防护门禁` -> `WADM1 自建留存/镜像数据模型设计` -> `WARCH1 最小自建历史留存实现` -> `wecom_attendance_approval_mirror_v1` -> `oa_hr_emergency_mode_v1` -> `wecom_recovery_writeback_v1` -> `wecom_ruleops_v1` 分合同实施；WOUA-FIX 已收口测试账号差异和处理决策，WRV1/WRA1/WMSG1 已验证运行入口、OAuth/绑定、脱敏消息、Deeplink、通讯录、人事助手和打卡读取主链路。WAPC2FLIVE 已生成请假/补卡低风险样例，WCBK1 已证明真实审批回调 URL、验签/解密和事件脱敏留证，WACP3R 已证明请假/补卡补偿拉取和详情读取可用，WREAD1 已确认请假/补卡可读性；自建留存模型和最小历史留存未明确前，不得进入深度考勤/审批镜像。
|
||||
5. 正式开发仍按 `wecom_hr_master_sync_v1` -> `runtime_first_wecom_enablement` -> `WOUA-FIX / WECOM-RUNTIME-READY-V1` -> `WAPC1 审批配置准备` -> `WAPC2 请假/补卡只读 POC` -> `WAPC2F 自动生成 POC 样件` -> `WAPC2FLIVE live 创建与 WAPC2 自动复跑` -> `WCBK1 回调只读 POC` -> `WEGOV1 企微主办治理与自建留存路线修正` -> `WACP3/WACP3R 补偿拉取 POC` -> `WREAD1 审批可读性与误审批防护门禁` -> `WADM1 自建留存/镜像数据模型设计` -> `WARCH1 最小自建历史留存实现` -> `wecom_attendance_approval_mirror_v1` -> `oa_hr_emergency_mode_v1` -> `wecom_recovery_writeback_v1` -> `wecom_ruleops_v1` 分合同实施；WOUA-FIX 已收口测试账号差异和处理决策，WRV1/WRA1/WMSG1 已验证运行入口、OAuth/绑定、脱敏消息、Deeplink、通讯录、人事助手和打卡读取主链路。WAPC2FLIVE 已生成请假/补卡低风险样例，WCBK1 已证明真实审批回调 URL、验签/解密和事件脱敏留证，WACP3R 已证明请假/补卡补偿拉取和详情读取可用，WREAD1 已确认请假/补卡可读性，WADM1 已明确自建留存模型；WARCH1 最小历史留存未实现前，不得进入深度考勤/审批镜像。
|
||||
6. 任何生产写接口、企微规则写入、应急模式开启或恢复回写都必须有单独批准、dry-run 或可审计记录。
|
||||
|
||||
WCPC 配置复跑清单：
|
||||
@@ -436,7 +443,7 @@ WAPC2 请假/补卡只读 POC 操作口径：
|
||||
- `WECOM_ALLOWED_RETURN_HOSTS=oa.hyinda.com`
|
||||
5. 先让管理员用账号密码登录，在 `个人设置` 完成一次绑定，再测试企业微信工作台直达；已绑定用户从手机企业微信进入时应直接看到移动工作台。
|
||||
6. 若启用 OA 同步企业微信打卡数据，在企业微信打卡 API「可调用接口的应用」中授权 `海音达工作台`。OA 默认可复用 `WECOM_AGENT_SECRET`；只有单独创建考勤同步应用时才额外配置 `WECOM_CHECKIN_SECRET`。
|
||||
7. HR/考勤员工日常审批后续配置企业微信原生审批模板作为主流程；WAPC2FLIVE 已自动生成请假/补卡 OA-POC 低风险样件并复跑只读 POC，WCBK1 已完成真实回调事件确认，WACP3R 已完成补偿拉取，WREAD1 已确认请假/补卡在企微中可读。后续仍需按 WEGOV1 顺序做 WADM1 自建留存/镜像模型和 WARCH1 最小历史留存；同意单击即通过需纳入操作提示和审计设计。外出/加班模板仍需后续单独配置或 POC。报销、财务、采购、合同和项目类 OA 主办审批仍使用企业微信消息提醒并回到 OA 页面完成。
|
||||
7. HR/考勤员工日常审批后续配置企业微信原生审批模板作为主流程；WAPC2FLIVE 已自动生成请假/补卡 OA-POC 低风险样件并复跑只读 POC，WCBK1 已完成真实回调事件确认，WACP3R 已完成补偿拉取，WREAD1 已确认请假/补卡在企微中可读，WADM1 已完成自建留存/镜像模型设计。后续仍需按 WEGOV1 顺序做 WARCH1 最小历史留存；同意单击即通过需纳入操作提示和审计设计。外出/加班模板仍需后续单独配置或 POC。报销、财务、采购、合同和项目类 OA 主办审批仍使用企业微信消息提醒并回到 OA 页面完成。
|
||||
|
||||
### 员工会看到的典型状态
|
||||
- 未绑定：登录页会提示“当前企业微信账号尚未绑定”，回退到账号密码登录。
|
||||
|
||||
+20
-1
@@ -6,7 +6,7 @@
|
||||
**上级事实源**：[海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md)
|
||||
**相关事实源**：[需求 - 统一审批中心规约](./需求-统一审批中心规约.md)、[企微 API 能力目录](./企微API能力目录.md)
|
||||
|
||||
本规约细化企业微信在 `hyb-oa` 中的基础设施边界、入口、免登/绑定、通讯录身份、消息通知、deeplink、打卡、人事助手、原生审批、OA 自建留存、OA 镜像、人工接管和恢复回写要求。WFOC 起产品方向调整为“企微优先 + OA 无痛接管”；DBWFOC 后进一步固定为：HR/考勤员工日常审批优先使用企业微信，OA 做按域镜像、备份接管、财务闭环和审计中台；采购、合同、项目、财务和高敏附件继续由 OA 主办。WAPI 后，所有企微相关开发必须先读取本规约和 [企微 API 能力目录](./企微API能力目录.md)，确认官方 API、Secret、权限、可信 IP、回调/模板和读写边界，再拆 Issue CSV。WMSG1 已证明企业微信应用消息和 Deeplink 真机回流可用；WAPC1 后审批进入配置准备清单，WAPC2 后先做请假/补卡模板详情与低风险 `sp_no` 只读 POC；WAPC2F 已实现 OA-POC 样件 dry-run 并公网验证 `PASS_FIXTURE_DRY_RUN_READY`。WAPC2FLIVE 已在用户批准后创建 OA-POC 请假/补卡测试模板和低风险测试审批单，自动复跑 WAPC2 为 `PASS_APPROVAL_POC`。WCBK1 已完成真实回调 URL 验证和一条现有 OA-POC 测试审批单事件确认，公网结论 `PASS_CALLBACK_EVENT_CONFIRMED`。WEGOV1 后固定“企微主办 HR/考勤成熟能力，OA 保存关键历史和外部关联键”的路线。WACP3R 已自动发现 OA-POC 请假/补卡模板并完成公网补偿拉取复跑，报告为 `PASS_WITH_FINDINGS`；补偿拉取和详情读取可用，finding 为回调证据文件未持久化。WREAD1F 后，用户真机确认请假/补卡审批卡片、列表和详情页可读，远端报告为 `PASS_READABLE`；同意单击即通过作为操作风险进入后续设计。后续仍必须完成自建留存/镜像数据模型和最小历史留存，不是直接进入审批镜像实现。
|
||||
本规约细化企业微信在 `hyb-oa` 中的基础设施边界、入口、免登/绑定、通讯录身份、消息通知、deeplink、打卡、人事助手、原生审批、OA 自建留存、OA 镜像、人工接管和恢复回写要求。WFOC 起产品方向调整为“企微优先 + OA 无痛接管”；DBWFOC 后进一步固定为：HR/考勤员工日常审批优先使用企业微信，OA 做按域镜像、备份接管、财务闭环和审计中台；采购、合同、项目、财务和高敏附件继续由 OA 主办。WAPI 后，所有企微相关开发必须先读取本规约和 [企微 API 能力目录](./企微API能力目录.md)，确认官方 API、Secret、权限、可信 IP、回调/模板和读写边界，再拆 Issue CSV。WMSG1 已证明企业微信应用消息和 Deeplink 真机回流可用；WAPC1 后审批进入配置准备清单，WAPC2 后先做请假/补卡模板详情与低风险 `sp_no` 只读 POC；WAPC2F 已实现 OA-POC 样件 dry-run 并公网验证 `PASS_FIXTURE_DRY_RUN_READY`。WAPC2FLIVE 已在用户批准后创建 OA-POC 请假/补卡测试模板和低风险测试审批单，自动复跑 WAPC2 为 `PASS_APPROVAL_POC`。WCBK1 已完成真实回调 URL 验证和一条现有 OA-POC 测试审批单事件确认，公网结论 `PASS_CALLBACK_EVENT_CONFIRMED`。WEGOV1 后固定“企微主办 HR/考勤成熟能力，OA 保存关键历史和外部关联键”的路线。WACP3R 已自动发现 OA-POC 请假/补卡模板并完成公网补偿拉取复跑，报告为 `PASS_WITH_FINDINGS`；补偿拉取和详情读取可用，finding 为回调证据文件未持久化。WREAD1F 后，用户真机确认请假/补卡审批卡片、列表和详情页可读，远端报告为 `PASS_READABLE`；同意单击即通过作为操作风险进入后续设计。WADM1 已将自建留存/镜像数据模型固化为后续 WARCH1 的设计输入，但尚未创建迁移或运行时写入。后续仍必须完成最小历史留存，不是直接进入审批镜像实现。
|
||||
|
||||
---
|
||||
|
||||
@@ -393,6 +393,25 @@ WAPC2 将审批配置准备先收窄到请假和补卡两类低风险链路，
|
||||
- 报告只输出脱敏模板 ID/`sp_no` 前缀、字段类型计数、审批节点计数和状态摘要，不输出表单值、附件、评论、完整 `sp_no` 或原始 payload。
|
||||
- 本阶段不接真实回调、不创建 OA 镜像表、不写 OA/企微数据、不进入 `wecom_attendance_approval_mirror_v1`。
|
||||
|
||||
## 7.15 WADM1 自建留存基础设施设计
|
||||
|
||||
WADM1 后，企业微信基础设施侧的数据职责调整为“先持久化关键历史，再增强镜像查询”。本节只描述设计，不代表 Prisma schema 已实现。
|
||||
|
||||
自建留存 V1 基础对象：
|
||||
|
||||
- 企微审批历史：请假、补卡先入 `WecomApprovalArchive` 设计域，保存完整外部键、规范化状态、申请人/审批人映射、时间、字段摘要和审批动作。
|
||||
- 回调事件：企微 POST 回调解密后不再只落文件报告，后续应入 `WecomApprovalCallbackEvent`，DB 内保存完整 `sp_no`、`template_id` 和 `approval_archive_id` 用于关联，以幂等键和摘要 digest 支撑重复投递识别；报告和日志只显示脱敏前缀。
|
||||
- 补偿拉取：`getapprovalinfo` 拉取 run/item 进入 `WecomApprovalCompensationRun` / `WecomApprovalCompensationItem`，用于跨时间窗口补齐漏回调；`getapprovaldetail` 详情快照作为业务状态最终校准来源。
|
||||
- 对账 finding：漏回调、重复回调、状态不一致、样例缺失、权限阻断等进入 `WecomApprovalReconcileFinding`，不得在 runner 中口头吞掉。
|
||||
- 打卡和人事：优先复用 `WecomCheckinSyncRun`、`WecomCheckinRecord`、`WecomHrMasterSyncRun`、`WecomHrMasterSyncItem` 和 `WecomIdentityBinding`；WARCH1 不新建平行打卡主模型，不重造企微风控。
|
||||
|
||||
基础设施边界：
|
||||
|
||||
- OA DB 可保存完整外部键用于补偿和恢复；所有日志、报告、Issue 和文档只输出脱敏前缀。
|
||||
- 不保存 access token、Secret、回调 Token、EncodingAESKey、原始 XML、密文、人脸、完整位置、设备明文或无治理原始 payload。
|
||||
- 企微 API 不可用时，OA 历史页应能查看已入库的历史摘要；V1 不承诺继续办理企微主办流程。
|
||||
- WARCH1 实施必须单独批准 schema、索引、迁移回滚、权限和 replay 策略。
|
||||
|
||||
---
|
||||
|
||||
## 8. 验收场景
|
||||
|
||||
+42
-3
@@ -5,7 +5,7 @@
|
||||
**状态**：模块级开发规约
|
||||
**上级事实源**：[海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md)
|
||||
|
||||
本规约细化 `hyb-oa` 审批中心和企业微信原生审批镜像的产品边界、角色权限、状态模型、异常规则、留痕要求和验收场景。WFOC 起，审批按主办方分层；DBWFOC 后边界进一步收窄：报销、财务、采购、合同和项目类审批继续由 OA 主办；请假、补卡、外出、加班等 HR/考勤员工日常审批优先由企业微信主办，OA 同步按域镜像并保留自建历史留存、人工接管和恢复回写能力。WMSG1 已验证企业微信应用消息和 Deeplink 回流，WAPC1 后审批镜像前置工作进入配置准备清单阶段，WAPC2 已提供请假/补卡只读 POC runner，WAPC2FLIVE 已自动生成请假/补卡 OA-POC 样件并复跑通过。WCBK1 已完成只读回调 URL 验证和真实审批事件确认，结论为 `PASS_CALLBACK_EVENT_CONFIRMED`。WEGOV1 后明确先利用企微成熟审批和考勤能力，同时由 OA 保存关键历史和外部关联键。WACP3R 已自动发现 OA-POC 请假/补卡模板并公网复跑到 `PASS_WITH_FINDINGS`：补偿拉取和详情读取可用，finding 是回调证据文件未持久化。WREAD1F 后已完成请假/补卡真机可读性确认：消息卡片、列表、详情页均可看清，远端报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` 为 `PASS_READABLE`；但同意按钮单击即通过，需在 WADM1/WARCH1 的审计留存、提示或操作规程中处理。后续仍必须完成 WADM1 自建留存/镜像数据模型设计和 WARCH1 最小历史留存，不能直接放行镜像实现。后续审批相关开发必须先从本规约拆分 Issue CSV，再进入技术方案和代码实现。
|
||||
本规约细化 `hyb-oa` 审批中心和企业微信原生审批镜像的产品边界、角色权限、状态模型、异常规则、留痕要求和验收场景。WFOC 起，审批按主办方分层；DBWFOC 后边界进一步收窄：报销、财务、采购、合同和项目类审批继续由 OA 主办；请假、补卡、外出、加班等 HR/考勤员工日常审批优先由企业微信主办，OA 同步按域镜像并保留自建历史留存、人工接管和恢复回写能力。WMSG1 已验证企业微信应用消息和 Deeplink 回流，WAPC1 后审批镜像前置工作进入配置准备清单阶段，WAPC2 已提供请假/补卡只读 POC runner，WAPC2FLIVE 已自动生成请假/补卡 OA-POC 样件并复跑通过。WCBK1 已完成只读回调 URL 验证和真实审批事件确认，结论为 `PASS_CALLBACK_EVENT_CONFIRMED`。WEGOV1 后明确先利用企微成熟审批和考勤能力，同时由 OA 保存关键历史和外部关联键。WACP3R 已自动发现 OA-POC 请假/补卡模板并公网复跑到 `PASS_WITH_FINDINGS`：补偿拉取和详情读取可用，finding 是回调证据文件未持久化。WREAD1F 后已完成请假/补卡真机可读性确认：消息卡片、列表、详情页均可看清，远端报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` 为 `PASS_READABLE`；但同意按钮单击即通过，需在 WARCH1 的审计留存、提示或操作规程中处理。WADM1 已完成自建留存/镜像数据模型设计；后续仍必须完成 WARCH1 最小历史留存，不能直接放行镜像实现。后续审批相关开发必须先从本规约拆分 Issue CSV，再进入技术方案和代码实现。
|
||||
|
||||
---
|
||||
|
||||
@@ -355,7 +355,7 @@ WF8-3、WF8-4、WF8-5 实现前必须基于本设计给技术方案；实现后
|
||||
- 采购单附件、合同正文、报价、供应商资料、发票、银行回单、代账资料和其他高敏附件不进入企业微信原生审批或企业微信附件；企业微信只做提醒、deeplink 和免登录回流。
|
||||
- 按域镜像是默认规则：企微主办 HR/考勤域镜像到 OA；OA 主办采购、合同、项目、财务和报销域不反向全量镜像到企微。
|
||||
- WFDG 后，审批相关页面和接口必须区分 `OA 主办`、`企微镜像` 和 `OA 应急接管`；企微镜像不得被误用为 OA 日常新建入口，OA 应急接管单据必须带 `EMERGENCY` 并进入恢复回写队列。
|
||||
- WAPI/WRRA/WOUA-FIX/WAPC1/WAPC2/WPROC1/WEGOV1 后，审批相关运行时迁移必须先读 [企微优先开发路线图](./企微优先开发路线图.md) 和 [企微 API 能力目录](./企微API能力目录.md)，按 `wecom_hr_master_sync_v1` -> `runtime_first_wecom_enablement` -> `WOUA-FIX / WECOM-RUNTIME-READY-V1` -> `WAPC1 审批配置准备` -> `WAPC2 请假/补卡只读 POC` -> `WAPC2F 自动生成 POC 样件` -> `WAPC2FLIVE live 创建与 WAPC2 自动复跑` -> `WCBK1 回调只读 POC` -> `WEGOV1 企微主办治理与自建留存路线修正` -> `WACP3/WACP3R 补偿拉取 POC` -> `WREAD1 审批可读性与误审批防护门禁` -> `WADM1 自建留存/镜像数据模型设计` -> `WARCH1 最小自建历史留存实现` -> `wecom_attendance_approval_mirror_v1` -> `oa_hr_emergency_mode_v1` -> `wecom_recovery_writeback_v1` 的顺序拆单功能 Issue CSV；WOUA-FIX 只收口了用户一致性测试账号差异和处理决策，WRV1/WRA1/WMSG1 只验证入口、OAuth/绑定、脱敏消息、deeplink、通讯录、人事助手、打卡只读主链路和真实消息回流。WAPC1 只固化审批配置准备清单；WAPC2 只读模板详情和低风险 `sp_no` 审批详情；WAPC2FLIVE 只生成 OA-POC 低风险测试样件并自动复跑只读 POC；WCBK1 只证明真实审批状态回调可验签、可解密、可脱敏留证；WACP3R 只证明补偿拉取和详情读取可用，并发现回调证据文件未持久化；WEGOV1 只修正混合主办、自建留存和测试治理口径；WREAD1 只证明请假/补卡当前样例可读，不代表自建留存或镜像实现完成。自建留存模型和最小历史留存未明确前，不得直接开发企微审批镜像或恢复回写。
|
||||
- WAPI/WRRA/WOUA-FIX/WAPC1/WAPC2/WPROC1/WEGOV1 后，审批相关运行时迁移必须先读 [企微优先开发路线图](./企微优先开发路线图.md) 和 [企微 API 能力目录](./企微API能力目录.md)，按 `wecom_hr_master_sync_v1` -> `runtime_first_wecom_enablement` -> `WOUA-FIX / WECOM-RUNTIME-READY-V1` -> `WAPC1 审批配置准备` -> `WAPC2 请假/补卡只读 POC` -> `WAPC2F 自动生成 POC 样件` -> `WAPC2FLIVE live 创建与 WAPC2 自动复跑` -> `WCBK1 回调只读 POC` -> `WEGOV1 企微主办治理与自建留存路线修正` -> `WACP3/WACP3R 补偿拉取 POC` -> `WREAD1 审批可读性与误审批防护门禁` -> `WADM1 自建留存/镜像数据模型设计` -> `WARCH1 最小自建历史留存实现` -> `wecom_attendance_approval_mirror_v1` -> `oa_hr_emergency_mode_v1` -> `wecom_recovery_writeback_v1` 的顺序拆单功能 Issue CSV；WOUA-FIX 只收口了用户一致性测试账号差异和处理决策，WRV1/WRA1/WMSG1 只验证入口、OAuth/绑定、脱敏消息、deeplink、通讯录、人事助手、打卡只读主链路和真实消息回流。WAPC1 只固化审批配置准备清单；WAPC2 只读模板详情和低风险 `sp_no` 审批详情；WAPC2FLIVE 只生成 OA-POC 低风险测试样件并自动复跑只读 POC；WCBK1 只证明真实审批状态回调可验签、可解密、可脱敏留证；WACP3R 只证明补偿拉取和详情读取可用，并发现回调证据文件未持久化；WEGOV1 只修正混合主办、自建留存和测试治理口径；WREAD1 只证明请假/补卡当前样例可读；WADM1 只完成模型设计，不代表历史留存或镜像实现完成。WARCH1 最小历史留存未实现前，不得直接开发企微审批镜像或恢复回写。
|
||||
- WRV1/WRA1 runner `npm run check:wecom-runtime-ready` 中的审批模板、测试 `sp_no` 和真实回调检查只允许输出 `NEEDS_CONFIG`；这类缺口不阻断运行优先主链路的 `PASS_WITH_CONFIG_GAPS`，但必须阻断 `wecom_attendance_approval_mirror_v1`、应急恢复回写和 RuleOps。`WECOM_CHECKIN_SYNC_ENABLED` 只控制正式考勤同步批次，不阻断 QA-only 打卡只读能力探测。
|
||||
- WMSG1 已证明企业微信应用消息可达和 Deeplink 可进入 OA 通知页；该证据只清除通知链路，不清除审批模板、测试 `sp_no` 或真实回调前置。WAPC1 固化配置准备清单后，WAPC2 先提供请假/补卡模板详情和低风险审批详情只读 POC；WPROC1 后优先用 WAPC2F 自动生成 POC 样件，不默认要求人工手动创建模板或测试单。人工介入限于写入批准、密钥/回调配置、企微后台无法 API 化配置、真机确认和风险拍板。
|
||||
- 后续企微审批同步的 POC 必须输出 `CAN_REUSE_NOW`、`NEEDS_CONFIG`、`NEEDS_API_POC`、`KEEP_OA_PRIMARY`、`NOT_SUPPORTED_BY_API`，缺模板、回调、Secret 或权限时记录 `SKIP/BLOCKED_BY_EXTERNAL_CONFIG`。
|
||||
@@ -418,9 +418,48 @@ WAPC2F 是 WAPC2 后的自动化优先补缺阶段，目标是尽量用 QA-only
|
||||
- `WEGOV1 企微主办治理与自建留存路线修正`：固定企微主办域、OA 主办域、OA 留存域和 OA 应急域；明确企业微信没有完整 sandbox 假设，默认使用受控测试域和自动化 runner。
|
||||
- `WACP3 补偿拉取 POC`：已新增 `check:wecom-approval-compensation-poc` 和 `getapprovalinfo` 只读封装；WACP3R 公网复跑为 `PASS_WITH_FINDINGS`，已按 `SMOKE002` creator 自动发现请假/补卡 OA-POC 模板并拉取审批详情。finding 为回调证据文件未持久化，需在 WADM1/WARCH1 的自建留存模型中解决。
|
||||
- `WREAD1 审批可读性与误审批防护门禁`：已新增 `check:wecom-approval-readability-gate` 只读 runner，并在 WREAD1F 新样例后完成真机确认。公网人工结果报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` 为 `PASS_READABLE`：请假和补卡消息卡片、审批列表、详情页足够看清；驳回有二次确认，同意单击即通过。后续不要求回退 OA 主办，但需在 WADM1/WARCH1 中处理单击同意的审计和操作提示风险。
|
||||
- `WADM1 自建留存/镜像数据模型设计`：先设计字段、状态机、幂等键、索引、隐私保留、审计和迁移回滚方案。
|
||||
- `WADM1 自建留存/镜像数据模型设计`：已完成字段、状态机、幂等键、索引、隐私保留、审计和迁移回滚方案设计；本阶段不改 schema、不写业务代码。
|
||||
- `WARCH1 最小自建历史留存实现`：先只读保存企微审批、打卡和人事关键快照，保证企微不可用时可查看历史，再进入完整镜像增强。
|
||||
|
||||
### 9.4.1 WADM1 自建审批留存模型
|
||||
|
||||
WADM1 只做模型设计，不修改 Prisma schema。后续 WARCH1 才能在单独合同中创建迁移和写入路径。
|
||||
|
||||
企微主办审批进入 OA 自建留存时，建议按以下模型拆分：
|
||||
|
||||
| 设计模型 | 职责 | 必要字段 |
|
||||
| --- | --- | --- |
|
||||
| `WecomApprovalArchive` | 审批单主表，表示一条企微审批在 OA 的历史事实 | `sp_no`、`template_id`、`template_type`、规范化状态、企微原状态码、申请人 OA 员工、申请人企微 userid、申请/完成/更新时间、最后来源、风险标记 |
|
||||
| `WecomApprovalParticipant` | 申请人、审批人、抄送人、节点参与人快照 | `sp_no`、角色、节点序号、企微 userid、OA 员工映射、是否当前节点、是否映射失败 |
|
||||
| `WecomApprovalAction` | 通过、驳回、撤回、转交、系统状态变化等动作历史 | `sp_no`、动作类型、操作者、动作时间、节点序号、意见摘要、来源和幂等键 |
|
||||
| `WecomApprovalFieldSummary` | 表单字段规范化摘要 | 字段 key、字段名、字段类型、规范化值、敏感级别、是否可展示 |
|
||||
| `WecomApprovalAttachmentSummary` | 低风险附件摘要和外部引用 | 附件数量、类型、外部引用摘要、是否下载、敏感级别 |
|
||||
| `WecomApprovalCallbackEvent` | 企微回调事件持久证据 | `approval_archive_id`、完整 `sp_no`、完整 `template_id`、事件类型、规范化状态、接收时间、企微事件时间、处理结果、幂等键、摘要 digest；日志和报告只输出脱敏前缀 |
|
||||
| `WecomApprovalCompensationRun` / `WecomApprovalCompensationItem` | 补偿拉取运行和逐单详情证据 | 时间窗口、模板过滤、游标、计数、错误分类、`sp_no` 关联、详情拉取状态 |
|
||||
| `WecomApprovalReconcileFinding` | 回调与补偿对账差异 | 漏回调、重复回调、状态不一致、样例缺失、权限阻断和解释状态 |
|
||||
|
||||
状态机统一为 `pending`、`approved`、`rejected`、`revoked`、`terminated`、`changed`、`unknown`、`sync_failed`。同一 `sp_no` 采用幂等 upsert，动作历史只追加不删除；若回调和补偿拉取状态冲突，主表不静默覆盖为成功，而是写入 `WecomApprovalReconcileFinding`。
|
||||
|
||||
回调与补偿合并规则：
|
||||
|
||||
- DB 业务表必须保存完整 `sp_no`、`template_id`、企微 userid 和 `approval_archive_id`，用于稳定关联和补偿恢复；脱敏只发生在日志、报告、Issue、文档、默认导出和普通 UI 摘要。
|
||||
- `getapprovaldetail` 的详情快照是业务状态的最终校准来源；回调是低延迟事件来源。补偿拉取成功拉到详情后，可以修正主表状态，但必须保留原回调事件和动作历史。
|
||||
- 主表维护 `status_observed_at`、`last_source`、`last_detail_digest`。新事件只有在 `observed_at` 晚于当前状态时间，或详情 digest 变化时才能推进主状态；旧的非终态事件不得覆盖较新的终态。
|
||||
- 终态 `approved`、`rejected`、`revoked`、`terminated` 不被较旧的 `pending` 或 `unknown` 覆盖；若企微详情返回不同终态，记录 `status_mismatch` finding，并以最新详情快照作为待确认状态。
|
||||
- 回调重试使用同一事件幂等键 upsert 并递增重试计数，不重复写动作历史。补偿拉取同一 `run_id + sp_no` 只能有一条 item，详情 digest 相同则只更新时间和来源，不重复生成动作。
|
||||
- source 优先级用于解释，不用于盲目覆盖：`getapprovaldetail` 详情快照 > 回调事件 > 手工导入/测试样例。任何跨来源不一致必须留 finding。
|
||||
|
||||
请假/补卡 WARCH1 V1 至少应保存：申请类型、申请人、审批人、时间范围或补卡时间、时长、原因摘要、状态、审批历史、来源、外部关联键和同步证据。外出/加班仍需后续样例或处理决策；不可把请假/补卡可读性结论扩展为外出/加班已通过。
|
||||
|
||||
同意单击即通过的风险处理不要求回退 OA 主办，但 WARCH1 之后的 OA 历史页和操作规程必须突出：审批动作来源、操作者、时间、状态变化、是否由企微单击同意触发，以及后续补偿拉取是否与回调一致。
|
||||
|
||||
隐私边界：
|
||||
|
||||
- OA DB 可保存完整 `sp_no`、`template_id` 和企微 userid，用于补偿、恢复和审计；日志、报告、Issue 和文档只输出脱敏前缀。
|
||||
- 不保存原始 XML、密文、Token、EncodingAESKey、access token、Secret 或无治理原始 payload。
|
||||
- 表单字段只保存业务必要的规范化字段；如后续确需保存原始 payload，必须另设加密存储、保留期限和访问审计。
|
||||
- 普通员工只能看本人历史；审批人看自己处理链路；HR/管理员按范围查看；导出默认脱敏。
|
||||
|
||||
### 9.5 WF8 邮件通道决策
|
||||
|
||||
WF8 当前正式验收通道为站内通知和企业微信个人应用消息。邮件通道先记录为冻结项，不作为当前 WF8 硬门禁；三渠道验收在本阶段按“两渠道验收 + 邮件冻结说明”处理。
|
||||
|
||||
+2
-2
@@ -7,7 +7,7 @@
|
||||
**相关事实源**：[需求 - 统一审批中心规约](./需求-统一审批中心规约.md)、[需求 - 企业微信基础设施规约](./需求-企业微信基础设施规约.md)
|
||||
**体验总依据**：[产品设计规则基线](./产品设计规则.md)
|
||||
|
||||
本规约细化请假、补卡、外出、加班与考勤修正的产品要求。WFOC 起，企业微信作为 HR/考勤员工日常审批和打卡规则主操作端；OA 负责按域镜像、应急接管、恢复回写、查询导出和审计。WEGOV1 后进一步明确：企微成熟 HR/考勤功能优先上线，OA 不重造企业微信完整打卡/考勤/HR 产品，但必须做自建历史留存、审计、入口、消息和应急兜底。WAPC2 后，请假和补卡先通过 QA-only runner 只读验证模板详情与低风险 `sp_no` 审批详情；WAPC2FLIVE 已生成 OA-POC 样件并复跑通过；WCBK1 已完成真实回调 URL 验证和一条测试审批事件确认；WACP3R 已自动发现模板并证明补偿拉取和详情读取可用。WREAD1F 后，用户真机确认请假/补卡在企业微信消息卡片、列表和详情页均可看清，远端报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` 为 `PASS_READABLE`；驳回有二次确认，同意单击即通过。后续还必须完成 WADM1 自建留存/镜像数据模型设计和 WARCH1 最小历史留存，这不代表审批镜像已实现。PC 和移动页面体验以产品设计规则基线为依据，不重复定义通用审批链和移动导航规则。
|
||||
本规约细化请假、补卡、外出、加班与考勤修正的产品要求。WFOC 起，企业微信作为 HR/考勤员工日常审批和打卡规则主操作端；OA 负责按域镜像、应急接管、恢复回写、查询导出和审计。WEGOV1 后进一步明确：企微成熟 HR/考勤功能优先上线，OA 不重造企业微信完整打卡/考勤/HR 产品，但必须做自建历史留存、审计、入口、消息和应急兜底。WAPC2 后，请假和补卡先通过 QA-only runner 只读验证模板详情与低风险 `sp_no` 审批详情；WAPC2FLIVE 已生成 OA-POC 样件并复跑通过；WCBK1 已完成真实回调 URL 验证和一条测试审批事件确认；WACP3R 已自动发现模板并证明补偿拉取和详情读取可用。WREAD1F 后，用户真机确认请假/补卡在企业微信消息卡片、列表和详情页均可看清，远端报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json` 为 `PASS_READABLE`；驳回有二次确认，同意单击即通过。WADM1 已完成自建留存/镜像数据模型设计，下一步仍需 WARCH1 最小历史留存实现；当前不代表审批镜像已实现。PC 和移动页面体验以产品设计规则基线为依据，不重复定义通用审批链和移动导航规则。
|
||||
|
||||
---
|
||||
|
||||
@@ -228,7 +228,7 @@ WFOC 后，正常审批规则优先以企业微信审批模板和打卡/假期
|
||||
- 当前 A0.10：`WEGOV1 企微主办治理与自建留存路线修正`，固定企微主办域、OA 主办域、OA 留存域、OA 应急域、受控测试域和自动化/人工边界。
|
||||
- 已完成 A0.11：`WACP3/WACP3R 补偿拉取 POC`，已证明按时间窗口获取审批单号并用 `getapprovaldetail` 拉详情；当前 finding 是 WCBK1 回调证据文件未持久化，需在 WADM1/WARCH1 的自建留存模型中解决。
|
||||
- 已完成 A0.12：`WREAD1 审批可读性与误审批防护门禁`，已新增只读 runner 并在 WREAD1F 新样例后完成人工真机确认；请假、补卡在企业微信消息、列表和详情页中均可看清，远端报告为 `PASS_READABLE`。风险记录：驳回有二次确认，同意单击即通过；外出/加班仍需后续样例或处理决策。
|
||||
- 后续 A0.13：`WADM1 自建留存/镜像数据模型设计`，先设计字段、状态机、幂等键、索引、隐私保留、迁移回滚，以及同意单击风险对应的审计和提示策略。
|
||||
- 已完成 A0.13：`WADM1 自建留存/镜像数据模型设计`，已固定请假/补卡审批留存主表、参与人/动作/字段摘要、回调事件、补偿拉取 run/item、对账 finding、隐私保留、迁移回滚，以及同意单击风险对应的审计和提示策略。本阶段不创建 schema、不写业务数据。
|
||||
- 后续 A0.14：`WARCH1 最小自建历史留存实现`，只读保存企微审批、打卡和人事关键快照，先满足企微不可用时可查看历史。
|
||||
- 后续 A1：`wecom_attendance_approval_mirror_v1`，同步企微请假、补卡、外出、加班审批、附件、历史和状态回调；该命名承接旧口径 `wecom_native_approval_mirror_v1`。WAPC2FLIVE 已生成请假/补卡 OA-POC 模板和低风险 `sp_no` 样例，WACP3R 已证明请假/补卡补偿拉取；正式开发前仍必须补齐外出/加班样例或处理决策、可读性门禁、自建留存模型、最小历史留存和必要打卡细项 POC。
|
||||
- 后续 A2：企微打卡规则、排班、记录、日报、月报按域镜像，覆盖 Secret/API 权限、短窗口同步、错误码和脱敏证据。
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
ID,Title,Description,Acceptance,Test_Method,Tools,Dev_Status,Review1_Status,Regression_Status,Files,Dependencies,Notes
|
||||
"WADM1-0","设计合同与边界冻结","建立 WADM1 自建留存/镜像数据模型设计合同；本轮只做 Issue CSV 和事实源设计，不改 Prisma schema、不写业务代码、不部署、不写 OA/企微业务数据。","1) 明确本轮只做数据模型设计；2) 不进入 WARCH1 实现、wecom_attendance_approval_mirror_v1、应急接管、恢复回写或 RuleOps；3) 继承 WEGOV1 四域边界；4) 记录请假/补卡 WREAD1 PASS_READABLE 和同意单击风险；5) 明确外出/加班仍需后续样例或处理决策。","受影响流程：WREAD1 PASS_READABLE -> WADM1 模型设计 -> WARCH1 准入；验证步骤：python3 /home/shunli/.codex/skills/plan/scripts/validate_issues_csv.py issues/2026-05-19_21-55-33-wecom-archive-mirror-data-model-design-v1.csv；node scripts/qa/check-process-contract.mjs --issue issues/2026-05-19_21-55-33-wecom-archive-mirror-data-model-design-v1.csv --profile wecom --json；node scripts/qa/check-process-contract.mjs --issue issues/2026-05-19_21-55-33-wecom-archive-mirror-data-model-design-v1.csv --profile docs-only --json。","python3|node|manual","DONE","DONE","DONE","issues/2026-05-19_21-55-33-wecom-archive-mirror-data-model-design-v1.csv","[]","docs-only/contract-only。本轮不调用企微 API；后续读取仍固定 WECOM_AGENT_SECRET，不尝试其他 Secret、无 fallback、不得靠多个 Secret；缺 Secret、权限、可信 IP、可见范围、模板、回调或样例时记录 NEEDS_CONFIG 或 SKIP/BLOCKED_BY_EXTERNAL_CONFIG。回滚/清理：删除本合同和事实源回写；无数据库迁移、无远端 env 修改、无 OA/企微写入。"
|
||||
"WADM1-1","四域数据模型边界","把企微主办域、OA 主办域、OA 留存域、OA 应急域映射到数据模型职责，明确哪些外部键和业务摘要进入 OA 留存，哪些高敏数据继续禁止进入企微原生审批。","1) 设计区分企微主办、OA 主办、OA 留存和 OA 应急；2) 保存完整外部关联键到 OA 数据库，但报告和日志只输出脱敏前缀；3) 报销、采购、合同、项目、付款、发票、银行回单、高敏附件继续 OA 主办；4) HR/考勤日常审批只保存必要历史和摘要。","受影响流程：域边界 -> schema 设计 -> 权限和日志策略；验证步骤：rg -n ""WADM1|企微主办域|OA 主办域|OA 留存域|OA 应急域|完整外部关联键|高敏附件"" docs .agents/skills/hyb-oa-delivery/SKILL.md。","rg","DONE","DONE","DONE","docs/企微优先开发路线图.md|docs/需求-统一审批中心规约.md|docs/需求-企业微信基础设施规约.md|docs/需求-请假考勤修正规约.md","[""WADM1-0""]","模型设计不得把采购、合同、报销、发票、银行回单或高敏附件推进企微原生审批。完整 template_id、sp_no、userid 可进入受权限保护的 OA DB 业务表；日志、报告、Issue 和文档不得保存完整值。"
|
||||
"WADM1-2","审批留存模型设计","设计企微审批自建留存表：审批单主表、参与人/节点/动作、字段摘要、附件摘要、状态机、幂等键、索引和员工映射关系。","1) 主表能表示 template、sp_no、申请人、审批人、状态、申请/完成时间、最后来源和风险标记；2) 节点/动作能表示审批流历史、同意/驳回/转交等事件；3) 字段摘要只保存业务必要字段，不保存无治理原始 payload；4) 状态机和幂等键支持回调与补偿拉取合并。","受影响流程：企微审批详情 -> OA 自建历史 -> 后续查询/对账；验证步骤：rg -n ""WecomApprovalArchive|审批留存|sp_no|template_id|idempotency|幂等|状态机|字段摘要"" docs .agents/skills/hyb-oa-delivery/SKILL.md。","rg","DONE","DONE","DONE","docs/需求-统一审批中心规约.md|docs/企微优先开发路线图.md","[""WADM1-1""]","建议模型命名优先复用现有 Wecom* 风格。WARCH1 可先实现主表、参与人快照、动作表和同步运行记录；附件只存摘要和外部引用，不下载高敏内容。"
|
||||
"WADM1-3","回调与补偿证据模型设计","设计回调事件、补偿拉取运行记录和对账结果模型，解决 WACP3R finding：回调证据文件未持久化，跨部署无法比对。","1) 回调事件表保存验签/解密后的规范化事件摘要、幂等键、接收时间、处理结果和关联审批单；2) 补偿拉取 run/item 保存窗口、模板过滤、游标、计数、错误和拉取详情关联；3) 对账结果可记录漏回调、重复回调、状态不一致和可解释差异；4) 不保存原始 XML、密文、Token、EncodingAESKey 或原始 payload。","受影响流程：企微回调 -> OA 持久证据 -> 补偿拉取比对；验证步骤：rg -n ""callback|回调事件|补偿拉取|漏回调|重复回调|状态不一致|原始 XML|EncodingAESKey"" docs .agents/skills/hyb-oa-delivery/SKILL.md。","rg","DONE","DONE","DONE","docs/需求-统一审批中心规约.md|docs/企微API能力目录.md","[""WADM1-2""]","WCBK1 已证明真实回调可用；WACP3R finding 必须由 WARCH1 持久化解决。回调密钥仍只在部署环境，不写入仓库、文档、Issue 或日志。"
|
||||
"WADM1-4","打卡与人事快照模型边界","设计打卡记录、打卡规则快照、人事助手花名册快照、假期余额摘要在 OA 自建留存中的边界，复用既有 WecomCheckin* 和 WHMS 模型。","1) 明确现有 WecomCheckinRecord/Run 可承载打卡记录摘要，后续只补规则快照、日报/月报或排班缺口；2) 人事花名册快照优先依托 WHMS run/item 或新增快照表；3) 假期余额只存摘要和时间点；4) 不保存 Secret、token、原始密文或无治理原始 payload。","受影响流程：企微打卡/人事助手 -> OA 历史查看 -> 后续最小留存；验证步骤：rg -n ""WecomCheckin|人事花名册|假期余额|规则快照|排班|日报|月报"" docs server/prisma/schema.prisma。","rg","DONE","DONE","DONE","docs/需求-企业微信基础设施规约.md|docs/需求-请假考勤修正规约.md|docs/企微优先开发路线图.md","[""WADM1-1""]","WARCH1 V1 可优先做审批留存和既有打卡记录读取持久化，不强行一次覆盖排班、日报、月报和假期余额；缺 API/权限时记录 NEEDS_API_POC 或 NEEDS_CONFIG。"
|
||||
"WADM1-5","隐私保留、权限和审计设计","定义完整外部键、业务摘要、表单字段、附件摘要、原始 payload、日志报告的保留策略，以及管理员/HR/员工/审计角色的访问边界。","1) OA DB 可保存完整外部键用于补偿和恢复；2) 报告、日志、文档只输出脱敏前缀；3) 原始 payload 默认不保存，确需保存必须另设加密存储和访问审计；4) 普通员工只能看自己的历史，管理视图按 HR/部门/管理员权限分层；5) 导出默认脱敏。","受影响流程：历史查看 -> 权限控制 -> 审计导出；验证步骤：rg -n ""隐私|脱敏|完整外部键|原始 payload|访问审计|导出|权限"" docs .agents/skills/hyb-oa-delivery/SKILL.md。","rg","DONE","DONE","DONE","docs/需求-统一审批中心规约.md|docs/需求-企业微信基础设施规约.md|docs/管理员手册.md","[""WADM1-2"",""WADM1-3"",""WADM1-4""]","同意单击即通过的风险不通过复制企微原始页面解决；WADM1 只记录审计、状态历史和必要提示策略，WARCH1 后页面可补充查看历史和审批轨迹。"
|
||||
"WADM1-6","WARCH1 最小实现切片与迁移回滚设计","把数据模型拆成 WARCH1 可实现的最小切片，定义 schema 迁移顺序、回填方式、失败回滚和验收口径。","1) WARCH1 V1 优先只读保存请假/补卡审批历史、回调事件、补偿拉取 run/item 和必要员工映射；2) 先不实现完整镜像查询增强、应急接管、恢复回写或 RuleOps；3) 迁移可回滚，写入可幂等重放；4) 断开企微 API 时 OA 仍能查看已保存历史摘要。","受影响流程：WADM1 设计 -> WARCH1 实现合同；验证步骤：rg -n ""WARCH1|最小自建历史留存|迁移|回滚|幂等重放|断开企微"" docs .agents/skills/hyb-oa-delivery/SKILL.md。","rg","DONE","DONE","DONE","docs/企微优先开发路线图.md|docs/需求-统一审批中心规约.md|docs/开发交付与变更管理规约.md","[""WADM1-5""]","WARCH1 仍需单独 Issue CSV 和方案批准；WADM1 不创建迁移文件。建议迁移顺序：先新增只写不读表，再 runner/backfill，再只读页面/接口，再运营验收。"
|
||||
"WADM1-7","事实源回写、评审和提交","更新路线图、审批规约、企微基础设施规约、请假考勤规约、管理员手册、文档索引、事实源矩阵和项目 skill；启动只读评审员 agent 审查模型风险；完成验证和中文提交。","1) 事实源记录 WADM1 设计结论；2) 评审员覆盖状态机、幂等、隐私、迁移回滚、权限和跳阶段风险；3) 文档审计、skill 校验、process gate 和 git diff --check 通过；4) 中文提交完成；5) 下一步明确进入 WARCH1。","受影响流程：WADM1 设计收口 -> WARCH1 准入；验证步骤：node scripts/qa/audit-docs.mjs --check-registry；python3 /home/shunli/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/hyb-oa-delivery；node scripts/qa/check-process-contract.mjs --baseline --json；git diff --check；git commit -m 'WADM1 设计企微自建留存数据模型'。","node|python3|git|agent-review","DONE","DONE","DONE","docs/企微优先开发路线图.md|docs/需求-统一审批中心规约.md|docs/需求-企业微信基础设施规约.md|docs/需求-请假考勤修正规约.md|docs/管理员手册.md|docs/文档索引.md|docs/文档事实源状态矩阵.md|.agents/skills/hyb-oa-delivery/SKILL.md","[""WADM1-6""]","评审员只读，不修改文件；评审指出的完整外部键、合并语义和合同状态一致性问题已修正文档。提交后继续按三脑轮次判断是否立即进入 WARCH1；若 WARCH1 schema/隐私风险需要人工拍板，则用问答方式暂停。"
|
||||
|
在新工单中引用
屏蔽一个用户