feat(退款): AUG26-006 补充当前退款套餐已用量与总量

补齐 PRD §2.3.1「退款管理补充字段」：退款列表、详情与导出新增
「当前退款套餐已用量」与「当前退款套餐总量」两个纯展示字段。

- 套餐定位口径与退款套餐失效保持一致，按优先级取唯一一条：
  冻结的 package_usage_id（且属于该订单）→ 订单主套餐 → 订单任一套餐，
  同级按标识升序。不按当前世代或当前生效套餐推断；不按套餐状态过滤，
  使退款后套餐转已失效时仍能回看用量。
- 列表与详情用固定两次查询批量解析（按标识、按订单），查询次数不随条数增长；
  详情复用同一函数。解析不到套餐或记录已物理删除时返回 0，不阻断读取。
- 导出新增两列并改用同一优先级的 LATERAL 取法，不再依赖只按 r.package_usage_id
  的 join——生产库 1296 条退款仅 157 条带该字段，旧取法会让多数行显示零值。
- 不改变退款金额校验、冻结实收、套餐失效、接续、停机与佣金回溯任何规则。

验证：测试库 junhong_cmp_test 实测冻结记录、订单主套餐回退、记录缺失返回 0 三项
解析场景与「4 条退款固定 2 次查询」；并以同批 43 条退款对拍 Go 解析器与导出 SQL，
口径不一致 0 条；导出 43 行列数与表头一致。无迁移、无接口路径变化。

openspec/changes/archive/2026-09-14-add-refund-package-usage-display/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-14

openspec/changes/archive/2026-09-14-add-refund-package-usage-display/design.md

