# 资产详情流量展示 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`