docs: 完善 REV-005 verify 联调准备材料

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-18 11:57:04 +08:00 · 2026-03-18 11:57:04 +08:00 · 19b4b749ab
commit 19b4b749ab
parent e6d7a0bd9f
3 changed files with 501 additions and 28 deletions
--- a/docs/design/00_Management/01_Project_Progress.md
+++ b/docs/design/00_Management/01_Project_Progress.md
@ -116,8 +116,18 @@

 > 说明：本表中的历史记录按当时原始表述保留；当前正式数据库口径统一以“达梦数据库 8.0+”为准。

-| 2026-03-17 | REV-005 作废与红冲边界转后续阶段预留（US4） | 1）在 `12_REV_Detailed.md`、`03_Interface_Design.md` 继续明确作废、红冲仅保留正式文档入口与状态预留，不纳入一期正常开票闭环实现；2）将当前交付边界收敛为“后台申请 + 查询兜底 + 结果回写 + 账单关联 + 客户侧电子票消费”；3）为后续扩展作废、红冲与更多电子票渠道保留可追溯入口。 | 当前已完成 REV-005 US1~US3 的最小闭环，需要继续按 `/speckit.implement` 收口 US4 文档边界，避免一期实现范围与后续能力混淆。 | 正面影响，REV-005 一期交付边界更稳定，评审与后续开发可明确区分“已交付正常开票闭环”和“后续扩展的作废/红冲能力”，减少范围蔓延与误判。 |
-| 2026-03-17 | REV-005 结果回写与客户侧电子发票消费闭环（US3） | 1）更新 `12_REV_Detailed.md`、`01_Database_Design.md`、`03_Interface_Design.md`，补齐结果回写、账单关联、客户侧查询/下载/推送电子发票规则；2）扩展 `InvoiceController.java`、`InvoiceServiceImpl.java`、`InvoiceMapper.java` 与相关 VO/DO，落地客户归属校验、`SUCCESS + fileUrl` 消费前置校验、账单开票状态联动、推送状态回写；3）执行 `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md`、`make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` 及 `mvn -f backend/sw-business/sw-business-server/pom.xml -DskipTests compile` 验证通过。 | 用户要求沿 `/speckit.implement` 持续推进 REV-005 US3，不中断实现链路，直接完成结果回写、账单关联与客户侧电子票消费闭环。 | 正面影响，REV-005 已形成“回写落账 + 账单状态联动 + 客户侧查询/下载/推送 + 最小编译验证”闭环，后续可继续衔接作废、红冲与更多电子发票渠道扩展。 |
+| 2026-03-18 | REV-005 统计模板补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 为 `T055`、`T060`、`T061`、`T062`、`T063` 新增可直接填写的样本记录模板；2）将 SC-001 ~ SC-004 的建议统计口径细化为表格字段与待补说明，避免后续只剩抽象待办；3）保持“模板已补齐但实际统计结果仍待联调/测试环境补录”的真实状态，不虚构样本结果。 | 用户继续推进 REV-005，希望把剩余统计类待办进一步收敛成可执行模板，便于后续直接补录真实样本而不是重新设计统计格式。 | 正面影响，REV-005 当前已具备统一的统计与日志抽样记录模板；后续补 `T055`、`T060 ~ T063` 时可直接按模板填充真实环境数据，减少再次整理验证文档结构的成本。 |
+| 2026-03-18 | REV-005 verify 执行入口补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 补齐 `/business/invoice/apply`、`/query`、`/query/compensate`、`/write-back`、`/customer/query`、`/customer/download`、`/customer/push`、`/invalidate`、`/red-ink` 的最小请求模板；2）继续补齐 `T055`、`T060 ~ T063` 的执行命令草稿与样本采集顺序，明确仅作为测试/联调环境占位模板，真实地址、鉴权信息、业务主键与统计结果均待后续替换和回填；3）同步 `03_Task_Checklist.md`，将 verify 阶段推进到“替换真实环境参数即可执行”的状态。 | 用户继续推进 REV-005，希望不要停留在抽象验证建议，而是把剩余 verify 工作推进到可直接执行、可直接补样本的程度。 | 正面影响，REV-005 当前已具备统一的验证入口、请求模板、命令草稿与采样顺序；后续在测试或联调环境中可直接替换参数发起请求并回填 `T055`、`T060 ~ T063` 的真实结果，减少重复梳理接口和命令的成本。 |
+| 2026-03-18 | REV-005 联调补录清单补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 新增 `T055`、`T060 ~ T063` 的联调补录清单，按“申请 → 查询 → 回写 → 补偿查询 → 客户查询/下载/推送 → 作废/红冲 → 日志抽样”顺序拆解步骤；2）为每一步明确主要输入、预期产出与回填位置，确保联调执行时不再重复梳理样本归档方式；3）同步 `03_Task_Checklist.md`，将 verify 阶段推进到“可按顺序执行并即时补录”的状态。 | 用户继续推进 REV-005，希望把剩余运行态补证工作从“有命令草稿”进一步推进到“有顺序、有产出、有回填位置”的联调操作清单。 | 正面影响，REV-005 当前已具备联调补录步骤清单，后续在测试或联调环境中可按固定顺序执行并即时回填样本、统计与日志证据，降低遗漏申请单号、受理号与日志检索条件的风险。 |
+| 2026-03-18 | REV-005 联调日报模板补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 新增联调日报 / 回填模板，覆盖日报头、当日执行摘要、样本回填索引、风险阻塞与当日结论；2）模板继续保持“只提供回填结构、不预填真实结果”的约束，避免后续联调记录与正式验证表脱节；3）同步 `03_Task_Checklist.md`，便于后续联调执行人与文档维护人使用同一套归档格式。 | 用户继续推进 REV-005，希望在联调补录清单之外，再提供一份可直接用于当天汇总与回填的日报模板，减少后续多人协作时记录口径不一致的问题。 | 正面影响，REV-005 当前不仅具备顺序化联调清单，也具备可直接归档的日报/回填模板；后续联调时可先记录当天执行情况，再回写正式统计表，提升多轮联调的可追溯性与一致性。 |
+| 2026-03-18 | REV-005 联调前置检查补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 新增联调前置检查清单，统一核对环境地址、鉴权信息、样本数据、主键映射、日志入口、回填责任与归档路径；2）继续保持“只补检查项，不预设联调结果”的约束，避免基础条件未确认就直接开始补录；3）同步 `03_Task_Checklist.md`，使后续联调执行前具备统一的准备项核对口径。 | 用户继续推进 REV-005，希望在联调步骤、日报模板之外，再补齐联调开始前必须核对的基础条件，减少环境、样本和日志入口反复确认的成本。 | 正面影响，REV-005 当前已具备联调前置检查清单；后续进入测试或联调环境前，可先按统一核对项确认环境、样本、鉴权与归档条件，降低联调过程中样本不可追溯、日志无法检索和回填责任不清的风险。 |
+| 2026-03-18 | REV-005 最终联调顺序与完成判定补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 新增最终联调执行顺序与完成判定清单，明确 `T060 → T061 → T062 → T063 → T055` 的建议收口顺序；2）为每个待办增加“完成标志 / 可勾选条件 / 是否已拿到真实样本 / 是否已回填正式表格 / 是否已留存附件”判定模板；3）同步 `03_Task_Checklist.md`，为后续联调完成后的任务关闭提供统一标准。 | 用户继续推进 REV-005，希望把剩余 verify 工作从“能执行”进一步推进到“知道何时算完成、按什么顺序关闭待办”的状态。 | 正面影响，REV-005 当前已具备最终联调执行顺序与完成判定标准；后续一旦取得真实样本，即可按统一顺序回填并关闭 `T055`、`T060 ~ T063`，避免因完成标准不一致导致台账与验证记录脱节。 |
+| 2026-03-18 | REV-005 剩余工作摘要补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 新增“剩余工作摘要（可直接引用）”，将 `T055`、`T060 ~ T063` 的剩余联调取证工作压缩为可直接引用的说明；2）明确当前剩余工作不再是设计或实现补充，而是测试/联调环境下补齐运行态统计与日志证据；3）同步 `03_Task_Checklist.md`，便于提测、汇报和交接时直接复用统一表述。 | 用户继续推进 REV-005，希望把最后剩余事项再压缩成一段可直接对外汇报的摘要，而不是继续分散在多个模板和清单中。 | 正面影响，REV-005 当前不仅具备详细的联调执行资料，也具备可直接引用的剩余工作摘要；后续无论是提测说明、周报汇报还是任务交接，都可以直接复用统一口径。 |
+| 2026-03-18 | REV-005 最终交付摘要同步 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 新增“当前交付摘要”，统一说明已完成交付、未闭环事项与对外引用口径；2）将 `specs/002-rev005-invoice-flow/tasks.md` 中 `T065` 标记完成，并同步 `03_Task_Checklist.md` 的交付摘要说明；3）保持 `spec.md`、`tasks.md`、`verification.md` 与管理台账一致，明确 REV-005 当前为“US1 ~ US4 实现态闭环完成，SC-001 ~ SC-005 运行态统计待补”。 | 用户继续推进 REV-005，希望把当前可交付结论、剩余风险与下一步建议收敛成可直接引用的统一摘要，而不是散落在多个文件中。 | 正面影响，REV-005 现在已具备一套可直接用于评审、提测前说明和后续交接的统一摘要口径；团队可以在不虚构量化验收数据的前提下，明确区分“已完成实现态闭环”和“待补运行态统计证据”。 |
+| 2026-03-18 | REV-005 验收证据缺口复核与 tasks 校准 | 1）手工重建 `specs/002-rev005-invoice-flow/tasks.md`，修复 US4 与 Final Phase 的 `T057 ~ T061` 重号，并将 SC-001 ~ SC-004 统计补证、spec 状态同步与最终交付摘要拆分为 `T060 ~ T065` 显式待办；2）复核 `specs/002-rev005-invoice-flow/verification.md`、`spec.md` 与仓库关键字检索结果，确认当前仓库内尚未定位到 REV-005 对应的专项压测脚本、统计脚本或样本台账；3）将 `spec.md` 状态调整为 `Verification Pending`，并把后续动作收敛到样本统计、运行态日志抽样与 DDL 风险跟踪。 | 用户继续推进 REV-005，希望在不虚构验收数据的前提下，把当前真实完成度、待补证据和 Speckit 任务口径收敛一致。 | 正面影响，REV-005 的任务台账、规格状态与验证结论已统一到“实现闭环基本完成、SC-001 ~ SC-004 量化证据待补”的当前真实状态；后续可直接围绕专项统计和联调样本继续收口，而不会误判为一期已完成量化验收。 |
+| 2026-03-18 | REV-005 SC-005 日志追溯矩阵补齐 | 1）基于 `InvoiceServiceImpl.java` 梳理发票申请、查询/补偿、结果回写、客户侧查询/下载/推送、作废、红冲等关键动作的统一日志写入点；2）确认上述动作均通过 `recordInvoiceOperatLog` 归一写入，并由 `OperatLogService.createOperatLog` 承接操作人、客户与日志内容上下文；3）在 `specs/002-rev005-invoice-flow/verification.md` 回写“关键动作 ↔ 日志写入点”矩阵，将 SC-005 收敛为“实现态证据已补齐、运行态样本待抽查”。 | 用户继续推进 REV-005，一期验收优先补齐 SC-005 的可引用验证证据，避免日志完整率仍停留在笼统结论。 | 正面影响，REV-005 已具备可直接引用的实现态日志追溯矩阵，申请、查询补偿、回写、客户侧查询/下载/推送、作废、红冲等关键动作均可定位到统一日志写入点；后续主要补充测试环境样本抽查即可收口运行态证据。 |
+| 2026-03-18 | REV-005 `biz_invoice` DDL 来源核实 | 1）在 `backend/sql`、`docs/design/04_Appendix/Archive/03_Design_Docs/数据库设计.md`、`sql/lhc_数据库设计.md`、`docs/guides/BACKEND_TABLE_MAPPING.md` 范围内交叉检索 `biz_invoice`、作废/红冲新增字段与迁移脚本；2）确认仓库内未找到与当前 `InvoiceDO.java` 对应的 `biz_invoice` 物理 DDL / migration；3）确认 Archive 与 `sql/lhc_数据库设计.md` 中同名 `biz_invoice` 更偏“开票配置表”，不能直接作为 REV-005 发票主记录表的落库依据；4）将该结论回写到 REV-005 验证与管理台账。 | 用户继续要求沿 REV-005 把 US4 剩余风险查清，不停留在“表结构待补”泛化表述。 | 正面影响，REV-005 当前已明确“接口/DO/文档承接口径已完成，但物理落库证据仍未在仓库内闭环”；后续若推进提测或联调，可直接把 DDL 缺口作为明确风险跟踪，避免误判作废/红冲字段已正式落库。 |
+| 2026-03-17 | REV-005 作废与红冲二期最小入口落地（US4） | 1）更新 `spec.md`、`plan.md`、`tasks.md`，将 US4 从“边界预留”升级为当前二期实现范围；2）更新 `12_REV_Detailed.md`、`03_Interface_Design.md`，明确后台作废/红冲入口、状态边界与客户侧消费约束；3）在 `InvoiceController.java`、`InvoiceService.java`、`InvoiceServiceImpl.java` 中将作废/红冲入口升级为专门请求 VO，并补齐原因/备注、原发票代码/号码校验与日志留痕；4）扩展 `InvoiceDO.java` 承接作废原因/备注、红冲原因/备注、原发票代码/号码与触发来源字段，并在 service 中回写最小上下文；5）更新 `01_Database_Design.md` 中 REV-005 发票承接口径，补充作废/红冲原因、备注、原票关联与查询补偿上下文；6）执行 `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` 与 `mvn -f backend/sw-business/sw-business-server/pom.xml -DskipTests compile` 并通过。 | 用户持续要求“继续推进 REV-005”，在一期闭环收口后继续落地 US4 二期最小能力入口，避免作废/红冲长期停留在文档预留状态。 | 正面影响，REV-005 已从“一期正常开票闭环”进一步扩展到“二期作废/红冲最小入口可评审、可编译验证”的状态；当前已补齐专门 VO 接线、原票引用校验、DO 字段承接与数据库承接口径，后续主要剩余 Mapper/表结构层面的正式持久化落地。 || 2026-03-17 | REV-005 结果回写与客户侧电子发票消费闭环（US3） | 1）更新 `12_REV_Detailed.md`、`01_Database_Design.md`、`03_Interface_Design.md`，补齐结果回写、账单关联、客户侧查询/下载/推送电子发票规则；2）扩展 `InvoiceController.java`、`InvoiceServiceImpl.java`、`InvoiceMapper.java` 与相关 VO/DO，落地客户归属校验、`SUCCESS + fileUrl` 消费前置校验、账单开票状态联动、推送状态回写；3）执行 `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md`、`make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` 及 `mvn -f backend/sw-business/sw-business-server/pom.xml -DskipTests compile` 验证通过。 | 用户要求沿 `/speckit.implement` 持续推进 REV-005 US3，不中断实现链路，直接完成结果回写、账单关联与客户侧电子票消费闭环。 | 正面影响，REV-005 已形成“回写落账 + 账单状态联动 + 客户侧查询/下载/推送 + 最小编译验证”闭环，后续可继续衔接作废、红冲与更多电子发票渠道扩展。 |
 | 2026-03-16 | REV-005 后台发票申请与校验闭环（US1） | 1）在 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java` 增加后台发票申请入口；2）在 `service/invoice/InvoiceServiceImpl.java` 实现客户、客户开票信息、账单与税率校验，确保仅已收费未开票账单允许申请；3）补齐 `applicationNo` 或 `custId + chargeIds` 幂等控制、申请单号生成与申请记录落库；4）执行 `mvn -f backend/sw-business/pom.xml -pl sw-business-server -am -DskipTests compile` 最小编译验证并通过。 | 用户要求继续推进 REV-005 implement，优先完成后台发票申请、开票校验与 US1 收尾，不中断当前实现链路。 | 正面影响，REV-005 已形成“后台申请入口 + 关键校验 + 幂等受理 + 最小编译验证”闭环，后续可在此基础上继续推进 SYS-008 调用、开票结果回写、账单状态联动与电子发票推送下载能力。 |
 | 2026-03-12 | OMX 任务路由样例落地 | 1）新增 `docs/design/00_Management/17_OMX_Task_Routing_Examples.md`，给出 `REV-004`、`REV-003` 与正式文档修订三类任务的 leader / explorer / executor / verifier 分工模板；2）补充各 lane 的提示词模板、推荐执行顺序与不建议的并行方式；3）更新 `00_Management/README.md` 收录该文档入口。 | 用户希望在治理层之外，再拿到针对当前项目可以直接复用的多 Agent 分工模板，而不是只看抽象原则。 | 正面影响，OMX 从“有规则”变成“可直接照着分工执行”；后续在 `REV-004`、`REV-003` 等闭环中可直接套用 lane 拆分，减少 leader 临时编排成本。 |
 | 2026-03-12 | OMX 多 Agent 治理层落地 | 1）在根 `AGENTS.md` 中新增 OMX 多 Agent 协作补充，明确分层 AGENTS、任务路由矩阵、写冲突规则、范围控制基线与 worktree/tmux 约定；2）新增 `backend/AGENTS.md`，固化 backend 开发边界、最小实现策略与 BPM 接入规则；3）新增 `docs/design/04_Appendix/Archive/AGENTS.md`，明确 Archive 默认只读与来源回写规则；4）新增 `docs/design/00_Management/16_OMX_Multi_Agent_Guide.md`，统一 leader / writer / executor / verifier 分工与协作拓扑；5）更新 `00_Management/README.md` 收录新指南入口。 | 用户明确准备采用 `oh-my-codex` 进行多 Agent 开发，需要对现有 AGENTS 体系做分层化和路由化改造，避免现有规则在 Team Mode 下失效。 | 正面影响，当前项目从“单 agent 规则完备”提升为“多 agent 可控协作”；后续接入 OMX 时，目录级职责、写权限边界、范围基线与会话约定已经成型，可显著降低并发改稿和多 worker 写冲突风险。 |
--- a/docs/design/00_Management/03_Task_Checklist.md
+++ b/docs/design/00_Management/03_Task_Checklist.md
@ -190,10 +190,25 @@
  - [x] `InvoiceController.java`、`InvoiceServiceImpl.java`、`InvoiceMapper.java` 与相关 VO/DO 已完成客户归属校验、下载/推送前置校验、账单状态联动与推送状态回写 ✅
  - [x] 已完成 `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` 与 `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` 文档校验 ✅
  - [x] 已完成 `mvn -f backend/sw-business/sw-business-server/pom.xml -DskipTests compile` 最小编译验证 ✅
- [x] **完成 REV-005 作废与红冲边界预留收口（US4）** ✅ (2026-03-17)
-  - [x] 已在 `12_REV_Detailed.md` 明确 `INVALID`、`RED_INK` 仅作为后续阶段状态与扩展入口，不纳入一期正常开票闭环 ✅
-  - [x] 已在 `03_Interface_Design.md` 明确 `IF-REV-008`、`IF-CS-004` 当前阶段不承诺作废/红冲消费与处理实现，仅保留协同与状态入口 ✅
-  - [x] 已在 `01_Project_Progress.md` 回写 US4 边界收口决策，便于后续评审与任务拆解引用 ✅
+- [x] **完成 REV-005 作废与红冲二期最小入口（US4）** ✅ (2026-03-17)
+  - [x] 已在 `spec.md`、`plan.md`、`tasks.md` 将 US4 从“后续预留”升级为当前二期实现范围 ✅
+  - [x] 已在 `12_REV_Detailed.md`、`03_Interface_Design.md` 明确作废/红冲的后台入口、状态边界与客户侧消费约束 ✅
+  - [x] `InvoiceController.java`、`InvoiceService.java`、`InvoiceServiceImpl.java` 已完成作废/红冲专门 VO 接线、状态校验、原发票代码/号码校验与原因/备注留痕 ✅
+  - [x] `InvoiceDO.java` 已补作废原因/备注、红冲原因/备注、原发票代码/号码与触发来源字段，并由 service 回写最小上下文 ✅
+  - [x] `01_Database_Design.md` 已补 REV-005 发票承接口径中的作废/红冲原因、备注、原票关联与查询补偿上下文字段说明 ✅
+  - [x] 已完成 `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` 与 `mvn -f backend/sw-business/sw-business-server/pom.xml -DskipTests compile` 验证 ✅
+  - [x] 已交叉核查 `backend/sql`、Archive 数据库设计、`sql/lhc_数据库设计.md` 与 `BACKEND_TABLE_MAPPING.md`；当前未找到与 `InvoiceDO.java` 对应的 `biz_invoice` 物理 DDL/迁移脚本，且历史同名 `biz_invoice` 更偏开票配置表，已作为后续风险明确登记 ✅
+  - [x] 已基于 `InvoiceServiceImpl.java` 补齐 SC-005“关键动作 ↔ 日志写入点”矩阵；申请、查询/补偿、结果回写、客户侧查询/下载/推送、作废、红冲均统一落到 `recordInvoiceOperatLog` 与 `OperatLogService.createOperatLog`，并已回写 `verification.md` 与管理台账 ✅
+- [x] 已手工校准 `specs/002-rev005-invoice-flow/tasks.md`，修复 US4 与 Final Phase 的 `T057 ~ T061` 重号，并将 SC-001 ~ SC-004 统计补证、spec 状态同步与最终交付摘要拆分为 `T060 ~ T065` 显式待办 ✅
+- [x] 已复核仓库内暂未发现 REV-005 对应的专项压测脚本、统计脚本或样本台账；`verification.md` 当前仍以“实现态证据已具备、量化验收待补样本统计”为真实结论 ✅
+- [x] 已在 `specs/002-rev005-invoice-flow/verification.md` 汇总当前交付摘要，明确 REV-005 已完成 US1 ~ US4 实现态闭环、当前状态为 `Verification Pending`，剩余工作聚焦 `T055` 与 `T060 ~ T063` 对应的运行态样本和专项统计 ✅
+- [x] 已为 `T055`、`T060 ~ T063` 在 `specs/002-rev005-invoice-flow/verification.md` 补齐可直接填写的样本记录模板、统计字段与待补说明；当前仍未补录真实环境结果 ✅
+- [x] 已为 `T055`、`T060 ~ T063` 补齐最小请求模板、执行命令草稿与样本采集顺序；当前 verify 阶段已具备“替换真实环境参数即可执行”的入口 ✅
+- [x] 已进一步整理 `T055`、`T060 ~ T063` 的联调补录清单，明确步骤顺序、输入参数、预期产出与回填位置；当前 verify 阶段已具备“按顺序执行并即时补录”的操作清单 ✅
+- [x] 已在 `specs/002-rev005-invoice-flow/verification.md` 补齐联调日报 / 回填模板，明确日报头、当日执行摘要、样本回填索引、风险阻塞与当日结论模板；后续联调结果可直接归档并回扣正式验证记录 ✅
+- [x] 已补齐 REV-005 联调前置检查清单，明确环境地址、鉴权信息、样本数据、主键映射、日志入口、回填责任与归档路径；进入联调前已具备统一核对项 ✅
+- [x] 已补齐 REV-005 最终联调执行顺序与完成判定清单，明确 `T060 → T061 → T062 → T063 → T055` 的建议收口顺序与单项勾选条件；后续联调完成后可直接据此关闭待办 ✅
+- [x] 已补齐 REV-005 剩余工作摘要，明确当前仅剩 `T055`、`T060 ~ T063` 的真实联调取证与结果回填，可直接用于提测、汇报与交接引用 ✅
 - [x] **完成 SYS-002 需求拆解总表与实现评估整理** ✅ (2026-03-17)
  - [x] 新增 `15_SYS002_Requirement_Breakdown.md`，形成 `SYS002-REQ-001 ~ 015` 的统一需求拆解口径 ✅
  - [x] 基于 `backend/sw-business` 与 `backend/sw-business-bank` 输出已实现 / 部分实现 / 未见实现评估结果 ✅
--- a/specs/002-rev005-invoice-flow/verification.md
+++ b/specs/002-rev005-invoice-flow/verification.md
@ -2,12 +2,12 @@

 ## 1. 验证范围

-本记录用于沉淀 `REV-005` 当前已完成的一期正常开票闭环验证证据，覆盖以下范围：
+本记录用于沉淀 `REV-005` 当前已完成的发票业务闭环验证证据，覆盖以下范围：

 - US1：后台发票申请与校验
 - US2：`SYS-008` 异步协同与查询兜底
 - US3：结果回写、账单关联与客户侧电子发票消费
- US4：作废与红冲边界预留（仅文档边界，不含 backend 实现）
+- US4：后台作废与红冲二期入口

 当前验证结论以已执行命令、已完成文档修订、最小编译验证和范围边界复核为主；`spec.md` 中 `SC-001 ~ SC-005` 的性能/统计指标尚未形成专门压测脚本或批量样本统计，本文件先记录现有证据、缺口与后续建议。

@ -16,10 +16,12 @@
 | 类别 | 命令 | 结果 | 说明 |
 |------|------|------|------|
 | 文档单文件校验 | `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` | 通过 | 已用于验证发票数据承接口径 |
-| 文档单文件校验 | `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` | 通过 | 已用于验证客户侧查询/下载/推送接口文档 |
-| backend 最小编译 | `mvn -f backend/sw-business/sw-business-server/pom.xml -DskipTests compile` | 通过 | 已用于验证 REV-005 US3 代码可编译 |
+| 文档单文件校验 | `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` | 通过 | 已用于验证客户侧查询/下载/推送与作废/红冲接口边界文档 |
+| 文档单文件校验 | `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` | 通过 | 已用于验证 REV-005 二期作废/红冲详细设计修订 |
+| backend 最小编译 | `mvn -f backend/sw-business/sw-business-server/pom.xml -DskipTests compile` | 通过 | 已用于验证 REV-005 US3/US4 代码可编译 |
 | 仓库交叉引用校验 | `make check-links` | 通过 | 当前链接检查输出为“所有链接检查通过” |
 | Mermaid 语法校验 | `make validate-mermaid` | 通过 | 当前 Mermaid 验证输出为“所有 mermaid 图表语法验证通过” |
+| 验收资产复核 | 仓库关键字检索（`SC-001`、`SC-002`、`SC-003`、`SC-004`、`样本统计`、`压测脚本`、`P95`） | 未发现现成统计资产 | 当前仓库内暂未定位到可直接复用的压测脚本、统计脚本或样本台账，SC-001 ~ SC-004 仍需在测试或联调环境补充专项证据 |

 ## 3. Success Criteria 对照

@ -28,7 +30,8 @@
 - **当前状态**：待补充专项验证
 - **现有证据**：backend 最小编译通过，后台申请接口与校验链路已实现
 - **缺口说明**：尚未执行接口响应时延采样，也未沉淀固定样本、环境与统计结果
- **后续建议**：在可用测试环境中对 `/admin-api/revenue/invoice/apply` 执行最小样本压测或定点采样，至少记录样本量、平均值、P95、排除外部调用口径
+- **后续建议**：在可用测试环境中对 `/business/invoice/apply` 执行最小样本压测或定点采样，至少记录样本量、平均值、P95、排除外部调用口径
+- **建议统计口径**：仅统计 `SYS-002` 本地受理、账单/客户/税率/限额校验、申请记录落库等内部处理时延；明确剔除 `SYS-008` 外部接口等待时间；结果表至少记录样本时间、样本环境、请求体摘要、平均值、P95、最大值与异常样本说明

 ### SC-002 发票申请校验通过率 > 95%（正常业务场景）

@ -36,6 +39,7 @@
 - **现有证据**：已实现账单收费状态、开票状态、客户开票信息、税率配置、开票限额、幂等控制等校验规则
 - **缺口说明**：尚未基于真实或模拟样本形成“正常场景通过率”统计
 - **后续建议**：准备覆盖正常账单、已开票账单、未缴费账单、限额超限账单等样本集，按样本分组输出通过/拦截统计
+- **建议统计口径**：将样本分为“正常业务场景”和“规则拦截场景”两组；SC-002 仅统计正常业务场景的申请成功率，结果表至少记录样本总数、成功数、失败数、失败原因分类，并单列幂等命中、原始单账单直接部分开票拦截等非正常场景说明

 ### SC-003 开票结果回写成功率 > 99%

@ -43,6 +47,7 @@
 - **现有证据**：已实现结果回写、成功终态保护、账单状态联动、失败原因留痕
 - **缺口说明**：尚未基于批量样本统计回写成功率
 - **后续建议**：在联调或测试环境中按申请单号、受理号建立样本集，统计回写请求总量、成功量、失败量与失败原因分类
+- **建议统计口径**：按“回写请求总量”“业务成功落账量”“业务失败量”“因成功终态保护而不覆盖原状态量”四类指标统计；失败样本需区分外部返回失败、查询超时、账单联动异常、数据缺失等分类，并保留申请单号/受理号映射以便追溯

 ### SC-004 电子发票下载成功率 > 99%

@ -50,29 +55,453 @@
 - **现有证据**：已实现仅 `SUCCESS + fileUrl` 可下载/推送的前置校验，客户归属校验与推送状态回写已落地
 - **缺口说明**：尚未形成客户侧下载成功率样本统计
 - **后续建议**：在具备有效电子票文件地址的样本下，统计查询、下载、推送三类动作成功率，并区分“无权限”“无文件”“非成功终态”等拦截原因
+- **建议统计口径**：以具备有效 `SUCCESS + fileUrl` 条件的样本作为成功率分母，同时单独记录被权限校验、文件缺失、非成功终态拦截的请求量；建议分别输出“客户查询成功率”“下载成功率”“推送成功率”三个子指标，避免把前置拦截与真实下载失败混为一类

 ### SC-005 操作日志完整率 100%（所有关键操作均有日志）

- **当前状态**：部分满足，待补充专项核对
- **现有证据**：申请、查询补偿、结果回写、客户侧下载/推送等关键动作已在当前实现中补充操作留痕
- **缺口说明**：尚未形成“关键动作清单 ↔ 日志写入点”逐项对照表
- **后续建议**：补一份日志追溯矩阵，至少覆盖申请、调用、查询、回写、下载、推送六类动作
+- **当前状态**：实现态证据已补齐，运行态样本待抽查
+- **现有证据**：`InvoiceServiceImpl` 已通过统一 `recordInvoiceOperatLog` 入口写入关键动作日志，并由 `OperatLogService.createOperatLog` 承接操作人、客户标识与日志内容上下文
+- **关键动作 ↔ 日志写入点矩阵**：

-## 4. US4 边界收口结论
+| 关键动作 | 业务入口 | 日志写入点 | 说明 |
+|------|------|------|------|
+| 发票申请 / 提交 SYS-008 开票申请 | `applyInvoice` | `recordInvoiceOperatLog(invoice, "提交SYS-008开票申请...")` | 记录申请受理与受理号 |
+| 后台查询结果 | `queryInvoice` → `refreshQueryContext` | `recordInvoiceOperatLog(invoice, "发票查询补偿，来源：...")` | 普通查询与补偿查询复用同一留痕点，依赖 `querySource` 区分 |
+| 结果回写 | `writeBackInvoice` | `recordInvoiceOperatLog(invoice, "回写发票结果...")` | 成功/失败终态更新后统一留痕 |
+| 成功终态保护 | `writeBackInvoice` | `recordInvoiceOperatLog(invoice, "收到回写结果但因成功终态保护未覆盖原状态...")` | 记录保护分支未覆盖原状态的原因 |
+| 客户侧查询 | `queryCustomerInvoice` → `refreshCustomerQueryContext` | `recordInvoiceOperatLog(invoice, "发票查询补偿，来源：CUSTOMER_QUERY...")` | 记录客户侧查询动作 |
+| 客户侧下载 | `downloadInvoice` | `recordInvoiceOperatLog(invoice, "客户侧下载电子发票")` | 记录电子发票下载动作 |
+| 客户侧推送 | `pushInvoice` | `recordInvoiceOperatLog(invoice, "客户侧推送电子发票...")` | 记录推送渠道与目标 |
+| 后台作废 | `invalidateInvoice` | `recordInvoiceOperatLog(invoice, buildPostProcessLog(...))` | 记录原因、备注与原票代码/号码 |
+| 后台红冲 | `redInkInvoice` | `recordInvoiceOperatLog(invoice, buildPostProcessLog(...))` | 记录原因、备注与原票代码/号码 |

-当前已在以下正式文档中明确：
+- **缺口说明**：尚未在测试或联调环境按上述矩阵逐项抽取实际日志样本，当前仍缺运行态日志记录证据
+- **后续建议**：按矩阵至少抽取申请、补偿查询、结果回写、客户下载、客户推送、作废、红冲各 1 条日志样本，核对操作人、客户、状态与日志内容是否一致
+
+### 待补样本记录模板（不含实际结果）
+
+#### T060 / SC-001 响应时延记录模板
+
+| 采样时间 | 环境 | 接口 | 样本量 | 平均值(ms) | P95(ms) | 最大值(ms) | 是否剔除 `SYS-008` 等待 | 异常样本说明 |
+|------|------|------|------:|------:|------:|------:|------|------|
+| 待补 | 待补 | `/business/invoice/apply` | 待补 | 待补 | 待补 | 待补 | 是 / 否（待补） | 待补 |
+
+- **待补说明**：采样时需同步记录请求体摘要（账单数、开票类型、客户类型）与测试环境配置，避免不同批次结果不可比。
+
+#### T061 / SC-002 申请通过率记录模板
+
+| 样本分组 | 样本总数 | 成功数 | 失败数 | 失败原因分类 | 统计口径说明 |
+|------|------:|------:|------:|------|------|
+| 正常业务场景 | 待补 | 待补 | 待补 | 待补 | 仅统计应当成功的申请样本 |
+| 规则拦截场景 | 待补 | 待补 | 待补 | 待补 | 单独记录，不计入 SC-002 分母 |
+
+- **待补说明**：建议至少覆盖正常账单、已开票账单、未缴费账单、限额超限账单、幂等命中、原始单账单直接部分开票拦截等样本。
+
+#### T062 / SC-003 回写成功率记录模板
+
+| 回写批次 | 回写请求总量 | 业务成功落账量 | 业务失败量 | 成功终态保护量 | 失败原因分类 | 追溯主键 |
+|------|------:|------:|------:|------:|------|------|
+| 待补 | 待补 | 待补 | 待补 | 待补 | 待补 | `applicationNo` / `sysRequestNo`（待补） |
+
+- **待补说明**：失败原因建议至少区分外部返回失败、查询超时、账单联动异常、数据缺失；同一批次需保留申请单号与受理号映射关系。
+
+#### T063 / SC-004 客户侧查询/下载/推送成功率记录模板
+
+| 动作类型 | 样本总数 | 成功数 | 失败数 | 前置拦截数 | 失败/拦截原因分类 | 统计口径说明 |
+|------|------:|------:|------:|------:|------|------|
+| 客户查询 | 待补 | 待补 | 待补 | 待补 | 待补 | 仅统计客户侧查询动作 |
+| 发票下载 | 待补 | 待补 | 待补 | 待补 | 待补 | 分母建议取具备 `SUCCESS + fileUrl` 条件的样本 |
+| 发票推送 | 待补 | 待补 | 待补 | 待补 | 待补 | 单列推送渠道与目标类型 |
+
+- **待补说明**：需区分“无权限”“无文件”“非成功终态”等前置拦截，不建议与真实下载/推送失败混算。
+
+#### T055 / SC-005 运行态日志抽样模板
+
+| 动作类型 | 样本来源 | 操作人/客户 | 状态前后值 | 日志摘要 | 结果 |
+|------|------|------|------|------|------|
+| 发票申请 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| 查询补偿 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| 结果回写 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| 客户下载 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| 客户推送 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| 后台作废 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| 后台红冲 | 待补 | 待补 | 待补 | 待补 | 待补 |
+
+- **待补说明**：样本抽取时需能回扣到 `recordInvoiceOperatLog` / `OperatLogService.createOperatLog` 的实现态矩阵，并保留查询来源、渠道、原票代码/号码等关键上下文。
+
+### 待补样本执行入口清单
+
+| 对应待办 | 接口/合同 | 当前请求路径 | Controller 入口 | Service 入口 | 说明 |
+|------|------|------|------|------|------|
+| `T060` / `T061` | `IF-REV-008` | `/business/invoice/apply` | `InvoiceController.applyInvoice` | `InvoiceService.applyInvoice` / `InvoiceServiceImpl.applyInvoice` | 用于申请时延采样与正常/拦截样本统计 |
+| `T062` | `IF-REV-009` | `/business/invoice/query`、`/business/invoice/query/compensate`、`/business/invoice/write-back` | `InvoiceController.queryInvoice`、`compensateQueryInvoice`、`writeBackInvoice` | `InvoiceService.queryInvoice`、`writeBackInvoice` / `InvoiceServiceImpl.queryInvoice`、`writeBackInvoice` | 用于查询补偿、回写成功率与成功终态保护样本 |
+| `T063` | `IF-CS-004` | `/business/invoice/customer/query`、`/business/invoice/customer/download`、`/business/invoice/customer/push` | `InvoiceController.queryCustomerInvoice`、`downloadInvoice`、`pushInvoice` | `InvoiceService.queryCustomerInvoice`、`downloadInvoice`、`pushInvoice` / `InvoiceServiceImpl.queryCustomerInvoice`、`downloadInvoice`、`pushInvoice` | 用于客户查询、下载、推送成功率统计 |
+| `T055` | `IF-REV-008`、`IF-REV-009`、`IF-CS-004`、`IF-EXT-007` | `/business/invoice/apply`、`/business/invoice/query`、`/business/invoice/customer/*`、`/business/invoice/invalidate`、`/business/invoice/red-ink` | `InvoiceController.applyInvoice`、`queryInvoice`、`queryCustomerInvoice`、`downloadInvoice`、`pushInvoice`、`invalidateInvoice`、`redInkInvoice` | `InvoiceServiceImpl.applyInvoice`、`queryInvoice`、`writeBackInvoice`、`queryCustomerInvoice`、`downloadInvoice`、`pushInvoice`、`invalidateInvoice`、`redInkInvoice` | 用于运行态日志抽样与动作-日志矩阵回扣 |
+
+- **执行说明**：当前仓库正式文档与 backend `InvoiceController` 的实现入口统一使用 `/business/invoice/*` 路径；若后续联调环境存在网关前缀或转发规则，应在样本记录中额外注明映射关系。
+- **本地验证入口排查结论**：当前仓库 `quickstart.md` 未提供可直接复用的 `curl` / Postman / HTTP 脚本来采集 `T055`、`T060 ~ T063` 的真实样本；现阶段可直接依赖的入口主要是接口设计、`InvoiceController` 路径声明与 `InvoiceService(Impl)` 调用链，真实样本仍需在可用测试或联调环境手工执行并回填。
+
+### 最小请求模板（待联调填真实值）
+
+- **用途说明**：以下 JSON 仅作为 `T055`、`T060 ~ T063` 的最小请求体草稿，用于后续在测试或联调环境手工发起请求并回填真实样本。
+- **填写约束**：示例中的 `applicationNo`、`sysRequestNo`、`invoiceId`、`chargeIds`、`custId` 等值均为占位符，执行前必须替换为环境中的真实数据。
+
+#### `/business/invoice/apply`
+
+```json
+{
+  "chargeIds": [10001],
+  "custId": 1024,
+  "invoiceType": "ELECTRONIC",
+  "invoiceTitle": "福建水务测试客户",
+  "sourceChannel": "COUNTER"
+}
+```
+
+- **最小必填字段来源**：`chargeIds`、`custId`、`invoiceType`、`invoiceTitle`、`sourceChannel`
+- **可选补充字段**：`applicationNo`（幂等单号）、`taxNo`、`email`、`mobile`、`remark`
+
+#### `/business/invoice/query`
+
+```json
+{
+  "applicationNo": "APP-REV005-001",
+  "querySource": "MANUAL"
+}
+```
+
+- **最小必填字段来源**：`querySource`
+- **定位建议**：`applicationNo`、`sysRequestNo` 二选一至少补一个真实定位键，避免联调时无法唯一定位申请记录
+
+#### `/business/invoice/query/compensate`
+
+```json
+{
+  "applicationNo": "APP-REV005-001",
+  "querySource": "AUTO_COMPENSATE"
+}
+```
+
+- **最小必填字段来源**：`querySource`
+- **说明**：controller 会按补偿查询语义覆盖 `querySource`，但请求体仍建议显式传入 `AUTO_COMPENSATE`
+
+#### `/business/invoice/write-back`
+
+```json
+{
+  "applicationNo": "APP-REV005-001",
+  "invoiceStatus": "SUCCESS"
+}
+```
+
+- **最小必填字段来源**：`invoiceStatus`
+- **定位建议**：`applicationNo`、`sysRequestNo` 二选一至少补一个真实定位键；若为成功样本，建议同步补 `invoiceCode`、`invoiceNumber`、`fileUrl`
+
+#### `/business/invoice/customer/query`
+
+```json
+{
+  "custId": 1024,
+  "invoiceId": 2048
+}
+```
+
+- **最小 Bean Validation 字段**：`custId`
+- **定位建议**：联调时应至少补 `applicationNo`、`sysRequestNo`、`invoiceId` 之一；上例默认使用 `invoiceId` 作为定位键
+
+#### `/business/invoice/customer/download`
+
+```json
+{
+  "custId": 1024,
+  "invoiceId": 2048
+}
+```
+
+- **最小 Bean Validation 字段**：`custId`
+- **定位建议**：与客户查询一致，联调时应至少补 `applicationNo`、`sysRequestNo`、`invoiceId` 之一
+
+#### `/business/invoice/customer/push`
+
+```json
+{
+  "custId": 1024,
+  "invoiceId": 2048,
+  "pushChannel": "EMAIL",
+  "pushEmail": "test@example.com"
+}
+```
+
+- **最小必填字段来源**：`custId`、`invoiceId`、`pushChannel`
+- **渠道补充说明**：`pushChannel=EMAIL` 时建议同时补 `pushEmail`；`pushChannel=SMS` 时建议同时补 `pushMobile`
+
+#### `/business/invoice/invalidate`
+
+```json
+{
+  "invoiceId": 2048,
+  "invalidReason": "测试作废样本"
+}
+```
+
+- **最小必填字段来源**：`invoiceId`、`invalidReason`
+- **可选补充字段**：`invalidRemark`、`originalInvoiceCode`、`originalInvoiceNumber`
+
+#### `/business/invoice/red-ink`
+
+```json
+{
+  "invoiceId": 2048,
+  "redInkReason": "测试红冲样本"
+}
+```
+
+- **最小必填字段来源**：`invoiceId`、`redInkReason`
+- **可选补充字段**：`redInkRemark`、`originalInvoiceCode`、`originalInvoiceNumber`
+
+### 执行命令草稿与样本采集顺序
+
+- **使用原则**：以下命令仅作为测试或联调环境的执行草稿，不包含真实环境地址、鉴权信息与业务主键；执行前需替换 `${BASE_URL}`、`${TOKEN}`、`${APPLICATION_NO}`、`${SYS_REQUEST_NO}`、`${INVOICE_ID}`、`${CUST_ID}`、`${CHARGE_ID}` 等占位符。
+- **结果约束**：命令执行后的真实响应、日志截图、统计数值不得预填，需在拿到实际结果后回填到本文件对应模板。
+
+#### 通用命令头草稿
+
+```bash
+curl -X POST "${BASE_URL}/business/invoice/apply" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"chargeIds":[${CHARGE_ID}],"custId":${CUST_ID},"invoiceType":"ELECTRONIC","invoiceTitle":"福建水务测试客户","sourceChannel":"COUNTER"}'
+```
+
+- **说明**：若联调环境存在网关前缀、灰度路由、租户头或其他鉴权头，应在执行记录中一并注明。
+
+#### T060 / T061：申请时延与通过率采样顺序
+
+1. 使用正常账单样本执行 `/business/invoice/apply`，记录请求时间、响应时间、`applicationNo` 与是否命中正常受理。
+2. 复用同一命令替换不同样本，分别覆盖已开票、未缴费、限额超限、幂等命中、原始单账单直接部分开票等场景。
+3. 将正常业务场景样本汇总到 `T061 / SC-002` 表，将规则拦截场景单独归类，不计入 SC-002 分母。
+
+```bash
+curl -X POST "${BASE_URL}/business/invoice/apply" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"chargeIds":[${CHARGE_ID}],"custId":${CUST_ID},"invoiceType":"ELECTRONIC","invoiceTitle":"福建水务测试客户","sourceChannel":"COUNTER"}'
+```
+
+#### T062：回写成功率采样顺序
+
+1. 先对已申请样本执行 `/business/invoice/query`，确认当前状态与 `sysRequestNo`。
+2. 对已拿到税控结果的样本执行 `/business/invoice/write-back`，分别覆盖成功回写、失败回写、成功终态保护三类场景。
+3. 若存在查询兜底场景，再执行 `/business/invoice/query/compensate`，补录补偿查询命中情况与失败分类。
+
+```bash
+curl -X POST "${BASE_URL}/business/invoice/query" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"applicationNo":"${APPLICATION_NO}","querySource":"MANUAL"}'
+
+curl -X POST "${BASE_URL}/business/invoice/write-back" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"applicationNo":"${APPLICATION_NO}","invoiceStatus":"SUCCESS"}'
+
+curl -X POST "${BASE_URL}/business/invoice/query/compensate" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"applicationNo":"${APPLICATION_NO}","querySource":"AUTO_COMPENSATE"}'
+```
+
+#### T063：客户侧查询 / 下载 / 推送采样顺序
+
+1. 先执行 `/business/invoice/customer/query`，确认客户归属与发票定位键可用。
+2. 对满足 `SUCCESS + fileUrl` 的样本执行 `/business/invoice/customer/download`。
+3. 在同一批样本上继续执行 `/business/invoice/customer/push`，按 `EMAIL`、`SMS` 等渠道分别统计。
+
+```bash
+curl -X POST "${BASE_URL}/business/invoice/customer/query" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"custId":${CUST_ID},"invoiceId":${INVOICE_ID}}'
+
+curl -X POST "${BASE_URL}/business/invoice/customer/download" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"custId":${CUST_ID},"invoiceId":${INVOICE_ID}}'
+
+curl -X POST "${BASE_URL}/business/invoice/customer/push" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"custId":${CUST_ID},"invoiceId":${INVOICE_ID},"pushChannel":"EMAIL","pushEmail":"test@example.com"}'
+```
+
+#### T055：运行态日志抽样顺序
+
+1. 任选一组完整样本，按“申请 → 查询/补偿 → 回写 → 客户查询/下载/推送 → 作废或红冲”顺序执行。
+2. 每执行一步立即在日志系统或数据库中抽取对应操作日志，核对操作人、客户标识、状态前后值与日志摘要。
+3. 作废与红冲建议分别至少准备 1 条独立成功样本，避免同一张票重复处理导致统计混淆。
+
+```bash
+curl -X POST "${BASE_URL}/business/invoice/invalidate" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"invoiceId":${INVOICE_ID},"invalidReason":"测试作废样本"}'
+
+curl -X POST "${BASE_URL}/business/invoice/red-ink" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"invoiceId":${INVOICE_ID},"redInkReason":"测试红冲样本"}'
+```
+
+- **日志抽样补充要求**：若运行态日志需经 Kibana、数据库表或应用日志文件检索取得，应在样本记录中额外注明检索入口、检索条件与截图/导出附件位置。
+
+### 联调补录清单（按顺序执行）
+
+| 步骤 | 对应待办 | 执行动作 | 主要输入 | 预期产出 | 回填位置 |
+|------|------|------|------|------|------|
+| 1 | `T060`、`T061` | 准备正常样本与规则拦截样本，执行 `/business/invoice/apply` | `BASE_URL`、鉴权头、`custId`、`chargeIds`、账单分组清单 | 响应报文、耗时、`applicationNo`、成功/拦截结论 | `T060 / SC-001`、`T061 / SC-002` 模板 |
+| 2 | `T062` | 对步骤 1 成功样本执行 `/business/invoice/query`，确认当前状态与 `sysRequestNo` | `applicationNo` 或 `sysRequestNo` | 查询结果、受理号、当前状态 | `T062 / SC-003` 模板 |
+| 3 | `T062` | 执行 `/business/invoice/write-back`，覆盖成功、失败、成功终态保护样本 | `applicationNo` / `sysRequestNo`、`invoiceStatus` | 回写结果、失败分类、成功终态保护命中情况 | `T062 / SC-003` 模板 |
+| 4 | `T062` | 对兜底样本执行 `/business/invoice/query/compensate` | `applicationNo` / `sysRequestNo` | 补偿查询结果、失败分类、补偿是否命中 | `T062 / SC-003` 模板 |
+| 5 | `T063` | 执行 `/business/invoice/customer/query`，确认客户归属与发票定位键有效 | `custId`、`invoiceId` / `applicationNo` / `sysRequestNo` | 查询结果、客户归属校验结论 | `T063 / SC-004` 模板 |
+| 6 | `T063` | 对 `SUCCESS + fileUrl` 样本执行 `/business/invoice/customer/download` | `custId`、`invoiceId` | 下载结果、前置拦截/真实失败分类 | `T063 / SC-004` 模板 |
+| 7 | `T063` | 对同批样本执行 `/business/invoice/customer/push`，按渠道分别采样 | `custId`、`invoiceId`、`pushChannel` | 推送结果、渠道分类、失败原因 | `T063 / SC-004` 模板 |
+| 8 | `T055` | 基于已成功样本执行 `/business/invoice/invalidate` 与 `/business/invoice/red-ink` | `invoiceId`、作废/红冲原因 | 后处理结果、日志抽样、状态前后值 | `T055 / SC-005` 模板 |
+| 9 | `T055` | 从日志系统、数据库表或应用日志文件提取关键动作留痕 | 检索入口、检索条件、时间窗口 | 日志截图/导出件、操作人/客户/状态核对结果 | `T055 / SC-005` 模板 |
+
+- **执行顺序约束**：步骤 2 ~ 4 依赖步骤 1 至少生成一批成功申请样本；步骤 6 ~ 8 依赖样本已达到 `SUCCESS` 且可定位到目标发票。
+- **补录原则**：每完成一步就即时回填对应表格，不要等全部联调结束后再集中补录，避免申请单号、受理号、日志检索条件丢失。
+- **证据留存建议**：除表格外，建议同时保留请求报文、响应报文、日志截图和必要的数据库查询结果，统一按 `applicationNo` 或 `sysRequestNo` 归档。
+
+### 联调日报 / 回填模板
+
+#### 日报头模板
+
+| 字段 | 填写说明 |
+|------|------|
+| 联调日期 | 填写当天日期 |
+| 联调环境 | 如 SIT / UAT / 联调环境名称 |
+| 执行人 | 填写执行人 |
+| 服务版本 | 填写分支、构建号或部署批次 |
+| 网关地址 | 填写实际调用入口，若有前置网关前缀需写明 |
+| 鉴权方式 | 如 Bearer Token、租户头、会话信息 |
+| 样本范围 | 填写当日使用的账单、客户、发票样本范围 |
+
+#### 当日执行摘要模板
+
+| 对应待办 | 是否执行 | 样本量 | 成功样本 | 失败/拦截样本 | 产出附件 |
+|------|------|------:|------:|------:|------|
+| `T060` / SC-001 响应时延 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| `T061` / SC-002 申请通过率 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| `T062` / SC-003 回写成功率 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| `T063` / SC-004 客户侧消费成功率 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| `T055` / SC-005 日志抽样 | 待补 | 待补 | 待补 | 待补 | 待补 |
+
+#### 样本回填索引模板
+
+| 样本标识 | `applicationNo` | `sysRequestNo` | `invoiceId` | 对应步骤 | 回填表格位置 | 备注 |
+|------|------|------|------|------|------|------|
+| 样本 A | 待补 | 待补 | 待补 | 步骤 1 ~ 9（按实际填写） | `T060/T061/T062/T063/T055`（按实际填写） | 待补 |
+| 样本 B | 待补 | 待补 | 待补 | 待补 | 待补 | 待补 |
+
+#### 风险与阻塞模板
+
+| 分类 | 现象 | 影响待办 | 临时处理 | 后续动作 |
+|------|------|------|------|------|
+| 环境 | 待补 | 待补 | 待补 | 待补 |
+| 数据 | 待补 | 待补 | 待补 | 待补 |
+| 接口 | 待补 | 待补 | 待补 | 待补 |
+| 日志 | 待补 | 待补 | 待补 | 待补 |
+
+#### 当日结论模板
+
+- **已完成回填**：待补
+- **未完成原因**：待补
+- **是否影响 `Verification Pending` 状态**：待补
+- **次日建议动作**：待补
+
+- **使用说明**：建议每次联调结束后先填写本节，再同步更新前文 `T055`、`T060 ~ T063` 的正式统计表，避免日报与正式验证记录脱节。
+
+### 联调前置检查清单
+
+| 检查项 | 核对内容 | 当前状态 |
+|------|------|------|
+| 环境地址 | 已确认 `${BASE_URL}`、网关前缀、服务版本与部署批次 | 待补 |
+| 鉴权信息 | 已确认 Bearer Token、租户头、会话信息或其他鉴权方式 | 待补 |
+| 样本数据 | 已准备正常样本、规则拦截样本、成功发票样本、作废样本、红冲样本 | 待补 |
+| 主键映射 | 已确认 `custId`、`chargeIds`、`applicationNo`、`sysRequestNo`、`invoiceId` 的映射关系 | 待补 |
+| 日志入口 | 已确认 Kibana、数据库表或应用日志文件的检索入口 | 待补 |
+| 回填责任 | 已确认谁负责日报填写、谁负责正式表格回填、谁负责附件归档 | 待补 |
+| 归档路径 | 已确认请求报文、响应报文、截图与日志附件的归档位置 | 待补 |
+
+- **执行要求**：未完成上述检查前，不建议直接开始批量联调，避免后续出现样本无法回溯、日志无法检索或统计口径不一致的问题。
+- **建议时点**：每轮联调开始前先更新本清单；若环境、样本或鉴权方式发生变化，应重新复核并更新时间。
+
+### 最终联调执行顺序与完成判定清单
+
+| 顺序 | 对应待办 | 完成标志 | 可勾选条件 |
+|------|------|------|------|
+| 1 | `T060` | 已形成一批申请时延样本 | 已记录 `/business/invoice/apply` 的样本量、平均值、P95、最大值，并注明是否剔除 `SYS-008` 等待 |
+| 2 | `T061` | 已形成正常场景与拦截场景分组统计 | 已区分正常业务场景与规则拦截场景，且正常场景成功/失败统计可追溯到样本主键 |
+| 3 | `T062` | 已形成查询、回写、补偿查询三类结果统计 | 已记录回写请求总量、业务成功落账量、业务失败量、成功终态保护量，并保留失败分类 |
+| 4 | `T063` | 已形成客户查询、下载、推送三类统计 | 已分别记录查询、下载、推送样本量、成功数、失败/前置拦截分类，并保留渠道与定位键 |
+| 5 | `T055` | 已形成关键动作日志样本 | 已抽取申请、查询/补偿、回写、客户下载、客户推送、作废、红冲至少各 1 条日志样本，并能回扣动作矩阵 |
+
+#### 建议最终执行顺序
+
+1. 先完成 `T060`，确保申请入口、环境耗时与基础样本可用。
+2. 再完成 `T061`，把同批申请样本分成“正常业务场景 / 规则拦截场景”两组。
+3. 基于成功申请样本推进 `T062`，补齐查询、回写与补偿查询链路统计。
+4. 仅在样本达到 `SUCCESS + fileUrl` 后推进 `T063`，避免把前置条件不满足的样本误计为下载失败。
+5. 最后完成 `T055`，对上述链路中已成功执行的样本逐项抽取日志，形成最终运行态留痕证据。
+
+#### 单项完成判定模板
+
+| 待办 | 是否已拿到真实样本 | 是否已回填正式表格 | 是否已留存附件 | 是否满足勾选条件 | 备注 |
+|------|------|------|------|------|------|
+| `T060` | 待补 | 待补 | 待补 | 待补 | 待补 |
+| `T061` | 待补 | 待补 | 待补 | 待补 | 待补 |
+| `T062` | 待补 | 待补 | 待补 | 待补 | 待补 |
+| `T063` | 待补 | 待补 | 待补 | 待补 | 待补 |
+| `T055` | 待补 | 待补 | 待补 | 待补 | 待补 |
+
+- **勾选原则**：只有当“真实样本已拿到 + 正式统计表已回填 + 附件已留存”三项同时满足时，对应待办才建议从 `tasks.md` 标记为完成。
+- **收口顺序**：建议按 `T060 → T061 → T062 → T063 → T055` 顺序逐项关闭，避免后置任务缺少前置样本支撑。
+
+### 剩余工作摘要（可直接引用）
+
+- **当前状态**：REV-005 已完成 US1 ~ US4 的实现态闭环与文档侧验证准备，当前处于 `Verification Pending`，剩余工作全部集中在 `T055`、`T060 ~ T063` 的真实联调取证与结果回填。
+- **剩余待办**：
+  1. `T060`：补 `/business/invoice/apply` 的真实响应时延样本与统计结果。
+  2. `T061`：补正常业务场景与规则拦截场景的申请通过率统计。
+  3. `T062`：补查询、回写、补偿查询链路的成功率与失败分类统计。
+  4. `T063`：补客户查询、下载、推送三类动作的成功率与前置拦截分类。
+  5. `T055`：补申请、查询/补偿、回写、客户下载/推送、作废、红冲的运行态日志样本。
+- **完成条件**：上述待办均需满足“真实样本已拿到、正式统计表已回填、附件已留存”三项条件后，方可在 `tasks.md` 中关闭。
+- **建议对外口径**：**REV-005 当前已具备提测前文档与验证准备条件，剩余工作不在于设计或实现补充，而在于测试/联调环境下补齐运行态统计与日志证据。**
+
+## 4. US4 二期实现结论
+
+当前已在以下正式文档与实现文件中明确：

 - `docs/design/02_Detailed_Design/12_REV_Detailed.md`
 - `docs/design/03_Technical_Design/03_Interface_Design.md`
- `docs/design/00_Management/01_Project_Progress.md`
- `docs/design/00_Management/03_Task_Checklist.md`
+- `specs/002-rev005-invoice-flow/spec.md`
+- `specs/002-rev005-invoice-flow/plan.md`
+- `specs/002-rev005-invoice-flow/tasks.md`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceInvalidateReqVO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceRedInkReqVO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java`

-收口结论如下：
+当前结论如下：

-1. 一期交付范围为“后台申请 + 查询兜底 + 结果回写 + 账单关联 + 客户侧电子票消费”。
-2. 发票作废、红冲继续由 `SYS-008` 统一承接。
-3. 当前阶段仅保留 `INVALID`、`RED_INK` 状态与后续扩展入口，不视为本轮 backend 已交付能力。
-4. 后续若进入作废/红冲实现，应在既有状态模型和文档入口上继续扩展，不回退当前一期闭环边界。
+1. 发票作废、红冲仍由 `SYS-008` 统一承接税控侧处理。
+2. `SYS-002` 已补齐后台作废 `/business/invoice/invalidate` 与红冲 `/business/invoice/red-ink` 入口，并通过专门请求 VO 承接原因、备注与原发票代码/号码。
+3. 当前实现仅允许对 `SUCCESS` 发票发起作废或红冲；若传入 `originalInvoiceCode`、`originalInvoiceNumber`，必须与当前发票记录一致，重复处理会被拦截。
+4. `InvoiceDO` 与 `01_Database_Design.md` 已补齐作废原因/备注、红冲原因/备注、原发票代码/号码与 `postProcessSource` 等承接口径；service 会同步写入 `latestResult`、`latestError`、账单关联状态与操作日志。
+5. 当前剩余风险主要集中在物理表结构/DDL 来源未在仓库内定位、批量作废/红冲能力未覆盖，以及缺少端到端联调样本。

 ## 5. 当前已完成文件

@ -101,9 +530,11 @@
 - `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceApplyReqVO.java`
 - `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceApplyRespVO.java`
 - `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceCustomerQueryReqVO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceInvalidateReqVO.java`
 - `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoicePushReqVO.java`
 - `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceQueryReqVO.java`
 - `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceQueryRespVO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceRedInkReqVO.java`
 - `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceWriteBackReqVO.java`
 - `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java`
 - `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/mysql/invoice/InvoiceMapper.java`
@ -114,11 +545,28 @@

 1. `SC-001 ~ SC-005` 尚缺可重复执行的专项测量脚本或统计记录。
 2. 当前 `make validate-mermaid` 输出仅覆盖仓库现有扫描范围，若后续扩展更多图表文件，仍需复核目标文件是否全部纳入。
-3. backend 子仓库仍存在与本轮无关的未提交改动，后续继续提交时需避免混入。
-4. 作废/红冲当前仅完成边界收口，尚未进入下一轮 planning、tasks 与实现拆解。
+3. 当前仓库内尚未定位到与 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java` 当前模型对应的 `biz_invoice` 物理 DDL 或迁移脚本；已核查 `backend/sql`、Archive 数据库设计与 `sql/lhc_数据库设计.md`，现有同名 `biz_invoice` 更偏开票配置表，作废/红冲新增字段的物理落库仍需结合实际数据库变更链路确认。
+4. 作废/红冲当前以单笔后台入口为主，尚未覆盖批量后处理、`SYS-008` 端到端联调样本与自动化回归验证。

 ## 7. 下一步建议

 1. 若继续推进一期验收，优先补 `SC-001 ~ SC-005` 的专项统计与样本口径。
-2. 若继续推进功能，下一阶段建议进入“作废/红冲”专项 planning，而不是在本轮正常开票闭环上继续追加范围。
-3. 若准备提测，可直接引用本文件作为当前已完成验证与剩余风险摘要。\n
+2. 若继续推进 US4，优先确认 `biz_invoice` 物理 DDL/迁移脚本来源，并补批量作废/红冲与联调样本，而不是继续重复扩展已完成的请求对象或数据承接口径。
+3. 若准备提测或评审，可直接引用本文件作为当前已完成验证、US4 二期实现范围与剩余风险摘要。
+
+## 8. 当前交付摘要
+
+### 8.1 已完成交付
+
+1. REV-005 的 US1 ~ US4 已完成正式文档、spec/planning 产物与 backend 最小实现闭环，并已补齐最小编译、文档校验、链接校验与 Mermaid 校验证据。
+2. `spec.md`、`tasks.md`、`verification.md`、`01_Project_Progress.md`、`03_Task_Checklist.md` 当前已统一到“实现闭环基本完成、量化验收证据待补”的一致状态。
+3. 当前仓库已明确可直接用于评审/提测前范围说明的结论：正常开票闭环与作废/红冲最小入口已形成正式实现范围，SC-005 实现态日志追溯矩阵已补齐。
+
+### 8.2 当前未闭环事项
+
+1. `T055`、`T060`、`T061`、`T062`、`T063` 仍未完成，分别对应运行态日志抽样、SC-001 响应时延、SC-002 申请通过率、SC-003 回写成功率、SC-004 客户侧查询/下载/推送成功率等专项统计证据。
+2. `biz_invoice` 物理 DDL / migration 来源仍未在仓库中定位，US4 的物理落库链路、批量后处理与端到端联调样本仍需继续跟踪。
+
+### 8.3 建议引用口径
+
+- 若当前需要向评审或提测说明 REV-005 状态，建议统一表述为：**REV-005 已完成 US1 ~ US4 的实现态闭环与最小校验，当前处于 Verification Pending，剩余工作主要是补 SC-001 ~ SC-005 的运行态样本与专项统计证据。**