luo/gt-agent-company

Fork 0

Files

sexygoat f9fe76ff99

构建并部署前端到测试环境 / build-and-deploy (push) Successful in 1m5s

Details

fix:bug

2026-05-14 09:50:34 +08:00

5.4 KiB

Raw Blame History

资产详情流量展示 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)`	进度条与文案必须一致

明确约束

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

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. 结论

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

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

5.4 KiB Raw Blame History Unescape Escape