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

21 KiB
Raw Blame History

Tasks: REV-005 发票业务流实现

Input: Design documents from /specs/002-rev005-invoice-flow/ Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/if-rev-008-invoice-application.md, contracts/if-rev-009-invoice-query.md, quickstart.md

Validation: 正式文档修改必须执行对应 make validate-file；涉及跨文档引用执行 make check-links；涉及 Mermaid/时序图执行 make validate-mermaid；backend 实现阶段需补充最小编译或等价流程验证，并将结果沉淀到 specs/002-rev005-invoice-flow/verification.md。

Current Calibration: 当前分支不满足 .specify/scripts/bash/check-prerequisites.sh 的 feature-branch 命名要求，因此本文件基于现有 spec.md、plan.md、research.md、data-model.md、contracts/、quickstart.md 手工重建。[x] 表示仓库内已有实现或证据，[ ] 表示仍待补齐的收口任务。

Organization: 任务按用户故事分组，确保每个故事都可以独立实现、独立验证、独立评审；Final Phase 仅保留跨故事收口事项。

Format: [ID] [P?] [Story] Description

  • [P]: 可并行执行（不同文件、无未完成依赖）
  • [Story]: 所属用户故事（[US1]、[US2]、[US3]、[US4]）
  • 每条任务都包含明确文件路径，便于直接执行

Path Conventions

  • 正式设计文档：docs/design/02_Detailed_Design/、docs/design/03_Technical_Design/
  • 管理台账：docs/design/00_Management/
  • planning 产物：specs/002-rev005-invoice-flow/
  • backend 发票模块：backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/

Phase 1: Scope & Source Confirmation (Shared Foundation)

Purpose: 确认本轮单一真源、影响范围与 backend 触点，避免后续任务偏离已收敛口径。

  • T001 确认 specs/002-rev005-invoice-flow/spec.md、plan.md、research.md、data-model.md、contracts/if-rev-008-invoice-application.md、contracts/if-rev-009-invoice-query.md、quickstart.md 作为 REV-005 任务拆解直接输入
  • T002 确认 docs/design/00_Management/01_Project_Progress.md、docs/design/00_Management/02_Delivery_Standards.md、docs/design/00_Management/03_Task_Checklist.md 与 .specify/memory/constitution.md 作为治理约束输入
  • T003 [P] 确认正式目标文档 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 的 REV-005 章节为主落点
  • T004 [P] 确认 backend 主触点 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java、service/invoice/InvoiceService.java、service/invoice/InvoiceServiceImpl.java、dal/dataobject/invoice/InvoiceDO.java、dal/mysql/invoice/InvoiceMapper.java

Phase 2: Foundational (Blocking Prerequisites)

Purpose: 先统一跨故事共享的状态、接口、数据承接和校验输出口径。

  • T005 对齐 specs/002-rev005-invoice-flow/spec.md、plan.md、verification.md 与 docs/design/02_Detailed_Design/12_REV_Detailed.md 中的共享状态口径 SUBMITTED/PENDING/SUCCESS/FAIL/INVALID/RED_INK
  • T006 对齐 specs/002-rev005-invoice-flow/contracts/if-rev-008-invoice-application.md、contracts/if-rev-009-invoice-query.md 与 docs/design/03_Technical_Design/03_Interface_Design.md 中 IF-REV-008、IF-REV-009、客户侧消费边界的接口职责
  • T007 对齐 specs/002-rev005-invoice-flow/data-model.md、docs/design/03_Technical_Design/01_Database_Design.md、backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java、dal/mysql/invoice/InvoiceMapper.java 的共享数据承接口径
  • T008 对齐 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java、service/invoice/InvoiceService.java、service/invoice/InvoiceServiceImpl.java 的共享路由和服务骨架
  • T009 [P] 对齐 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceApplyReqVO.java、InvoiceApplyRespVO.java、InvoiceQueryReqVO.java、InvoiceQueryRespVO.java、InvoiceWriteBackReqVO.java、InvoiceCustomerQueryReqVO.java、InvoicePushReqVO.java 的公共请求/响应承接
  • T010 [P] 核对 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/custinvoice/CustInvoiceController.java、service/custinvoice/CustInvoiceServiceImpl.java、controller/admin/invoicetaxrate/InvoiceTaxrateController.java、service/invoicetaxrate/InvoiceTaxrateServiceImpl.java 的客户开票信息与税率依赖
  • T011 对齐 specs/002-rev005-invoice-flow/verification.md、docs/design/00_Management/01_Project_Progress.md、docs/design/00_Management/03_Task_Checklist.md 的校验沉淀和台账回写出口

