tangweijie
3eccab2cf9
1. AGENTS.md 更新 - water-docs: 新增 specs/ 与 docs/design/ 生命周期规则章节 - water-backend: 更新协作引用（建设期/建成后、evidence 模块化） 2. specs/ 重复合并 - 006-reminder-event-design 合并入 003-rev006-reminder-event-design - 001-rev004-accounting 删除冗余 data-model.md + contracts/ - 002-rev005-invoice-flow 删除冗余 data-model.md + contracts/ 3. evidence 按模块归档 - 35 个 REV-004 文件归入 evidence/rev004-accounting/ - 7 个通用 bugfix 文件归入 evidence/bugfix/ 和 bugfix/frontend/ - 新建 rev005-invoice/、rev006-reminder/、rev007-statistics/ 目录 4. guides/ 清理 - 14 个 REV004_*.md 移入 evidence/rev004-accounting/ 5. 遗留文件处理 - docs/research/ 归档到 Archive/06_Migration_Plans/ - backend-check detached worktrees 清理 6. 交叉引用修复 - 006-reminder-event-design → 003-rev006-reminder-event-design - docs/guides/REV004_ → docs/evidence/rev004-accounting/REV004_ 7. DB 设计文档修正（01_Database_Design.md） - biz_invoice 明确为开票配置表，非发票记录表 - 新增 biz_invoice_record 为发票申请/结果主表 - 新增 biz_charge_invoice_rel 账单-发票关联说明 - REV-005 承接口径表名全部修正 8. 发票审计证据 - 新增 evidence/rev005-invoice/2026-06-16-invoice-document-audit.md
130 lines
6.2 KiB
Markdown
130 lines
6.2 KiB
Markdown
# 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 项验证样本的补充。
|