@@ -0,0 +1,64 @@
+## Context
+
+PRD §2.3.1 要求退款列表、详情与导出展示「当前退款套餐已用量/总量」。这两个字段是纯展示投影，已归档的 `add-refund-methods-and-original-route-refunds` 未包含它们，见 proposal.md「Why」。
+
+现状事实（开工核对）：
+
+- `tb_refund_request.package_usage_id` 可空：生产库 1296 条退款仅 157 条有值，测试库 43 条中 30 条有值。因此**只读该列会让绝大多数退款显示零值**，与 PRD「退款订单自动关联的唯一套餐」不符。
+- 既有 `InvalidatePackagesForRefund`（`internal/service/package/activation_service.go`）定位待失效套餐的口径是：优先 `id = package_usage_id AND order_id = 订单`，为空时取该订单全部套餐使用记录（再连带其加油包）。
+- 导出场景已 `LEFT JOIN tb_package_usage AS pu ON pu.id = r.package_usage_id` 并已取 `pu.package_name`，但该 join 只覆盖「已冻结 package_usage_id」的退款，同样漏掉多数记录。
+- `PackageUsage` 的真实流量字段为 `data_usage_mb`（真已用）与 `data_limit_mb`（真总量），单位 MB。
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 列表、详情与导出稳定返回当前退款套餐的真实已用量与总量，且同一退款多次查询结果一致。
+- 复用既有退款失效的套餐定位口径，使展示与系统实际失效的套餐一致。
+- 列表与导出不因这两个字段引入逐条查询。
+
+**Non-Goals:**
+
+- 不新增退款申请时的套餐选择能力，也不改变 `package_usage_id` 的写入时机。
+- 不展示套餐名称、到期时间等其他套餐信息（导出既有「套餐名称」列保持不变）。
+- 不改变退款金额校验、冻结实收、套餐失效、接续、停机与佣金回溯规则。
+
+## Decisions
+
+### 1. 套餐定位顺序：冻结记录 → 订单主套餐 → 订单任一套餐
+
+展示口径与 `InvalidatePackagesForRefund` 对齐：
+
+1. `refund.package_usage_id` 指向且属于该退款关联订单的套餐使用记录；
+2. 否则该订单下 `master_usage_id IS NULL` 的主套餐使用记录；
+3. 否则该订单下任一套餐使用记录。
+
+同一优先级内按 `id ASC` 取第一条。**不按当前世代或当前生效套餐推断**：换货后权益仍保留原订单关系（既有失效逻辑注释即如此说明），按世代推断会指向错误的资产。
+
+第 3 步兜底只按 `order_id` 过滤、**不按状态过滤**，与失效逻辑一致；这也满足 PRD「当前可取得」——退款后套餐已转已失效（status=4）并写入 `refund_id`，此时仍需展示其用量。若加状态过滤，退款完成后字段会集体变零，与用途矛盾。
+
+> 该顺序与失效口径的**唯一差异**：失效会作用于该订单的全部套餐使用记录（含加油包），而展示取唯一一条「当前退款套餐」。PRD 2.3.16 明确当前业务一张订单仅购买一个套餐，因此取主套餐即代表；多套餐时取主套餐而非拼接，避免把加油包用量混算进主套餐口径。
+
+**备选与取舍**：曾考虑直接返回该订单全部套餐的汇总用量。否决理由：PRD 只要求「唯一套餐」的两个字段，汇总会把加油包算入主套餐总量，与失效口径和用户预期都不一致。
+
+### 2. 空值语义：解析不到即返回 0，不阻断读取
+
+套餐使用记录不存在、已物理删除或字段为空时返回 0。理由是这两个字段是展示增强，任何情况下都不应让退款列表、详情或导出失败；`RefundResponse` 既有字段多为值类型，用 0 表示「无数据」与既有风格一致。
+
+### 3. 批量读取避免 N+1
+
+列表与导出按「先收集本次退款申请集合的 `package_usage_id` 与 `order_id`，再批量查询套餐使用记录，最后在内存中按决策 1 的顺序择一」实现：
+
+- 一次查询 `WHERE id IN (…)` 覆盖来自 `package_usage_id` 的候选；
+- 一次查询 `WHERE order_id IN (…)` 覆盖订单候选；
+- 内存中按 `id ASC` 取每个退款申请的第一条命中。
+
+因此每页列表与每次导出分片固定为 2 次套餐查询，与退款条数无关。
+
+详情为单条退款，复用同一批量函数即可，无需特例。
+
+## Risks / Trade-offs
+
+- **[导出列数变化]** 新增两列会改变既有导出文件的列次序，下游若有按列序解析的脚本会错位 → 缓解：两列插入在既有「套餐名称」之后、`refundExportRow` 与表头同步调整；本次为新增列，按列名解析的下游不受影响。
+- **[多套餐订单取主套餐]** 订单意外存在多条套餐使用记录时只展示主套餐用量 → 缓解：与 PRD 2.3.16 的单套餐前提一致；若后续放开多套餐，需单独 Change 重新定义展示口径。
+- **[不按状态过滤]** 已失效套餐仍展示用量 → 这是刻意的：退款完成后正是需要回看被退套餐的用量，加状态过滤会使字段在退款后归零。

openspec/changes/archive/2026-09-14-add-refund-package-usage-display/proposal.md

@@ -0,0 +1,24 @@
+## Why
+
+PRD §2.3.1 要求退款管理列表、详情与导出新增「当前退款套餐已用量」和「当前退款套餐总量」，供审批与运营判断退款合理性；已归档的 `add-refund-methods-and-original-route-refunds` 漏掉了这两个纯展示字段，当前列表、详情与导出均不返回套餐使用情况。
+
+## What Changes
+
+- 退款申请列表、详情与导出新增两个展示字段：当前退款套餐的真实已用量与真实总量（单位 MB）。
+- 「当前退款套餐」按既定退款失效口径解析：优先取退款申请冻结的套餐使用记录；未冻结时取该退款关联订单的套餐使用记录（优先主套餐，其次任一），与 `InvalidatePackagesForRefund` 的定位口径一致。
+- 两个字段只读展示：**BREAKING** 无（纯新增响应字段）。不改变退款金额校验、套餐失效、接驳下一套餐、停机评估、佣金回溯或渠道退款任何规则。
+- 套餐使用记录缺失或已物理删除时两个字段返回 0，不阻断列表、详情或导出。
+
+## Capabilities
+
+### New Capabilities
+
+- 无。
+
+### Modified Capabilities
+
+- `order-refund-exchange`: 退款列表、详情与导出的可观察字段增加当前退款套餐的真实已用量与总量。
+
+## Impact
+
+影响退款查询投影与导出场景：`internal/model/dto/refund_dto.go`、`internal/service/refund/service.go`（列表与详情投影）、`internal/service/refund/attempt_query.go` 同目录新增套餐使用批量读取、`internal/exporter/refund_scene.go`。无迁移、无接口路径变化、无第三方交互；导出新增两列会改变既有导出文件的列次序与列数。