Phase 3: User Story 1 - 发票申请与校验 (Priority: P1) 🎯 MVP

Goal: 实现后台单笔/批量发票申请入口，完成账单状态、客户开票信息、税率和限额校验，并生成发票申请记录。

Independent Test: 后台提交已收费未开票账单时能生成申请单号；未缴费、已开票、原始单账单直接部分开票等场景被正确拦截；正式文档与接口合同保持一致。

Implementation for User Story 1

  • T012 [US1] 更新 docs/design/02_Detailed_Design/12_REV_Detailed.md 中 REV-005 的后台申请入口、校验规则、批量开票和“禁止原始单账单直接任意部分开票”说明
  • T013 [US1] 更新 specs/002-rev005-invoice-flow/contracts/if-rev-008-invoice-application.md 中后台申请的请求字段、响应字段、幂等口径和失败提示
  • T014 [US1] 更新 docs/design/03_Technical_Design/03_Interface_Design.md 中 IF-REV-008 的后台申请/批量开票接口定义
  • T015 [US1] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java 增加后台发票申请入口
  • T016 [US1] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java 与 service/invoice/InvoiceServiceImpl.java 实现申请单号生成、账单/客户/税率校验和申请记录落库
  • T017 [P] [US1] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceApplyReqVO.java 与 InvoiceApplyRespVO.java 承接 chargeIds、custId、invoiceType、invoiceTitle、taxNo、email、mobile、sourceChannel、remark
  • T018 [P] [US1] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java 与 dal/mysql/invoice/InvoiceMapper.java 承接 applicationNo、申请状态、受理号等字段映射
  • T019 [US1] 在 specs/002-rev005-invoice-flow/verification.md 记录 docs/design/02_Detailed_Design/12_REV_Detailed.md 与 docs/design/03_Technical_Design/03_Interface_Design.md 的 make validate-file 校验结果，固化申请链路文档证据
  • T020 [US1] 在 specs/002-rev005-invoice-flow/verification.md 记录 backend/sw-business/sw-business-server/pom.xml 范围内的最小编译结果，固化申请链路代码证据
  • T021 [US1] 更新 docs/design/00_Management/01_Project_Progress.md 与 docs/design/00_Management/03_Task_Checklist.md 同步 US1 收口结果
  • T022 [US1] 在 specs/002-rev005-invoice-flow/verification.md 补充“重复申请”“开票过程中账单状态变化”“原始单账单直接部分开票被拒绝”的样本记录与结论

Checkpoint: 后台申请与校验链路可独立评审，IF-REV-008 与 REV-005 详细设计保持一致。

Phase 4: User Story 2 - 调用 SYS-008 开票并查询兜底 (Priority: P1)

Goal: 实现提交开票申请后的异步协同、受理号记录、定时/主动查询兜底，并保证成功状态不被后续失败结果覆盖。

Independent Test: 发票申请成功后生成受理号与查询上下文；查询接口可按申请单号/受理号返回结果；查询异常不会覆盖既有成功状态。

