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

流量模型统一接口回放样例

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 资产解析

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 当前主套餐

curl -X GET "http://localhost:8080/api/admin/assets/<identifier>/current-package" \
  -H "Authorization: Bearer <admin-token>"

重点核对：

• 有主套餐时仅返回主套餐记录
• 无主套餐时返回 200 + null
• 记录字段包含 package_usage_id + 统一五字段 + reduction_pct + enable_virtual_data

3.3 套餐历史

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 + enable_virtual_data
• 不再出现 virtual_limit_mb / virtual_remain_mb / virtual_ratio

4. C 端接口回放

4.1 资产信息

curl -X GET "http://localhost:8080/api/c/v1/asset/info?identifier=<identifier>" \
  -H "Authorization: Bearer <client-token>"

重点核对：

• 仅返回当前主套餐摘要
• 无主套餐时五字段为 0，current_package_usage_id = null
• 当前主套餐摘要包含 enable_virtual_data
• 不再出现 package_total_mb / package_used_mb / package_remain_mb

4.2 套餐历史

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. 验收结论模板

每次回放后，按下述模板记录：

- [ ] 样例 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 完全一致