diff --git a/docs/design/02_Detailed_Design/12_REV_Detailed.md b/docs/design/02_Detailed_Design/12_REV_Detailed.md index a2deb77..2ca6c07 100644 --- a/docs/design/02_Detailed_Design/12_REV_Detailed.md +++ b/docs/design/02_Detailed_Design/12_REV_Detailed.md @@ -356,7 +356,7 @@ flowchart TD ### 功能说明 -负责一期正常开票闭环的业务接入与状态落账，覆盖后台发票申请、开票校验、`SYS-008` 异步协同、查询兜底、结果回写、账单关联以及客户侧已开票电子发票查询/下载/推送；作废与红冲仅保留后续扩展入口。 +负责发票业务闭环的业务接入与状态落账，覆盖后台发票申请、开票校验、`SYS-008` 异步协同、查询兜底、结果回写、账单关联、客户侧已开票电子发票查询/下载/推送，以及后台作废与红冲处理。 ### 业务流程 @@ -391,7 +391,7 @@ flowchart TD 3. 个人与企业开票均通过客户开票信息与税率表完成合法性校验；如需多张发票，沿用拆账/分账后的账单分别开票口径。 4. `SYS-008` 采用“异步申请 + 查询兜底”模式，成功状态不得被后续失败查询结果覆盖。 5. 电子发票仅在 `SUCCESS` 且存在票据文件地址时允许客户侧下载或推送。 -6. 发票作废、红冲由 `SYS-008` 统一承接，当前阶段仅保留状态与文档入口，不纳入一期正常闭环实现范围。 +6. 发票作废、红冲仍由 `SYS-008` 统一承接税控侧处理，`SYS-002` 负责后台触发入口、状态校验、查询补偿、结果落账与日志留痕；当前轮次按二期范围补齐 backend 实现入口。 ### 后台申请入口与校验补充 @@ -447,7 +447,7 @@ flowchart TD - **已落地**：发票主记录、税率配置、客户开票信息，以及一期正常开票闭环所需的后台申请、查询兜底、结果回写、账单关联与客户侧电子发票消费能力。 - **部分落地**：发票修改、开票过程留痕在后端中已有相关对象，但整套发票明细/批次类对象尚未全部确认。 -- **后续预留**：发票作废、红冲及其批量处理仍由 `SYS-008` 统一承接，当前仅保留 `INVALID`、`RED_INK` 状态与正式文档入口，不表述为本轮 backend 已交付能力。 +- **二期补齐**：发票作废、红冲及其查询补偿仍由 `SYS-008` 统一承接，但当前轮次补齐后台触发入口、状态流转、结果回写与日志留痕，不再仅停留于文档预留。 - **文档先行**：发票明细、营业账开票关系等对象仍按设计能力描述，不表述为本轮已确认独立表。 diff --git a/docs/design/03_Technical_Design/01_Database_Design.md b/docs/design/03_Technical_Design/01_Database_Design.md index b62ebe5..4391643 100644 --- a/docs/design/03_Technical_Design/01_Database_Design.md +++ b/docs/design/03_Technical_Design/01_Database_Design.md @@ -1114,7 +1114,7 @@ retrieval_priority: P0 | 对象 | 已有字段 | 待补字段 | 仅快照/历史只读字段 | | :--- | :--- | :--- | :--- | -| `biz_invoice` 发票申请/结果主对象 | `code`、`cust_id`、`charge_id`、`invoice_status`、`invoice_amount` | `application_no`、`sys_request_no`、`invoice_type`、`invoice_title`、`tax_no`、`email`、`mobile`、`source_channel`、`fail_reason`、`invoice_code`、`invoice_number`、`file_url`、`last_try_time`、`next_try_time`、`try_count`、`push_status`、`charge_ids_snapshot`、`charge_bind_status` | 旧开票批次号、旧配置版本号、旧平台扩展回执 | +| `biz_invoice` 发票申请/结果主对象 | `code`、`cust_id`、`charge_id`、`invoice_status`、`invoice_amount` | `application_no`、`sys_request_no`、`invoice_type`、`invoice_title`、`tax_no`、`email`、`mobile`、`source_channel`、`fail_reason`、`invoice_code`、`invoice_number`、`file_url`、`last_try_time`、`next_try_time`、`try_count`、`push_status`、`charge_ids_snapshot`、`charge_bind_status`、作废原因/备注、红冲原因/备注、原票/红票关联标识、作废/红冲申请来源、补偿查询/结果回写上下文 | 旧开票批次号、旧配置版本号、旧平台扩展回执 | | `biz_cust_invoice` 客户开票信息 | `cust_id`、`invoice_title`、`tax_no`、`email`、`mobile` | 企业/个人抬头类型、默认推送方式等扩展属性按后续实现补齐 | 旧抬头版本、历史修改快照 | | `biz_invoice_taxrate` 税率配置 | `tax_code`、`tax_name`、`tax_rate`、`status` | 税率生效区间、适用票种范围等扩展控制字段 | 旧税率版本快照 | | 账单-发票关系快照 | 当前主模型通过 `biz_invoice` 与 `biz_charge*` 关联承接 | `charge_ids_snapshot`、账单集合来源、客户侧身份匹配结果、操作留痕标识 | 旧营业账开票关系表、旧发票明细表 | diff --git a/docs/design/03_Technical_Design/03_Interface_Design.md b/docs/design/03_Technical_Design/03_Interface_Design.md index 025b41d..85dbab1 100644 --- a/docs/design/03_Technical_Design/03_Interface_Design.md +++ b/docs/design/03_Technical_Design/03_Interface_Design.md @@ -409,13 +409,14 @@ retrieval_priority: P0 | 接口编号 | IF-REV-008 | | 归属模块 | REV-005 | | 请求方式 | POST | -| 请求路径 | `/admin-api/revenue/invoice/apply` | -| 功能描述 | 后台对已收费未开票账单发起单笔/批量开票申请，生成申请单号并调用 `SYS-008` | +| 请求路径 | `/business/invoice/apply` | +| 功能描述 | 后台对已收费未开票账单发起单笔/批量开票申请，并在同一管理域内受理作废/红冲后处理入口 | | 核心表 | `biz_invoice`、`biz_invoice_taxrate`、`biz_cust_invoice` | 边界约束： - 一期仅支持后台营业收费员/财务人员发起申请，客户侧不直接调用本接口。 -- 发票开具、作废、红冲能力由 `SYS-008` 统一承接，`SYS-002` 仅负责业务单据归集、申请发起、查询补偿与结果落账。 +- 发票开具、作废、红冲能力均由 `SYS-008` 统一承接税控侧处理，`SYS-002` 负责业务单据归集、申请发起、后台作废/红冲触发、查询补偿与结果落账。 +- 后台发票后处理沿同一管理域补充 `/business/invoice/invalidate` 与 `/business/invoice/red-ink` 两个入口，分别承接作废与红冲动作；处理结果继续通过 `IF-REV-009` 或 `IF-EXT-007` 统一收口。 - 原始单账单不支持直接任意部分金额开票；如需多张发票，应基于拆账/分账后的账单集合申请。 ### IF-REV-009 发票结果查询接口 @@ -425,8 +426,8 @@ retrieval_priority: P0 | 接口编号 | IF-REV-009 | | 归属模块 | REV-005 | | 请求方式 | POST | -| 请求路径 | `/admin-api/revenue/invoice/query` | -| 功能描述 | 后台按申请单号/受理号查询开票结果，并支持系统补偿查询兜底 | +| 请求路径 | `/business/invoice/query`（补偿查询：`/business/invoice/query/compensate`） | +| 功能描述 | 后台按申请单号/受理号查询开票、作废或红冲结果，并支持系统补偿查询兜底 | | 核心表 | `biz_invoice`、`biz_operat_log` | ### IF-REV-011 银行代收协同接口 @@ -494,14 +495,14 @@ retrieval_priority: P0 |------|------| | 接口编号 | IF-CS-004 | | 归属模块 | CS-004 | -| 请求方式 | GET / POST | -| 请求路径 | `/app-api/customer/invoice` | +| 请求方式 | POST | +| 请求路径 | `/business/invoice/customer/query`、`/business/invoice/customer/download`、`/business/invoice/customer/push` | | 功能描述 | 面向客户渠道查询、下载、推送本人已开具电子发票 | | 核心表 | `biz_invoice`、`biz_cust_invoice`、`biz_invoice_taxrate` | 边界约束： - 一期客户侧仅消费已形成 `SUCCESS` 终态且具备票据地址的电子发票结果，不直接发起开票申请。 -- 发票作废、红冲及其结果消费由 `SYS-008` 统一承接，当前阶段仅保留状态、字段与后续扩展入口，不纳入 `IF-CS-004` 一期必选实现范围。 +- 发票作废、红冲仍由 `SYS-008` 统一承接税控侧处理；`IF-CS-004` 仅消费当前仍可展示、下载、推送的有效电子发票结果，不开放客户侧直接发起作废或红冲。 ### IF-CS-006 业务办理进度接口 @@ -800,6 +801,33 @@ retrieval_priority: P0 - 幂等键优先使用 `applicationNo`，未传入时按 `custId + chargeIds` 组合控制重复申请。 - 申请成功后必须创建查询补偿上下文，不依赖回调作为唯一结果来源。 +#### 后台作废请求参数（`/business/invoice/invalidate`） + +| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 | +|------|------|------|------|---------------| +| invoiceId | Long | 是 | 发票记录 ID | `biz_invoice.id` | +| invalidReason | String | 是 | 作废原因 | `biz_invoice.invalid_reason` | +| invalidRemark | String | 否 | 作废备注 | `biz_invoice.invalid_remark` | +| originalInvoiceCode | String | 否 | 原发票代码；传入时必须与当前发票记录一致 | `biz_invoice.original_invoice_code` | +| originalInvoiceNumber | String | 否 | 原发票号码；传入时必须与当前发票记录一致 | `biz_invoice.original_invoice_number` | + +#### 后台红冲请求参数（`/business/invoice/red-ink`） + +| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 | +|------|------|------|------|---------------| +| invoiceId | Long | 是 | 发票记录 ID | `biz_invoice.id` | +| redInkReason | String | 是 | 红冲原因 | `biz_invoice.red_ink_reason` | +| redInkRemark | String | 否 | 红冲备注 | `biz_invoice.red_ink_remark` | +| originalInvoiceCode | String | 否 | 原发票代码；传入时必须与当前发票记录一致 | `biz_invoice.original_invoice_code` | +| originalInvoiceNumber | String | 否 | 原发票号码；传入时必须与当前发票记录一致 | `biz_invoice.original_invoice_number` | + +#### 后台作废/红冲处理约束 + +- 作废与红冲仅允许对当前 `invoiceStatus=SUCCESS` 的记录发起；已进入 `INVALID` 或 `RED_INK` 的记录必须拒绝重复处理。 +- 后台提交作废或红冲后，应同步写入原因、备注、原票引用与触发来源，当前实现的触发来源分别为 `ADMIN_INVALIDATE`、`ADMIN_RED_INK`。 +- 作废与红冲的即时返回仅表示后台已受理本次后处理动作；最终状态仍通过 `IF-REV-009` 查询补偿或 `IF-EXT-007` 回写统一收口。 +- 后处理动作必须保留操作日志，记录触发人、目标状态、原因、备注与原发票代码/号码。 + ### IF-REV-009 发票结果查询接口 #### 请求参数 @@ -817,7 +845,7 @@ retrieval_priority: P0 | invoiceId | Long | 发票主记录 ID | `biz_invoice.id` | | applicationNo | String | 发票申请单号 | `biz_invoice.application_no` | | sysRequestNo | String | `SYS-008` 受理号 | `biz_invoice.sys_request_no` | -| invoiceStatus | String | 状态：`SUBMITTED`、`PENDING`、`SUCCESS`、`FAIL` | `biz_invoice.invoice_status` | +| invoiceStatus | String | 状态：`SUBMITTED`、`PENDING`、`SUCCESS`、`FAIL`、`INVALID`、`RED_INK` | `biz_invoice.invoice_status` | | invoiceCode | String | 发票代码 | `biz_invoice.invoice_code` | | invoiceNumber | String | 发票号码 | `biz_invoice.invoice_number` | | fileUrl | String | 电子发票文件地址 | `biz_invoice.file_url` | @@ -834,7 +862,8 @@ retrieval_priority: P0 - 查询入口同时服务于后台人工查询与系统补偿查询，两类触发必须复用同一状态落账规则。 - 当 `querySource=AUTO_COMPENSATE` 时，接口语义表示由系统补偿任务触发一次兜底查询，并刷新最近查询时间、下次计划时间与累计次数。 - 查询结果若确认开票成功，应回写票号、票据地址与账单-发票关联状态；若仍处理中，仅维持 `PENDING` 并更新补偿上下文。 -- 已进入 `SUCCESS` 的发票记录不得被后续失败查询结果覆盖；若外部返回异常，应记录到操作留痕并保留人工核查入口。 +- 对已发起作废或红冲的记录，查询结果应允许把终态更新为 `INVALID` 或 `RED_INK`，并同步刷新 `latestResult`、`latestError`、账单关联状态与后处理上下文。 +- 已进入 `SUCCESS` 的正常开票终态不得被后续失败查询结果覆盖；若外部返回异常，应记录到操作留痕并保留人工核查入口。 ### IF-REV-011 银行代收协同接口 @@ -976,8 +1005,9 @@ retrieval_priority: P0 #### 客户侧消费约束 - 客户侧仅允许访问本人 `custId` 名下发票记录，`invoiceId`、`applicationNo`、`sysRequestNo` 任一定位成功后仍需再次校验客户归属。 -- 下载与推送前必须校验 `invoiceStatus=SUCCESS` 且 `fileUrl` 非空；不满足条件时返回不可消费原因。 +- 下载与推送前必须校验 `invoiceStatus=SUCCESS` 且 `fileUrl` 非空；已作废、已红冲或缺少电子票地址的记录一律返回不可消费原因。 - 推送成功后回写 `pushStatus=PUSHED`；失败则更新为 `FAIL` 并记录失败原因。 +- 客户侧只消费已形成有效电子票结果的记录，不暴露后台作废、红冲入口，也不直接展示后处理请求参数。 ### IF-CS-003 在线支付下单接口 @@ -1569,7 +1599,7 @@ sequenceDiagram - 账务调整、退款、坏账、冲正类精细接口 - 催缴管理中针对不同通知策略和停复水联动的细分接口 -- 发票红冲、作废、补开等票据后处理接口 +- 发票补开等扩展票据后处理接口 ### 文档先行 diff --git a/specs/002-rev005-invoice-flow/plan.md b/specs/002-rev005-invoice-flow/plan.md index 49c2429..a790712 100644 --- a/specs/002-rev005-invoice-flow/plan.md +++ b/specs/002-rev005-invoice-flow/plan.md @@ -47,7 +47,7 @@ - 一期默认后台开票，客户侧不直接申请开票 - 一期不支持原始单账单直接任意部分金额开票 - `SYS-008` 结果获取采用查询兜底，不假设回调可用 -- 本轮 implement 默认聚焦正常开票闭环，作废/红冲仅保留正式文档与后续任务预留，不作为一期必交付开发范围 +- 本轮 implement 先完成正常开票闭环收口，再在二期补齐作废/红冲的正式文档、backend 入口、状态流转与结果落账 - 仓库内引用保持相对路径口径 **Scale/Scope**: 跨文档 + backend 实施 planning，覆盖 1 个 feature spec、1 个 implementation plan、1 份 research、1 份 data-model、2 份 contracts、1 份 quickstart，并为后续 tasks/implement 提供输入。 diff --git a/specs/002-rev005-invoice-flow/spec.md b/specs/002-rev005-invoice-flow/spec.md index 8206846..6a2fc4d 100644 --- a/specs/002-rev005-invoice-flow/spec.md +++ b/specs/002-rev005-invoice-flow/spec.md @@ -2,7 +2,7 @@ **Feature Branch**: `002-rev005-invoice-flow` **Created**: 2026-03-16 -**Status**: Draft +**Status**: Verification Pending **Input**: 实现 REV-005 发票业务流核心功能：发票申请、开票校验、调用 SYS-008 发票服务、接收开票结果回写、更新发票与账单关联状态。 --- @@ -80,18 +80,20 @@ --- -### User Story 4 - 发票作废与红冲预留 (Priority: P3) +### User Story 4 - 发票作废与红冲 (Priority: P3) -为已开发票的作废和红字发票能力保留正式文档与任务入口，但一期 implement 默认不纳入本轮正常开票闭环交付。 +对已成功开具的发票提供后台作废与红冲入口，由 `SYS-008` 承接税控侧处理，`SYS-002` 负责发起申请、校验状态、查询补偿、结果回写与账单关联状态同步；客户侧仍仅消费有效电子发票结果，不直接发起作废或红冲。 -**Why this priority**: 业务完整性要求，但优先级低于正常开票流程，当前仅作为后续能力预留。 +**Why this priority**: 作废与红冲属于已开票后的后处理能力，依赖正常开票闭环，但必须在本轮二期中形成正式设计与 backend 实现入口。 -**Independent Test**: 验证正式文档已明确作废和红冲属于后续阶段能力，不影响一期正常开票流程的实现边界。 +**Independent Test**: 验证后台可对满足条件的成功发票发起作废或红冲；`SYS-008` 返回结果后，发票状态正确更新为 `INVALID` 或 `RED_INK`，并保留原票关联、失败原因与操作日志。 **Acceptance Scenarios**: -1. **Given** 一期仅交付正常开票闭环，**When** 审阅 REV-005 范围说明，**Then** 作废与红冲被标记为后续能力，不作为本轮 implement 必选范围 -2. **Given** 后续需要扩展作废或红冲，**When** 进入下一轮 planning/implement，**Then** 可在既有状态模型上继续补齐能力而不破坏当前范围边界 +1. **Given** 发票状态为 `SUCCESS` 且未作废、未红冲，**When** 后台发起作废申请，**Then** 系统校验通过并调用 `SYS-008`，成功后将发票状态更新为 `INVALID` +2. **Given** 发票状态为 `SUCCESS` 且业务要求通过红字发票冲销，**When** 后台发起红冲申请，**Then** 系统校验通过并调用 `SYS-008`，成功后将发票状态更新为 `RED_INK` +3. **Given** 发票已处于 `INVALID` 或 `RED_INK`，**When** 再次发起作废或红冲，**Then** 系统拒绝重复处理并返回明确原因 +4. **Given** `SYS-008` 未立即返回终态，**When** 系统执行主动查询或补偿查询，**Then** 保持处理中上下文并在取得终态后统一落账 --- @@ -118,7 +120,10 @@ - **FR-008**: 系统 MUST 更新发票状态（申请中/已开票/开票失败） - **FR-009**: 系统 MUST 建立发票与账单的关联关系，并保留兼容老系统拆账/分账后分别开票及后续合并开票扩展的映射能力 - **FR-010**: 系统 MUST 支持客户侧查询、下载、推送已开具的电子发票，但一期不开放客户侧直接申请开票 -- **FR-011**: 系统 MUST 记录一期关键操作日志（申请、查询、开票、结果回写、客户侧查询/下载/推送）；作废与红冲日志作为后续能力预留 +- **FR-011**: 系统 MUST 记录关键操作日志（申请、查询、开票、结果回写、客户侧查询/下载/推送、作废、红冲），并保留触发来源、状态前后值与失败原因 +- **FR-012**: 系统 MUST 提供后台发票作废入口，仅允许对已开票成功且未作废、未红冲的发票发起作废 +- **FR-013**: 系统 MUST 提供后台发票红冲入口，仅允许对已开票成功且未红冲的发票发起红字冲销，并保留原票关联信息 +- **FR-014**: 系统 MUST 通过查询补偿或结果回写统一落账作废/红冲终态，并同步更新发票状态、失败原因和账单发票关联状态 ### Key Entities @@ -191,7 +196,7 @@ ## Next Steps -1. `/speckit.clarify` - 澄清接口细节和边界情况 -2. `/speckit.plan` - 制定技术实现方案 -3. `/speckit.tasks` - 拆解开发任务 -4. `/speckit.implement` - 执行开发 +1. 在可用测试或联调环境中补充 SC-001 的响应时延采样，记录样本量、平均值、P95 与“排除外部调用”的统计口径。 +2. 为 SC-002 ~ SC-004 准备样本集与统计表，将申请通过率、回写成功率、查询/下载/推送成功率沉淀到 `specs/002-rev005-invoice-flow/verification.md`。 +3. 抽取 SC-005 运行态日志样本，核对操作人、客户、状态与日志内容是否与实现态矩阵一致。 +4. 继续跟踪 `biz_invoice` 物理 DDL / migration 来源，并在提测前明确联调、落库与批量后处理风险。 diff --git a/specs/002-rev005-invoice-flow/tasks.md b/specs/002-rev005-invoice-flow/tasks.md index 008b6b6..c7a992c 100644 --- a/specs/002-rev005-invoice-flow/tasks.md +++ b/specs/002-rev005-invoice-flow/tasks.md @@ -1,11 +1,13 @@ # Tasks: REV-005 发票业务流实现 **Input**: Design documents from `/specs/002-rev005-invoice-flow/` -**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `contracts/` +**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 实现阶段需补充最小编译/流程验证。 +**Validation**: 正式文档修改必须执行对应 `make validate-file`；涉及跨文档引用执行 `make check-links`；涉及 Mermaid/时序图执行 `make validate-mermaid`；backend 实现阶段需补充最小编译或等价流程验证，并将结果沉淀到 `specs/002-rev005-invoice-flow/verification.md`。 -**Organization**: 任务按用户故事分组，确保每个故事都可以独立实现、独立验证、独立评审。 +**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` @@ -22,29 +24,28 @@ --- -## Phase 1: Setup（共享准备） +## Phase 1: Scope & Source Confirmation (Shared Foundation) -**Purpose**: 固化本轮实现边界、目标文件和 backend 触点，避免后续修改偏离单一真源。 +**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` +- [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（共享基础能力） +## Phase 2: Foundational (Blocking Prerequisites) -**Purpose**: 先补齐所有用户故事共用的模型、状态、接口骨架与文档统一口径。 +**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` +- [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` 的校验沉淀和台账回写出口 --- @@ -52,23 +53,21 @@ **Goal**: 实现后台单笔/批量发票申请入口，完成账单状态、客户开票信息、税率和限额校验，并生成发票申请记录。 -**Independent Test**: 后台提交已收费未开票账单时能生成申请单号；未缴费、已开票、直接部分开票等场景被正确拦截；正式文档与接口合同保持一致。 +**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 后台申请与校验任务状态 +- [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 详细设计保持一致。 @@ -78,23 +77,21 @@ **Goal**: 实现提交开票申请后的异步协同、受理号记录、定时/主动查询兜底，并保证成功状态不被后续失败结果覆盖。 -**Independent Test**: 发票申请成功后生成受理号与查询任务；查询接口可按申请单号/受理号返回结果；查询异常不会覆盖既有成功状态。 +**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 查询兜底与异步协同任务状态 +- [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` 口径已稳定。 @@ -108,51 +105,60 @@ ### 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 结果回写与客户侧消费任务状态 +- [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) +## Phase 6: User Story 4 - 发票作废与红冲 (Priority: P3) -**Goal**: 将作废与红冲明确标注为后续阶段能力，只在正式文档和管理台账中保留边界与后续入口，不纳入一期 implement 必选交付。 +**Goal**: 在一期正常开票闭环基础上，补齐后台发票作废与红冲的正式文档、接口入口、状态校验、`SYS-008` 协同、查询补偿与结果落账能力。 -**Independent Test**: 审阅 spec、plan、tasks 与正式文档后，可确认作废/红冲属于后续能力预留，不要求本轮 backend 代码实现。 +**Independent Test**: 后台可对满足条件的 `SUCCESS` 发票发起作废或红冲；接口、详细设计与 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` 同步作废与红冲改为后续阶段任务预留的状态说明 +- [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**: 作废与红冲的范围边界已稳定，不再与一期正常开票闭环交付混淆。 +**Checkpoint**: 作废与红冲已从“预留”升级为可评审、可编译验证的二期能力入口。 --- ## Final Phase: Cross-Cutting Closure -**Purpose**: 完成仓库级一致性复核、统一校验、成功标准验证和交付总结。 +**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` 执行完成后输出修改文件、验证结果、剩余风险与下一步建议 +- [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` 汇总最终交付说明、剩余风险与下一步建议 --- @@ -160,29 +166,31 @@ ### Phase Dependencies -- **Setup**: 无依赖，但必须先完成，作为正式文档与 backend 触点的统一基线 -- **Foundational**: 依赖 Setup，必须在用户故事前完成 -- **US1**: 依赖 Foundational；是 MVP 的最小闭环入口 -- **US2**: 依赖 US1；需要复用申请单和受理号 -- **US3**: 依赖 US2；需要复用终态结果与查询补偿数据 -- **US4**: 依赖 US3；仅做范围预留与文档/台账标注 +- **Scope & Source Confirmation**: 无依赖；必须先完成，作为单一真源与范围边界基线 +- **Foundational**: 依赖 Scope & Source Confirmation；必须在用户故事前完成 +- **US1**: 依赖 Foundational；是 MVP 最小闭环入口 +- **US2**: 依赖 US1；复用申请单号、受理号和基础申请链路 +- **US3**: 依赖 US2；复用终态结果、查询补偿和电子票结果 +- **US4**: 依赖 US3；在正常开票闭环基础上补齐后处理能力 - **Final Phase**: 依赖所有已选择的用户故事完成 ### Within Each User Story -- 先更新正式文档，再更新 backend 接口与服务 -- 先补请求/响应对象和数据映射，再实现服务逻辑 -- 先完成内容编辑，再运行验证命令 -- 先完成验证，再更新管理台账 +- 先更新正式文档与合同，再更新 backend 接口与服务 +- 先补请求/响应对象与数据映射，再实现服务逻辑 +- 先固化文档/代码验证证据，再更新管理台账 +- 运行态样本、统计口径与 Success Criteria 证据在该故事完成后补齐 ### Parallel Opportunities -- `T004` 与 `T005` 可并行盘点 backend 依赖 -- `T011` 与 `T012` 可并行新增 VO 骨架 +- `T003` 与 `T004` 可并行确认正式文档与 backend 触点 +- `T009` 与 `T010` 可并行确认 VO 及外部依赖对象 - US1 中 `T017` 与 `T018` 可并行 -- US2 中 `T030` 与 `T031` 可并行 -- US3 中 `T044` 与 `T045` 可并行 -- `T057` 与 `T058` 可并行执行 +- US2 中 `T028` 与 `T029` 可并行 +- US3 中 `T039` 与 `T040` 可并行 +- US4 中 `T051` 与 `T052` 可并行 +- Final Phase 中 `T056` 与 `T057` 可并行 +- Final Phase 中 `T060`、`T061`、`T062`、`T063` 可在样本准备完成后并行统计 --- @@ -190,22 +198,24 @@ ### MVP First -1. 完成 Phase 1-2，统一正式文档与 backend 触点基线 -2. 优先交付 **US1 发票申请与校验**，形成最小可用后台入口 -3. 再交付 **US2 异步协同与查询兜底**，完成 `SYS-008` 结果获取闭环 -4. 再交付 **US3 结果回写、账单关联与客户侧消费**，形成一期完整业务闭环 -5. **US4 作废与红冲预留** 仅保留文档与台账入口，不纳入本轮 backend 实现 +1. 先完成 Shared Foundation，统一文档、接口、数据和台账出口。 +2. 优先交付 **US1 发票申请与校验**，形成后台最小受理入口。 +3. 再交付 **US2 异步协同与查询兜底**，完成 `SYS-008` 结果获取闭环。 +4. 再交付 **US3 结果回写、账单关联与客户侧消费**，形成一期完整业务闭环。 +5. 最后交付 **US4 作废与红冲**，补齐二期后处理入口。 +6. 进入 Final Phase，集中补齐 Success Criteria 量化证据和最终交付摘要。 ### Independent Test Criteria by Story -- **US1**: 后台发票申请成功生成申请单号，非法账单/直接部分开票被拦截 +- **US1**: 后台发票申请成功生成申请单号，非法账单/原始单账单直接部分开票被拦截 - **US2**: 查询接口可按申请单号或受理号返回结果，成功终态不被失败覆盖 - **US3**: 结果回写后账单与发票关联可查，客户侧只能查看并下载/推送本人已开票电子票 -- **US4**: 作废与红冲被稳定标注为后续阶段能力，不与一期实现范围冲突 +- **US4**: 后台可发起作废/红冲，终态正确更新为 `INVALID` 或 `RED_INK`，且保留原票关系、失败原因与日志留痕 ### Notes -- 本任务集同时覆盖正式文档收敛与 backend 实施准备，执行时应始终以 `specs/002-rev005-invoice-flow/spec.md` 为单一需求总源 -- Archive 文档仅用于校验与追溯，不作为正式交付主稿直接替代 -- 仓库内未找到 `.specify/scripts/bash/check-prerequisites.sh`，本轮按现有 planning artifacts 手工推进 Speckit 任务流 -- Success Criteria 已显式映射到 Final Phase 验证任务，若当前环境无法完成统计验证，应至少产出明确的验证记录与剩余风险说明 +- 本任务清单已修复旧版 `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 脚本。