fujian_water_biz_doc/specs/002-rev005-invoice-flow/verification.md

# REV-005 验证记录

## 1. 验证范围

本记录用于沉淀 `REV-005` 当前已完成的发票业务闭环验证证据，覆盖以下范围：

- US1：后台发票申请与校验
- US2：`SYS-008` 异步协同与查询兜底
- US3：结果回写、账单关联与客户侧电子发票消费
- US4：后台作废与红冲二期入口

当前验证结论以已执行命令、已完成文档修订、最小编译验证和范围边界复核为主；`spec.md` 中 `SC-001 ~ SC-005` 的性能/统计指标尚未形成专门压测脚本或批量样本统计，本文件先记录现有证据、缺口与后续建议。

## 2. 已执行验证命令与结果

| 类别 | 命令 | 结果 | 说明 |
|------|------|------|------|
| 文档单文件校验 | `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` | 通过 | 已用于验证发票数据承接口径 |
| 文档单文件校验 | `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` | 通过 | 已用于验证客户侧查询/下载/推送与作废/红冲接口边界文档 |
| 文档单文件校验 | `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` | 通过 | 已用于验证 REV-005 二期作废/红冲详细设计修订 |
| backend 最小编译 | `mvn -f backend/sw-business/sw-business-server/pom.xml -DskipTests compile` | 通过 | 已用于验证 REV-005 US3/US4 代码可编译 |
| 仓库交叉引用校验 | `make check-links` | 通过 | 当前链接检查输出为“所有链接检查通过” |
| Mermaid 语法校验 | `make validate-mermaid` | 通过 | 当前 Mermaid 验证输出为“所有 mermaid 图表语法验证通过” |
| 验收资产复核 | 仓库关键字检索（`SC-001`、`SC-002`、`SC-003`、`SC-004`、`样本统计`、`压测脚本`、`P95`） | 未发现现成统计资产 | 当前仓库内暂未定位到可直接复用的压测脚本、统计脚本或样本台账，SC-001 ~ SC-004 仍需在测试或联调环境补充专项证据 |

## 3. Success Criteria 对照

### SC-001 发票申请接口响应时间 < 500ms（不包含外部服务调用）

- **当前状态**：待补充专项验证（实现态证据已补强）
- **现有证据**：backend 最小编译通过，后台申请接口与校验链路已实现
- **实现态补充证据**：`InvoiceController.applyInvoice` 已固定暴露 `/business/invoice/apply` 入口；`InvoiceApplyReqVO` 强制要求 `chargeIds`、`custId`、`invoiceType`、`invoiceTitle`、`sourceChannel`；`InvoiceServiceImpl.applyInvoice` 当前同步执行的仅包括账单去重排序、幂等单号生成、客户/客户开票信息/账单/税率校验、`InvoiceDO` 落库与操作日志写入，并未在该方法内直接同步调用外部 `SYS-008`，而是通过生成 `sysRequestNo`、写入 `PENDING` 状态后结束本地受理流程。
- **缺口说明**：尚未执行接口响应时延采样，也未沉淀固定样本、环境与统计结果
- **后续建议**：在可用测试环境中对 `/business/invoice/apply` 执行最小样本压测或定点采样，至少记录样本量、平均值、P95、排除外部调用口径
- **建议统计口径**：仅统计 `SYS-002` 本地受理、账单/客户/税率/限额校验、申请记录落库等内部处理时延；明确剔除 `SYS-008` 外部接口等待时间；结果表至少记录样本时间、样本环境、请求体摘要、平均值、P95、最大值与异常样本说明

### SC-002 发票申请校验通过率 > 95%（正常业务场景）

- **当前状态**：待补充样本统计（实现态证据已补强）
- **现有证据**：已实现账单收费状态、开票状态、客户开票信息、税率配置、开票限额、幂等控制等校验规则
- **实现态补充证据**：`validateCustInvoice` 已明确拦截“客户未维护开票信息”“客户开票信息不存在”“发票抬头不一致”“税号不一致”“电子发票缺少邮箱/手机号”等场景；`validateCharges` 已明确拦截“账单不存在”“账单与客户不匹配”“仅已收费账单允许申请开票”“存在已开票账单”；`validateInvoiceTaxrate` 会拦截缺少可用税率配置；`applyInvoice` 对同一 `applicationNo` 或 `custId + chargeIds` 组合会直接返回既有申请，因此幂等命中样本应单列说明，不能混入正常成功率分母。
- **缺口说明**：尚未基于真实或模拟样本形成“正常场景通过率”统计
- **后续建议**：准备覆盖正常账单、已开票账单、未缴费账单、限额超限账单等样本集，按样本分组输出通过/拦截统计
- **建议统计口径**：将样本分为“正常业务场景”和“规则拦截场景”两组；SC-002 仅统计正常业务场景的申请成功率，结果表至少记录样本总数、成功数、失败数、失败原因分类，并单列幂等命中、原始单账单直接部分开票拦截等非正常场景说明

### SC-003 开票结果回写成功率 > 99%

- **当前状态**：待补充样本统计（实现态证据已补强）
- **现有证据**：已实现结果回写、成功终态保护、账单状态联动、失败原因留痕
- **实现态补充证据**：`writeBackInvoice` 已支持按 `applicationNo` / `sysRequestNo` 定位发票，统一回写 `invoiceStatus`、`invoiceCode`、`invoiceNumber`、`fileUrl`、`pushStatus`、`latestResult`、`latestError` 与 `failReason`，并调用 `syncChargeInvoiceState` 做账单联动；若当前记录已是 `SUCCESS` 且收到非成功回写，会命中“成功终态保护”分支，仅刷新查询上下文与日志，不覆盖既有成功结果；`queryInvoice` 与 `/query/compensate` 复用 `refreshQueryContext`，可为回写失败、超时与补偿查询样本提供统一追溯键。
- **缺口说明**：尚未基于批量样本统计回写成功率
- **后续建议**：在联调或测试环境中按申请单号、受理号建立样本集，统计回写请求总量、成功量、失败量与失败原因分类
- **建议统计口径**：按“回写请求总量”“业务成功落账量”“业务失败量”“因成功终态保护而不覆盖原状态量”四类指标统计；失败样本需区分外部返回失败、查询超时、账单联动异常、数据缺失等分类，并保留申请单号/受理号映射以便追溯

