# 套餐与佣金业务模型

本文档定义了套餐、套餐系列、佣金的完整业务模型，作为系统改造的规范参考。

---

## 一、核心概念

### 1.1 两种佣金类型

系统只有两种佣金类型：

| 佣金类型 | 触发时机 | 触发次数 | 计算方式 |
|---------|---------|---------|---------|
| **差价佣金** | 每笔订单 | 每单都触发 | 下级成本价 - 自己成本价 |
| **一次性佣金** | 首充/累计充值达标 | 每张卡/设备只触发一次 | 上级给的 - 给下级的 |

### 1.2 实体关系

```
┌─────────────────┐
│   套餐系列       │
│  PackageSeries  │
├─────────────────┤
│ • 系列名称      │
│ • 一次性佣金规则 │ ← 可选配置
└────────┬────────┘
         │ 1:N
         ▼
┌─────────────────┐          ┌─────────────────┐
│     套餐        │          │    卡/设备      │
│    Package      │          │   IoT/Device    │
├─────────────────┤          ├─────────────────┤
│ • 成本价        │          │ • 绑定系列ID    │
│ • 建议售价      │          │ • 累计充值金额  │ ← 按系列累计
│ • 真流量(必填)  │          │ • 是否已首充    │ ← 按系列记录
│ • 虚流量(可选)  │          └────────┬────────┘
│ • 虚流量开关    │                   │
└────────┬────────┘                   │ 分配
         │                            ▼
         │ 分配              ┌─────────────────┐
         ▼                   │      店铺       │
┌─────────────────┐          │      Shop       │
│   套餐分配      │◀─────────┤ • 代理层级      │
│ PkgAllocation   │          │ • 上级店铺ID    │
├─────────────────┤          └─────────────────┘
│ • 店铺ID        │
│ • 套餐ID        │
│ • 成本价(加价后)│
│ • 一次性佣金额  │ ← 给该代理的金额
└─────────────────┘
```

---

## 二、套餐模型

### 2.1 字段定义

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `cost_price` | int64 | 是 | 成本价（平台设置的基础成本价，分） |
| `suggested_price` | int64 | 是 | 建议售价（给代理参考，分） |
| `real_data_mb` | int64 | 是 | 真实流量额度（MB） |
| `enable_virtual_data` | bool | 否 | 是否启用虚流量 |
| `virtual_data_mb` | int64 | 否 | 虚流量额度（启用时必填，≤ 真实流量，MB） |

### 2.2 流量停机判断

```
停机目标值 = enable_virtual_data ? virtual_data_mb : real_data_mb
```

### 2.3 不同用户视角

| 用户类型 | 看到的成本价 | 看到的一次性佣金 |
|---------|-------------|-----------------|
| 平台 | 基础成本价 | 完整规则 |
| 代理A | A的成本价（已加价） | A能拿到的金额 |
| 代理A1 | A1的成本价（再加价） | A1能拿到的金额 |

---

## 三、差价佣金

### 3.1 计算规则

```
平台设置基础成本价: 100
    │
    │ 分配给代理A，设置成本价: 120
    ▼
代理A成本价: 120
    │
    │ 分配给代理A1，设置成本价: 130
    ▼
代理A1成本价: 130
    │
    │ A1销售给客户，售价: 200
    ▼

结果：
  • A1 收入 = 200 - 130 = 70元（销售利润，不是佣金）
  • A 佣金 = 130 - 120 = 10元（差价佣金）
  • 平台收入 = 120元
```

### 3.2 关键区分

- **收入/利润**：末端代理的 `售价 - 自己成本价`
- **差价佣金**：上级代理的 `下级成本价 - 自己成本价`
- **平台收入**：一级代理的成本价

---

## 四、一次性佣金

### 4.1 触发条件

| 条件类型 | 说明 | 强充要求 |
|---------|------|---------|
| `first_recharge` | 首充：该卡/设备在该系列下的第一次充值 | 必须强充 |
| `accumulated_recharge` | 累计充值：累计充值金额达到阈值 | 可选强充 |

### 4.2 规则配置（套餐系列层面）

| 配置项 | 类型 | 说明 |
|--------|------|------|
| `enable` | bool | 是否启用一次性佣金 |
| `trigger_type` | string | 触发类型：`first_recharge` / `accumulated_recharge` |
| `threshold` | int64 | 触发阈值（分）：首充要求金额 或 累计要求金额 |
| `commission_type` | string | 返佣类型：`fixed`(固定) / `tiered`(梯度) |
| `commission_amount` | int64 | 固定返佣金额（fixed类型时） |
| `tiers` | array | 梯度配置（tiered类型时） |
| `validity_type` | string | 时效类型：`permanent` / `fixed_date` / `relative` |
| `validity_value` | string | 时效值（到期日期 或 月数） |
| `enable_force_recharge` | bool | 是否启用强充 |
| `force_calc_type` | string | 强充金额计算：`fixed`(固定) / `dynamic`(动态差额) |
| `force_amount` | int64 | 强充金额（fixed类型时） |

### 4.3 链式分配

一次性佣金在整条代理链上按约定分配：

