fix: 流量保留两位小数

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

@@ -0,0 +1,227 @@
+# 资产详情流量展示 Spec
+
+## 1. 背景
+
+原始说明见 `docs/资产详情流量.md`。
+
+本次需要统一资产详情中套餐流量的展示口径，避免“当前生效套餐”和“套餐列表”出现字段选择不一致、剩余流量计算不一致的问题。
+
+本 Spec 仅定义前端展示和计算规则，不涉及后端接口改造。
+
+---
+
+## 2. 适用范围
+
+### 页面范围
+
+- 资产详情页：`src/pages/agent-system/asset-detail/index.vue`
+
+### 联动范围
+
+- 资产搜索页中的同类套餐展示：`src/pages/agent-system/asset-search/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` 与 `asset-search` 不允许维护不同口径的同名逻辑
+- 格式化继续沿用现有 `formatDataSize`，本次不单独引入新的单位换算规则
+
+---
+
+## 8. 验收标准
+
+### 验收用例 1：`enable_virtual_data = true`
+
+输入：
+
+```json
+{
+  "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`
+
+输入：
+
+```json
+{
+  "real_total_mb": 1024000,
+  "real_used_mb": 7848,
+  "virtual_used_mb": 11211.425208,
+  "enable_virtual_data": false
+}
+```
+
+期望：
+
+- 总流量 = `1024000`
+- 已使用 = `7848`
+- 剩余 = `1016152`
+
+### 验收用例 3：超限
+
+输入：
+
+```json
+{
+  "real_total_mb": 100,
+  "real_used_mb": 120,
+  "virtual_used_mb": 120,
+  "enable_virtual_data": false
+}
+```
+
+期望：
+
+- 已使用 = `120`
+- 剩余 = `0`
+- 进度条 = `100%`
+
+### 验收用例 4：跨页面一致性
+
+- 同一套餐数据在 `asset-detail` 与 `asset-search` 中展示结果一致
+- 当前生效套餐卡片与套餐列表摘要使用同一套字段口径
+
+---
+
+## 9. 结论
+
+本次变更的核心是统一三件事：
+
+1. 总流量固定取 `real_total_mb`
+2. 已使用根据 `enable_virtual_data` 选择 `virtual_used_mb` 或 `real_used_mb`
+3. 剩余必须使用 `总流量 - 已使用` 计算，不能再固定减 `real_used_mb`