tangweijie/fujian_water_biz_doc
1
0
Fork 0
Code Issues Pull Requests 12 Actions Packages Projects Releases 1 Wiki Activity
fujian_water_biz_doc/specs/002-rev005-invoice-flow/verification.md
tangweijie 91f37d6622 docs: 收口 REV-005 US4 边界与验证记录 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-17 10:22:56 +08:00

7.8 KiB
Raw Blame History

REV-005 验证记录

1. 验证范围

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

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

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

2. 已执行验证命令与结果

类别 命令 结果 说明
文档单文件校验 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 check-links 通过 当前链接检查输出为“所有链接检查通过”
Mermaid 语法校验 make validate-mermaid 通过 当前 Mermaid 验证输出为“所有 mermaid 图表语法验证通过”

3. Success Criteria 对照

SC-001 发票申请接口响应时间 < 500ms（不包含外部服务调用）

  • 当前状态：待补充专项验证
  • 现有证据：backend 最小编译通过，后台申请接口与校验链路已实现
  • 缺口说明：尚未执行接口响应时延采样，也未沉淀固定样本、环境与统计结果
  • 后续建议：在可用测试环境中对 /admin-api/revenue/invoice/apply 执行最小样本压测或定点采样，至少记录样本量、平均值、P95、排除外部调用口径

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

  • 当前状态：待补充样本统计
  • 现有证据：已实现账单收费状态、开票状态、客户开票信息、税率配置、开票限额、幂等控制等校验规则
  • 缺口说明：尚未基于真实或模拟样本形成“正常场景通过率”统计
  • 后续建议：准备覆盖正常账单、已开票账单、未缴费账单、限额超限账单等样本集，按样本分组输出通过/拦截统计

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

  • 当前状态：待补充样本统计
  • 现有证据：已实现结果回写、成功终态保护、账单状态联动、失败原因留痕
  • 缺口说明：尚未基于批量样本统计回写成功率
  • 后续建议：在联调或测试环境中按申请单号、受理号建立样本集，统计回写请求总量、成功量、失败量与失败原因分类

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

  • 当前状态：待补充样本统计
  • 现有证据：已实现仅 SUCCESS + fileUrl 可下载/推送的前置校验，客户归属校验与推送状态回写已落地
  • 缺口说明：尚未形成客户侧下载成功率样本统计
  • 后续建议：在具备有效电子票文件地址的样本下，统计查询、下载、推送三类动作成功率，并区分“无权限”“无文件”“非成功终态”等拦截原因

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

  • 当前状态：部分满足，待补充专项核对
  • 现有证据：申请、查询补偿、结果回写、客户侧下载/推送等关键动作已在当前实现中补充操作留痕
  • 缺口说明：尚未形成“关键动作清单 ↔ 日志写入点”逐项对照表
  • 后续建议：补一份日志追溯矩阵，至少覆盖申请、调用、查询、回写、下载、推送六类动作

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

收口结论如下：

  1. 一期交付范围为“后台申请 + 查询兜底 + 结果回写 + 账单关联 + 客户侧电子票消费”。
  2. 发票作废、红冲继续由 SYS-008 统一承接。
  3. 当前阶段仅保留 INVALID、RED_INK 状态与后续扩展入口，不视为本轮 backend 已交付能力。
  4. 后续若进入作废/红冲实现，应在既有状态模型和文档入口上继续扩展，不回退当前一期闭环边界。

5. 当前已完成文件

正式文档

  • docs/design/02_Detailed_Design/12_REV_Detailed.md
  • docs/design/03_Technical_Design/01_Database_Design.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

spec/planning 产物

  • specs/002-rev005-invoice-flow/spec.md
  • specs/002-rev005-invoice-flow/plan.md
  • specs/002-rev005-invoice-flow/research.md
  • specs/002-rev005-invoice-flow/data-model.md
  • specs/002-rev005-invoice-flow/contracts/if-rev-008-invoice-application.md
  • specs/002-rev005-invoice-flow/contracts/if-rev-009-invoice-query.md
  • specs/002-rev005-invoice-flow/tasks.md
  • specs/002-rev005-invoice-flow/verification.md

backend 相关实现

  • 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/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/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/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
  • 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

6. 剩余风险

  1. SC-001 ~ SC-005 尚缺可重复执行的专项测量脚本或统计记录。
  2. 当前 make validate-mermaid 输出仅覆盖仓库现有扫描范围，若后续扩展更多图表文件，仍需复核目标文件是否全部纳入。
  3. backend 子仓库仍存在与本轮无关的未提交改动，后续继续提交时需避免混入。
  4. 作废/红冲当前仅完成边界收口，尚未进入下一轮 planning、tasks 与实现拆解。

7. 下一步建议

  1. 若继续推进一期验收，优先补 SC-001 ~ SC-005 的专项统计与样本口径。
  2. 若继续推进功能，下一阶段建议进入“作废/红冲”专项 planning，而不是在本轮正常开票闭环上继续追加范围。
  3. 若准备提测，可直接引用本文件作为当前已完成验证与剩余风险摘要。\n