212 lines
19 KiB
Markdown
212 lines
19 KiB
Markdown
# 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 触点，避免后续修改偏离单一真源。
|
||
|
||
- [x] 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` 作为本轮正式文档治理前置输入
|
||
- [x] 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 相关章节
|
||
- [x] 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` 为直接输入
|
||
- [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`
|
||
- [x] 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**: 先补齐所有用户故事共用的模型、状态、接口骨架与文档统一口径。
|
||
|
||
- [x] T006 定义共享发票状态与来源口径并更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 中 REV-005 状态说明为 `SUBMITTED/PENDING/SUCCESS/FAIL/INVALID/RED_INK`
|
||
- [x] T007 定义共享接口编号与职责分工并更新 `docs/design/03_Technical_Design/03_Interface_Design.md` 中 `IF-REV-008`、`IF-REV-009` 与客户侧查询下载相关章节，同时收敛 `IF-CS-004` 与客户侧消费口径的编号/职责边界
|
||
- [x] T008 定义共享数据承接口径并更新 `docs/design/03_Technical_Design/01_Database_Design.md` 中 `biz_invoice`、`biz_cust_invoice`、`biz_invoice_taxrate`、账单-发票关系快照说明，并标明已有字段、待补字段与仅快照字段
|
||
- [x] T009 在 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java` 声明 REV-005 共用能力入口（申请、查询、结果回写、客户侧下载/推送、作废/红冲预留）
|
||
- [x] T010 在 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java` 预留 REV-005 共用接口路由入口，避免继续仅停留在配置 CRUD
|
||
- [x] 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`
|
||
- [x] 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
|
||
|
||
- [x] T013 [US1] 更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 中 REV-005 的后台申请入口、校验规则、批量开票和“禁止原始单账单直接任意部分开票”描述
|
||
- [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` 承接申请单号、受理号、申请状态、限额校验所需字段映射，并与 `docs/design/03_Technical_Design/01_Database_Design.md` 标注保持一致
|
||
- [x] 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` 与账单对象校验，确保仅已收费未开票账单可申请
|
||
- [x] T020 [US1] 在 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java` 实现 `applicationNo` 或 `custId + chargeIds` 幂等控制
|
||
- [x] T021 [US1] 运行 `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` 验证 REV-005 详细设计章节
|
||
- [x] T022 [US1] 运行 `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` 验证 `IF-REV-008` 接口文档
|
||
- [x] T023 [US1] 在 `backend/sw-business/sw-business-server/pom.xml` 所在模块执行一次最小 Maven 编译验证（例如以 invoice 相关变更为范围的编译/测试命令），确认 `controller/admin/invoice/InvoiceController.java` 与 `service/invoice/InvoiceServiceImpl.java` 的申请链路可编译
|
||
- [x] T024 [US1] 更新 `docs/design/00_Management/01_Project_Progress.md` 记录 REV-005 后台申请与校验闭环进展
|
||
- [x] 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
|
||
|
||
- [x] T026 [US2] 更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 中 REV-005 的 `SYS-008` 异步协同、查询补偿、终态保护和异常核查流程
|
||
- [x] T027 [US2] 更新 `docs/design/03_Technical_Design/03_Interface_Design.md` 中 `IF-REV-009` 的后台查询、系统补偿查询和状态流转时序
|
||
- [x] T028 [US2] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java` 增加后台查询接口与补偿查询触发入口
|
||
- [x] T029 [US2] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java` 实现提交 `SYS-008`、记录 `sysRequestNo`、创建查询任务、按申请单号/受理号查询结果
|
||
- [x] 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`
|
||
- [x] 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` 标注保持一致
|
||
- [x] T032 [US2] 在 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java` 实现“成功状态不被失败结果覆盖”的幂等保护
|
||
- [x] T033 [US2] 在 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java` 记录查询补偿与异常留痕到操作日志对象
|
||
- [x] T034 [US2] 运行 `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` 验证 REV-005 异步与补偿流程描述
|
||
- [x] T035 [US2] 运行 `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` 验证 `IF-REV-009` 查询接口文档
|
||
- [x] T036 [US2] 在 `backend/sw-business/sw-business-server/pom.xml` 所在模块执行一次最小 Maven 编译验证，并以受理号/申请单号查询场景确认查询链路可返回 `PENDING/SUCCESS/FAIL` 且保护终态
|
||
- [x] T037 [US2] 更新 `docs/design/00_Management/01_Project_Progress.md` 记录 REV-005 查询兜底与异步协同进展
|
||
- [x] 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
|
||
|
||
- [x] T039 [US3] 更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 中 REV-005 的结果回写、账单关联、客户侧查看/下载/推送规则
|
||
- [x] T040 [US3] 更新 `docs/design/03_Technical_Design/01_Database_Design.md` 中 `biz_invoice`、账单-发票关系快照、客户查询身份与操作留痕承接口径，并标明已有字段、待补字段与仅快照字段
|
||
- [x] T041 [US3] 更新 `docs/design/03_Technical_Design/03_Interface_Design.md` 中客户侧查看、下载、推送电子发票的请求/响应约束
|
||
- [x] T042 [US3] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java` 增加结果回写、客户侧查询、下载、推送接口
|
||
- [x] T043 [US3] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java` 实现结果回写、账单关联状态更新、客户侧权限校验与电子票文件处理
|
||
- [x] 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` 承接回写与客户侧消费字段
|
||
- [x] 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` 标注保持一致
|
||
- [x] T046 [US3] 在 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java` 实现客户侧仅可访问本人已开具电子发票的鉴权限制
|
||
- [x] T047 [US3] 在 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java` 实现下载/推送前校验 `SUCCESS` 状态与 `fileUrl` 存在性
|
||
- [x] T048 [US3] 运行 `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` 验证数据承接口径
|
||
- [x] T049 [US3] 运行 `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` 验证客户侧查询下载推送接口文档
|
||
- [x] T050 [US3] 在 `backend/sw-business/sw-business-server/pom.xml` 所在模块执行一次最小 Maven 编译验证，并以客户侧查询/下载/推送场景确认结果回写、账单关联与电子票消费链路可调用
|
||
- [x] T051 [US3] 更新 `docs/design/00_Management/01_Project_Progress.md` 记录 REV-005 结果回写与客户侧消费进展
|
||
- [x] 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
|
||
|
||
- [x] T053 [US4] 更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 标注作废与红冲为后续阶段能力，并说明其与正常开票闭环的边界
|
||
- [x] T054 [US4] 更新 `docs/design/03_Technical_Design/03_Interface_Design.md` 标注作废/红冲接口为预留能力或后续规划，不纳入一期 implement 必选范围
|
||
- [x] T055 [US4] 在 `docs/design/00_Management/01_Project_Progress.md` 记录作废与红冲转为后续阶段能力预留的决策
|
||
- [x] T056 [US4] 在 `docs/design/00_Management/03_Task_Checklist.md` 同步作废与红冲改为后续阶段任务预留的状态说明
|
||
|
||
**Checkpoint**: 作废与红冲的范围边界已稳定，不再与一期正常开票闭环交付混淆。
|
||
|
||
---
|
||
|
||
## Final Phase: Cross-Cutting Closure
|
||
|
||
**Purpose**: 完成仓库级一致性复核、统一校验、成功标准验证和交付总结。
|
||
|
||
- [x] 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` 的交叉引用
|
||
- [x] 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` 中的可用性
|
||
- [x] 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`
|
||
- [x] T060 根据 `specs/002-rev005-invoice-flow/spec.md` 的 `SC-002`、`SC-003`、`SC-004`、`SC-005` 补充统计脚本或验证记录，明确数据来源、样本范围、统计口径，并将校验通过率、回写成功率、下载成功率、日志完整率结果写入 `specs/002-rev005-invoice-flow/verification.md`
|
||
- [x] 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 验证任务，若当前环境无法完成统计验证，应至少产出明确的验证记录与剩余风险说明
|