### SC-004 电子发票下载成功率 > 99%

- **当前状态**：待补充样本统计（实现态证据已补强）
- **现有证据**：已实现仅 `SUCCESS + fileUrl` 可下载/推送的前置校验，客户归属校验与推送状态回写已落地
- **实现态补充证据**：`getRequiredCustomerInvoice` 已要求 `custId` 必填，且 `invoiceId`、`applicationNo`、`sysRequestNo` 至少提供一个定位键，并会拦截“未找到当前客户可访问的电子发票”；`validateDownloadableInvoice` 已明确拦截“当前发票状态不可下载或推送”“电子发票文件地址不存在”；`pushInvoice` 仅支持 `EMAIL`、`SMS` 两类渠道，并分别校验邮箱/手机号是否可用，成功后会更新 `pushStatus`、`latestResult` 并记录渠道与目标。
- **缺口说明**：尚未形成客户侧下载成功率样本统计
- **后续建议**：在具备有效电子票文件地址的样本下，统计查询、下载、推送三类动作成功率，并区分“无权限”“无文件”“非成功终态”等拦截原因
- **建议统计口径**：以具备有效 `SUCCESS + fileUrl` 条件的样本作为成功率分母，同时单独记录被权限校验、文件缺失、非成功终态拦截的请求量；建议分别输出“客户查询成功率”“下载成功率”“推送成功率”三个子指标，避免把前置拦截与真实下载失败混为一类

### SC-005 操作日志完整率 100%（所有关键操作均有日志）

- **当前状态**：实现态证据已补齐，运行态样本待抽查
- **现有证据**：`InvoiceServiceImpl` 已通过统一 `recordInvoiceOperatLog` 入口写入关键动作日志，并由 `OperatLogService.createOperatLog` 承接操作人、客户标识与日志内容上下文
- **关键动作 ↔ 日志写入点矩阵**：

| 关键动作 | 业务入口 | 日志写入点 | 说明 |
|------|------|------|------|
| 发票申请 / 提交 SYS-008 开票申请 | `applyInvoice` | `recordInvoiceOperatLog(invoice, "提交SYS-008开票申请...")` | 记录申请受理与受理号 |
| 后台查询结果 | `queryInvoice` → `refreshQueryContext` | `recordInvoiceOperatLog(invoice, "发票查询补偿，来源：...")` | 普通查询与补偿查询复用同一留痕点，依赖 `querySource` 区分 |
| 结果回写 | `writeBackInvoice` | `recordInvoiceOperatLog(invoice, "回写发票结果...")` | 成功/失败终态更新后统一留痕 |
| 成功终态保护 | `writeBackInvoice` | `recordInvoiceOperatLog(invoice, "收到回写结果但因成功终态保护未覆盖原状态...")` | 记录保护分支未覆盖原状态的原因 |
| 客户侧查询 | `queryCustomerInvoice` → `refreshCustomerQueryContext` | `recordInvoiceOperatLog(invoice, "发票查询补偿，来源：CUSTOMER_QUERY...")` | 记录客户侧查询动作 |
| 客户侧下载 | `downloadInvoice` | `recordInvoiceOperatLog(invoice, "客户侧下载电子发票")` | 记录电子发票下载动作 |
| 客户侧推送 | `pushInvoice` | `recordInvoiceOperatLog(invoice, "客户侧推送电子发票...")` | 记录推送渠道与目标 |
| 后台作废 | `invalidateInvoice` | `recordInvoiceOperatLog(invoice, buildPostProcessLog(...))` | 记录原因、备注与原票代码/号码 |
| 后台红冲 | `redInkInvoice` | `recordInvoiceOperatLog(invoice, buildPostProcessLog(...))` | 记录原因、备注与原票代码/号码 |

- **缺口说明**：尚未在测试或联调环境按上述矩阵逐项抽取实际日志样本，当前仍缺运行态日志记录证据
- **DDL/迁移跟进结论**：已交叉核查 `backend/sql`、Archive 数据库设计、`sql/lhc_数据库设计.md` 与 `BACKEND_TABLE_MAPPING.md`；当前仍未定位到与 `InvoiceDO` 最新字段完全一致的 `biz_invoice` 物理 DDL / migration 脚本，现有同名历史对象更偏开票配置表，US4 的物理落库链路仍需继续结合实际数据库变更记录确认。
- **后续建议**：按矩阵至少抽取申请、补偿查询、结果回写、客户下载、客户推送、作废、红冲各 1 条日志样本，核对操作人、客户、状态与日志内容是否一致

### 待补样本记录模板（不含实际结果）

#### T060 / SC-001 响应时延记录模板

| 采样时间 | 环境 | 接口 | 样本量 | 平均值(ms) | P95(ms) | 最大值(ms) | 是否剔除 `SYS-008` 等待 | 异常样本说明 |
|------|------|------|------:|------:|------:|------:|------|------|
| 待补 | 待补 | `/business/invoice/apply` | 待补 | 待补 | 待补 | 待补 | 是 / 否（待补） | 待补 |

- **待补说明**：采样时需同步记录请求体摘要（账单数、开票类型、客户类型）与测试环境配置，避免不同批次结果不可比。

#### T061 / SC-002 申请通过率记录模板

| 样本分组 | 样本总数 | 成功数 | 失败数 | 失败原因分类 | 统计口径说明 |
|------|------:|------:|------:|------|------|
| 正常业务场景 | 待补 | 待补 | 待补 | 待补 | 仅统计应当成功的申请样本 |
| 规则拦截场景 | 待补 | 待补 | 待补 | 待补 | 单独记录，不计入 SC-002 分母 |

- **待补说明**：建议至少覆盖正常账单、已开票账单、未缴费账单、限额超限账单、幂等命中、原始单账单直接部分开票拦截等样本。

#### T062 / SC-003 回写成功率记录模板

