gt-agent-company/docs/资产详情流量-spec.md

资产详情流量展示 Spec

1. 背景

原始说明见 docs/资产详情流量.md。

本次需要统一资产详情中套餐流量的展示口径，避免“当前生效套餐”和“套餐列表”出现字段选择不一致、剩余流量计算不一致的问题。

本 Spec 仅定义前端展示和计算规则，不涉及后端接口改造。

---

2. 适用范围

页面范围

• 资产详情页：src/pages/agent-system/asset-detail/index.vue

联动范围

• 资产详情页中的同类套餐展示：src/pages/agent-system/asset-detail/index.vue

本次覆盖的 UI 区块

• 当前生效套餐卡片
• 套餐列表中的流量摘要
• 套餐进度条文案与进度百分比

不在本次范围内

• 后端接口字段定义
• 其他页面中与套餐无关的流量汇总展示

---

3. 数据来源

当前生效套餐

• 接口：GET /api/admin/assets/:identifier/current-package

套餐列表

• 接口：GET /api/admin/assets/:identifier/packages

本次展示使用的关键字段

字段	类型	说明
real_total_mb	number	真流量总量
real_used_mb	number	真流量已使用
virtual_used_mb	number	虚流量已使用
enable_virtual_data	boolean	是否按虚流量口径展示已使用
paid_amount	number	套餐金额，单位分

说明：

• 本次总流量固定使用 real_total_mb
• 本次已使用根据 enable_virtual_data 在 virtual_used_mb 和 real_used_mb 间切换
• 本次剩余流量以前端计算结果为准，不直接取其他剩余字段

---

4. 统一展示口径

展示项	计算规则	备注
总流量	real_total_mb	固定使用该字段
已使用	enable_virtual_data === true ? virtual_used_mb : real_used_mb	仅做字段切换，不做额外换算
剩余	max(总流量 - 已使用, 0)	与页面展示的“已使用”保持同口径
进度百分比	total <= 0 ? 0 : min(已使用 / 总流量 * 100, 100)	进度条与文案必须一致

明确约束

1. 不使用 virtual_total_mb 作为“总流量”展示值。
2. 不使用 real_used_mb 单独计算“剩余”，必须使用页面实际展示的“已使用”值参与计算。
3. 不因为字段名差异而在前端自行做虚实流量换算。

---

5. 页面展示要求

5.1 当前生效套餐

当前卡片中的以下区域必须使用统一口径：

• 总量：显示 real_total_mb
• 已使用：根据 enable_virtual_data 切换展示
• 剩余：使用 总量 - 已使用
• 进度条文案：已使用 / 总量
• 进度条宽度：使用同一组 已使用、总量 计算
• 总量、已使用、剩余 的展示值统一保留两位小数

5.2 套餐列表

套餐列表每一项中当前展示的 已用 / 总量 必须使用相同口径：

• 已用：根据 enable_virtual_data 切换
• 总量：固定使用 real_total_mb
• 剩余：显示 总量 - 已使用
• 金额：显示 paid_amount / 100 后的元金额
• 总量、已用、剩余 的展示值统一保留两位小数

如果后续套餐列表新增“剩余”字段，必须沿用本 Spec 中的剩余计算规则，不得单独定义。

---

6. 边界处理

空值处理

• null、undefined、NaN 按 0 处理

超限处理

• 当 已使用 > 总流量 时：
  • 剩余 显示 0
  • 进度条按 100% 展示

总量为 0

• 总量 = 0 时：
  • 已使用 按规则正常显示
  • 剩余 显示 0
  • 进度条显示 0%

---

7. 实现要求

统一计算入口

建议统一封装以下计算函数，并在相关页面复用：

• getPackageTotalMb
• getPackageUsedMb
• getPackageRemainMb
• getPackageUsagePercent

关键实现要求

• getPackageRemainMb 必须改为基于“当前展示的已使用值”计算
• asset-detail 页面内不同区块不允许维护不同口径的同名逻辑
• 格式化继续沿用现有 formatDataSize，本次不单独引入新的单位换算规则

---

8. 验收标准

验收用例 1：enable_virtual_data = true

输入：

{
  "real_total_mb": 1024000,
  "real_used_mb": 7848,
  "virtual_used_mb": 11211.425208,
  "enable_virtual_data": true
}

期望：

• 总流量 = 1024000
• 已使用 = 11211.425208
• 剩余 = 1012788.574792
• 进度百分比约 = 1.09%

格式化后参考展示：

• 总量：1000.00GB
• 已使用：10.95GB
• 剩余：989.05GB

验收用例 2：enable_virtual_data = false

输入：

{
  "real_total_mb": 1024000,
  "real_used_mb": 7848,
  "virtual_used_mb": 11211.425208,
  "enable_virtual_data": false
}

期望：

• 总流量 = 1024000
• 已使用 = 7848
• 剩余 = 1016152

验收用例 3：超限

输入：

{
  "real_total_mb": 100,
  "real_used_mb": 120,
  "virtual_used_mb": 120,
  "enable_virtual_data": false
}

期望：

• 已使用 = 120
• 剩余 = 0
• 进度条 = 100%

验收用例 4：跨页面一致性

• 同一套餐数据在 asset-detail 页面各区块中的展示结果一致
• 当前生效套餐卡片与套餐列表摘要使用同一套字段口径

---

9. 结论

本次变更的核心是统一三件事：

1. 总流量固定取 real_total_mb
2. 已使用根据 enable_virtual_data 选择 virtual_used_mb 或 real_used_mb
3. 剩余必须使用 总流量 - 已使用 计算，不能再固定减 real_used_mb