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

222 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 触点,避免后续任务偏离已收敛口径。
- [x] 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 任务拆解直接输入
- [x] 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` 作为治理约束输入
- [x] 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 章节为主落点
- [x] 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**: 先统一跨故事共享的状态、接口、数据承接和校验输出口径。
- [x] 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`
- [x] 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`、客户侧消费边界的接口职责
- [x] 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` 的共享数据承接口径
- [x] 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` 的共享路由和服务骨架
- [x] 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` 的公共请求/响应承接
- [x] 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` 的客户开票信息与税率依赖
- [x] 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
- [x] T012 [US1] 更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 中 REV-005 的后台申请入口、校验规则、批量开票和“禁止原始单账单直接任意部分开票”说明
- [x] T013 [US1] 更新 `specs/002-rev005-invoice-flow/contracts/if-rev-008-invoice-application.md` 中后台申请的请求字段、响应字段、幂等口径和失败提示
- [x] T014 [US1] 更新 `docs/design/03_Technical_Design/03_Interface_Design.md``IF-REV-008` 的后台申请/批量开票接口定义
- [x] T015 [US1] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java` 增加后台发票申请入口
- [x] T016 [US1] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java``service/invoice/InvoiceServiceImpl.java` 实现申请单号生成、账单/客户/税率校验和申请记录落库
- [x] 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`
- [x] 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`、申请状态、受理号等字段映射
- [x] 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` 校验结果,固化申请链路文档证据
- [x] T020 [US1] 在 `specs/002-rev005-invoice-flow/verification.md` 记录 `backend/sw-business/sw-business-server/pom.xml` 范围内的最小编译结果,固化申请链路代码证据
- [x] 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
- [x] T023 [US2] 更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 中 REV-005 的 `SYS-008` 异步协同、查询补偿、终态保护和异常核查流程
- [x] T024 [US2] 更新 `specs/002-rev005-invoice-flow/contracts/if-rev-009-invoice-query.md` 中后台查询、系统补偿查询和客户侧消费前置规则
- [x] T025 [US2] 更新 `docs/design/03_Technical_Design/03_Interface_Design.md``IF-REV-009` 的查询与补偿查询接口定义
- [x] T026 [US2] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java` 增加后台查询与补偿查询入口
- [x] 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` 申请提交、受理号记录和按申请单号/受理号查询
- [x] 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`
- [x] 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`
- [x] T030 [US2] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java` 实现成功终态保护和查询来源留痕
- [x] 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` 的查询链路校验结果
- [x] 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
- [x] T034 [US3] 更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 中 REV-005 的结果回写、账单关联、客户侧查看/下载/推送规则
- [x] T035 [US3] 更新 `docs/design/03_Technical_Design/01_Database_Design.md``biz_invoice`、账单-发票关系快照、客户查询身份与操作留痕承接口径
- [x] T036 [US3] 更新 `docs/design/03_Technical_Design/03_Interface_Design.md` 中客户侧查看、下载、推送电子发票的请求/响应约束
- [x] T037 [US3] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java` 增加结果回写、客户侧查询、下载、推送接口
- [x] T038 [US3] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java``service/invoice/InvoiceServiceImpl.java` 实现结果回写、账单关联和客户侧消费逻辑
- [x] 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` 承接回写与客户侧消费字段
- [x] 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`、关联状态字段
- [x] T041 [US3] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java` 实现客户归属校验和 `SUCCESS + fileUrl` 前置校验
- [x] 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` 的结果回写/客户消费链路校验结果
- [x] 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
- [x] T045 [US4] 更新 `specs/002-rev005-invoice-flow/spec.md``specs/002-rev005-invoice-flow/plan.md`,将作废/红冲从“后续预留”提升为当前 REV-005 二期范围
- [x] T046 [US4] 更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 明确作废与红冲的触发入口、状态流转、原票约束、账单联动与日志要求
- [x] T047 [US4] 更新 `docs/design/03_Technical_Design/03_Interface_Design.md` 明确后台作废/红冲接口、请求响应字段、查询补偿与客户侧消费边界
- [x] T048 [US4] 更新 `docs/design/03_Technical_Design/01_Database_Design.md` 标注作废/红冲所需承接字段、原票关联与失败原因口径
- [x] T049 [US4] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java` 增加后台作废与红冲接口
- [x] T050 [US4] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java``service/invoice/InvoiceServiceImpl.java` 实现作废、红冲、原票校验、查询补偿与日志留痕
- [x] 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` 承接原因、备注、原票关联等字段
- [x] 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` 承接作废/红冲状态、原票关联、失败原因与查询上下文
- [x] 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` 的作废/红冲链路校验结果
- [x] 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**: 完成仓库级一致性复核、成功标准证据补齐和最终交付总结。
- [x] 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` 的交叉引用校验结果
- [x] 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 校验结果
- [x] T058 在 `specs/002-rev005-invoice-flow/verification.md` 固化 `biz_invoice` 物理 DDL / migration 来源交叉核查结果与剩余风险
- [x] 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 客户侧查询/下载/推送成功率的样本统计、拦截原因和结论
- [x] T064 在 `specs/002-rev005-invoice-flow/spec.md` 更新 `Status``Next Steps`,使其与 `specs/002-rev005-invoice-flow/tasks.md``verification.md` 的当前完成度一致
- [x] 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 脚本。