| 回写批次 | 回写请求总量 | 业务成功落账量 | 业务失败量 | 成功终态保护量 | 失败原因分类 | 追溯主键 |
|------|------:|------:|------:|------:|------|------|
| 待补 | 待补 | 待补 | 待补 | 待补 | 待补 | `applicationNo` / `sysRequestNo`（待补） |

- **待补说明**：失败原因建议至少区分外部返回失败、查询超时、账单联动异常、数据缺失；同一批次需保留申请单号与受理号映射关系。

#### T063 / SC-004 客户侧查询/下载/推送成功率记录模板

| 动作类型 | 样本总数 | 成功数 | 失败数 | 前置拦截数 | 失败/拦截原因分类 | 统计口径说明 |
|------|------:|------:|------:|------:|------|------|
| 客户查询 | 待补 | 待补 | 待补 | 待补 | 待补 | 仅统计客户侧查询动作 |
| 发票下载 | 待补 | 待补 | 待补 | 待补 | 待补 | 分母建议取具备 `SUCCESS + fileUrl` 条件的样本 |
| 发票推送 | 待补 | 待补 | 待补 | 待补 | 待补 | 单列推送渠道与目标类型 |

- **待补说明**：需区分“无权限”“无文件”“非成功终态”等前置拦截，不建议与真实下载/推送失败混算。

#### T055 / SC-005 运行态日志抽样模板

| 动作类型 | 样本来源 | 操作人/客户 | 状态前后值 | 日志摘要 | 结果 |
|------|------|------|------|------|------|
| 发票申请 | 待补 | 待补 | 待补 | 待补 | 待补 |
| 查询补偿 | 待补 | 待补 | 待补 | 待补 | 待补 |
| 结果回写 | 待补 | 待补 | 待补 | 待补 | 待补 |
| 客户下载 | 待补 | 待补 | 待补 | 待补 | 待补 |
| 客户推送 | 待补 | 待补 | 待补 | 待补 | 待补 |
| 后台作废 | 待补 | 待补 | 待补 | 待补 | 待补 |
| 后台红冲 | 待补 | 待补 | 待补 | 待补 | 待补 |

- **待补说明**：样本抽取时需能回扣到 `recordInvoiceOperatLog` / `OperatLogService.createOperatLog` 的实现态矩阵，并保留查询来源、渠道、原票代码/号码等关键上下文。
- **DDL 跟进说明**：与日志样本同步收口时，还需补记本轮核查结论：当前仓库仍未定位到与 `InvoiceDO` 当前模型完全对齐的 `biz_invoice` 物理 DDL / migration 来源；若联调环境已完成数据库变更，应同时记录变更单号、脚本路径或 DBA 提供的物理表结构证明。

### 待补样本执行入口清单

| 对应待办 | 接口/合同 | 当前请求路径 | Controller 入口 | Service 入口 | 说明 |
|------|------|------|------|------|------|
| `T060` / `T061` | `IF-REV-008` | `/business/invoice/apply` | `InvoiceController.applyInvoice` | `InvoiceService.applyInvoice` / `InvoiceServiceImpl.applyInvoice` | 用于申请时延采样与正常/拦截样本统计 |
| `T062` | `IF-REV-009` | `/business/invoice/query`、`/business/invoice/query/compensate`、`/business/invoice/write-back` | `InvoiceController.queryInvoice`、`compensateQueryInvoice`、`writeBackInvoice` | `InvoiceService.queryInvoice`、`writeBackInvoice` / `InvoiceServiceImpl.queryInvoice`、`writeBackInvoice` | 用于查询补偿、回写成功率与成功终态保护样本 |
| `T063` | `IF-CS-004` | `/business/invoice/customer/query`、`/business/invoice/customer/download`、`/business/invoice/customer/push` | `InvoiceController.queryCustomerInvoice`、`downloadInvoice`、`pushInvoice` | `InvoiceService.queryCustomerInvoice`、`downloadInvoice`、`pushInvoice` / `InvoiceServiceImpl.queryCustomerInvoice`、`downloadInvoice`、`pushInvoice` | 用于客户查询、下载、推送成功率统计 |
| `T055` | `IF-REV-008`、`IF-REV-009`、`IF-CS-004`、`IF-EXT-007` | `/business/invoice/apply`、`/business/invoice/query`、`/business/invoice/customer/*`、`/business/invoice/invalidate`、`/business/invoice/red-ink` | `InvoiceController.applyInvoice`、`queryInvoice`、`queryCustomerInvoice`、`downloadInvoice`、`pushInvoice`、`invalidateInvoice`、`redInkInvoice` | `InvoiceServiceImpl.applyInvoice`、`queryInvoice`、`writeBackInvoice`、`queryCustomerInvoice`、`downloadInvoice`、`pushInvoice`、`invalidateInvoice`、`redInkInvoice` | 用于运行态日志抽样与动作-日志矩阵回扣 |

- **执行说明**：当前仓库正式文档与 backend `InvoiceController` 的实现入口统一使用 `/business/invoice/*` 路径；若后续联调环境存在网关前缀或转发规则，应在样本记录中额外注明映射关系。
- **本地验证入口排查结论**：当前仓库 `quickstart.md` 未提供可直接复用的 `curl` / Postman / HTTP 脚本来采集 `T055`、`T060 ~ T063` 的真实样本；现阶段可直接依赖的入口主要是接口设计、`InvoiceController` 路径声明与 `InvoiceService(Impl)` 调用链，真实样本仍需在可用测试或联调环境手工执行并回填。

### 最小请求模板（待联调填真实值）

- **用途说明**：以下 JSON 仅作为 `T055`、`T060 ~ T063` 的最小请求体草稿，用于后续在测试或联调环境手工发起请求并回填真实样本。
- **填写约束**：示例中的 `applicationNo`、`sysRequestNo`、`invoiceId`、`chargeIds`、`custId` 等值均为占位符，执行前必须替换为环境中的真实数据。

#### `/business/invoice/apply`

```json
{
  "chargeIds": [10001],
  "custId": 1024,
  "invoiceType": "ELECTRONIC",
  "invoiceTitle": "福建水务测试客户",
  "sourceChannel": "COUNTER"
}
```

