fujian_water_biz_doc/specs/002-rev005-invoice-flow/plan.md

# Implementation Plan: REV-005 发票业务流实现

**Branch**: `002-rev005-invoice-flow` | **Date**: 2026-03-16 | **Spec**: `/specs/002-rev005-invoice-flow/spec.md`
**Input**: Feature specification from `/specs/002-rev005-invoice-flow/spec.md`

## Summary

本轮围绕 `REV-005` 发票业务流补齐从已收费账单到电子发票结果落账的业务闭环，形成可直接指导 backend 实施与正式文档修订的 planning 产物。计划目标是在既有 `biz_invoice`、`biz_cust_invoice`、`biz_invoice_taxrate` 基础上，明确发票申请、后台批量/单笔开票、`SYS-008` 异步协同与查询兜底、结果回写、账单-发票关联、客户侧查询下载推送的实现口径。

本次计划输出以 spec 澄清结果为准：一期采用“后台开票 + 客户侧查询下载”模式；`SYS-008` 对接采用“异步申请 + 轮询查询兜底”；不支持原始单账单直接任意部分金额开票，如需多张发票沿用老系统拆账/分账后的账单分别开票；正式主文档需回写 `12_REV_Detailed.md`、`03_Interface_Design.md` 与 `01_Database_Design.md`，backend 侧则在现有 `InvoiceController.java`、`InvoiceServiceImpl.java` 基础上扩展业务接口与服务能力。

## Technical Context

**Primary Work Product**: REV-005 planning 设计产物，包括实施计划、研究结论、数据模型、接口合同与最小校验说明。
**Source of Truth Documents**:
- `specs/002-rev005-invoice-flow/spec.md`
- `.specify/memory/constitution.md`
- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
- `docs/design/03_Technical_Design/03_Interface_Design.md`
- `docs/design/03_Technical_Design/01_Database_Design.md`
**Reference Sources**:
- `docs/guides/BACKEND_CURRENT_STATUS.md`
- `docs/guides/BACKEND_TABLE_MAPPING.md`
- `docs/design/04_Appendix/Archive/02_Manuals/营收系统_用户操作手册.md`
- `docs/design/04_Appendix/Archive/02_Manuals/福建水投微网厅操作手册.md`
- `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md`
- `docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.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/service/invoice/InvoiceServiceImpl.java`
**Validation Commands**:
- `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md`
- `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md`
- `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md`
- `make check-links`
- `make validate-mermaid`
**Target Scope**:
- `REV-005` 正式详细设计补充
- `IF-REV-008`（后台发票申请/开具）与 `IF-CS-004`（客户侧查询下载）口径收敛
- 新增 `IF-REV-009` 发票结果查询/补偿查询口径
- `biz_invoice*`、`biz_cust_invoice`、账单-发票关联与历史关系快照的承接口径
- backend 发票业务 Service/Controller 扩展边界
**Project Type**: 文档治理仓库（同时为 backend 实施提供 planning 输入）
**Constraints**:
- 不新增平行正式主稿
- 不发明超出主文档与老系统交集的新业务规则
- Archive 仅作核对与追溯来源，不替代正式结论
- 一期默认后台开票，客户侧不直接申请开票
- 一期不支持原始单账单直接任意部分金额开票
- `SYS-008` 结果获取采用查询兜底，不假设回调可用
- 本轮 implement 先完成正常开票闭环收口，再在二期补齐作废/红冲的正式文档、backend 入口、状态流转与结果落账
- 仓库内引用保持相对路径口径
**Scale/Scope**: 跨文档 + backend 实施 planning，覆盖 1 个 feature spec、1 个 implementation plan、1 份 research、1 份 data-model、2 份 contracts、1 份 quickstart，并为后续 tasks/implement 提供输入。

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- [x] **主文档归属已确认**：本轮 planning 产物落在 `specs/002-rev005-invoice-flow/`，正式口径将回写既有 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md`，不新增平行正式稿。
- [x] **范围基线已确认**：`REV-005` 在 `12_REV_Detailed.md`、`03_Interface_Design.md`、旧系统操作手册、数据字典中均有明确发票管理/电子发票交集口径，可直接推进；原始单账单任意部分开票未作为一期主能力纳入。
- [x] **Archive 使用方式合规**：Archive 仅作为老系统能力、字段与菜单口径来源，正式结论仍以当前主文档与 spec 澄清结果为准。
- [x] **一致性影响已列出**：已识别 `IF-REV-008` / `IF-CS-004` / 发票查询补偿接口编号、`biz_invoice*` 承接口径、旧“回调”改为“查询兜底”、后台/客户侧入口边界等一致性项。
- [x] **校验与台账动作已规划**：已明确正式文档最小校验命令；plan 阶段仅生成 planning 产物，不强制更新 `01_Project_Progress.md` / `03_Task_Checklist.md`，待正式主文档修订或任务闭环后再回写。

### Post-Design Re-check

- [x] 设计产物保持“主文档修订 + backend 实施 planning”定位，没有绕开单一真源另写平行正式稿。
- [x] `data-model.md` 采用逻辑实体 + 现有物理承接 + 历史关系快照三层表达，没有把旧系统全部细表表述为当前已落地在线表。
- [x] `contracts/` 中接口合同统一回扣后台开票、客户侧查询下载、`SYS-008` 查询兜底与幂等回写口径。
- [x] `quickstart.md` 仅定义评审入口、最小校验与 backend 验证建议，不引入超范围部署/发布动作。
- [x] 结果获取方式统一为“异步申请 + 查询兜底”，不再保留与航信接口事实冲突的“直接回调”口径。

## Project Structure

### Documentation (this feature)

```text
specs/002-rev005-invoice-flow/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   ├── if-rev-008-invoice-application.md
│   └── if-rev-009-invoice-query.md
└── tasks.md
```

### Repository Touchpoints

```text
docs/design/
├── 00_Management/
│   ├── 01_Project_Progress.md
│   ├── 02_Delivery_Standards.md
│   └── 03_Task_Checklist.md
├── 02_Detailed_Design/
│   └── 12_REV_Detailed.md
├── 03_Technical_Design/
│   ├── 01_Database_Design.md
│   └── 03_Interface_Design.md
└── 04_Appendix/Archive/