Implementation for User Story 2

  • T023 [US2] 更新 docs/design/02_Detailed_Design/12_REV_Detailed.md 中 REV-005 的 SYS-008 异步协同、查询补偿、终态保护和异常核查流程
  • T024 [US2] 更新 specs/002-rev005-invoice-flow/contracts/if-rev-009-invoice-query.md 中后台查询、系统补偿查询和客户侧消费前置规则
  • T025 [US2] 更新 docs/design/03_Technical_Design/03_Interface_Design.md 中 IF-REV-009 的查询与补偿查询接口定义
  • T026 [US2] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java 增加后台查询与补偿查询入口
  • T027 [US2] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java 与 service/invoice/InvoiceServiceImpl.java 实现 SYS-008 申请提交、受理号记录和按申请单号/受理号查询
  • T028 [P] [US2] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceQueryReqVO.java 与 InvoiceQueryRespVO.java 承接 applicationNo、sysRequestNo、querySource
  • T029 [P] [US2] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java 与 dal/mysql/invoice/InvoiceMapper.java 承接 lastTryTime、nextTryTime、tryCount、latestResult、latestError
  • T030 [US2] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java 实现成功终态保护和查询来源留痕
  • T031 [US2] 在 specs/002-rev005-invoice-flow/verification.md 记录 docs/design/02_Detailed_Design/12_REV_Detailed.md、docs/design/03_Technical_Design/03_Interface_Design.md 与 backend/sw-business/sw-business-server/pom.xml 的查询链路校验结果
  • T032 [US2] 更新 docs/design/00_Management/01_Project_Progress.md 与 docs/design/00_Management/03_Task_Checklist.md 同步 US2 收口结果
  • T033 [US2] 在 specs/002-rev005-invoice-flow/verification.md 补充 SYS-008 不可用、受理超时、补偿查询重试等异常样本与结论

Checkpoint: SYS-008 异步协同与查询兜底链路可独立演示，IF-REV-009 口径已稳定。

Phase 5: User Story 3 - 结果回写、账单关联与客户侧消费 (Priority: P2)

Goal: 实现开票结果回写、账单-发票关联状态更新，以及客户侧查看/下载/推送已开具电子发票。

Independent Test: 开票成功后账单与发票建立关联；客户侧仅能查看属于当前客户且已开具的电子发票；下载/推送前必须校验 SUCCESS + fileUrl。

Implementation for User Story 3

  • T034 [US3] 更新 docs/design/02_Detailed_Design/12_REV_Detailed.md 中 REV-005 的结果回写、账单关联、客户侧查看/下载/推送规则
  • T035 [US3] 更新 docs/design/03_Technical_Design/01_Database_Design.md 中 biz_invoice、账单-发票关系快照、客户查询身份与操作留痕承接口径
  • T036 [US3] 更新 docs/design/03_Technical_Design/03_Interface_Design.md 中客户侧查看、下载、推送电子发票的请求/响应约束
  • T037 [US3] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java 增加结果回写、客户侧查询、下载、推送接口
  • T038 [US3] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java 与 service/invoice/InvoiceServiceImpl.java 实现结果回写、账单关联和客户侧消费逻辑
  • T039 [P] [US3] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceWriteBackReqVO.java、InvoiceCustomerQueryReqVO.java、InvoicePushReqVO.java 承接回写与客户侧消费字段
  • T040 [P] [US3] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java 与 dal/mysql/invoice/InvoiceMapper.java 承接 invoiceCode、invoiceNumber、fileUrl、pushStatus、关联状态字段
  • T041 [US3] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java 实现客户归属校验和 SUCCESS + fileUrl 前置校验
  • T042 [US3] 在 specs/002-rev005-invoice-flow/verification.md 记录 docs/design/03_Technical_Design/01_Database_Design.md、docs/design/03_Technical_Design/03_Interface_Design.md 与 backend/sw-business/sw-business-server/pom.xml 的结果回写/客户消费链路校验结果
  • T043 [US3] 更新 docs/design/00_Management/01_Project_Progress.md 与 docs/design/00_Management/03_Task_Checklist.md 同步 US3 收口结果
  • T044 [US3] 在 specs/002-rev005-invoice-flow/verification.md 补充 SC-003 与 SC-004 所需的回写、查询、下载、推送样本统计和结论