- **最小必填字段来源**：`chargeIds`、`custId`、`invoiceType`、`invoiceTitle`、`sourceChannel`
- **可选补充字段**：`applicationNo`（幂等单号）、`taxNo`、`email`、`mobile`、`remark`

#### `/business/invoice/query`

```json
{
  "applicationNo": "APP-REV005-001",
  "querySource": "MANUAL"
}
```

- **最小必填字段来源**：`querySource`
- **定位建议**：`applicationNo`、`sysRequestNo` 二选一至少补一个真实定位键，避免联调时无法唯一定位申请记录

#### `/business/invoice/query/compensate`

```json
{
  "applicationNo": "APP-REV005-001",
  "querySource": "AUTO_COMPENSATE"
}
```

- **最小必填字段来源**：`querySource`
- **说明**：controller 会按补偿查询语义覆盖 `querySource`，但请求体仍建议显式传入 `AUTO_COMPENSATE`

#### `/business/invoice/write-back`

```json
{
  "applicationNo": "APP-REV005-001",
  "invoiceStatus": "SUCCESS"
}
```

- **最小必填字段来源**：`invoiceStatus`
- **定位建议**：`applicationNo`、`sysRequestNo` 二选一至少补一个真实定位键；若为成功样本，建议同步补 `invoiceCode`、`invoiceNumber`、`fileUrl`

#### `/business/invoice/customer/query`

```json
{
  "custId": 1024,
  "invoiceId": 2048
}
```

- **最小 Bean Validation 字段**：`custId`
- **定位建议**：联调时应至少补 `applicationNo`、`sysRequestNo`、`invoiceId` 之一；上例默认使用 `invoiceId` 作为定位键

#### `/business/invoice/customer/download`

```json
{
  "custId": 1024,
  "invoiceId": 2048
}
```

- **最小 Bean Validation 字段**：`custId`
- **定位建议**：与客户查询一致，联调时应至少补 `applicationNo`、`sysRequestNo`、`invoiceId` 之一

#### `/business/invoice/customer/push`

```json
{
  "custId": 1024,
  "invoiceId": 2048,
  "pushChannel": "EMAIL",
  "pushEmail": "test@example.com"
}
```

- **最小必填字段来源**：`custId`、`invoiceId`、`pushChannel`
- **渠道补充说明**：`pushChannel=EMAIL` 时建议同时补 `pushEmail`；`pushChannel=SMS` 时建议同时补 `pushMobile`

#### `/business/invoice/invalidate`

```json
{
  "invoiceId": 2048,
  "invalidReason": "测试作废样本"
}
```

- **最小必填字段来源**：`invoiceId`、`invalidReason`
- **可选补充字段**：`invalidRemark`、`originalInvoiceCode`、`originalInvoiceNumber`

#### `/business/invoice/red-ink`

```json
{
  "invoiceId": 2048,
  "redInkReason": "测试红冲样本"
}
```

- **最小必填字段来源**：`invoiceId`、`redInkReason`
- **可选补充字段**：`redInkRemark`、`originalInvoiceCode`、`originalInvoiceNumber`

### 执行命令草稿与样本采集顺序

- **使用原则**：以下命令仅作为测试或联调环境的执行草稿，不包含真实环境地址、鉴权信息与业务主键；执行前需替换 `${BASE_URL}`、`${TOKEN}`、`${APPLICATION_NO}`、`${SYS_REQUEST_NO}`、`${INVOICE_ID}`、`${CUST_ID}`、`${CHARGE_ID}` 等占位符。
- **结果约束**：命令执行后的真实响应、日志截图、统计数值不得预填，需在拿到实际结果后回填到本文件对应模板。

#### 通用命令头草稿

```bash
curl -X POST "${BASE_URL}/business/invoice/apply" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"chargeIds":[${CHARGE_ID}],"custId":${CUST_ID},"invoiceType":"ELECTRONIC","invoiceTitle":"福建水务测试客户","sourceChannel":"COUNTER"}'
```

- **说明**：若联调环境存在网关前缀、灰度路由、租户头或其他鉴权头，应在执行记录中一并注明。

#### T060 / T061：申请时延与通过率采样顺序

1. 使用正常账单样本执行 `/business/invoice/apply`，记录请求时间、响应时间、`applicationNo` 与是否命中正常受理。
2. 复用同一命令替换不同样本，分别覆盖已开票、未缴费、限额超限、幂等命中、原始单账单直接部分开票等场景。
3. 将正常业务场景样本汇总到 `T061 / SC-002` 表，将规则拦截场景单独归类，不计入 SC-002 分母。

```bash
curl -X POST "${BASE_URL}/business/invoice/apply" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"chargeIds":[${CHARGE_ID}],"custId":${CUST_ID},"invoiceType":"ELECTRONIC","invoiceTitle":"福建水务测试客户","sourceChannel":"COUNTER"}'
```

#### T062：回写成功率采样顺序

1. 先对已申请样本执行 `/business/invoice/query`，确认当前状态与 `sysRequestNo`。
2. 对已拿到税控结果的样本执行 `/business/invoice/write-back`，分别覆盖成功回写、失败回写、成功终态保护三类场景。
3. 若存在查询兜底场景，再执行 `/business/invoice/query/compensate`，补录补偿查询命中情况与失败分类。

```bash
curl -X POST "${BASE_URL}/business/invoice/query" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"applicationNo":"${APPLICATION_NO}","querySource":"MANUAL"}'

curl -X POST "${BASE_URL}/business/invoice/write-back" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"applicationNo":"${APPLICATION_NO}","invoiceStatus":"SUCCESS"}'

curl -X POST "${BASE_URL}/business/invoice/query/compensate" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"applicationNo":"${APPLICATION_NO}","querySource":"AUTO_COMPENSATE"}'
```

#### T063：客户侧查询 / 下载 / 推送采样顺序

1. 先执行 `/business/invoice/customer/query`，确认客户归属与发票定位键可用。
2. 对满足 `SUCCESS + fileUrl` 的样本执行 `/business/invoice/customer/download`。
3. 在同一批样本上继续执行 `/business/invoice/customer/push`，按 `EMAIL`、`SMS` 等渠道分别统计。

