# 套餐系统升级 - 使用指南

## 场景一：囤货待实名激活

### 业务场景

代理商后台为未实名的卡/设备预先购买套餐，用户实名后自动激活。

### 操作流程

```
1. 代理商登录后台
2. 选择未实名的卡/设备
3. 购买套餐（选择支持实名激活的套餐）
4. 套餐状态：待激活（status=0, pending_realname_activation=true）
5. 用户完成实名认证
6. 系统自动激活套餐
```

### 前置条件

- 套餐必须启用 `enable_realname_activation=true`
- 卡/设备当前未实名

### 注意事项

- 囤货套餐在实名前不会计算有效期
- 实名后，有效期从激活日期开始计算
- 如果卡/设备已实名，套餐会立即激活

---

## 场景二：主套餐排队

### 业务场景

用户当前有生效中的主套餐，想提前购买下一个套餐。

### 操作流程

```
1. 用户购买新主套餐
2. 系统检测到已有生效中主套餐
3. 新套餐进入排队状态（status=0, priority=N+1）
4. 当前主套餐过期
5. 系统自动激活排队中的下一个套餐
```

### 排队规则

| 情况 | 新套餐状态 |
|------|-----------|
| 无生效中主套餐 | 立即激活（status=1, priority=1） |
| 有生效中主套餐 | 排队等待（status=0, priority=MAX+1） |

### 查看排队情况

```http
GET /api/h5/packages/my-usage

// 响应
{
  "main_package": {
    "package_name": "月度套餐",
    "status": 1,  // 生效中
    "expires_at": "2025-03-31T23:59:59Z"
  },
  "queued_packages": [
    {
      "package_name": "季度套餐",
      "status": 0,  // 排队中
      "priority": 2
    }
  ]
}
```

---

## 场景三：加油包购买

### 业务场景

用户主套餐流量不够用，需要购买加油包补充流量。

### 操作流程

```
1. 确认用户有生效中或待生效的主套餐
2. 用户选择加油包
3. 系统自动绑定到当前主套餐
4. 加油包立即生效
5. 流量扣减时优先使用加油包
```

### 购买限制

| 限制项 | 说明 |
|-------|------|
| 必须有主套餐 | 无主套餐无法购买加油包 |
| 混买禁止 | 同一订单不能同时购买主套餐和加油包 |

### 加油包生命周期

```
主套餐过期 → 加油包自动失效（status=4）
```

### 加油包有效期

| 类型 | 有效期计算 |
|------|-----------|
| 随主套餐 | 与主套餐同时过期（has_independent_expiry=false） |
| 独立有效期 | 从购买日期开始计算（has_independent_expiry=true） |

---

## 场景四：流量查询

### 客户端查询我的流量

```http
GET /api/h5/packages/my-usage
Authorization: Bearer {token}
```

响应示例：

```json
{
  "code": 0,
  "data": {
    "main_package": {
      "package_usage_id": 101,
      "package_name": "月度套餐 30G",
      "data_limit_mb": 30720,
      "data_usage_mb": 15360,
      "status": 1,
      "activated_at": "2025-02-01T00:00:00Z",
      "expires_at": "2025-02-28T23:59:59Z"
    },
    "addon_packages": [
      {
        "package_usage_id": 102,
        "package_name": "加油包 5G",
        "data_limit_mb": 5120,
        "data_usage_mb": 2048,
        "status": 1,
        "priority": 2
      }
    ],
    "total": {
      "total_mb": 35840,
      "used_mb": 17408,
      "remaining_mb": 18432
    }
  }
}
```

### 后台查询套餐流量详单

```http
GET /api/admin/package-usage/101/daily-records?start_date=2025-02-01&end_date=2025-02-15
Authorization: Bearer {token}
```

响应示例：

```json
{
  "code": 0,
  "data": {
    "package_usage_id": 101,
    "package_name": "月度套餐 30G",
    "records": [
      {
        "date": "2025-02-01",
        "daily_usage_mb": 1024,
        "cumulative_usage_mb": 1024
      },
      {
        "date": "2025-02-02",
        "daily_usage_mb": 512,
        "cumulative_usage_mb": 1536
      }
    ],
    "total_usage_mb": 15360
  }
}
```

---

## 套餐状态说明

| 状态码 | 名称 | 说明 |
|-------|------|------|
| 0 | 待生效 | 排队中或待实名激活 |
| 1 | 生效中 | 正在使用 |
| 2 | 已用完 | 流量已耗尽 |
| 3 | 已过期 | 超过有效期 |
| 4 | 已失效 | 主套餐过期导致加油包失效 |

---

## 流量重置说明

### 重置类型

| 类型 | 套餐类型 | 重置时间 | 适用场景 |
|------|---------|---------|---------|
| 日重置 | 所有 | 每天 00:00:00 | 日租卡 |
| 月重置 | 自然月 | 每月1号 00:00:00 | 自然月套餐 |
| 月重置 | 按天 | 从激活日起每30天 | 按天套餐 |
| 年重置 | 所有 | 每年1月1日 | 年度套餐 |
| 不重置 | 所有 | 不重置 | 一次性流量包 |

### 重置行为

```
重置前：data_usage_mb = 25600
重置后：data_usage_mb = 0
```

- 重置只清空已用流量，不影响有效期
- 流量用完的套餐（status=2）重置后恢复为生效中（status=1）

---

## 停复机说明

### 停机条件

所有生效套餐流量用完：
- 主套餐 status=2
- 所有加油包 status=2

### 复机条件

- 购买新套餐
- 套餐流量重置
- 排队套餐激活

### 停机记录

```sql
-- 停机记录在 tb_iot_card 表
stopped_at: 停机时间
stop_reason: 停机原因（如 "流量耗尽"）

-- 复机后
resumed_at: 复机时间
```

---

## 常见问题

### Q: 为什么购买加油包提示"必须有主套餐"？

A: 加油包必须绑定到主套餐，请先购买主套餐再购买加油包。

### Q: 主套餐过期后加油包还能用吗？

A: 不能。主套餐过期后，绑定的加油包会自动失效（status=4）。

### Q: 套餐排队后可以取消吗？

A: 目前不支持取消排队中的套餐，请联系客服处理。

### Q: 流量重置后为什么还是停机状态？

A: 流量重置后系统会自动触发复机，如果仍是停机状态，请检查运营商接口是否正常。

### Q: H5 端未实名用户如何购买套餐？

A: H5 端必须先完成实名认证才能购买套餐。代理商可在后台为未实名用户囤货。