backend/sw-business/sw-business-server/
├── src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java
└── src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java
```

**Structure Decision**:
- `specs/002-rev005-invoice-flow/spec.md`：作为 REV-005 范围、澄清结果与验收边界总源。
- `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/quickstart.md`：提供文档评审、最小校验与 backend 验证入口。
- `docs/design/02_Detailed_Design/12_REV_Detailed.md`：后续正式补充 REV-005 业务规则、状态流转和旧系统对齐说明。
- `docs/design/03_Technical_Design/03_Interface_Design.md`：后续正式补充 `IF-REV-008`、`IF-REV-009` 与客户侧查询下载口径。
- `docs/design/03_Technical_Design/01_Database_Design.md`：后续正式补充 `biz_invoice*`、账单-发票关联快照与历史关系承接口径。
- `InvoiceController.java` / `InvoiceServiceImpl.java`：后续实现阶段扩展后台申请、查询、回写与批量开票能力，不再仅限配置 CRUD。

## Phase 0 Research Summary

1. 一期采用“后台开票 + 客户侧查询下载推送”的入口策略，后台营业收费员/财务人员负责申请和开具，客户侧不直接发起开票申请。
2. `SYS-008` 对接采用“异步申请 + 轮询查询兜底”模式，适配航信等不提供稳定回调的开票服务现状。
3. 一期不支持原始单账单直接任意部分金额开票；如需多张发票，沿用老系统拆账/分账后分别开票的口径，并保留批量开票能力。
4. 当前 backend 已有 `InvoiceController.java`、`InvoiceServiceImpl.java`，但实际只覆盖开票配置/模板 CRUD，未实现发票申请、查询、回写、账单关联闭环。
5. 在线主模型以 `biz_invoice`、`biz_invoice_taxrate`、`biz_cust_invoice` 为主承接，旧“营业账开票表/发票明细表/开票配置快照”按历史关系快照或辅助映射处理，不机械复制旧表族。
6. 正式文档应同时对齐当前主文档、旧系统操作手册与数据字典，避免只保留“申请 + 回写”而遗漏老系统已有的查询、下载、批量开票与结果导出语义。

## Phase 1 Design Outputs

### Data Model
- `data-model.md` 已定义：
  - `InvoiceApplication`
  - `InvoiceRecord`
  - `ChargeInvoiceRelation`
  - `InvoiceQueryTask`
  - `InvoiceResultWriteBack`
- 其中明确区分逻辑实体、现有在线主表承接与历史关系快照，兼容后续合并开票/拆账开票扩展。

### Contracts
- `contracts/if-rev-008-invoice-application.md`
  - 固化后台发票申请/批量开票的请求字段、响应字段、校验规则与幂等口径。
- `contracts/if-rev-009-invoice-query.md`
  - 固化查询兜底、结果补偿查询、客户侧查询下载的请求/响应与状态表达。

### Quickstart
- `quickstart.md` 已给出：
  - 范围校验
  - 老系统对齐校验
  - 文档最小校验命令
  - backend 实施前的现状核对点
  - 后续 tasks/implement 的最小验收入口

### Agent Context
- 仓库内未找到 `.specify/scripts/**/update-agent-context.sh`；本轮不执行自动 agent context 更新脚本。
- 后续若补齐该脚本，可按仓库统一约定再执行一次上下文同步。

## Implementation Strategy for Next Phase

下一阶段 `/speckit.tasks` 应按以下顺序拆解：

1. **正式文档收敛任务**
   - 更新 `12_REV_Detailed.md` 中 REV-005 场景、状态机、入口边界、老系统对齐说明
   - 更新 `03_Interface_Design.md` 中 `IF-REV-008`、`IF-REV-009` 与客户侧查询下载口径
   - 更新 `01_Database_Design.md` 中 `biz_invoice*`、账单-发票关联快照和查询补偿字段说明
2. **backend 基础扩展任务**
   - 为现有 `InvoiceController.java` / `InvoiceServiceImpl.java` 增加后台申请、查询、结果写回、批量开票能力
   - 增加与账单、客户开票信息、税率配置的校验联动
3. **`SYS-008` 协同与补偿任务**
   - 发票申请协同调用
   - 查询兜底任务与幂等回写
   - 失败原因与异常核查留痕
4. **客户侧结果消费任务**
   - 查询已开发票状态
   - 下载/推送电子发票
   - 与后台开票状态保持一致
5. **校验与闭环任务**
   - 文档 `make validate-file` / `make check-links` / `make validate-mermaid`
   - backend 核心流程验证
   - 必要时回写 `01_Project_Progress.md` 与 `03_Task_Checklist.md`

## Complexity Tracking

本计划未发生 Constitution 违规项，无需豁免说明。