```bash
curl -X POST "${BASE_URL}/business/invoice/customer/query" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"custId":${CUST_ID},"invoiceId":${INVOICE_ID}}'

curl -X POST "${BASE_URL}/business/invoice/customer/download" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"custId":${CUST_ID},"invoiceId":${INVOICE_ID}}'

curl -X POST "${BASE_URL}/business/invoice/customer/push" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"custId":${CUST_ID},"invoiceId":${INVOICE_ID},"pushChannel":"EMAIL","pushEmail":"test@example.com"}'
```

#### T055：运行态日志抽样顺序

1. 任选一组完整样本，按“申请 → 查询/补偿 → 回写 → 客户查询/下载/推送 → 作废或红冲”顺序执行。
2. 每执行一步立即在日志系统或数据库中抽取对应操作日志，核对操作人、客户标识、状态前后值与日志摘要。
3. 作废与红冲建议分别至少准备 1 条独立成功样本，避免同一张票重复处理导致统计混淆。

```bash
curl -X POST "${BASE_URL}/business/invoice/invalidate" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"invoiceId":${INVOICE_ID},"invalidReason":"测试作废样本"}'

curl -X POST "${BASE_URL}/business/invoice/red-ink" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"invoiceId":${INVOICE_ID},"redInkReason":"测试红冲样本"}'
```

- **日志抽样补充要求**：若运行态日志需经 Kibana、数据库表或应用日志文件检索取得，应在样本记录中额外注明检索入口、检索条件与截图/导出附件位置。

### 当天联调最小执行卡片

适用场景：当天已经拿到可用环境、鉴权信息和最小样本，目标不是重新梳理设计，而是直接补 `T060`、`T061`、`T062`、`T063`、`T055` 的真实证据。

#### 开始前只确认 6 件事

| 检查项 | 最低要求 |
|------|------|
| `BASE_URL` | 已确认实际网关地址和前缀 |
| `TOKEN` | 已确认可访问 `/business/invoice/*` 的鉴权信息 |
| 正常申请样本 | 至少 1 组可成功申请的 `custId + chargeIds` |
| 规则拦截样本 | 至少 2 组，如未缴费、已开票、限额超限或重复申请 |
| 成功发票样本 | 至少 1 组能进入 `SUCCESS + fileUrl` |
| 日志入口 | 已确认日志查询入口或数据库检索方式 |

#### 当天最小执行顺序

| 顺序 | 动作 | 目标待办 | 最少产出 |
|------|------|------|------|
| 1 | 执行 `/business/invoice/apply` 正常样本和拦截样本 | `T060`、`T061` | 响应时间、`applicationNo`、成功/拦截分类 |
| 2 | 对成功申请样本执行 `/business/invoice/query` | `T062` | `sysRequestNo`、当前状态、查询结果 |
| 3 | 执行 `/business/invoice/write-back`，至少覆盖 `SUCCESS` 和 1 类失败 | `T062` | 回写结果、失败分类、是否命中成功终态保护 |
| 4 | 对兜底样本执行 `/business/invoice/query/compensate` | `T062` | 补偿查询结果 |
| 5 | 对 `SUCCESS + fileUrl` 样本执行客户侧查询/下载/推送 | `T063` | 查询结果、下载结果、推送结果 |
| 6 | 对成功样本执行作废或红冲，并立即抽取日志 | `T055` | 后处理结果、状态前后值、日志样本 |

#### 当天必须回填的 5 个位置

| 待办 | 回填位置 | 最低回填要求 |
|------|------|------|
| `T060` | `SC-001` 响应时延表 | 样本量、平均值、P95、最大值 |
| `T061` | `SC-002` 申请通过率表 | 正常样本与拦截样本分组统计 |
| `T062` | `SC-003` 回写成功率表 | 成功量、失败量、失败分类、保护量 |
| `T063` | `SC-004` 客户侧消费表 | 查询/下载/推送三类统计 |
| `T055` | `SC-005` 日志抽样表 | 至少 1 条关键动作日志样本 |

#### 当天结束前的收口判断

- 若已拿到真实样本，但还没回填正式表格：不要关闭 `tasks.md` 中对应待办。
- 若已回填表格，但没有请求报文、响应报文或日志截图：仍视为证据不完整。
- 只有“样本已拿到 + 表格已回填 + 附件已留存”同时满足，才建议勾掉对应任务。

#### 当天可直接复制的变量模板

```bash
export BASE_URL="https://your-host"
export TOKEN="replace-with-real-token"

export CUST_ID="1024"
export CHARGE_ID="10001"
export INVOICE_ID="2048"

export APPLICATION_NO="APP-REV005-001"
export SYS_REQUEST_NO="SYS008-APP-REV005-001"

export PUSH_EMAIL="test@example.com"
export PUSH_MOBILE="13800000000"
```

#### 当天可直接复制的最小命令组

