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/plan.md
tangweijie d8b2416f12 docs: 补齐 REV-005 作废红冲设计与任务 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-18 12:36:50 +08:00

12 KiB
Raw Blame History

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.

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

Post-Design Re-check

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

Project Structure

Documentation (this feature)

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

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 违规项，无需豁免说明。