From 178917cb7a92d62fddcede3ca91346a0838239d0 Mon Sep 17 00:00:00 2001 From: shunli Date: Wed, 11 Mar 2026 16:55:04 +0800 Subject: [PATCH] =?UTF-8?q?docs(P20T3-5):=20=E5=B7=AE=E6=97=85=E5=AF=B9?= =?UTF-8?q?=E8=B4=A6=E8=BE=B9=E7=95=8C=E4=BA=8B=E4=BB=B6=E7=9F=A9=E9=98=B5?= =?UTF-8?q?=E6=94=B6=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/domain-events.md | 8 +++++++- docs/feature-matrix.md | 15 +++++++++++---- docs/integration-boundaries.md | 19 ++++++++++++++++--- scripts/validate-feature-matrix.py | 1 + 4 files changed, 35 insertions(+), 8 deletions(-) diff --git a/docs/domain-events.md b/docs/domain-events.md index ffc79dff..1369cc46 100644 --- a/docs/domain-events.md +++ b/docs/domain-events.md @@ -1,4 +1,4 @@ -# 领域事件清单（P19 / P19+IM-1 / P19+ERP-3 / P19+AI-1 / P20+TRAVEL-1 / P20+TRAVEL-2） +# 领域事件清单（P19 / P19+IM-1 / P19+ERP-3 / P19+AI-1 / P20+TRAVEL-1 / P20+TRAVEL-2 / P20+TRAVEL-3） **快照日期**：2026-03-10 **目标**：冻结 `hyb-oa` 当前采购、资产与差旅域的标准领域事件名，并补充 `P19+IM-1` 已实际消费的 IM 通知类型清单，以及 `P19+ERP-1 / ERP-3 / AI-1 / TRAVEL-1` 已实际落地的消费映射，作为后续 ERP / IM / AI / TRAVEL 适配的事实源。 @@ -133,3 +133,9 @@ - `CardAuthorization` 导入成功后写支付预算 `authorize`；`CardTransaction` 的 `charge + settled` 写 `settle`，`refund / reversal` 写 `reverse`，且这些支付账轨不回改 `travel_request` 在 `TRAVEL-1` 已冻结的申请预算确认点。 - 差旅订单只有在已结算交易与订单金额/币种完全匹配时才会从 `imported` 推进到 `confirmed`；之后由 `mark-paid` 手工结算动作把订单推进到 `paid`，形成运营闭环。 - `travel_order.paid` 的固定消费路径为：`travel_order.paid` → `TravelOrderPaymentJournalSlice` → `erp.journal.export`；若 `erp_sync` feature flag 未开启，仅记录审计摘要，不进入 Outbox。 + +## 14. P20+TRAVEL-3 已实现消费说明 +- `P20+TRAVEL-3` 不新增新的公开业务领域事件名；`TravelReconciliationBatch` / `TravelReconciliationItem` 当前只作为内部运营事实与批次快照存在，不进入稳定公共事件表。 +- `travel_order.paid` 继续保持 `TRAVEL-2` 已冻结的稳定承诺，并作为 `TRAVEL-3` 对账批次生成时的只读事实来源之一；对账批次不会反向改写该事件的消费语义。 +- `erp.travel.export` 在 `TRAVEL-3` 中新增，但它被固定归类为批次级集成事件，不计入公开业务领域事件名；其消费路径为 `TravelReconciliationBatch(reconciled)` → `TravelReconciliationSummaryPayload` → `erp.travel.export`。 +- `card_authorization.imported`、`card_transaction.imported`、`card_transaction.reversed` 仍只保留为内部支付轨道事实；`TRAVEL-3` 只读取这些事实构建 snapshot，不提升为新的稳定公共事件名。 diff --git a/docs/feature-matrix.md b/docs/feature-matrix.md index 296b439e..19663f8e 100644 --- a/docs/feature-matrix.md +++ b/docs/feature-matrix.md @@ -1,8 +1,8 @@ -# hyb-oa 实现状态矩阵（P5-P19+IM-1+ERP-3+R10+MCP-1+AI-1+TRAVEL-1+TRAVEL-2） +# hyb-oa 实现状态矩阵（P5-P19+IM-1+ERP-3+R10+MCP-1+AI-1+TRAVEL-1+TRAVEL-2+TRAVEL-3） -**快照日期**：2026-03-10 -**范围**：`F1-F42`（含 `F19b/F19c/F19d`）+ `R1-S2` + `P9A1-P9D1` + `P10E1-P10G1` + `G0-G6` + `H1` + `M1-M4` + `P13-0-P13-8` + `P14-0-P14-8` + `P15A-0-P15A-5` + `P15B-0-P15B-6` + `P16A-0-P16A-6` + `P16B-0-P16B-6` + `P16C-0-P16C-6` + `R9-0-R9-3` + `G2-0-G2-6` + `P17A-0-P17A-6` + `P17B-0-P17B-6` + `P18A-0-P18A-6` + `P18B-0-P18B-6` + `P19-0-P19-6` + `P19IM1-0-P19IM1-6` + `P19ERP1-0-P19ERP1-6` + `P19ERP2-0-P19ERP2-6` + `P19ERP3-0-P19ERP3-6` + `R10-0-R10-4` + `P19MCP1-0-P19MCP1-4` + `P19AI1-0-P19AI1-5` + `P20TRAVEL1-0-P20TRAVEL1-5` + `P20TRAVEL2-0-P20TRAVEL2-5`，共 248 项。 -**事实源**：`issues/2026-02-09_13-39-02-p5-blueprint-v3.csv` + `issues/2026-02-09_23-30-00-p6-p8-remaining-work-master.csv` + `issues/2026-02-10_09-42-31-p9-maintenance-performance-matrix.csv` + `issues/2026-02-10_10-35-30-p10-production-hardening.csv` + `issues/2026-02-11-p11-p12-governance-mobile.csv` + `issues/2026-02-12_01-09-41-p13-l5-governance.csv` + `issues/2026-02-13_00-11-56-p14-l5-operationalization.csv` + `issues/2026-03-06_14-30-00-p15a-l5-permission-decouple.csv` + `issues/2026-03-06_14-30-00-p15b-l5-leave-v1.csv` + `issues/2026-03-07_13-47-05-p16a-l5-master-data-core.csv` + `issues/2026-03-07_16-22-07-p16b-l5-holiday-calendar.csv` + `issues/2026-03-07_17-14-39-p16c-l5-suppliers.csv` + `issues/2026-03-07_18-15-03-r9-g2-p19-roadmap-refresh.csv` + `issues/2026-03-07_18-16-00-g2-l5-cross-domain-bridge.csv` + `issues/2026-03-07_19-33-09-p17a-l5-procurement-core.csv` + `issues/2026-03-07_21-00-37-p17b-l5-procurement-budget-archive.csv` + `issues/2026-03-07_22-02-09-p18a-l5-asset-registry-core.csv` + `issues/2026-03-07_22-34-03-p18b-l5-asset-movements-inventory.csv` + `issues/2026-03-07_23-22-00-p19-l4-integration-readiness.csv` + `issues/2026-03-08_12-18-10-p19-im-1-l5-collaboration-adapter.csv` + `issues/2026-03-08_14-10-53-p19-erp-1-l5-masterdata-journal-bridge.csv` + `issues/2026-03-08_22-46-51-p19-erp-2-l5-procurement-commitment-archive.csv` + `issues/2026-03-09_00-10-00-p19-erp-3-l5-asset-ledger-summary.csv` + `issues/2026-03-09_10-15-00-r10-post-erp3-roadmap-refresh.csv` + `issues/2026-03-09_10-25-00-p19-mcp-1-l4-readonly-tools-baseline.csv` + `issues/2026-03-10_12-54-30-p19-ai-1-l5-suggestion-workbench-refresh.csv` + `issues/2026-03-10_17-32-21-p20-travel-1-l5-request-intake-refresh.csv` + `issues/2026-03-10_21-05-59-p20-travel-2-l5-corporate-payments-refresh.csv`（执行合同） +**快照日期**：2026-03-11 +**范围**：`F1-F42`（含 `F19b/F19c/F19d`）+ `R1-S2` + `P9A1-P9D1` + `P10E1-P10G1` + `G0-G6` + `H1` + `M1-M4` + `P13-0-P13-8` + `P14-0-P14-8` + `P15A-0-P15A-5` + `P15B-0-P15B-6` + `P16A-0-P16A-6` + `P16B-0-P16B-6` + `P16C-0-P16C-6` + `R9-0-R9-3` + `G2-0-G2-6` + `P17A-0-P17A-6` + `P17B-0-P17B-6` + `P18A-0-P18A-6` + `P18B-0-P18B-6` + `P19-0-P19-6` + `P19IM1-0-P19IM1-6` + `P19ERP1-0-P19ERP1-6` + `P19ERP2-0-P19ERP2-6` + `P19ERP3-0-P19ERP3-6` + `R10-0-R10-4` + `P19MCP1-0-P19MCP1-4` + `P19AI1-0-P19AI1-5` + `P20TRAVEL1-0-P20TRAVEL1-5` + `P20TRAVEL2-0-P20TRAVEL2-5` + `P20TRAVEL3-0-P20TRAVEL3-5`，共 254 项。 +**事实源**：`issues/2026-02-09_13-39-02-p5-blueprint-v3.csv` + `issues/2026-02-09_23-30-00-p6-p8-remaining-work-master.csv` + `issues/2026-02-10_09-42-31-p9-maintenance-performance-matrix.csv` + `issues/2026-02-10_10-35-30-p10-production-hardening.csv` + `issues/2026-02-11-p11-p12-governance-mobile.csv` + `issues/2026-02-12_01-09-41-p13-l5-governance.csv` + `issues/2026-02-13_00-11-56-p14-l5-operationalization.csv` + `issues/2026-03-06_14-30-00-p15a-l5-permission-decouple.csv` + `issues/2026-03-06_14-30-00-p15b-l5-leave-v1.csv` + `issues/2026-03-07_13-47-05-p16a-l5-master-data-core.csv` + `issues/2026-03-07_16-22-07-p16b-l5-holiday-calendar.csv` + `issues/2026-03-07_17-14-39-p16c-l5-suppliers.csv` + `issues/2026-03-07_18-15-03-r9-g2-p19-roadmap-refresh.csv` + `issues/2026-03-07_18-16-00-g2-l5-cross-domain-bridge.csv` + `issues/2026-03-07_19-33-09-p17a-l5-procurement-core.csv` + `issues/2026-03-07_21-00-37-p17b-l5-procurement-budget-archive.csv` + `issues/2026-03-07_22-02-09-p18a-l5-asset-registry-core.csv` + `issues/2026-03-07_22-34-03-p18b-l5-asset-movements-inventory.csv` + `issues/2026-03-07_23-22-00-p19-l4-integration-readiness.csv` + `issues/2026-03-08_12-18-10-p19-im-1-l5-collaboration-adapter.csv` + `issues/2026-03-08_14-10-53-p19-erp-1-l5-masterdata-journal-bridge.csv` + `issues/2026-03-08_22-46-51-p19-erp-2-l5-procurement-commitment-archive.csv` + `issues/2026-03-09_00-10-00-p19-erp-3-l5-asset-ledger-summary.csv` + `issues/2026-03-09_10-15-00-r10-post-erp3-roadmap-refresh.csv` + `issues/2026-03-09_10-25-00-p19-mcp-1-l4-readonly-tools-baseline.csv` + `issues/2026-03-10_12-54-30-p19-ai-1-l5-suggestion-workbench-refresh.csv` + `issues/2026-03-10_17-32-21-p20-travel-1-l5-request-intake-refresh.csv` + `issues/2026-03-10_21-05-59-p20-travel-2-l5-corporate-payments-refresh.csv` + `issues/2026-03-11_09-57-28-p20-travel-3-l5-reconciliation-erp-bridge-refresh.csv`（执行合同） **说明**： - 本矩阵用于全局读图（审计/交接/回归覆盖追踪），不替代 `issues/*.csv` 的执行合同职责。 @@ -288,3 +288,10 @@ | P20TRAVEL2-3 | 发票绑定标记已支付与ERP journal出站 | N/A | 2026-03-09_10-55-00-p20-travel-2-l5-corporate-payments.csv | 2026-03-10_21-05-59-p20-travel-2-l5-corporate-payments-refresh.csv | 2026-03-10 | DONE | server:test | 发票池支持 `travelOrderId` 排他绑定，`mark-paid` 支持幂等支付确认，并按 `travel_order.paid` 复用 `erp.journal.export` 出站 | | P20TRAVEL2-4 | 差旅前端支付轨道与发票绑定交互 | N/A | 2026-03-09_10-55-00-p20-travel-2-l5-corporate-payments.csv | 2026-03-10_21-05-59-p20-travel-2-l5-corporate-payments-refresh.csv | 2026-03-10 | DONE | client:typecheck/build | 差旅详情新增对公支付轨道卡片，支持只读摘要、标记已支付、发票绑定与冻结建议交互，失败仅卡片内降级 | | P20TRAVEL2-5 | P20TRAVEL2文档矩阵同步与回归收口 | N/A | 2026-03-09_10-55-00-p20-travel-2-l5-corporate-payments.csv | 2026-03-10_21-05-59-p20-travel-2-l5-corporate-payments-refresh.csv | 2026-03-10 | DONE | server:test + client:typecheck/build + validate-feature-matrix | ADR、边界文档、领域事件、Feature Matrix 与全量回归同步收口，主线里程碑推进到 248 | + +| P20TRAVEL3-0 | P20TRAVEL3执行合同刷新建档 | N/A | 2026-03-09_11-05-00-p20-travel-3-l5-reconciliation-erp-bridge.csv | 2026-03-11_09-57-28-p20-travel-3-l5-reconciliation-erp-bridge-refresh.csv | 2026-03-11 | DONE | CSV 校验 | 以 superseding CSV 刷新 TRAVEL-3 执行合同，冻结批次快照、只读对账与 `erp.travel.export` 摘要桥边界 | +| P20TRAVEL3-1 | 对账批次模型与序列基线 | N/A | 2026-03-09_11-05-00-p20-travel-3-l5-reconciliation-erp-bridge.csv | 2026-03-11_09-57-28-p20-travel-3-l5-reconciliation-erp-bridge-refresh.csv | 2026-03-11 | DONE | server:prisma-validate + server:test | 新增 `TravelReconciliationBatch`、`TravelReconciliationItem`、`travel_reconciliation_batch` 单号与 seed，不改写既有订单/交易状态语义 | +| P20TRAVEL3-2 | 对账引擎批次接口与人工确认 | N/A | 2026-03-09_11-05-00-p20-travel-3-l5-reconciliation-erp-bridge.csv | 2026-03-11_09-57-28-p20-travel-3-l5-reconciliation-erp-bridge-refresh.csv | 2026-03-11 | DONE | server:test | 差旅对账支持批次快照、差异判定、confirm / reopen / finalize，且只读发现差异不自动修复订单或预算 | +| P20TRAVEL3-3 | ERP travel export与批次轨道 | N/A | 2026-03-09_11-05-00-p20-travel-3-l5-reconciliation-erp-bridge.csv | 2026-03-11_09-57-28-p20-travel-3-l5-reconciliation-erp-bridge-refresh.csv | 2026-03-11 | DONE | server:test | 新增 `erp.travel.export`、`travel_payable_summary` / `travel_settlement_batch` binding 与 batch-level track / requeue，不影响既有 `travel_order_payment` journal | +| P20TRAVEL3-4 | 差旅页对账Tab与前端联动 | N/A | 2026-03-09_11-05-00-p20-travel-3-l5-reconciliation-erp-bridge.csv | 2026-03-11_09-57-28-p20-travel-3-l5-reconciliation-erp-bridge-refresh.csv | 2026-03-11 | DONE | client:typecheck/build | `/travel-requests?tab=reconciliation&batchId=` 已支持批次列表、KPI、异常确认、Finalize 与 ERP 轨道重试联动 | +| P20TRAVEL3-5 | P20TRAVEL3文档矩阵同步与回归收口 | N/A | 2026-03-09_11-05-00-p20-travel-3-l5-reconciliation-erp-bridge.csv | 2026-03-11_09-57-28-p20-travel-3-l5-reconciliation-erp-bridge-refresh.csv | 2026-03-11 | DONE | server:test + client:typecheck/build + validate-feature-matrix | 边界文档、领域事件、Feature Matrix、CSV 校验与全量回归同步收口，主线里程碑推进到 254 | diff --git a/docs/integration-boundaries.md b/docs/integration-boundaries.md index c7d3fe2a..f181cd76 100644 --- a/docs/integration-boundaries.md +++ b/docs/integration-boundaries.md @@ -1,7 +1,7 @@ -# 集成边界冻结（P19 / P19+IM-1 / P19+ERP-3 / R10 / P19+MCP-1 / P19+AI-1 / P20+TRAVEL-1 / P20+TRAVEL-2） +# 集成边界冻结（P19 / P19+IM-1 / P19+ERP-3 / R10 / P19+MCP-1 / P19+AI-1 / P20+TRAVEL-1 / P20+TRAVEL-2 / P20+TRAVEL-3） **快照日期**：2026-03-10 -**当前基线**：`P19+IM-1`、`P19+ERP-1`、`P19+ERP-2`、`P19+ERP-3`、`P19+MCP-1`、`P19+AI-1` 与 `P20+TRAVEL-1`、`P20+TRAVEL-2` 已完成；当前运行时已落地企微群机器人 + 深链 + Outbox 异步派发的一期协同适配，以及 ERP 主数据 Pull、报销付款凭证切片、采购双阶段 journal / 归档摘要出站、资产台账摘要出站、Postgres MCP 只读工具基线、报销 / 采购 / 资产详情页 AI 只读建议挂件，以及差旅申请主单 / 行程段 / 审批预算锁定 / `travel_orders` 关联入站与混合双轨对公支付闭环的两期差旅基线。 +**当前基线**：`P19+IM-1`、`P19+ERP-1`、`P19+ERP-2`、`P19+ERP-3`、`P19+MCP-1`、`P19+AI-1` 与 `P20+TRAVEL-1`、`P20+TRAVEL-2`、`P20+TRAVEL-3` 已完成；当前运行时已落地企微群机器人 + 深链 + Outbox 异步派发的一期协同适配，以及 ERP 主数据 Pull、报销付款凭证切片、采购双阶段 journal / 归档摘要出站、资产台账摘要出站、Postgres MCP 只读工具基线、报销 / 采购 / 资产详情页 AI 只读建议挂件，以及差旅申请主单 / 行程段 / 审批预算锁定 / `travel_orders` 关联入站、混合双轨对公支付闭环与批次级对账摘要桥的三期差旅基线。 **目标**：在保持核心域稳定的前提下，冻结 ERP / IM / AI / MCP / TRAVEL 的长期边界，并记录 IM 一期、ERP 三期、AI 一期与差旅一期的已实现范围、禁入规则以及 R10 之后的固定主线顺序。 ## 1. 总体原则 @@ -170,6 +170,19 @@ - 不在 `TRAVEL-2` 提前实现 AP 摘要桥接、核销批次、requeue / dead-letter 运营面板；这些能力继续固定在 `P20+TRAVEL-3`。 - `card_authorization.imported`、`card_transaction.imported`、`card_transaction.reversed` 当前仍只作为内部导入事实与支付轨道明细，不提升为稳定公共事件名。 +### 5.5 P20+TRAVEL-3 已实现范围 +- 已新增 `TravelReconciliationBatch` 与 `TravelReconciliationItem`，固定采用“批次快照 + 明细快照”持久化结构；人工确认、ERP 出站、track / requeue 都基于 batch，而不是 request-level 运行时即席对比。 +- 已固定 `TRAVEL-3` 只覆盖 `TravelOrder.status = paid` 的统付订单、同范围 `CardTransaction.status in (settled, reversed)` 的支付交易，以及不落在本批次范围内的 `orphan transaction`；`linked_reimbursement_id` 仅作为只读快照上下文保留。 +- 已新增 `/api/travel/reconciliation/batches`、`/api/travel/reconciliation/items/:itemId/confirm|reopen`、`/api/travel/reconciliation/batches/:batchId/finalize`，并固定 `matched` 项自动确认、其余 anomaly 必须人工确认后才能把 batch 从 `draft` 推进到 `reconciled`。 +- 已新增批次级集成事件 `erp.travel.export`，在 `erp_sync` 总闸开启且 batch 已 `reconciled` 时，按 `travel_reconciliation_batch::summary` dedupe key 出站 AP/对账摘要；成功派发后统一沉淀 `travel_payable_summary` 与 `travel_settlement_batch` 两类 binding。 +- 已把前端入口固定在 `/travel-requests?tab=reconciliation&batchId=`，在同一路径下展示 KPI、异常明细、人工确认与 ERP 轨道，不新增独立差旅对账路由。 + +### 5.6 差旅三期明确不做 +- 不自动修正 `TravelOrder.amount/status`、不自动改 `TravelRequest`、不自动改预算账轨；对账只做差异发现与人工接受，不做自动修复。 +- 不把 `travel_order_payment` journal 并入 `erp.travel.export`；`TRAVEL-2` 的订单支付出站继续保留，`TRAVEL-3` 只新增批次级 AP/对账摘要桥。 +- 不做真实商旅供应商清结算、拒付、退款回调、税分摊、复杂票规，也不新增 workflow 审批实例。 +- 若源数据变化，只允许新建下一批 reconciliation batch，不回刷已 finalized 的历史批次快照。 + ## 6. 事件与通知交付规范 ### 6.1 事件最小结构 @@ -228,7 +241,7 @@ ## 9. R10 后续路线冻结 ### 9.1 固定主线顺序 -- `P20+TRAVEL-2` 已完成后，当前固定后续主线顺序为：`P20+TRAVEL-3 -> P21+PWA-1 -> P21+PWA-2`。 +- `P20+TRAVEL-3` 已完成后，当前固定后续主线顺序为：`P21+PWA-1 -> P21+PWA-2`。 - 历史主线顺序仍保持：`P19+MCP-1 -> P19+AI-1 -> P20+TRAVEL-1 -> P20+TRAVEL-2 -> P20+TRAVEL-3 -> P21+PWA-1 -> P21+PWA-2`。 - 后续阶段继续遵循“先治理，再工具，再建议，再业务，再移动”的总顺序，不并行开启两个重业务 phase。 - 每个 phase 固定遵循：`执行合同 CSV -> 方案批准 -> 开发 -> 测试 -> 文档矩阵收口 -> 合并 main`。 diff --git a/scripts/validate-feature-matrix.py b/scripts/validate-feature-matrix.py index cb9617b7..ead967a7 100755 --- a/scripts/validate-feature-matrix.py +++ b/scripts/validate-feature-matrix.py @@ -47,6 +47,7 @@ CSV_FACT_SOURCES = [ ROOT / "issues" / "2026-03-10_12-54-30-p19-ai-1-l5-suggestion-workbench-refresh.csv", ROOT / "issues" / "2026-03-10_17-32-21-p20-travel-1-l5-request-intake-refresh.csv", ROOT / "issues" / "2026-03-10_21-05-59-p20-travel-2-l5-corporate-payments-refresh.csv", + ROOT / "issues" / "2026-03-11_09-57-28-p20-travel-3-l5-reconciliation-erp-bridge-refresh.csv", ] ID_PATTERN = re.compile(r"^[A-Z][0-9][0-9A-Za-z-]*$")