luo/gt-agent-company
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2c6011bd4a5a71bc7409d1b2e1a8690412ee6b90
gt-agent-company/套餐管理系统说明.md
sexygoat 3c62cc1cd1 first
2026-03-31 18:41:52 +08:00

414 lines
12 KiB
Markdown
Raw Blame History

# 套餐管理系统 - 移动端H5
> **小米米家风格** - 套餐使用记录管理系统
---
## ✨ 功能说明
这是一个**套餐使用记录管理系统**,展示和管理用户的套餐使用情况。
### 核心功能
- ✅ **套餐统计** - 总数、生效中、待生效、已过期
- ✅ **套餐列表** - 筛选、搜索、分类展示
- ✅ **套餐详情** - 流量使用、时间信息、操作按钮
- ✅ **状态管理** - 5种状态标识和颜色区分
- ✅ **流量可视化** - 进度条显示虚流量/真流量
---
## 🚀 快速启动
```bash
# 启动开发服务器
pnpm dev:h5
# 访问地址
http://localhost:5173/
```
---
## 📋 数据字段说明
### 套餐状态 (status)
| 值 | 状态名称 | 颜色 | 说明 |
|----|---------|------|------|
| 0 | 待生效 | 橙色 | 已购买但未激活 |
| 1 | 生效中 | 绿色 | 正常使用中 |
| 2 | 已用完 | 灰色 | 流量已耗尽 |
| 3 | 已过期 | 红色 | 超过有效期 |
| 4 | 已失效 | 灰色 | 主动失效 |
### 套餐类型 (package_type)
- **formal** - 正式套餐 (主套餐)
- **addon** - 加油包 (附加套餐,有master_usage_id)
### 使用类型 (usage_type)
- **single_card** - 单卡使用
- **device** - 设备使用
### 流量相关
- **data_limit_mb** - 真流量总量(MB)
- **data_usage_mb** - 已用真流量(MB)
- **virtual_limit_mb** - 虚流量总量(MB)
- **virtual_used_mb** - 已用虚流量(MB)
- **virtual_remain_mb** - 剩余虚流量(MB)
- **virtual_ratio** - 虚流量比例 (真实/虚拟)
**示例**: 如果 virtual_ratio = 0.5
- 真流量 1GB = 虚流量 2GB
- 显示比例: 1:2
---
## 🎨 页面结构
### 1. 数据概览页 (Dashboard)
```
┌─────────────────────────────────┐
│ GT Agent [代理端][企业端] │
│ 🔍 [搜索套餐名称...] │
├─────────────────────────────────┤
│ │
│ ┌──────┬──────┐ │ ← 统计卡片
│ │套餐 │生效中│ │
│ │总数 │ │ │
│ │ 4 │ 2 │ │
│ └──────┴──────┘ │
│ ┌──────┬──────┐ │
│ │待生效│已过期│ │
│ │ 1 │ 1 │ │
│ └──────┴──────┘ │
│ │
│ ┌─────────────────────┐ │ ← 快捷操作
│ │ 套餐 添加 统计 记录│ │
│ └─────────────────────┘ │
│ │
│ ┌─────────────────────┐ │ ← 最近套餐
│ │ 最近套餐 查看全部→│ │
│ │ │ │
│ │ 月付套餐 50GB │ │
│ │ 生效中 │ │
│ │ [进度条] 25/100GB │ │
│ │ 到期: 2024-04-01 │ │
│ └─────────────────────┘ │
│ │
└─────────────────────────────────┘
```
### 2. 套餐列表页
```
┌─────────────────────────────────┐
│ ← 返回 套餐列表 [筛选] │
├─────────────────────────────────┤
│ │
│ [全部] 生效中 待生效 已过期 → │ ← 筛选标签
│ │
│ ┌─────────────────────┐ │ ← 套餐卡片
│ │ 月付套餐 50GB 生效中│ │
│ │ 正式套餐 优先级:1 │ │
│ │ │ │
│ │ 虚流量使用 │ │
│ │ [████░░░] 25/100GB │ │
│ │ 真流量: 12.5/50GB │ │
│ │ │ │
│ │ 激活:2024-03-01 │ │
│ │ 到期:2024-04-01(剩5天) │ │
│ └─────────────────────┘ │
│ │
│ ┌─────────────────────┐ │
│ │ 加油包 20GB 生效中│ │
│ │ 加油包 优先级:2 │ │
│ │ [████░░░] 10/40GB │ │
│ └─────────────────────┘ │
│ │
└─────────────────────────────────┘
```
### 3. 套餐详情页
```
┌─────────────────────────────────┐
│ ← 返回列表 │
├─────────────────────────────────┤
│ │
│ ┌─────────────────────┐ │ ← 基本信息
│ │ 月付套餐 50GB 生效中│ │
│ │ │ │
│ │ 套餐类型: 正式套餐 │ │
│ │ 优先级: 1 │ │
│ └─────────────────────┘ │
│ │
│ ┌─────────────────────┐ │ ← 流量使用
│ │ 流量使用 │ │
│ │ │ │
│ │ 虚流量使用 25% │ │
│ │ [████████░░] │ │
│ │ │ │
│ │ 已用 剩余 总量│ │
│ │ 25GB 75GB 100GB│ │
│ │ │ │
│ │ 真流量: 12.5/50GB │ │
│ │ [████░░░░░] │ │
│ │ │ │
│ │ 虚流量比例: 1:2 │ │
│ └─────────────────────┘ │
│ │
│ ┌─────────────────────┐ │ ← 时间信息
│ │ 时间信息 │ │
│ │ 创建:2024-02-25 │ │
│ │ 激活:2024-03-01 │ │
│ │ 到期:2024-04-01 │ │
│ │ 剩余5天 │ │
│ └─────────────────────┘ │
│ │
│ [续费套餐] [购买加油包] │
│ │
└─────────────────────────────────┘
```
---
## 🎨 状态颜色方案
### 套餐状态标签
```scss
// 待生效 (status: 0)
color: #ff9800
background: #fff3e0
// 生效中 (status: 1)
color: #4caf50
background: #e8f5e9
// 已用完 (status: 2)
color: #9e9e9e
background: #f5f5f5
// 已过期 (status: 3)
color: #f44336
background: #ffebee
// 已失效 (status: 4)
color: #757575
background: #eeeeee
```
### 进度条颜色
```scss
// 正常使用 (status: 1)
进度条: #4caf50 (绿色)
// 已用完 (status: 2)
进度条: #f44336 (红色)
// 真流量进度条
进度条: #2196f3 (蓝色)
```
### 剩余天数颜色
```scss
// ≤ 7天 (即将过期)
text-color: #f44336 (红色)
// 7-30天 (提醒)
text-color: #ff9800 (橙色)
// > 30天 (正常)
text-color: #4caf50 (绿色)
```
---
## 💡 交互说明
### 1. 套餐筛选
点击顶部筛选标签:
- **全部** - 显示所有套餐
- **生效中** - 仅显示 status = 1
- **待生效** - 仅显示 status = 0
- **已过期** - 仅显示 status = 3
### 2. 查看详情
点击套餐卡片 → 跳转详情页
### 3. 返回导航
- 列表页 → 点击"← 返回" → 数据概览
- 详情页 → 点击"← 返回列表" → 列表页
---
## 📊 流量计算逻辑
### 虚流量比例计算
```typescript
// 示例: virtual_ratio = 0.5
// 真流量 1GB = 虚流量 2GB
显示比例 = 1 : (1 / virtual_ratio)
= 1 : (1 / 0.5)
= 1 : 2
// 虚流量换算
virtual_limit_mb = data_limit_mb / virtual_ratio
= 50GB / 0.5
= 100GB
```
### 使用百分比
```typescript
usagePercent = (used / total) * 100
= (25600 / 102400) * 100
= 25%
```
### 剩余天数
```typescript
remainingDays = (expires_at - now) / (24小时)
= 向上取整
// 颜色判断
if (remainingDays <= 7) → 红色
else if (remainingDays <= 30) → 橙色
else → 绿色
```
---
## 🔧 数据示例
### 示例 1: 正式套餐
```json
{
"package_usage_id": 1,
"package_id": 101,
"package_name": "月付套餐 50GB",
"package_type": "formal",
"status": 1,
"status_name": "生效中",
"data_limit_mb": 51200, // 50GB
"data_usage_mb": 12800, // 12.5GB
"virtual_limit_mb": 102400, // 100GB (50GB / 0.5)
"virtual_used_mb": 25600, // 25GB
"virtual_remain_mb": 76800, // 75GB
"virtual_ratio": 0.5, // 1:2比例
"priority": 1,
"usage_type": "single_card",
"master_usage_id": null,
"activated_at": "2024-03-01T10:00:00Z",
"expires_at": "2024-04-01T10:00:00Z",
"created_at": "2024-02-25T15:30:00Z"
}
```
### 示例 2: 加油包
```json
{
"package_usage_id": 2,
"package_id": 102,
"package_name": "加油包 20GB",
"package_type": "addon",
"status": 1,
"status_name": "生效中",
"data_limit_mb": 20480, // 20GB
"data_usage_mb": 5120, // 5GB
"virtual_limit_mb": 40960, // 40GB
"virtual_used_mb": 10240, // 10GB
"virtual_remain_mb": 30720, // 30GB
"virtual_ratio": 0.5,
"priority": 2,
"usage_type": "single_card",
"master_usage_id": 1, // 关联主套餐ID
"activated_at": "2024-03-15T14:00:00Z",
"expires_at": "2024-04-15T14:00:00Z",
"created_at": "2024-03-15T13:00:00Z"
}
```
---
## ✅ 设计检查清单
- [x] 套餐状态使用对应颜色标签
- [x] 进度条颜色区分状态
- [x] 虚流量/真流量分别展示
- [x] 虚流量比例清晰显示
- [x] 剩余天数有颜色提醒
- [x] 加油包显示主套餐关联
- [x] 待生效套餐不显示激活/到期时间
- [x] 流量单位自动换算 (MB/GB)
- [x] 所有时间格式统一
- [x] 空状态有友好提示
---
## 🎯 下一步开发
### 优先级 P0
- [ ] **API接口对接** - 获取真实套餐数据
- [ ] **搜索功能** - 按套餐名称搜索
- [ ] **下拉刷新** - 刷新套餐列表
- [ ] **分页加载** - 长列表分页
### 优先级 P1
- [ ] **续费功能** - 续费套餐表单
- [ ] **购买加油包** - 加油包选择和购买
- [ ] **套餐详情操作** - 更多操作选项
- [ ] **使用记录** - 流量使用历史
### 优先级 P2
- [ ] **图表统计** - 流量使用趋势图
- [ ] **到期提醒** - 即将到期推送
- [ ] **自动续费** - 自动续费开关
---
## 📐 字段映射表
| API字段 | 显示名称 | 类型 | 说明 |
|---------|---------|------|------|
| package_usage_id | 套餐使用ID | number | 主键 |
| package_id | 套餐ID | number | 套餐模板ID |
| package_name | 套餐名称 | string | 显示标题 |
| package_type | 套餐类型 | string | formal/addon |
| status | 状态码 | number | 0-4 |
| status_name | 状态名称 | string | 中文状态 |
| data_limit_mb | 真流量总量 | number | MB单位 |
| data_usage_mb | 真流量已用 | number | MB单位 |
| virtual_limit_mb | 虚流量总量 | number | MB单位 |
| virtual_used_mb | 虚流量已用 | number | MB单位 |
| virtual_remain_mb | 虚流量剩余 | number | MB单位 |
| virtual_ratio | 虚流量比例 | number | 小数 |
| priority | 优先级 | number | 越小越优先 |
| usage_type | 使用类型 | string | single_card/device |
| master_usage_id | 主套餐ID | number/null | 加油包关联 |
| activated_at | 激活时间 | datetime/null | ISO格式 |
| expires_at | 到期时间 | datetime/null | ISO格式 |
| created_at | 创建时间 | datetime | ISO格式 |
---
**小米米家风格 - 简约、清晰、易用** 🎨
Reference in New Issue View Git Blame Copy Permalink