openspec/changes/archive/2026-09-14-add-refund-package-usage-display/specs/order-refund-exchange/spec.md

@@ -0,0 +1,39 @@
+## ADDED Requirements
+
+### Requirement: 退款展示当前退款套餐用量
+
+退款管理列表、详情与导出 SHALL 返回「当前退款套餐已用量」与「当前退款套餐总量」两个字段，取值为该套餐使用记录当前可取得的真实已用量与真实总量（单位 MB）。两个字段 MUST 仅用于展示、查询与导出，MUST NOT 参与或改变退款金额校验、冻结实收金额、套餐失效、接续下一套餐、停机评估、佣金回溯或渠道退款任何规则。
+
+「当前退款套餐」MUST 按与退款套餐失效一致的口径解析，且 MUST 按下列优先级取唯一一条：退款申请冻结的套餐使用记录（其 `package_usage_id`）；该退款关联订单下 `master_usage_id` 为空的主套餐使用记录；该退款关联订单下任一套餐使用记录。同一优先级内按使用记录标识升序取第一条，保证同一退款每次返回相同结果。解析 MUST NOT 按当前生效套餐或当前世代推断，也 MUST NOT 跨订单取套餐。
+
+套餐使用记录不存在、已被物理删除或字段为空时，两个字段 SHALL 返回 0，且 MUST NOT 因此阻断列表、详情或导出。列表返回 MUST NOT 因逐条查询套餐使用记录而放大查询次数。
+
+#### Scenario: 退款申请已冻结套餐使用记录
+
+- **GIVEN** 退款申请记录了套餐使用记录标识，且该记录属于其关联订单
+- **WHEN** 查询退款列表、详情或导出
+- **THEN** 两个字段返回该套餐使用记录的真实已用量与真实总量
+
+#### Scenario: 退款申请未冻结套餐使用记录
+
+- **GIVEN** 退款申请的套餐使用记录为空，且其关联订单存在主套餐使用记录
+- **WHEN** 查询退款列表、详情或导出
+- **THEN** 两个字段返回该订单主套餐使用记录的已用量与总量，不返回零值
+
+#### Scenario: 套餐使用记录已不存在
+
+- **GIVEN** 退款申请冻结的套餐使用记录已被物理删除，且解析结果为空
+- **WHEN** 查询退款列表、详情或导出
+- **THEN** 两个字段返回 0，且列表、详情与导出仍正常返回该退款申请
+
+#### Scenario: 列表不因套餐字段放大查询
+
+- **GIVEN** 退款列表一页返回多条退款申请
+- **WHEN** 查询该页列表
+- **THEN** 系统以批量方式读取套餐使用记录，查询次数不随该页退款申请条数线性增长
+
+#### Scenario: 展示字段不影响资金与权益规则
+
+- **GIVEN** 任一退款申请
+- **WHEN** 系统解析并返回这两个展示字段
+- **THEN** 退款金额校验、冻结实收金额、套餐失效、接续下一套餐、停机评估与佣金回溯行为均不发生变化

openspec/changes/archive/2026-09-14-add-refund-package-usage-display/tasks.md