Checkpoint: 发票结果回写、账单关联和客户侧电子票消费链路可以独立评审并验证。

Phase 6: User Story 4 - 发票作废与红冲 (Priority: P3)

Goal: 在一期正常开票闭环基础上，补齐后台发票作废与红冲的正式文档、接口入口、状态校验、SYS-008 协同、查询补偿与结果落账能力。

Independent Test: 后台可对满足条件的 SUCCESS 发票发起作废或红冲；接口、详细设计与 backend 实现口径一致；最小编译与文档校验通过。

Implementation for User Story 4

  • T045 [US4] 更新 specs/002-rev005-invoice-flow/spec.md 与 specs/002-rev005-invoice-flow/plan.md，将作废/红冲从“后续预留”提升为当前 REV-005 二期范围
  • T046 [US4] 更新 docs/design/02_Detailed_Design/12_REV_Detailed.md 明确作废与红冲的触发入口、状态流转、原票约束、账单联动与日志要求
  • T047 [US4] 更新 docs/design/03_Technical_Design/03_Interface_Design.md 明确后台作废/红冲接口、请求响应字段、查询补偿与客户侧消费边界
  • T048 [US4] 更新 docs/design/03_Technical_Design/01_Database_Design.md 标注作废/红冲所需承接字段、原票关联与失败原因口径
  • T049 [US4] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java 增加后台作废与红冲接口
  • T050 [US4] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java 与 service/invoice/InvoiceServiceImpl.java 实现作废、红冲、原票校验、查询补偿与日志留痕
  • T051 [P] [US4] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceInvalidateReqVO.java 与 InvoiceRedInkReqVO.java 承接原因、备注、原票关联等字段
  • T052 [P] [US4] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java 与 dal/mysql/invoice/InvoiceMapper.java 承接作废/红冲状态、原票关联、失败原因与查询上下文
  • T053 [US4] 在 specs/002-rev005-invoice-flow/verification.md 记录 docs/design/02_Detailed_Design/12_REV_Detailed.md、docs/design/03_Technical_Design/03_Interface_Design.md 与 backend/sw-business/sw-business-server/pom.xml 的作废/红冲链路校验结果
  • T054 [US4] 更新 docs/design/00_Management/01_Project_Progress.md 与 docs/design/00_Management/03_Task_Checklist.md 同步 US4 收口结果
  • T055 [US4] 在 specs/002-rev005-invoice-flow/verification.md 补充作废/红冲运行态日志样本，并跟进 biz_invoice 物理 DDL / migration 来源风险的后续结论

Checkpoint: 作废与红冲已从“预留”升级为可评审、可编译验证的二期能力入口。

Final Phase: Cross-Cutting Closure

Purpose: 完成仓库级一致性复核、成功标准证据补齐和最终交付总结。

  • T056 [P] 在 specs/002-rev005-invoice-flow/verification.md 记录 make check-links 对 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 的交叉引用校验结果
  • T057 [P] 在 specs/002-rev005-invoice-flow/verification.md 记录 make validate-mermaid 对 docs/design/02_Detailed_Design/12_REV_Detailed.md 与 docs/design/03_Technical_Design/03_Interface_Design.md 的 Mermaid 校验结果
  • T058 在 specs/002-rev005-invoice-flow/verification.md 固化 biz_invoice 物理 DDL / migration 来源交叉核查结果与剩余风险
  • T059 在 specs/002-rev005-invoice-flow/verification.md 固化 SC-005“关键动作 ↔ 日志写入点”矩阵，并回扣 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java
  • T060 在 specs/002-rev005-invoice-flow/verification.md 补充 /business/invoice/apply 的 SC-001 响应时延采样口径、命令和结果
  • T061 在 specs/002-rev005-invoice-flow/verification.md 补充 SC-002 正常业务场景的发票申请通过率样本统计、分组和结论
  • T062 在 specs/002-rev005-invoice-flow/verification.md 补充 SC-003 开票结果回写成功率的样本统计、失败分类和结论
  • T063 在 specs/002-rev005-invoice-flow/verification.md 补充 SC-004 客户侧查询/下载/推送成功率的样本统计、拦截原因和结论
  • T064 在 specs/002-rev005-invoice-flow/spec.md 更新 Status 与 Next Steps，使其与 specs/002-rev005-invoice-flow/tasks.md、verification.md 的当前完成度一致
  • T065 在 specs/002-rev005-invoice-flow/tasks.md、specs/002-rev005-invoice-flow/verification.md、docs/design/00_Management/01_Project_Progress.md、docs/design/00_Management/03_Task_Checklist.md 汇总最终交付说明、剩余风险与下一步建议

