junhong_cmp_fiber/docs/refactor-commission-package-model/前端接口迁移指南.md

套餐与佣金模型重构 - 前端接口迁移指南

版本: v1.1
更新日期: 2026-02-03
影响范围: 套餐管理、系列管理、分配管理相关接口

---

一、变更概述

本次重构主要目标：

1. 简化套餐价格字段（移除语义不清的字段）
2. 支持真流量/虚流量共存机制
3. 实现一次性佣金链式分配（上级给下级设置金额）
4. 统一分配模型

⚠️ 重要：废弃内容汇总

请确保前端代码中不再使用以下内容：

已废弃的枚举值

旧值	新值	说明
single_recharge	first_recharge	触发类型：单次充值 → 首充

已废弃的请求字段（系列分配接口）

以下字段在系列分配接口中已完全移除，前端不应再传递：

// ❌ 以下字段已废弃，请勿使用
{
  "enable_one_time_commission": true,      // 已废弃
  "one_time_commission_type": "fixed",     // 已废弃
  "one_time_commission_trigger": "...",    // 已废弃
  "one_time_commission_threshold": 10000,  // 已废弃
  "one_time_commission_mode": "fixed",     // 已废弃
  "one_time_commission_value": 5000,       // 已废弃
  "enable_force_recharge": false,          // 已废弃
  "force_recharge_amount": 0               // 已废弃
}

替代方案：一次性佣金规则现在在套餐系列中配置，系列分配只需设置 one_time_commission_amount。

已废弃的响应字段

系列分配响应中不再返回以下字段：

• one_time_commission_type
• one_time_commission_trigger
• one_time_commission_threshold
• one_time_commission_mode
• one_time_commission_value
• enable_force_recharge
• force_recharge_amount
• force_recharge_trigger_type
• one_time_commission_tiers（完整梯度配置）

---

二、套餐接口变更

2.1 创建套餐 POST /api/admin/packages

❌ 移除字段:

{
  "price": 9900,           // 已移除
  "data_type": "real",     // 已移除
  "data_amount_mb": 1024   // 已移除
}

✅ 新增字段:

{
  "enable_virtual_data": true,    // 是否启用虚流量
  "real_data_mb": 1024,           // 真流量额度(MB) - 必填
  "virtual_data_mb": 512,         // 虚流量额度(MB) - 启用虚流量时必填
  "cost_price": 5000              // 成本价(分) - 必填
}

完整请求示例:

{
  "package_code": "PKG_001",
  "package_name": "月度套餐",
  "series_id": 1,
  "package_type": "formal",
  "duration_months": 1,
  "real_data_mb": 1024,
  "virtual_data_mb": 512,
  "enable_virtual_data": true,
  "cost_price": 5000,
  "suggested_retail_price": 9900
}

校验规则:

• 启用虚流量时 (enable_virtual_data: true)：
  • virtual_data_mb 必须 > 0
  • virtual_data_mb 必须 ≤ real_data_mb

---

2.2 更新套餐 PUT /api/admin/packages/:id

字段变更同上，所有字段均为可选。

---

2.3 套餐列表/详情响应变更

✅ 新增字段（代理用户可见）:

{
  "id": 1,
  "package_code": "PKG_001",
  "package_name": "月度套餐",
  "real_data_mb": 1024,
  "virtual_data_mb": 512,
  "enable_virtual_data": true,
  "cost_price": 5000,
  "suggested_retail_price": 9900,
  
  // 以下字段仅代理用户可见
  "one_time_commission_amount": 1000,  // 该代理能拿到的一次性佣金(分)
  "profit_margin": 4900,               // 利润空间(分)
  "current_commission_rate": "5.00元/单",
  "tier_info": {
    "current_rate": "5.00元/单",
    "next_threshold": 100,
    "next_rate": "8.00元/单"
  }
}

说明:

• cost_price: 对于平台/平台用户是基础成本价，对于代理用户是该代理的成本价（从分配关系中获取）
• one_time_commission_amount: 该代理能拿到的一次性佣金金额

---

三、套餐系列接口变更

3.1 创建/更新套餐系列

✅ 新增嵌套结构 one_time_commission_config:

{
  "series_code": "SERIES_001",
  "series_name": "标准套餐系列",
  "description": "包含所有标准流量套餐",
  "one_time_commission_config": {
    "enable": true,
    "trigger_type": "first_recharge",
    "threshold": 10000,
    "commission_type": "fixed",
    "commission_amount": 5000,
    "validity_type": "permanent",
    "validity_value": "",
    "enable_force_recharge": false,
    "force_calc_type": "fixed",
    "force_amount": 0
  }
}

字段说明:

字段	类型	说明
enable	boolean	是否启用一次性佣金
trigger_type	string	触发类型: first_recharge(首充) / accumulated_recharge(累计充值)
threshold	int64	触发阈值（分）
commission_type	string	佣金类型: fixed(固定) / tiered(梯度)
commission_amount	int64	固定佣金金额（分），commission_type=fixed 时使用
validity_type	string	时效类型: permanent(永久) / fixed_date(固定日期) / relative(相对时长)
validity_value	string	时效值: 日期(2026-12-31) 或 月数(12)
enable_force_recharge	boolean	是否启用强充
force_calc_type	string	强充计算类型: fixed(固定) / dynamic(动态)
force_amount	int64	强充金额（分），force_calc_type=fixed 时使用