```bash
# 1. 申请
curl -X POST "${BASE_URL}/business/invoice/apply" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"chargeIds\":[${CHARGE_ID}],\"custId\":${CUST_ID},\"invoiceType\":\"ELECTRONIC\",\"invoiceTitle\":\"福建水务测试客户\",\"sourceChannel\":\"COUNTER\"}"

# 2. 查询
curl -X POST "${BASE_URL}/business/invoice/query" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"applicationNo\":\"${APPLICATION_NO}\",\"querySource\":\"MANUAL\"}"

# 3. 回写成功
curl -X POST "${BASE_URL}/business/invoice/write-back" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"applicationNo\":\"${APPLICATION_NO}\",\"sysRequestNo\":\"${SYS_REQUEST_NO}\",\"invoiceStatus\":\"SUCCESS\",\"invoiceCode\":\"FPDM001\",\"invoiceNumber\":\"FPHM001\",\"fileUrl\":\"https://example.com/invoice.pdf\"}"

# 4. 补偿查询
curl -X POST "${BASE_URL}/business/invoice/query/compensate" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"applicationNo\":\"${APPLICATION_NO}\",\"querySource\":\"AUTO_COMPENSATE\"}"

# 5. 客户侧查询 / 下载 / 推送
curl -X POST "${BASE_URL}/business/invoice/customer/query" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"custId\":${CUST_ID},\"invoiceId\":${INVOICE_ID}}"

curl -X POST "${BASE_URL}/business/invoice/customer/download" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"custId\":${CUST_ID},\"invoiceId\":${INVOICE_ID}}"

curl -X POST "${BASE_URL}/business/invoice/customer/push" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"custId\":${CUST_ID},\"invoiceId\":${INVOICE_ID},\"pushChannel\":\"EMAIL\",\"pushEmail\":\"${PUSH_EMAIL}\"}"

# 6. 作废 / 红冲
curl -X POST "${BASE_URL}/business/invoice/invalidate" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"invoiceId\":${INVOICE_ID},\"invalidReason\":\"测试作废样本\"}"

curl -X POST "${BASE_URL}/business/invoice/red-ink" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"invoiceId\":${INVOICE_ID},\"redInkReason\":\"测试红冲样本\"}"
```

#### 单日执行记录表

| 时间 | 执行动作 | 样本主键 | 响应摘要 | 日志是否已取到 | 已回填位置 |
|------|------|------|------|------|------|
| 待补 | apply | `applicationNo` / `chargeId` | 待补 | 待补 | `T060/T061` |
| 待补 | query | `applicationNo` / `sysRequestNo` | 待补 | 待补 | `T062` |
| 待补 | write-back | `applicationNo` / `sysRequestNo` | 待补 | 待补 | `T062` |
| 待补 | compensate | `applicationNo` / `sysRequestNo` | 待补 | 待补 | `T062` |
| 待补 | customer query | `invoiceId` / `custId` | 待补 | 待补 | `T063` |
| 待补 | download | `invoiceId` / `custId` | 待补 | 待补 | `T063` |
| 待补 | push | `invoiceId` / `custId` | 待补 | 待补 | `T063` |
| 待补 | invalidate / red-ink | `invoiceId` | 待补 | 待补 | `T055` |

### 联调补录清单（按顺序执行）

| 步骤 | 对应待办 | 执行动作 | 主要输入 | 预期产出 | 回填位置 |
|------|------|------|------|------|------|
| 1 | `T060`、`T061` | 准备正常样本与规则拦截样本，执行 `/business/invoice/apply` | `BASE_URL`、鉴权头、`custId`、`chargeIds`、账单分组清单 | 响应报文、耗时、`applicationNo`、成功/拦截结论 | `T060 / SC-001`、`T061 / SC-002` 模板 |
| 2 | `T062` | 对步骤 1 成功样本执行 `/business/invoice/query`，确认当前状态与 `sysRequestNo` | `applicationNo` 或 `sysRequestNo` | 查询结果、受理号、当前状态 | `T062 / SC-003` 模板 |
| 3 | `T062` | 执行 `/business/invoice/write-back`，覆盖成功、失败、成功终态保护样本 | `applicationNo` / `sysRequestNo`、`invoiceStatus` | 回写结果、失败分类、成功终态保护命中情况 | `T062 / SC-003` 模板 |
| 4 | `T062` | 对兜底样本执行 `/business/invoice/query/compensate` | `applicationNo` / `sysRequestNo` | 补偿查询结果、失败分类、补偿是否命中 | `T062 / SC-003` 模板 |
| 5 | `T063` | 执行 `/business/invoice/customer/query`，确认客户归属与发票定位键有效 | `custId`、`invoiceId` / `applicationNo` / `sysRequestNo` | 查询结果、客户归属校验结论 | `T063 / SC-004` 模板 |
| 6 | `T063` | 对 `SUCCESS + fileUrl` 样本执行 `/business/invoice/customer/download` | `custId`、`invoiceId` | 下载结果、前置拦截/真实失败分类 | `T063 / SC-004` 模板 |
| 7 | `T063` | 对同批样本执行 `/business/invoice/customer/push`，按渠道分别采样 | `custId`、`invoiceId`、`pushChannel` | 推送结果、渠道分类、失败原因 | `T063 / SC-004` 模板 |
| 8 | `T055` | 基于已成功样本执行 `/business/invoice/invalidate` 与 `/business/invoice/red-ink` | `invoiceId`、作废/红冲原因 | 后处理结果、日志抽样、状态前后值 | `T055 / SC-005` 模板 |
| 9 | `T055` | 从日志系统、数据库表或应用日志文件提取关键动作留痕 | 检索入口、检索条件、时间窗口 | 日志截图/导出件、操作人/客户/状态核对结果 | `T055 / SC-005` 模板 |

- **执行顺序约束**：步骤 2 ~ 4 依赖步骤 1 至少生成一批成功申请样本；步骤 6 ~ 8 依赖样本已达到 `SUCCESS` 且可定位到目标发票。
- **补录原则**：每完成一步就即时回填对应表格，不要等全部联调结束后再集中补录，避免申请单号、受理号、日志检索条件丢失。
- **证据留存建议**：除表格外，建议同时保留请求报文、响应报文、日志截图和必要的数据库查询结果，统一按 `applicationNo` 或 `sysRequestNo` 归档。

### 联调日报 / 回填模板

#### 日报头模板

| 字段 | 填写说明 |
|------|------|
| 联调日期 | 填写当天日期 |
| 联调环境 | 如 SIT / UAT / 联调环境名称 |
| 执行人 | 填写执行人 |
| 服务版本 | 填写分支、构建号或部署批次 |
| 网关地址 | 填写实际调用入口，若有前置网关前缀需写明 |
| 鉴权方式 | 如 Bearer Token、租户头、会话信息 |
| 样本范围 | 填写当日使用的账单、客户、发票样本范围 |

#### 当日执行摘要模板

