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

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

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

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