---

四、系列分配接口变更

4.1 创建系列分配 POST /api/admin/shop-series-allocations

❌ 移除字段（旧接口中的一次性佣金完整配置）:

{
  "enable_one_time_commission": true,
  "one_time_commission_type": "fixed",
  "one_time_commission_trigger": "single_recharge",
  "one_time_commission_threshold": 10000,
  "one_time_commission_mode": "fixed",
  "one_time_commission_value": 5000,
  "enable_force_recharge": false,
  "force_recharge_amount": 0
}

✅ 新增字段:

{
  "shop_id": 10,
  "series_id": 1,
  "base_commission": {
    "mode": "fixed",
    "value": 500
  },
  "one_time_commission_amount": 5000  // 给被分配店铺的一次性佣金金额(分)
}

说明:

• 一次性佣金的规则（触发条件、阈值、时效等）现在在套餐系列中统一配置
• 系列分配只需要设置给下级的金额

---

4.2 系列分配响应

{
  "id": 1,
  "shop_id": 10,
  "shop_name": "测试店铺",
  "series_id": 1,
  "series_name": "标准套餐系列",
  "allocator_shop_id": 5,
  "allocator_shop_name": "上级店铺",
  "base_commission": {
    "mode": "fixed",
    "value": 500
  },
  "one_time_commission_amount": 5000,
  "status": 1,
  "created_at": "2026-02-03T10:00:00Z",
  "updated_at": "2026-02-03T10:00:00Z"
}

---

五、套餐分配接口变更

5.1 创建/更新套餐分配

✅ 新增字段:

{
  "shop_id": 10,
  "package_id": 1,
  "cost_price": 6000,
  "one_time_commission_amount": 3000  // 给下级的一次性佣金金额(分)
}

校验规则:

• one_time_commission_amount 必须 ≥ 0
• one_time_commission_amount 不能超过上级能拿到的金额
• 平台用户不受金额限制

---

5.2 套餐分配响应

{
  "id": 1,
  "shop_id": 10,
  "shop_name": "下级店铺",
  "package_id": 1,
  "package_name": "月度套餐",
  "package_code": "PKG_001",
  "allocation_id": 5,
  "cost_price": 6000,
  "calculated_cost_price": 5500,
  "one_time_commission_amount": 3000,
  "status": 1,
  "created_at": "2026-02-03T10:00:00Z",
  "updated_at": "2026-02-03T10:00:00Z"
}

---

六、一次性佣金链式分配说明

6.1 概念

平台设置系列一次性佣金规则：首充 100 元返 50 元

平台 → 一级代理 A（给 A 设置 40 元）
        ↓
      一级代理 A → 二级代理 B（给 B 设置 25 元）
                    ↓
                  二级代理 B → 三级代理 C（给 C 设置 10 元）

当三级代理 C 的客户首充 100 元时：

• 三级代理 C 获得: 10 元
• 二级代理 B 获得: 25 - 10 = 15 元
• 一级代理 A 获得: 40 - 25 = 15 元
• 平台获得: 50 - 40 = 10 元

6.2 前端展示建议

在分配界面展示：

• "上级能拿到的一次性佣金: 40 元"
• "给下级设置的一次性佣金: [输入框，最大 40 元]"
• "自己实际获得: [自动计算] 元"

---

七、枚举值参考

触发类型 (trigger_type)

值	说明
first_recharge	首充触发
accumulated_recharge	累计充值触发

佣金类型 (commission_type)

值	说明
fixed	固定金额
tiered	梯度（根据销量/销售额）

时效类型 (validity_type)

值	说明	validity_value 格式
permanent	永久有效	空
fixed_date	固定到期日	2026-12-31
relative	相对时长（激活后N月）	12

强充计算类型 (force_calc_type)

值	说明
fixed	固定金额
dynamic	动态计算（max(首充要求, 套餐售价)）

---

八、迁移检查清单

🔴 必须删除的代码

请搜索并删除以下内容：

# 搜索废弃的枚举值
grep -r "single_recharge" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.vue"

# 搜索废弃的字段名
grep -r "one_time_commission_type\|one_time_commission_trigger\|one_time_commission_threshold\|one_time_commission_mode\|one_time_commission_value\|enable_one_time_commission\|force_recharge_amount\|enable_force_recharge" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.vue"

套餐管理页面

• 移除 price、data_type、data_amount_mb 字段
• 新增 enable_virtual_data 开关
• 新增虚流量校验逻辑（≤ 真流量）
• 代理视角显示 one_time_commission_amount

套餐系列管理页面

• 新增一次性佣金规则配置表单
• 支持时效类型选择和值输入
• 触发类型使用 first_recharge（不是旧的 single_recharge）

系列分配页面

• 删除旧的一次性佣金完整配置表单（8个字段）
• 删除梯度配置表单
• 新增 one_time_commission_amount 输入（金额字段）
• 显示上级能拿到的最大金额作为输入上限

套餐分配页面

• 新增 one_time_commission_amount 输入
• 显示校验错误（超过上级金额限制）

全局检查

• 将所有 single_recharge 替换为 first_recharge
• 移除系列分配相关的废弃字段引用
• 更新 TypeScript 类型定义

---

九、联系方式

如有疑问，请联系后端开发团队。