修正数据

docs/traffic-model-unification/接口回放样例.md

@@ -0,0 +1,149 @@
+# 流量模型统一接口回放样例
+
+## 1. 目的
+
+本文用于给 `refactor-traffic-model-semantics` 提供固定回放样例，确保后台 / C 端接口、OpenAPI 和数据库公式在同一口径下验收。
+
+## 2. 典型样例
+
+### 样例 A：100 / 70 / 50 → 71.43
+
+- `real_total_mb = 100`
+- `virtual_total_mb = 70`
+- `real_used_mb = 50`
+- `display_gain_ratio = 100 / 70 = 1.428571`
+- `virtual_used_mb = min(50 * 1.428571, 100) = 71.43`
+- `reduction_pct = 1.428571 - 1 = 0.428571`
+
+### 样例 B：100 / 70 / 69 → 98.57
+
+- `real_total_mb = 100`
+- `virtual_total_mb = 70`
+- `real_used_mb = 69`
+- `display_gain_ratio = 100 / 70 = 1.428571`
+- `virtual_used_mb = min(69 * 1.428571, 100) = 98.57`
+- `reduction_pct = 0.428571`
+
+### 样例 C：100 / 70 / 70 → 100
+
+- `real_total_mb = 100`
+- `virtual_total_mb = 70`
+- `real_used_mb = 70`
+- `virtual_used_mb = min(70 * 1.428571, 100) = 100`
+- 该套餐应判定为耗尽
+
+### 样例 D：未启用虚流量退化为真流量视图
+
+- `real_total_mb = 100`
+- `virtual_total_mb = 100`
+- `real_used_mb = 69`
+- `virtual_used_mb = 69`
+- `reduction_pct = 0`
+
+## 3. 后台接口回放
+
+### 3.1 资产解析
+
+```bash
+curl -X GET "http://localhost:8080/api/admin/assets/resolve/<identifier>" \
+  -H "Authorization: Bearer <admin-token>"
+```
+
+重点核对：
+
+- `current_package_usage_id`
+- `real_total_mb`
+- `real_used_mb`
+- `virtual_total_mb`
+- `virtual_used_mb`
+- `reduction_pct`
+- 不再出现 `package_total_mb` / `package_used_mb` / `package_remain_mb`
+
+### 3.2 当前主套餐
+
+```bash
+curl -X GET "http://localhost:8080/api/admin/assets/<identifier>/current-package" \
+  -H "Authorization: Bearer <admin-token>"
+```
+
+重点核对：
+
+- 有主套餐时仅返回主套餐记录
+- 无主套餐时返回 `200 + null`
+- 记录字段包含 `package_usage_id + 统一五字段 + reduction_pct`
+
+### 3.3 套餐历史
+
+```bash
+curl -X GET "http://localhost:8080/api/admin/assets/<identifier>/packages?page=1&page_size=20" \
+  -H "Authorization: Bearer <admin-token>"
+```
+
+重点核对：
+
+- 列表每条记录都包含 `package_usage_id + 统一五字段 + reduction_pct`
+- 不再出现 `virtual_limit_mb` / `virtual_remain_mb` / `virtual_ratio`
+
+## 4. C 端接口回放
+
+### 4.1 资产信息
+
+```bash
+curl -X GET "http://localhost:8080/api/c/v1/asset/info?identifier=<identifier>" \
+  -H "Authorization: Bearer <client-token>"
+```
+
+重点核对：
+
+- 仅返回当前主套餐摘要
+- 无主套餐时五字段为 `0`，`current_package_usage_id = null`
+- 不再出现 `package_total_mb` / `package_used_mb` / `package_remain_mb`
+
+### 4.2 套餐历史
+
+```bash
+curl -X GET "http://localhost:8080/api/c/v1/asset/package-history?identifier=<identifier>&page=1&page_size=20" \
+  -H "Authorization: Bearer <client-token>"
+```
+
+重点核对：
+
+- 列表项统一返回 `package_usage_id + 统一五字段 + reduction_pct`
+- `generation` 过滤仍然有效
+- 不新增 `total.virtual_used_mb` 或等价聚合字段
+
+## 5. OpenAPI 核对点
+
+### 5.1 后台 `docs/admin-openapi.yaml`
+
+必须包含：
+
+- `current_package_usage_id`
+- `real_total_mb`
+- `real_used_mb`
+- `virtual_total_mb`
+- `virtual_used_mb`
+- `reduction_pct`
+
+必须移除：
+
+- `package_total_mb`
+- `package_used_mb`
+- `package_remain_mb`
+- `virtual_limit_mb`
+- `virtual_remain_mb`
+- `virtual_ratio`
+
+## 6. 验收结论模板
+
+每次回放后，按下述模板记录：
+
+```markdown
+- [ ] 样例 A（100/70/50 → 71.43）通过
+- [ ] 样例 B（100/70/69 → 98.57）通过
+- [ ] 样例 C（100/70/70 → 100，且耗尽）通过
+- [ ] 样例 D（未启用虚流量退化）通过
+- [ ] 后台 resolve/current-package/packages 不再返回旧字段
+- [ ] C 端 asset/info/package-history 不再返回旧字段
+- [ ] OpenAPI 与 DTO 完全一致
+```