huang
95fc0b0a1b
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 8m16s
151 lines
3.8 KiB
Markdown
151 lines
3.8 KiB
Markdown
# 流量模型统一接口回放样例
|
||
|
||
## 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 + enable_virtual_data`
|
||
|
||
### 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 + enable_virtual_data`
|
||
- 不再出现 `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`
|
||
- 当前主套餐摘要包含 `enable_virtual_data`
|
||
- 不再出现 `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 完全一致
|
||
```
|