gt-agent-company/套餐列表页面说明.md

套餐列表页面 - 使用说明

小米米家风格 - 简约、纯粹的套餐管理页面

---

🚀 快速启动

pnpm dev:h5
# 访问 http://localhost:5173/

页面入口: src/pages/agent-system/index.vue

---

✨ 页面结构

简化设计

• ✅ 无顶部导航 - 去除Logo、搜索框、角色切换
• ✅ 直接显示列表 - 首页即套餐列表
• ✅ 两层结构 - 列表页 + 详情页

首页 (套餐列表)
├─ 统计卡片 (4个)
├─ 筛选标签 (全部、生效中、待生效、已过期)
└─ 套餐卡片列表
    └─ 点击卡片 → 套餐详情页
                  └─ 点击返回 → 回到首页

---

📱 页面展示

首页 - 套餐列表

┌─────────────────────────────────┐
│                                 │
│  ┌──────┬──────┐                │ ← 统计卡片
│  │套餐  │生效中│                │
│  │总数  │      │                │
│  │  4   │  2   │                │
│  └──────┴──────┘                │
│  ┌──────┬──────┐                │
│  │待生效│已过期│                │
│  │  1   │  1   │                │
│  └──────┴──────┘                │
│                                 │
│  [全部] 生效中 待生效 已过期 →  │ ← 筛选标签
│                                 │
│  ┌─────────────────────┐        │ ← 套餐卡片
│  │  月付套餐 50GB   生效中│        │
│  │  正式套餐   优先级:1  │        │
│  │                     │        │
│  │  虚流量使用          │        │
│  │  [████░░░] 25/100GB │        │
│  │  真流量: 12.5/50GB  │        │
│  │                     │        │
│  │  激活:03-01  到期:04-01 │     │
│  │            (剩5天)   │        │
│  └─────────────────────┘        │
│                                 │
│  ┌─────────────────────┐        │
│  │  加油包 20GB    生效中│        │
│  │  加油包   优先级:2   │        │
│  │  [████░░░] 10/40GB  │        │
│  │  激活:03-15  到期:04-15│      │
│  └─────────────────────┘        │
│                                 │
└─────────────────────────────────┘

详情页 - 套餐详情

┌─────────────────────────────────┐
│  ← 返回                          │
├─────────────────────────────────┤
│                                 │
│  ┌─────────────────────┐        │ ← 基本信息
│  │  月付套餐 50GB   生效中│        │
│  │                     │        │
│  │  套餐类型: 正式套餐 │        │
│  │  优先级: 1          │        │
│  └─────────────────────┘        │
│                                 │
│  ┌─────────────────────┐        │ ← 流量详情
│  │  流量使用           │        │
│  │                     │        │
│  │  虚流量使用   25%   │        │
│  │  [████████░░]       │        │
│  │                     │        │
│  │  已用    剩余    总量│        │
│  │  25GB   75GB   100GB│        │
│  │                     │        │
│  │  真流量: 12.5/50GB  │        │
│  │  [████░░░░░]        │        │
│  │                     │        │
│  │  虚流量比例: 1:2    │        │
│  └─────────────────────┘        │
│                                 │
│  ┌─────────────────────┐        │ ← 时间信息
│  │  时间信息           │        │
│  │  创建:2024-02-25    │        │
│  │  激活:2024-03-01    │        │
│  │  到期:2024-04-01    │        │
│  │       剩余5天       │        │
│  └─────────────────────┘        │
│                                 │
│  [续费套餐] [购买加油包]        │
│                                 │
└─────────────────────────────────┘

---

🎨 核心功能

1. 统计卡片 (4个)

套餐总数 - 蓝色图标
生效中   - 绿色图标
待生效   - 橙色图标
已过期   - 红色图标

2. 状态筛选

点击筛选标签过滤套餐:

标签	筛选条件	颜色
全部	显示所有	橙色背景 (激活态)
生效中	status = 1	绿色背景 (激活态)
待生效	status = 0	橙色背景 (激活态)
已过期	status = 3	红色背景 (激活态)

3. 套餐卡片

每个卡片显示:

• 标题行 - 套餐名称 + 状态标签
• 类型行 - 套餐类型 + 优先级
• 虚流量进度条 - 8px高度,显示使用比例
• 真流量文字 - 已用/总量
• 时间行 - 激活时间 + 到期时间 + 剩余天数

4. 套餐详情

点击卡片进入详情页,显示:

• 基本信息 - 名称、类型、优先级、关联主套餐
• 流量使用 - 虚流量大进度条 + 三格统计 + 真流量小进度条 + 比例
• 时间信息 - 创建、激活、到期、剩余天数
• 操作按钮 - 续费套餐 / 购买加油包

