# 套餐管理系统 - 移动端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格式 |

---

**小米米家风格 - 简约、清晰、易用** 🎨