huang
95fc0b0a1b
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 8m16s
114 lines
5.8 KiB
Markdown
114 lines
5.8 KiB
Markdown
# 流量模型统一字段替换矩阵
|
||
|
||
## 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`
|
||
|
||
因此，本次变更仅做字段契约收口，不调整上述路由路径。
|