# 流量模型统一字段替换矩阵

## 1. 目的

本文用于固化 `refactor-traffic-model-semantics` 变更前后的字段替换关系，作为后台 / C 端接口、OpenAPI 文档和手工回放的统一对照基线。

## 2. 统一后的核心字段

本次 contract 收口后，流量相关字段统一为：

| 字段 | 含义 |
|------|------|
| `current_package_usage_id` | 当前主套餐对应的套餐使用记录 ID，无主套餐时为 `null` |
| `real_total_mb` | 套餐真实总量，内部来源 `tb_package_usage.data_limit_mb` |
| `real_used_mb` | 套餐真实已用，内部来源 `tb_package_usage.data_usage_mb` |
| `virtual_total_mb` | 套餐业务停机阈值，优先来源 `tb_package_usage.virtual_total_mb_snapshot` |
| `virtual_used_mb` | 展示已用量，公式 `min(real_used_mb * display_gain_ratio, real_total_mb)` |
| `reduction_pct` | 展示增幅比例，公式 `(real_total_mb / virtual_total_mb) - 1` |

## 3. 字段替换矩阵

### 3.1 后台 `GET /api/admin/assets/resolve/:identifier`

| 现状字段 | 现状来源 | 新字段 | 新语义 |
|---------|---------|--------|--------|
| `current_package` | 主套餐名称 | `current_package` | 保留，语义不变 |
| `package_total_mb` | `data_limit_mb / virtual_ratio` | `real_total_mb` | 真总量 |
| `package_used_mb` | `data_usage_mb / virtual_ratio` | `real_used_mb` | 真已用 |
| `package_remain_mb` | `(data_limit_mb - data_usage_mb) / virtual_ratio` | `virtual_total_mb` / `virtual_used_mb` | 不再返回 remain，改为显式真/虚语义 |
| 无 | 无 | `current_package_usage_id` | 当前主套餐使用记录 ID |
| 无 | 无 | `reduction_pct` | 展示增幅比例 |

### 3.2 后台 `GET /api/admin/assets/:identifier/current-package`

| 现状字段 | 现状来源 | 新字段 | 新语义 |
|---------|---------|--------|--------|
| `data_limit_mb` | `tb_package_usage.data_limit_mb` | `real_total_mb` | 真总量 |
| `data_usage_mb` | `tb_package_usage.data_usage_mb` | `real_used_mb` | 真已用 |
| `virtual_limit_mb` | `data_limit_mb / virtual_ratio` | `virtual_total_mb` | 业务停机阈值 |
| `virtual_used_mb` | `data_usage_mb / virtual_ratio` | `virtual_used_mb` | 改为统一公式计算 |
| `virtual_remain_mb` | `(data_limit_mb - data_usage_mb) / virtual_ratio` | 删除 | 不再返回 |
| `virtual_ratio` | `tb_package.virtual_ratio` | `reduction_pct` | 只保留外部增幅比例 |
| 无 | 无 | `package_usage_id` | 保留既有字段 |
| 无 | `tb_package_usage.enable_virtual_data_snapshot` | `enable_virtual_data` | 返回套餐使用记录快照，供前端区分是否启用虚流量 |

### 3.3 后台 `GET /api/admin/assets/:identifier/packages`

| 现状字段 | 现状来源 | 新字段 | 新语义 |
|---------|---------|--------|--------|
| `data_limit_mb` | `tb_package_usage.data_limit_mb` | `real_total_mb` | 真总量 |
| `data_usage_mb` | `tb_package_usage.data_usage_mb` | `real_used_mb` | 真已用 |
| `virtual_limit_mb` | `data_limit_mb / virtual_ratio` | `virtual_total_mb` | 业务停机阈值 |
| `virtual_used_mb` | `data_usage_mb / virtual_ratio` | `virtual_used_mb` | 统一公式 |
| `virtual_remain_mb` | `(data_limit_mb - data_usage_mb) / virtual_ratio` | 删除 | 不再返回 |
| `virtual_ratio` | `tb_package.virtual_ratio` | `reduction_pct` | 只保留外部比例 |
| `package_usage_id` | `tb_package_usage.id` | `package_usage_id` | 保留，作为记录主键 |
| 无 | `tb_package_usage.enable_virtual_data_snapshot` | `enable_virtual_data` | 返回套餐使用记录快照，供前端区分是否启用虚流量 |

### 3.4 C 端 `GET /api/c/v1/asset/info`

| 现状字段 | 现状来源 | 新字段 | 新语义 |
|---------|---------|--------|--------|
| `current_package` | 主套餐名称 | `current_package` | 保留 |
| `package_total_mb` | 来自后台资产解析结果 | `real_total_mb` | 真总量 |
| `package_used_mb` | 来自后台资产解析结果 | `real_used_mb` | 真已用 |
| `package_remain_mb` | 来自后台资产解析结果 | `virtual_total_mb` / `virtual_used_mb` | 不再返回 remain |
| 无 | 无 | `current_package_usage_id` | 当前主套餐使用记录 ID |
| 无 | 无 | `reduction_pct` | 展示增幅比例 |
| 无 | `tb_package_usage.enable_virtual_data_snapshot` | `enable_virtual_data` | 返回当前主套餐快照，供前端区分是否启用虚流量 |

### 3.5 C 端 `GET /api/c/v1/asset/package-history`

| 现状字段 | 现状来源 | 新字段 | 新语义 |
|---------|---------|--------|--------|
| `data_limit_mb` | `tb_package_usage.data_limit_mb` | `real_total_mb` | 真总量 |
| `data_usage_mb` | `tb_package_usage.data_usage_mb` | `real_used_mb` | 真已用 |
| `virtual_limit_mb` | `data_limit_mb / virtual_ratio` | `virtual_total_mb` | 业务停机阈值 |
| `virtual_used_mb` | `data_usage_mb / virtual_ratio` | `virtual_used_mb` | 统一公式 |
| `virtual_remain_mb` | `(data_limit_mb - data_usage_mb) / virtual_ratio` | 删除 | 不再返回 |
| `virtual_ratio` | `tb_package.virtual_ratio` | `reduction_pct` | 只保留外部比例 |
| `package_usage_id` | `tb_package_usage.id` | `package_usage_id` | 保留 |

## 4. OpenAPI 对齐基线

当前 `docs/admin-openapi.yaml` 仍存在以下待淘汰字段定义：

- `package_total_mb`
- `package_used_mb`
- `package_remain_mb`
- `virtual_limit_mb`
- `virtual_remain_mb`
- `virtual_ratio`

本次变更完成后，后台 OpenAPI 需仅保留：

- `current_package_usage_id`
- `real_total_mb`
- `real_used_mb`
- `virtual_total_mb`
- `virtual_used_mb`
- `reduction_pct`

## 5. 路由基线

当前实际注册路由已经统一为 `:identifier` 口径：

- `GET /api/admin/assets/resolve/:identifier`
- `GET /api/admin/assets/:identifier/current-package`
- `GET /api/admin/assets/:identifier/packages`
- `GET /api/c/v1/asset/info`
- `GET /api/c/v1/asset/package-history`

因此，本次变更仅做字段契约收口，不调整上述路由路径。