```
系列规则：首充100返20

分配配置：
  平台给A：20元
  A给A1：8元
  A1给A2：5元

触发首充时：
  A2 获得：5元
  A1 获得：8 - 5 = 3元
  A  获得：20 - 8 = 12元
  ─────────────────────
  合计：20元 ✓
```

### 4.4 首充流程

```
客户购买套餐
    │
    ▼
预检：系列是否启用一次性佣金且为首充？
    │
   否 ───────────────────▶ 正常购买流程
    │
   是
    │
    ▼
该卡/设备在该系列下是否已首充过？
    │
   是 ───────────────────▶ 正常购买流程（不再返佣）
    │
   否
    │
    ▼
计算强充金额 = max(首充要求, 套餐售价)
    │
    ▼
返回提示："需要充值 xxx 元"
    │
    ▼
用户确认 → 创建充值订单(金额=强充金额)
    │
    ▼
用户支付
    │
    ▼
支付成功：
  1. 钱进入钱包
  2. 标记该卡/设备已首充
  3. 自动创建套餐购买订单并完成
  4. 扣款（套餐售价）
  5. 触发一次性佣金，链式分配
```

### 4.5 累计充值流程

```
客户充值（直接充值到钱包）
    │
    ▼
累计充值金额 += 本次充值金额
    │
    ▼
该卡/设备是否已触发过累计充值返佣？
    │
   是 ───────────────────▶ 结束（不再返佣）
    │
   否
    │
    ▼
累计金额 >= 累计要求？
    │
   否 ───────────────────▶ 结束（继续累计）
    │
   是
    │
    ▼
触发一次性佣金，链式分配
标记该卡/设备已触发累计充值返佣
```

**累计规则**：

| 操作类型 | 是否累计 |
|---------|---------|
| 直接充值到钱包 | ✅ 累计 |
| 直接购买套餐（不经过钱包） | ❌ 不累计 |
| 强充购买套餐（先充值再扣款） | ✅ 累计（充值部分） |

---

## 五、梯度佣金

梯度佣金是一次性佣金的进阶版，根据代理销量/销售额动态调整返佣金额。

### 5.1 配置项

| 配置项 | 类型 | 说明 |
|--------|------|------|
| `tier_dimension` | string | 梯度维度：`sales_count`(销量) / `sales_amount`(销售额) |
| `stat_scope` | string | 统计范围：`self`(仅自己) / `self_and_sub`(自己+下级) |
| `tiers` | array | 梯度档位列表 |
| `tiers[].threshold` | int64 | 阈值（销量或销售额） |
| `tiers[].amount` | int64 | 返佣金额（分） |

### 5.2 示例

```
梯度规则（销量维度）：
┌────────────────┬────────────────────────┐
│    销量区间     │    首充100返佣金额     │
├────────────────┼────────────────────────┤
│    >= 0        │         5元            │
├────────────────┼────────────────────────┤
│    >= 100      │        10元            │
├────────────────┼────────────────────────┤
│    >= 200      │        20元            │
└────────────────┴────────────────────────┘

代理A当前销量150单 → 落在 [100, 200) 区间 → 首充返10元
```

### 5.3 梯度升级

```
初始状态：
  代理A 销量150（适用10元档），给A1设置5元
  
  触发时：A1得5元，A得10-5=5元

升级后（A销量达到210）：
  A 适用20元档，A1配置仍为5元
  
  触发时：A1得5元（不变），A得20-5=15元（增量归上级）
```

### 5.4 统计周期

- 统计周期与一次性佣金时效一致
- 只统计该套餐系列下的销量/销售额

---

## 六、约束规则

### 6.1 套餐分配

1. 下级成本价 >= 自己成本价（不能亏本卖）
2. 只能分配自己有权限的套餐给下级
3. 只能分配给直属下级（不能跨级）

### 6.2 一次性佣金分配

4. 给下级的金额 <= 自己能拿到的金额
5. 给下级的金额 >= 0（可以设为0，独吞全部）

### 6.3 流量

6. 虚流量 <= 真实流量

### 6.4 配置修改

7. 修改配置只影响之后的新订单
8. 代理只能修改"给下级多少钱"，不能修改触发规则
9. 平台修改系列规则不影响已分配的代理，需收回重新分配

### 6.5 触发限制

10. 一次性佣金每张卡/设备只触发一次
11. "首充"指该卡/设备在该系列下的第一次充值
12. 累计充值只统计"充值"操作，不统计"直接购买"

---

## 七、操作流程

### 7.1 理想的线性流程

```
1. 创建套餐系列
   └─▶ 可选：配置一次性佣金规则

2. 创建套餐
   └─▶ 归属到系列
   └─▶ 设置成本价、建议售价
   └─▶ 设置真流量（必填）、虚流量（可选）

3. 分配套餐给代理
   └─▶ 设置代理成本价（加价）
   └─▶ 如果系列启用一次性佣金：设置给代理的一次性佣金额度

4. 分配资产（卡/设备）给代理
   └─▶ 资产绑定的套餐系列自动跟着走

5. 代理销售
   └─▶ 客户购买套餐
   └─▶ 差价佣金自动计算并入账给上级
   └─▶ 满足一次性佣金条件时，按链式分配入账
```

---

## 八、与现有代码的差异

详见改造提案：[refactor-commission-package-model](../openspec/changes/refactor-commission-package-model/)