228 lines
5.4 KiB
Markdown
228 lines
5.4 KiB
Markdown
# 资产详情流量展示 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`
|