# Proposal: 套餐系统升级 - 支持自然月/按天套餐与多套餐管理

## Why

现有套餐系统仅支持简单的按月计算模式，无法满足业务方提出的复杂套餐需求。具体痛点包括：(1) 代理商囤货场景无法支持 - 需要提前为未实名设备低价采购套餐，等待首次实名时自动激活；(2) 套餐类型单一 - 缺少自然月套餐（按月边界计算）和按天套餐（灵活天数）；(3) 多套餐管理混乱 - 主套餐可同时多个生效、加油包无生命周期管理、流量扣减无优先级；(4) 流量统计不精细 - 客户无法区分主套餐和加油包用量，缺少套餐维度的流量详单。这些限制直接影响运营效率和用户体验。

## What Changes

### 套餐模型扩展
- 新增 `calendar_type` 字段：支持 `natural_month`（自然月套餐）和 `by_day`（按天套餐）
- 新增 `data_reset_cycle` 字段：支持 `daily`、`monthly`、`yearly`、`none` 四种流量重置周期
- 新增 `enable_realname_activation` 字段：标识是否需要首次实名激活（后台囤货场景）

### 套餐使用记录扩展
- PackageUsage 表 `status` 字段扩展：
  - 0 - 待生效（等待实名或排队中）
  - 1 - 生效中
  - 2 - 已用完
  - 3 - 已过期
  - 4 - 已失效（加油包跟随主套餐失效）
- 新增 `priority` 字段：主套餐排队顺序（数字越小优先级越高）
- 新增 `master_usage_id` 字段：加油包关联的主套餐ID
- 新增 `has_independent_expiry` 字段：加油包是否有独立有效期
- 新增 `pending_realname_activation` 字段：是否等待实名激活
- 新增流量重置相关字段：`data_reset_cycle`、`last_reset_at`、`next_reset_at`

### 新增套餐流量日记录表
- 创建 `PackageUsageDailyRecord` 表，按套餐维度记录每日流量增量
- 字段：`package_usage_id`、`date`、`daily_usage_mb`、`cumulative_usage_mb`
- 索引：`package_usage_id + date` 联合唯一索引

### 业务逻辑改造
- **首次实名激活**：轮询系统检测到首次实名时，触发 Asynq 任务激活待生效套餐
- **主套餐排队**：订单服务购买主套餐时，自动分配 priority，当前主套餐过期后调度器自动激活下一个
- **加油包生命周期**：主套餐过期时，轮询系统级联失效其关联的所有加油包
- **流量扣减优先级**：轮询系统更新流量时，优先扣减加油包（按 priority），再扣主套餐
- **停机条件**：轮询系统检查主套餐 + 所有加油包流量都用完才触发停机
- **流量重置调度**：定时任务根据 `data_reset_cycle` 定期重置套餐流量

### API 改造
- **套餐管理 API** (`/api/admin/packages`)：
  - POST/PUT 支持新增字段（calendar_type, data_reset_cycle, enable_realname_activation）
  - GET 返回包含新增字段
- **订单 API** (`/api/admin/orders` 和 `/api/h5/orders`)：
  - POST 支持主套餐排队逻辑（自动分配 priority）
  - POST 支持加油包购买限制（必须有主套餐）
  - 客户端未实名时购买套餐返回错误
- **流量查询 API**（新增）：
  - `GET /api/h5/packages/my-usage` - 客户视图（主套餐、每个加油包、总计）
  - `GET /api/admin/package-usage/:id/daily-records` - 套餐流量详单（按日）
  - 现有卡流量详单继续按卡维度统计

### 轮询系统扩展
- 新增套餐激活检查任务（HandlePackageActivation）
- 新增流量重置调度任务（HandleDataReset）
- 扩展流量检查任务（HandleCarddataCheck）支持新的扣减优先级和停机条件

## Capabilities

### New Capabilities
- `package-calendar-type` - 套餐周期类型管理（自然月/按天）
- `package-data-reset` - 套餐流量重置周期管理
- `package-realname-activation` - 首次实名激活机制
- `package-queue-activation` - 主套餐排队生效机制
- `addon-package-lifecycle` - 加油包生命周期管理
- `package-usage-priority` - 流量扣减优先级机制
- `package-usage-daily-record` - 套餐流量日记录
- `package-usage-customer-view` - 客户视图流量查询

### Modified Capabilities
- `package-management` - 套餐管理能力扩展（新增字段支持）
- `order-management` - 订单管理能力扩展（主套餐排队、加油包购买限制）
- `iot-card` - IoT卡轮询系统扩展（流量扣减优先级、停机条件）

## Impact

### 数据库
- 修改 `tb_package` 表（新增 3 个字段）
- 修改 `tb_package_usage` 表（新增 7 个字段，扩展 status 枚举）
- 新增 `tb_package_usage_daily_record` 表
- 需要数据库迁移脚本

### 代码模块
- `internal/model/package.go` - Package 和 PackageUsage 模型扩展
- `internal/model/package_usage_daily_record.go` - 新增模型
- `internal/service/order/` - 订单服务改造（主套餐排队、加油包限制）
- `internal/service/package/` - 套餐服务改造（支持新字段）
- `internal/polling/` - 轮询系统扩展（激活调度、流量扣减优先级、重置调度）
- `internal/handler/admin/package.go` - Handler 层 API 改造
- `internal/handler/h5/package_usage.go` - 新增客户视图 Handler
- `internal/store/postgres/package*.go` - Store 层查询逻辑扩展
- `pkg/errors/codes.go` - 新增错误码

### API
- **BREAKING** - `POST /api/admin/packages` 请求体新增可选字段
- **BREAKING** - `GET /api/admin/packages/:id` 响应体新增字段
- **NEW** - `GET /api/h5/packages/my-usage` - 客户视图
- **NEW** - `GET /api/admin/package-usage/:id/daily-records` - 套餐流量详单
- **BREAKING** - `POST /api/admin/orders` 和 `POST /api/h5/orders` 行为变更（主套餐排队、加油包限制）

### 依赖系统
- **Asynq 任务队列** - 新增套餐激活任务类型、流量重置任务类型
- **轮询系统** - 扩展流量检查、新增激活检查、新增重置调度
- **OpenAPI 文档生成器** - 需要更新以支持新增 Handler

### 性能
- 套餐激活调度延迟目标 < 1分钟
- 流量查询 API P95 < 200ms（现有要求保持）
- 轮询系统千万级卡规模支持不退化

### 测试
- 核心业务逻辑单元测试覆盖率 ≥ 90%
- 所有 Spec Scenarios 有对应的验收测试
- 需要编写集成测试验证完整流程（囤货 → 实名 → 激活 → 扣减 → 重置）