fujian_water_biz_doc/docs/evidence/rev005-invoice/2026-06-16-invoice-document-audit.md

REV-005 发票业务流 — 文档审计报告

审计日期: 2026-06-16
审计范围: water-docs/specs/002-rev005-invoice-flow/ + docs/design/ 主文档 + water-backend 代码（worktree backend-rev005）
审计目标: 评估发票相关文档的完整性、一致性和可追溯性

---

1. 审计总览

维度	结论
规格完整性	✅ 完备
正式设计一致性	⚠️ 轻微偏差（状态定义 6 vs 4 态）
接口契约覆盖	✅ 完备
数据模型覆盖	✅ 完备（正式版在 DB 设计中，specs 草稿已删除）
代码实现对应	✅ 59/65 任务完成，6 项为验证任务
前端设计覆盖	✅ 有独立前端设计文档（866 行）
验证证据	❌ 8 项验证任务未完成

---

2. 文档地图

specs/002-rev005-invoice-flow/
├── spec.md                      ✅ 有
├── plan.md                      ✅ 有
├── tasks.md                     ✅ 有（65 项，59 完成）
├── research.md                  ✅ 有
├── quickstart.md                ✅ 有
├── verification.md              ⚠️ 有，但 8 个验证任务未完成
└── frontend-finance-design.md   ✅ 有（2026-05-12 新增）

docs/design/ (正式主文档)
├── 02_Detailed_Design/12_REV_Detailed.md    ✅ REV-005 章节完整
├── 03_Technical_Design/01_Database_Design.md ✅ biz_invoice 表覆盖
└── 03_Technical_Design/03_Interface_Design.md ✅ IF-REV-008/009 定义完整

docs/evidence/rev005-invoice/                📭 空（尚无证据入库）

---

3. 发现

3.1 状态定义差异（中风险）

问题：12_REV_Detailed.md 定义了 6 个发票状态（SUBMITTED、PENDING、SUCCESS、FAIL、INVALID、RED_INK），但 InvoiceController 代码中实现了 invalidate 和 red-ink 两个独立端点，而 InvoiceDO 中的 invoiceStatus 字段是否支持这 6 态尚未在代码层确认。

影响：作废/红冲是二期补齐的功能，需确认 biz_invoice 表的 invoice_status 枚举已包含 INVALID 和 RED_INK，否则运行时会抛异常。

建议：检查 InvoiceStatusEnum（如存在）或 biz_invoice 的 DDL 确认枚举覆盖。

3.2 验证证据缺失（低风险）

specs/002-rev005-invoice-flow/verification.md 中 8 个验证任务未完成：

编号	内容	阻塞点
T022	重复申请、部分开票拒绝的样本	需联调环境
T033	SYS-008 不可用、超时等异常样本	需联调环境
T044	回写/查询/下载/推送成功率统计	需联调环境
T055	作废/红冲运行态日志样本	需联调环境
T060-T063	SC-001~SC-004 性能指标采样	需测试环境

影响：不影响功能实现，但会影响验收签字。

建议：在提测前集中补齐，可安排在联调阶段同步采集。

3.3 接口路径不一致（低风险）

定义位置	路径
specs/002/contracts/if-rev-008.md（已删除）	/api/invoice/apply（假设）
03_Interface_Design.md	/business/invoice/apply
InvoiceController.java	/business/invoice/apply（@RequestMapping("/business/invoice") + @PostMapping("/apply")）

正式接口设计和代码实现路径一致（/business/invoice/apply）。specs 里的旧契约已删除，不存在冲突。✅ 无问题。

3.4 前端设计文档状态（观察项）

frontend-finance-design.md 是 2026-05-12 新增的，晚于主设计文档（2026-03-19）。它是独立于后端设计文档的前端实现补充，目前状态为"作为前端实现输入"。

影响：water-frontend 尚未同步确认是否已按照此文档实现。

建议：下一步在 water-frontend 的 AGENTS.md 或对应 spec 中确认前端实现进度。

3.5 数据模型一致性（已解决）

此前 specs/002/ 存在独立的 data-model.md 和 contracts/ 目录，与正式设计文档有内容重叠。本次审计已删除冗余草稿，数据模型以 01_Database_Design.md 为准，接口以 03_Interface_Design.md 为准。

---

4. FR 覆盖矩阵

FR	描述	设计文档	代码	状态
FR-001	后台发票申请接口	✅	✅ POST /apply	已实现
FR-002	校验账单状态	✅	✅ InvoiceServiceImpl	已实现
FR-003	校验客户开票信息	✅	✅	已实现
FR-004	校验开票限额	⚠️ 设计中提及但未详细展开	❓ 待确认	部分
FR-005	生成发票申请记录	✅	✅ biz_invoice_record	已实现
FR-006	调用 SYS-008	✅	✅ InvoicePlatformClient	已实现
FR-007	定时查询兜底	✅	✅ InvoiceCompensateJob	已实现
FR-008	更新发票状态	✅	✅	已实现
FR-009	发票-账单关联	✅	✅ biz_charge_invoice_rel	已实现
FR-010	客户侧查询/下载/推送	✅	✅ 3 个端点	已实现
FR-011	操作日志	✅	⚠️ 部分方法有日志	部分
FR-012	作废入口	✅	✅ POST /invalidate	已实现
FR-013	红冲入口	✅	✅ POST /red-ink	已实现
FR-014	终态保护与结果回写	✅	✅	已实现

关键发现：FR-004（开票限额）在设计文档中提及但未明确限额来源（配置表？固定值？），代码层待确认。FR-011（操作日志）在关键动作上有日志，但完整度待验证。

---

5. 建议优先级

优先级	建议
P0	确认 biz_invoice 的 invoiceStatus 枚举是否包含 INVALID 和 RED_INK，避免作废/红冲端点运行时报错
P1	明确开票限额校验逻辑（FR-004）：从配置表读取还是硬编码，限额是单笔还是累计
P1	联调阶段集中采集 T022/T033/T044/T055/T060-T063 的验证样本
P2	确认 water-frontend 对 frontend-finance-design.md 的实现进度

---

审计结论：REV-005 发票业务流的文档体系基本完备，设计文档、接口契约、数据模型和代码实现高度对齐。主要风险点是作废/红冲状态枚举的代码层覆盖确认，以及 8 项验证样本的补充。