---

🎯 状态颜色

套餐状态标签

状态	文字颜色	背景颜色
待生效	#ff9800	#fff3e0
生效中	#4caf50	#e8f5e9
已用完	#9e9e9e	#f5f5f5
已过期	#f44336	#ffebee
已失效	#757575	#eeeeee

进度条颜色

// 虚流量进度条
status === 1 (生效中) → #4caf50 绿色
status === 2 (已用完) → #f44336 红色
其他状态             → #9e9e9e 灰色

// 真流量进度条
固定使用 #2196f3 蓝色

剩余天数

≤ 7天   → #f44336 红色 (紧急)
8-30天  → #ff9800 橙色 (提醒)
> 30天  → 不显示颜色 (正常)

---

💡 交互说明

列表页交互

1. 点击统计卡片 - 无交互 (纯展示)
2. 点击筛选标签 - 过滤套餐列表
3. 点击套餐卡片 - 进入套餐详情页
4. 上下滑动 - 浏览套餐列表

详情页交互

1. 点击返回按钮 - 返回套餐列表
2. 点击续费套餐 - (待实现) 打开续费表单
3. 点击购买加油包 - (待实现) 跳转加油包选择页

---

📊 数据示例

套餐列表数据

interface PackageUsage {
  package_usage_id: number        // 使用记录ID
  package_id: number              // 套餐模板ID
  package_name: string            // 套餐名称
  package_type: 'formal' | 'addon' // 套餐类型
  status: 0 | 1 | 2 | 3 | 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              // 使用类型
  master_usage_id: number | null  // 主套餐ID
  activated_at: string | null     // 激活时间
  expires_at: string | null       // 到期时间
  created_at: string              // 创建时间
}

---

🔧 核心函数

1. 流量格式化

function formatDataSize(mb: number): string {
  if (mb < 1024) return `${mb}MB`
  return `${(mb / 1024).toFixed(1)}GB`
}

// 示例:
formatDataSize(512)    // → "512MB"
formatDataSize(51200)  // → "50.0GB"

2. 使用百分比

function calcUsagePercent(used: number, total: number): number {
  if (total === 0) return 0
  return Math.min(Math.round((used / total) * 100), 100)
}

// 示例:
calcUsagePercent(25600, 102400)  // → 25

3. 剩余天数

function calcRemainingDays(expiresAt: string | null): number | null {
  if (!expiresAt) return null
  const now = new Date()
  const expireDate = new Date(expiresAt)
  const diff = expireDate.getTime() - now.getTime()
  return Math.ceil(diff / (1000 * 60 * 60 * 24))
}

// 示例:
calcRemainingDays('2024-04-01T10:00:00Z')  // → 5 (假设今天是3月27日)

4. 时间格式化

function formatDate(dateStr: string | null): string {
  if (!dateStr) return '--'
  const date = new Date(dateStr)
  return `${date.getMonth() + 1}-${String(date.getDate()).padStart(2, '0')}`
}

// 示例:
formatDate('2024-03-01T10:00:00Z')  // → "3-01"
formatDate(null)                    // → "--"

---

✅ 设计检查清单

• 移除顶部导航栏
• 移除Logo和搜索框
• 移除角色切换
• 首页直接显示套餐列表
• 统计卡片正常显示
• 筛选标签功能正常
• 套餐卡片样式正确
• 详情页返回功能正常
• 状态颜色准确
• 进度条显示正确

---

🎯 下一步开发

优先级 P0 (核心功能)

• API接口对接 - 获取真实套餐数据
• 下拉刷新 - 刷新套餐列表
• 上拉加载 - 分页加载更多

优先级 P1 (重要功能)

• 续费功能 - 续费套餐表单和支付
• 购买加油包 - 加油包选择和购买流程
• 套餐详情操作 - 更多操作选项

优先级 P2 (增强体验)

• 图表统计 - 流量使用趋势图
• 到期提醒 - 即将到期推送通知
• 搜索功能 - 按套餐名称搜索

---

📐 布局尺寸

间距

页面边距: px-4 (16px)
卡片间距: gap-3 (12px)
卡片内边距: p-4 (16px)
小元素间距: gap-2 (8px)

字号

24px - 统计数值
16px - 套餐名称
14px - 按钮文字
13px - 流量数值
12px - 状态标签
11px - 时间信息

圆角

12px - 卡片圆角
8px  - 进度条圆角
full - 状态标签圆角

---

小米米家风格 - 简约纯粹 🎨