Dependencies & Execution Order

Phase Dependencies

  • Scope & Source Confirmation: 无依赖；必须先完成，作为单一真源与范围边界基线
  • Foundational: 依赖 Scope & Source Confirmation；必须在用户故事前完成
  • US1: 依赖 Foundational；是 MVP 最小闭环入口
  • US2: 依赖 US1；复用申请单号、受理号和基础申请链路
  • US3: 依赖 US2；复用终态结果、查询补偿和电子票结果
  • US4: 依赖 US3；在正常开票闭环基础上补齐后处理能力
  • Final Phase: 依赖所有已选择的用户故事完成

Within Each User Story

  • 先更新正式文档与合同，再更新 backend 接口与服务
  • 先补请求/响应对象与数据映射，再实现服务逻辑
  • 先固化文档/代码验证证据，再更新管理台账
  • 运行态样本、统计口径与 Success Criteria 证据在该故事完成后补齐

Parallel Opportunities

  • T003 与 T004 可并行确认正式文档与 backend 触点
  • T009 与 T010 可并行确认 VO 及外部依赖对象
  • US1 中 T017 与 T018 可并行
  • US2 中 T028 与 T029 可并行
  • US3 中 T039 与 T040 可并行
  • US4 中 T051 与 T052 可并行
  • Final Phase 中 T056 与 T057 可并行
  • Final Phase 中 T060、T061、T062、T063 可在样本准备完成后并行统计

Implementation Strategy

MVP First

  1. 先完成 Shared Foundation，统一文档、接口、数据和台账出口。
  2. 优先交付 US1 发票申请与校验，形成后台最小受理入口。
  3. 再交付 US2 异步协同与查询兜底，完成 SYS-008 结果获取闭环。
  4. 再交付 US3 结果回写、账单关联与客户侧消费，形成一期完整业务闭环。
  5. 最后交付 US4 作废与红冲，补齐二期后处理入口。
  6. 进入 Final Phase，集中补齐 Success Criteria 量化证据和最终交付摘要。

Independent Test Criteria by Story

  • US1: 后台发票申请成功生成申请单号，非法账单/原始单账单直接部分开票被拦截
  • US2: 查询接口可按申请单号或受理号返回结果，成功终态不被失败覆盖
  • US3: 结果回写后账单与发票关联可查，客户侧只能查看并下载/推送本人已开票电子票
  • US4: 后台可发起作废/红冲，终态正确更新为 INVALID 或 RED_INK，且保留原票关系、失败原因与日志留痕

Notes

  • 本任务清单已修复旧版 T057 ~ T061 在 US4 与 Final Phase 重号的问题。
  • 本任务清单保留当前仓库真实完成度：现有实现与已落账证据标记为 [x]，待补统计与运行态样本标记为 [ ]。
  • specs/002-rev005-invoice-flow/verification.md 是 SC-001 ~ SC-005 证据的唯一落点；若当前环境无法完成统计验证，至少要明确样本口径、缺口和风险。
  • docs/design/04_Appendix/Archive/ 仅用于核对与追溯，不作为正式主稿替代来源。
  • 由于当前分支为 dev/rev004-implementation，本次 /speckit.tasks 按现有 artifacts 手工推进，而非依赖 feature-branch prerequisite 脚本。