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 91f37d6622 docs: 收口 REV-005 US4 边界与验证记录 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-17 10:22:56 +08:00

19 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/

Validation: 正式文档修改必须执行对应 make validate-file；涉及跨文档引用执行 make check-links；涉及 Mermaid/时序图执行 make validate-mermaid。backend 实现阶段需补充最小编译/流程验证。

Organization: 任务按用户故事分组，确保每个故事都可以独立实现、独立验证、独立评审。

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: Setup（共享准备）

Purpose: 固化本轮实现边界、目标文件和 backend 触点，避免后续修改偏离单一真源。

  • T001 阅读 docs/design/00_Management/01_Project_Progress.md、docs/design/00_Management/02_Delivery_Standards.md、docs/design/00_Management/03_Task_Checklist.md 作为本轮正式文档治理前置输入
  • T002 阅读并锁定本轮目标文档 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 相关章节
  • T003 确认本轮源文档边界并在 specs/002-rev005-invoice-flow/tasks.md 执行时以 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 为直接输入
  • 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
  • T005 [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

Phase 2: Foundational（共享基础能力）

Purpose: 先补齐所有用户故事共用的模型、状态、接口骨架与文档统一口径。

  • T006 定义共享发票状态与来源口径并更新 docs/design/02_Detailed_Design/12_REV_Detailed.md 中 REV-005 状态说明为 SUBMITTED/PENDING/SUCCESS/FAIL/INVALID/RED_INK
  • T007 定义共享接口编号与职责分工并更新 docs/design/03_Technical_Design/03_Interface_Design.md 中 IF-REV-008、IF-REV-009 与客户侧查询下载相关章节，同时收敛 IF-CS-004 与客户侧消费口径的编号/职责边界
  • T008 定义共享数据承接口径并更新 docs/design/03_Technical_Design/01_Database_Design.md 中 biz_invoice、biz_cust_invoice、biz_invoice_taxrate、账单-发票关系快照说明，并标明已有字段、待补字段与仅快照字段
  • T009 在 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java 声明 REV-005 共用能力入口（申请、查询、结果回写、客户侧下载/推送、作废/红冲预留）
  • T010 在 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java 预留 REV-005 共用接口路由入口，避免继续仅停留在配置 CRUD
  • T011 [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
  • T012 [P] 新增结果回写与客户侧消费基础请求/响应对象到 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceWriteBackReqVO.java、InvoiceCustomerQueryReqVO.java、InvoicePushReqVO.java

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

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

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

Implementation for User Story 1

  • T013 [US1] 更新 docs/design/02_Detailed_Design/12_REV_Detailed.md 中 REV-005 的后台申请入口、校验规则、批量开票和“禁止原始单账单直接任意部分开票”描述
  • 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 承接申请单号、受理号、申请状态、限额校验所需字段映射，并与 docs/design/03_Technical_Design/01_Database_Design.md 标注保持一致
  • T019 [US1] 在 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java 接入 biz_cust_invoice、biz_invoice_taxrate 与账单对象校验，确保仅已收费未开票账单可申请
  • T020 [US1] 在 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java 实现 applicationNo 或 custId + chargeIds 幂等控制
  • T021 [US1] 运行 make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md 验证 REV-005 详细设计章节
  • T022 [US1] 运行 make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md 验证 IF-REV-008 接口文档
  • T023 [US1] 在 backend/sw-business/sw-business-server/pom.xml 所在模块执行一次最小 Maven 编译验证（例如以 invoice 相关变更为范围的编译/测试命令），确认 controller/admin/invoice/InvoiceController.java 与 service/invoice/InvoiceServiceImpl.java 的申请链路可编译
  • T024 [US1] 更新 docs/design/00_Management/01_Project_Progress.md 记录 REV-005 后台申请与校验闭环进展
  • T025 [US1] 更新 docs/design/00_Management/03_Task_Checklist.md 同步 REV-005 后台申请与校验任务状态

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

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

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

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

Implementation for User Story 2

  • T026 [US2] 更新 docs/design/02_Detailed_Design/12_REV_Detailed.md 中 REV-005 的 SYS-008 异步协同、查询补偿、终态保护和异常核查流程
  • T027 [US2] 更新 docs/design/03_Technical_Design/03_Interface_Design.md 中 IF-REV-009 的后台查询、系统补偿查询和状态流转时序
  • T028 [US2] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java 增加后台查询接口与补偿查询触发入口
  • T029 [US2] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java 实现提交 SYS-008、记录 sysRequestNo、创建查询任务、按申请单号/受理号查询结果
  • T030 [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
  • T031 [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，并与 docs/design/03_Technical_Design/01_Database_Design.md 标注保持一致
  • T032 [US2] 在 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java 实现“成功状态不被失败结果覆盖”的幂等保护
  • T033 [US2] 在 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java 记录查询补偿与异常留痕到操作日志对象
  • T034 [US2] 运行 make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md 验证 REV-005 异步与补偿流程描述
  • T035 [US2] 运行 make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md 验证 IF-REV-009 查询接口文档
  • T036 [US2] 在 backend/sw-business/sw-business-server/pom.xml 所在模块执行一次最小 Maven 编译验证，并以受理号/申请单号查询场景确认查询链路可返回 PENDING/SUCCESS/FAIL 且保护终态
  • T037 [US2] 更新 docs/design/00_Management/01_Project_Progress.md 记录 REV-005 查询兜底与异步协同进展
  • T038 [US2] 更新 docs/design/00_Management/03_Task_Checklist.md 同步 REV-005 查询兜底与异步协同任务状态

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

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

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

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

Implementation for User Story 3

  • T039 [US3] 更新 docs/design/02_Detailed_Design/12_REV_Detailed.md 中 REV-005 的结果回写、账单关联、客户侧查看/下载/推送规则
  • T040 [US3] 更新 docs/design/03_Technical_Design/01_Database_Design.md 中 biz_invoice、账单-发票关系快照、客户查询身份与操作留痕承接口径，并标明已有字段、待补字段与仅快照字段
  • T041 [US3] 更新 docs/design/03_Technical_Design/03_Interface_Design.md 中客户侧查看、下载、推送电子发票的请求/响应约束
  • T042 [US3] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java 增加结果回写、客户侧查询、下载、推送接口
  • T043 [US3] 更新 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java 实现结果回写、账单关联状态更新、客户侧权限校验与电子票文件处理
  • T044 [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 承接回写与客户侧消费字段
  • T045 [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、关联状态字段，并与 docs/design/03_Technical_Design/01_Database_Design.md 标注保持一致
  • T046 [US3] 在 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java 实现客户侧仅可访问本人已开具电子发票的鉴权限制
  • T047 [US3] 在 backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java 实现下载/推送前校验 SUCCESS 状态与 fileUrl 存在性
  • T048 [US3] 运行 make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md 验证数据承接口径
  • T049 [US3] 运行 make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md 验证客户侧查询下载推送接口文档
  • T050 [US3] 在 backend/sw-business/sw-business-server/pom.xml 所在模块执行一次最小 Maven 编译验证，并以客户侧查询/下载/推送场景确认结果回写、账单关联与电子票消费链路可调用
  • T051 [US3] 更新 docs/design/00_Management/01_Project_Progress.md 记录 REV-005 结果回写与客户侧消费进展
  • T052 [US3] 更新 docs/design/00_Management/03_Task_Checklist.md 同步 REV-005 结果回写与客户侧消费任务状态

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

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

Goal: 将作废与红冲明确标注为后续阶段能力，只在正式文档和管理台账中保留边界与后续入口，不纳入一期 implement 必选交付。

Independent Test: 审阅 spec、plan、tasks 与正式文档后，可确认作废/红冲属于后续能力预留，不要求本轮 backend 代码实现。

Implementation for User Story 4

  • T053 [US4] 更新 docs/design/02_Detailed_Design/12_REV_Detailed.md 标注作废与红冲为后续阶段能力，并说明其与正常开票闭环的边界
  • T054 [US4] 更新 docs/design/03_Technical_Design/03_Interface_Design.md 标注作废/红冲接口为预留能力或后续规划，不纳入一期 implement 必选范围
  • T055 [US4] 在 docs/design/00_Management/01_Project_Progress.md 记录作废与红冲转为后续阶段能力预留的决策
  • T056 [US4] 在 docs/design/00_Management/03_Task_Checklist.md 同步作废与红冲改为后续阶段任务预留的状态说明

Checkpoint: 作废与红冲的范围边界已稳定，不再与一期正常开票闭环交付混淆。

Final Phase: Cross-Cutting Closure

Purpose: 完成仓库级一致性复核、统一校验、成功标准验证和交付总结。

  • T057 [P] 运行 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 的交叉引用
  • T058 [P] 运行 make validate-mermaid 复核 REV-005 相关 Mermaid/时序图在 docs/design/02_Detailed_Design/12_REV_Detailed.md 与 docs/design/03_Technical_Design/03_Interface_Design.md 中的可用性
  • T059 根据 specs/002-rev005-invoice-flow/spec.md 的 SC-001 在 backend/sw-business/sw-business-server/pom.xml 所在模块补充并执行发票申请接口响应时延验证，并将命令、样本说明与结果记录到 specs/002-rev005-invoice-flow/verification.md
  • T060 根据 specs/002-rev005-invoice-flow/spec.md 的 SC-002、SC-003、SC-004、SC-005 补充统计脚本或验证记录，明确数据来源、样本范围、统计口径，并将校验通过率、回写成功率、下载成功率、日志完整率结果写入 specs/002-rev005-invoice-flow/verification.md
  • T061 汇总最终交付说明并在 specs/002-rev005-invoice-flow/tasks.md 执行完成后输出修改文件、验证结果、剩余风险与下一步建议

Dependencies & Execution Order

Phase Dependencies

  • Setup: 无依赖，但必须先完成，作为正式文档与 backend 触点的统一基线
  • Foundational: 依赖 Setup，必须在用户故事前完成
  • US1: 依赖 Foundational；是 MVP 的最小闭环入口
  • US2: 依赖 US1；需要复用申请单和受理号
  • US3: 依赖 US2；需要复用终态结果与查询补偿数据
  • US4: 依赖 US3；仅做范围预留与文档/台账标注
  • Final Phase: 依赖所有已选择的用户故事完成

Within Each User Story

  • 先更新正式文档，再更新 backend 接口与服务
  • 先补请求/响应对象和数据映射，再实现服务逻辑
  • 先完成内容编辑，再运行验证命令
  • 先完成验证，再更新管理台账

Parallel Opportunities

  • T004 与 T005 可并行盘点 backend 依赖
  • T011 与 T012 可并行新增 VO 骨架
  • US1 中 T017 与 T018 可并行
  • US2 中 T030 与 T031 可并行
  • US3 中 T044 与 T045 可并行
  • T057 与 T058 可并行执行

Implementation Strategy

MVP First

  1. 完成 Phase 1-2，统一正式文档与 backend 触点基线
  2. 优先交付 US1 发票申请与校验，形成最小可用后台入口
  3. 再交付 US2 异步协同与查询兜底，完成 SYS-008 结果获取闭环
  4. 再交付 US3 结果回写、账单关联与客户侧消费，形成一期完整业务闭环
  5. US4 作废与红冲预留 仅保留文档与台账入口，不纳入本轮 backend 实现

Independent Test Criteria by Story

  • US1: 后台发票申请成功生成申请单号，非法账单/直接部分开票被拦截
  • US2: 查询接口可按申请单号或受理号返回结果，成功终态不被失败覆盖
  • US3: 结果回写后账单与发票关联可查，客户侧只能查看并下载/推送本人已开票电子票
  • US4: 作废与红冲被稳定标注为后续阶段能力，不与一期实现范围冲突

Notes

  • 本任务集同时覆盖正式文档收敛与 backend 实施准备，执行时应始终以 specs/002-rev005-invoice-flow/spec.md 为单一需求总源
  • Archive 文档仅用于校验与追溯，不作为正式交付主稿直接替代
  • 仓库内未找到 .specify/scripts/bash/check-prerequisites.sh，本轮按现有 planning artifacts 手工推进 Speckit 任务流
  • Success Criteria 已显式映射到 Final Phase 验证任务，若当前环境无法完成统计验证，应至少产出明确的验证记录与剩余风险说明