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

## 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 完全一致
```