| 对应待办 | 是否执行 | 样本量 | 成功样本 | 失败/拦截样本 | 产出附件 |
|------|------|------:|------:|------:|------|
| `T060` / SC-001 响应时延 | 待补 | 待补 | 待补 | 待补 | 待补 |
| `T061` / SC-002 申请通过率 | 待补 | 待补 | 待补 | 待补 | 待补 |
| `T062` / SC-003 回写成功率 | 待补 | 待补 | 待补 | 待补 | 待补 |
| `T063` / SC-004 客户侧消费成功率 | 待补 | 待补 | 待补 | 待补 | 待补 |
| `T055` / SC-005 日志抽样 | 待补 | 待补 | 待补 | 待补 | 待补 |

#### 样本回填索引模板

| 样本标识 | `applicationNo` | `sysRequestNo` | `invoiceId` | 对应步骤 | 回填表格位置 | 备注 |
|------|------|------|------|------|------|------|
| 样本 A | 待补 | 待补 | 待补 | 步骤 1 ~ 9（按实际填写） | `T060/T061/T062/T063/T055`（按实际填写） | 待补 |
| 样本 B | 待补 | 待补 | 待补 | 待补 | 待补 | 待补 |

#### 风险与阻塞模板

| 分类 | 现象 | 影响待办 | 临时处理 | 后续动作 |
|------|------|------|------|------|
| 环境 | 待补 | 待补 | 待补 | 待补 |
| 数据 | 待补 | 待补 | 待补 | 待补 |
| 接口 | 待补 | 待补 | 待补 | 待补 |
| 日志 | 待补 | 待补 | 待补 | 待补 |

#### 当日结论模板

- **已完成回填**：待补
- **未完成原因**：待补
- **是否影响 `Verification Pending` 状态**：待补
- **次日建议动作**：待补

- **使用说明**：建议每次联调结束后先填写本节，再同步更新前文 `T055`、`T060 ~ T063` 的正式统计表，避免日报与正式验证记录脱节。

### 联调前置检查清单

| 检查项 | 核对内容 | 当前状态 |
|------|------|------|
| 环境地址 | 已确认 `${BASE_URL}`、网关前缀、服务版本与部署批次 | 待补 |
| 鉴权信息 | 已确认 Bearer Token、租户头、会话信息或其他鉴权方式 | 待补 |
| 样本数据 | 已准备正常样本、规则拦截样本、成功发票样本、作废样本、红冲样本 | 待补 |
| 主键映射 | 已确认 `custId`、`chargeIds`、`applicationNo`、`sysRequestNo`、`invoiceId` 的映射关系 | 待补 |
| 日志入口 | 已确认 Kibana、数据库表或应用日志文件的检索入口 | 待补 |
| 回填责任 | 已确认谁负责日报填写、谁负责正式表格回填、谁负责附件归档 | 待补 |
| 归档路径 | 已确认请求报文、响应报文、截图与日志附件的归档位置 | 待补 |

- **执行要求**：未完成上述检查前，不建议直接开始批量联调，避免后续出现样本无法回溯、日志无法检索或统计口径不一致的问题。
- **建议时点**：每轮联调开始前先更新本清单；若环境、样本或鉴权方式发生变化，应重新复核并更新时间。

### 最终联调执行顺序与完成判定清单

| 顺序 | 对应待办 | 完成标志 | 可勾选条件 |
|------|------|------|------|
| 1 | `T060` | 已形成一批申请时延样本 | 已记录 `/business/invoice/apply` 的样本量、平均值、P95、最大值，并注明是否剔除 `SYS-008` 等待 |
| 2 | `T061` | 已形成正常场景与拦截场景分组统计 | 已区分正常业务场景与规则拦截场景，且正常场景成功/失败统计可追溯到样本主键 |
| 3 | `T062` | 已形成查询、回写、补偿查询三类结果统计 | 已记录回写请求总量、业务成功落账量、业务失败量、成功终态保护量，并保留失败分类 |
| 4 | `T063` | 已形成客户查询、下载、推送三类统计 | 已分别记录查询、下载、推送样本量、成功数、失败/前置拦截分类，并保留渠道与定位键 |
| 5 | `T055` | 已形成关键动作日志样本 | 已抽取申请、查询/补偿、回写、客户下载、客户推送、作废、红冲至少各 1 条日志样本，并能回扣动作矩阵 |

#### 建议最终执行顺序

1. 先完成 `T060`，确保申请入口、环境耗时与基础样本可用。
2. 再完成 `T061`，把同批申请样本分成“正常业务场景 / 规则拦截场景”两组。
3. 基于成功申请样本推进 `T062`，补齐查询、回写与补偿查询链路统计。
4. 仅在样本达到 `SUCCESS + fileUrl` 后推进 `T063`，避免把前置条件不满足的样本误计为下载失败。
5. 最后完成 `T055`，对上述链路中已成功执行的样本逐项抽取日志，形成最终运行态留痕证据。

#### 单项完成判定模板

| 待办 | 是否已拿到真实样本 | 是否已回填正式表格 | 是否已留存附件 | 是否满足勾选条件 | 备注 |
|------|------|------|------|------|------|
| `T060` | 待补 | 待补 | 待补 | 待补 | 待补 |
| `T061` | 待补 | 待补 | 待补 | 待补 | 待补 |
| `T062` | 待补 | 待补 | 待补 | 待补 | 待补 |
| `T063` | 待补 | 待补 | 待补 | 待补 | 待补 |
| `T055` | 待补 | 待补 | 待补 | 待补 | 待补 |

- **勾选原则**：只有当“真实样本已拿到 + 正式统计表已回填 + 附件已留存”三项同时满足时，对应待办才建议从 `tasks.md` 标记为完成。
- **收口顺序**：建议按 `T060 → T061 → T062 → T063 → T055` 顺序逐项关闭，避免后置任务缺少前置样本支撑。

### 剩余工作摘要（可直接引用）

- **当前状态**：REV-005 已完成 US1 ~ US4 的实现态闭环与文档侧验证准备，当前处于 `Verification Pending`，剩余工作全部集中在 `T055`、`T060 ~ T063` 的真实联调取证与结果回填。
- **剩余待办**：
  1. `T060`：补 `/business/invoice/apply` 的真实响应时延样本与统计结果。
  2. `T061`：补正常业务场景与规则拦截场景的申请通过率统计。
  3. `T062`：补查询、回写、补偿查询链路的成功率与失败分类统计。
  4. `T063`：补客户查询、下载、推送三类动作的成功率与前置拦截分类。
  5. `T055`：补申请、查询/补偿、回写、客户下载/推送、作废、红冲的运行态日志样本。