@@ -0,0 +1,13 @@
+## 1. 查询投影
+
+- [x] 1.1 新增退款套餐用量批量读取：按「冻结套餐使用记录优先级 → 订单主套餐 → 订单任一套餐使用记录、同级按 id 升序取第一条」解析每个退款申请的当前退款套餐，返回真实已用量与真实总量（MB）。实现为固定两次查询（`id IN` 与 `order_id IN`）+ 内存择一，不得按退款条数逐条查询；套餐记录不存在或字段为空时返回 0，不报错。 证据：`internal/service/refund/package_usage.go`（`loadRefundPackageUsages` 两次查询 + `resolveRefundPackageUsage` 优先级择一）。烟测实测：冻结套餐记录返回 321/1000；未冻结回退订单主套餐返回 321/1000（非零）；套餐记录物理删除返回 0 且不报错；4 条退款的套餐查询次数恒为 2（不随条数增长）。
+- [x] 1.2 退款列表、详情响应新增「当前退款套餐已用量」与「当前退款套餐总量」两个字段：列表批量填充、详情单条填充，字段单位与含义写入中文 description，枚举与单位不得与既有套餐 DTO 冲突。 证据：`internal/model/dto/refund_dto.go` 的 `RefundResponse.RefundPackageUsedMB`/`RefundPackageTotalMB`（中文 description 含单位与零值语义）；`internal/service/refund/service.go` 列表批量填充、详情单条填充。`go run cmd/gendocs/main.go` 生成的 OpenAPI 已包含两个字段。
+
+## 2. 导出
+
+- [x] 2.1 退款导出场景新增两列「当前退款套餐已用量(MB)」与「当前退款套餐总量(MB)」，插入在既有「套餐名称」列之后；同步调整 `refundExportRow`、Select 列与表头，保持表头与行元素数量、顺序严格一致。该两列必须覆盖未冻结 `package_usage_id` 的退款，不得沿用只按 `r.package_usage_id` join 的取法。 证据：`internal/exporter/refund_scene.go` 表头与行新增「当前退款套餐已用量(MB)」「当前退款套餐总量(MB)」两列（位于「套餐名称」之后），并以 LATERAL 按同一优先级取唯一套餐记录，不再依赖 `r.package_usage_id` join。烟测实测：导出 43 行列数与表头一致，两个新列下标为 6/7，43/43 行取到套餐总量（改动前仅 30/43 有 `package_usage_id`）。
+
+## 3. 验证
+
+- [x] 3.1 按 ENG-TEST-001 在维护者指定的 `junhong_cmp_test` PostgreSQL + Redis DB 6 验证，仅创建与删除本 Change 自有 fixture，禁止重置整库：冻结过套餐使用记录的退款返回该记录用量；未冻结但订单存在主套餐的退款返回主套餐用量而非零；套餐记录已物理删除时返回 0 且列表/详情/导出仍正常；列表与导出的套餐查询次数固定为 2 次、不随条数增长；确认退款金额校验、套餐失效、接续、停机与佣金回溯行为无变化。 证据：测试库 `junhong_cmp_test` 实测四项解析场景与 2 次固定查询；并以同批 43 条退款做 Go 解析器与导出 SQL 的口径对拍，**不一致 0 条**。未修改退款金额校验、套餐失效、接续、停机与佣金回溯相关代码。fixture 全部清理，未重置整库。
+- [x] 3.2 运行 `gofmt -w`、`go build ./cmd/api ./cmd/worker`、`go run cmd/gendocs/main.go`、`openspec validate add-refund-package-usage-display --strict`、`openspec validate --all`、`openspec doctor --json` 与 `./scripts/context-health.sh`；自动化测试按项目决策为 N/A，验证脚本在完成后删除，不留测试文件。 证据：`gofmt -l`（变更集）无输出；`go build ./cmd/api ./cmd/worker` 退出码 0；`go run cmd/gendocs/main.go` 退出码 0 且 OpenAPI 含新字段；`openspec validate add-refund-package-usage-display --strict` 有效；`openspec validate --all` 通过；`openspec doctor --json` healthy；`./scripts/context-health.sh` 通过。验证脚本已删除，仓库内 `*_test.go` 计数为 0。