修正数据

docs/traffic-model-unification/字段替换矩阵.md

@@ -0,0 +1,110 @@
+# 流量模型统一字段替换矩阵
+
+## 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` | 保留既有字段 |
+
+### 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` | 保留，作为记录主键 |
+
+### 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` | 展示增幅比例 |
+
+### 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`
+
+因此，本次变更仅做字段契约收口，不调整上述路由路径。