- **完成条件**：上述待办均需满足“真实样本已拿到、正式统计表已回填、附件已留存”三项条件后，方可在 `tasks.md` 中关闭。
- **建议对外口径**：**REV-005 当前已具备提测前文档与验证准备条件，剩余工作不在于设计或实现补充，而在于测试/联调环境下补齐运行态统计与日志证据。**

## 4. US4 二期实现结论

当前已在以下正式文档与实现文件中明确：

- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
- `docs/design/03_Technical_Design/03_Interface_Design.md`
- `specs/002-rev005-invoice-flow/spec.md`
- `specs/002-rev005-invoice-flow/plan.md`
- `specs/002-rev005-invoice-flow/tasks.md`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceInvalidateReqVO.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceRedInkReqVO.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java`

当前结论如下：

1. 发票作废、红冲仍由 `SYS-008` 统一承接税控侧处理。
2. `SYS-002` 已补齐后台作废 `/business/invoice/invalidate` 与红冲 `/business/invoice/red-ink` 入口，并通过专门请求 VO 承接原因、备注与原发票代码/号码。
3. 当前实现仅允许对 `SUCCESS` 发票发起作废或红冲；若传入 `originalInvoiceCode`、`originalInvoiceNumber`，必须与当前发票记录一致，重复处理会被拦截。
4. `InvoiceDO` 与 `01_Database_Design.md` 已补齐作废原因/备注、红冲原因/备注、原发票代码/号码与 `postProcessSource` 等承接口径；service 会同步写入 `latestResult`、`latestError`、账单关联状态与操作日志。
5. 当前剩余风险主要集中在物理表结构/DDL 来源未在仓库内定位、批量作废/红冲能力未覆盖，以及缺少端到端联调样本。

## 5. 当前已完成文件

### 正式文档

- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
- `docs/design/03_Technical_Design/01_Database_Design.md`
- `docs/design/03_Technical_Design/03_Interface_Design.md`
- `docs/design/00_Management/01_Project_Progress.md`
- `docs/design/00_Management/03_Task_Checklist.md`

### spec/planning 产物

- `specs/002-rev005-invoice-flow/spec.md`
- `specs/002-rev005-invoice-flow/plan.md`
- `specs/002-rev005-invoice-flow/research.md`
- `specs/002-rev005-invoice-flow/data-model.md`
- `specs/002-rev005-invoice-flow/contracts/if-rev-008-invoice-application.md`
- `specs/002-rev005-invoice-flow/contracts/if-rev-009-invoice-query.md`
- `specs/002-rev005-invoice-flow/tasks.md`
- `specs/002-rev005-invoice-flow/verification.md`

### backend 相关实现

- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceApplyReqVO.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceApplyRespVO.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceCustomerQueryReqVO.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceInvalidateReqVO.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoicePushReqVO.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceQueryReqVO.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceQueryRespVO.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceRedInkReqVO.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceWriteBackReqVO.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/mysql/invoice/InvoiceMapper.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java`
- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java`

## 6. 剩余风险

1. `SC-001 ~ SC-005` 尚缺可重复执行的专项测量脚本或统计记录。
2. 当前 `make validate-mermaid` 输出仅覆盖仓库现有扫描范围，若后续扩展更多图表文件，仍需复核目标文件是否全部纳入。
3. 当前仓库内尚未定位到与 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java` 当前模型对应的 `biz_invoice` 物理 DDL 或迁移脚本；已核查 `backend/sql`、Archive 数据库设计与 `sql/lhc_数据库设计.md`，现有同名 `biz_invoice` 更偏开票配置表，作废/红冲新增字段的物理落库仍需结合实际数据库变更链路确认。
4. 作废/红冲当前以单笔后台入口为主，尚未覆盖批量后处理、`SYS-008` 端到端联调样本与自动化回归验证。

## 7. 下一步建议

1. 若继续推进一期验收，优先补 `SC-001 ~ SC-005` 的专项统计与样本口径。
2. 若继续推进 US4，优先确认 `biz_invoice` 物理 DDL/迁移脚本来源，并补批量作废/红冲与联调样本，而不是继续重复扩展已完成的请求对象或数据承接口径。
3. 若准备提测或评审，可直接引用本文件作为当前已完成验证、US4 二期实现范围与剩余风险摘要。

## 8. 当前交付摘要

### 8.1 已完成交付

1. REV-005 的 US1 ~ US4 已完成正式文档、spec/planning 产物与 backend 最小实现闭环，并已补齐最小编译、文档校验、链接校验与 Mermaid 校验证据。
2. `spec.md`、`tasks.md`、`verification.md`、`01_Project_Progress.md`、`03_Task_Checklist.md` 当前已统一到“实现闭环基本完成、量化验收证据待补”的一致状态。
3. 当前仓库已明确可直接用于评审/提测前范围说明的结论：正常开票闭环与作废/红冲最小入口已形成正式实现范围，SC-005 实现态日志追溯矩阵已补齐。

### 8.2 当前未闭环事项

1. `T055`、`T060`、`T061`、`T062`、`T063` 仍未完成，分别对应运行态日志抽样、SC-001 响应时延、SC-002 申请通过率、SC-003 回写成功率、SC-004 客户侧查询/下载/推送成功率等专项统计证据。
2. `biz_invoice` 物理 DDL / migration 来源仍未在仓库中定位，US4 的物理落库链路、批量后处理与端到端联调样本仍需继续跟踪。

### 8.3 建议引用口径

- 若当前需要向评审或提测说明 REV-005 状态，建议统一表述为：**REV-005 已完成 US1 ~ US4 的实现态闭环与最小校验，当前处于 Verification Pending，剩余工作主要是补 SC-001 ~ SC-005 的运行态样本与专项统计证据。**