# 红人分佣结算设计方案

## 一、背景

`2027-07-30会议纪要-整理版.md` 中提出红人管理需要记录合作次数、合作费用、分佣信息。

现有 `红人客户与寄样订单实现方案.md` 已经明确：

- 红人作为 `customer.type = 3` 的客户类型，不新增红人主表。
- 红人寄样订单复用 `sale_order`。
- 佣金、合作费用、其他费用可写入 `cost` 表，并通过费用类型区分。

当前缺口是：`cost` 适合记录已经确认或已经发生的费用，但不能完整表达“分佣规则、订单归因、佣金试算、结算确认、付款状态、调整记录”的业务过程。

因此需要在现有费用归集基础上补充分佣结算设计。

## 二、设计目标

1. 支持给红人配置分佣规则。
2. 支持把销售订单归因到红人。
3. 支持按订单自动计算应结佣金。
4. 支持人工调整、审核确认和生成结算单。
5. 支持付款后落到现有 `cost` 表，纳入订单成本和财务统计。
6. 保持红人主数据仍复用 `customer`，不新增独立红人主表。

## 三、核心口径

红人分佣分为四层：

```text
红人资料：customer(type = 3)
分佣规则：influencer_commission_rule
订单佣金：influencer_commission_order
结算单：influencer_commission_settlement / settlement_detail
实际付款成本：cost(type = 红人佣金)
```

其中：

- `influencer_commission_order` 记录每个订单应结佣金。
- `influencer_commission_settlement` 记录某个周期对某个红人的结算结果。
- `cost` 只记录结算确认后的实际付款费用，不承担规则计算和结算状态。

## 四、业务流程

### 1. 配置红人分佣规则

入口：红人详情页或红人管理页。

可配置：

- 固定金额。
- 按订单实收金额比例。
- 按订单毛利比例。
- 按商品金额比例。
- 阶梯分佣。
- 手工指定佣金。

第一阶段建议优先支持：

1. 固定金额。
2. 订单实收金额比例。
3. 手工指定佣金。

毛利比例和阶梯分佣可作为第二阶段。

### 2. 订单归因

订单需要明确属于哪个红人带来的销售。

归因来源建议：

| 来源 | 说明 |
| --- | --- |
| 手工选择红人 | ERP 创建订单时选择红人 |
| 折扣码 | Shopify 折扣码绑定红人 |
| 推广链接/UTM | 通过链接参数识别红人 |
| 红人寄样后转化 | 人工把正式销售订单关联到红人 |

第一阶段建议先支持手工选择红人，后续再接 Shopify 折扣码和推广链接。

### 3. 订单佣金计算

订单满足以下条件时生成佣金记录：

1. 订单已归因到红人。
2. 订单不是红人寄样订单。
3. 订单未取消。
4. 订单达到可结算节点，例如已发货、已完成或售后期结束。

佣金计算结果写入 `influencer_commission_order`。

### 4. 结算确认

按周期生成结算单，例如月结：

```text
选择红人 + 结算周期
  -> 查询周期内可结算订单佣金
  -> 生成结算单草稿
  -> 财务/负责人确认
  -> 结算单锁定
```

结算单锁定后，对应订单佣金记录不允许直接修改，只能通过调整单或重新打开结算单处理。

### 5. 付款与成本归集

结算单付款后生成 `cost` 记录：

```text
cost.pm = PM_OUT
cost.type = COST_TYPE_INFLUENCER_COMMISSION
cost.customer_id = 红人 customer.id
cost.amount = 实付佣金
cost.currency = 结算币种
cost.date = 付款时间
cost.trade_no = 付款流水号
cost.admin_remark = 结算单号/周期说明
```

如果结算单包含具体订单明细，可按以下方式处理：

- 第一阶段：生成一条汇总 `cost`，只关联 `customer_id`。
- 第二阶段：如需订单利润精确回写，可按订单拆成多条 `cost`，分别关联 `sale_order_id`。

推荐第一阶段先汇总生成一条 `cost`，避免过早复杂化付款记录。

## 五、推荐表结构

### 1. 红人分佣规则表

```sql
CREATE TABLE `hg_influencer_commission_rule` (
  `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
  `company_id` char(18) NOT NULL COMMENT '公司ID',
  `customer_id` int(11) unsigned NOT NULL COMMENT '红人客户ID',
  `title` varchar(128) DEFAULT NULL COMMENT '规则名称',
  `rule_type` tinyint(2) unsigned NOT NULL DEFAULT '1' COMMENT '规则类型: 1固定金额 2订单实收比例 3订单毛利比例 4商品金额比例 5手工',
  `commission_rate` decimal(8,4) DEFAULT NULL COMMENT '分佣比例，百分比',
  `commission_amount` decimal(10,2) DEFAULT NULL COMMENT '固定佣金金额',
  `currency` char(4) NOT NULL DEFAULT 'USD' COMMENT '币种',
  `settle_node` tinyint(2) unsigned NOT NULL DEFAULT '2' COMMENT '可结算节点: 1已付款 2已发货 3已完成 4售后期结束',
  `after_sale_days` int(11) unsigned NOT NULL DEFAULT '0' COMMENT '售后保护天数',
  `effective_start_date` date DEFAULT NULL COMMENT '生效开始日期',
  `effective_end_date` date DEFAULT NULL COMMENT '生效结束日期',
  `status` tinyint(2) unsigned NOT NULL DEFAULT '1' COMMENT '状态: 1启用 0停用',
  `admin_remark` varchar(500) DEFAULT NULL COMMENT '备注',
  `create_admin_id` int(11) unsigned DEFAULT NULL COMMENT '创建人',
  `edit_admin_id` int(11) unsigned DEFAULT NULL COMMENT '编辑人',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `update_time` datetime DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_company_customer` (`company_id`, `customer_id`),
  KEY `idx_status_date` (`status`, `effective_start_date`, `effective_end_date`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='红人分佣规则';
```

说明：

- 红人仍然来自 `customer`，通过 `customer_id` 关联。
- 同一个红人可以有多条历史规则，但同一时间只允许一条启用规则生效。
- 如果需要按平台、产品、渠道配置不同规则，可第二阶段增加适用范围字段或规则明细表。

### 2. 订单佣金表

```sql
CREATE TABLE `hg_influencer_commission_order` (
  `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
  `company_id` char(18) NOT NULL COMMENT '公司ID',
  `customer_id` int(11) unsigned NOT NULL COMMENT '红人客户ID',
  `sale_order_id` int(11) unsigned NOT NULL COMMENT '销售订单ID',
  `rule_id` int(11) unsigned DEFAULT NULL COMMENT '分佣规则ID',
  `source_type` tinyint(2) unsigned NOT NULL DEFAULT '1' COMMENT '归因来源: 1手工 2折扣码 3推广链接 4系统导入',
  `source_value` varchar(255) DEFAULT NULL COMMENT '归因值，如折扣码/UTM/链接',
  `order_amount` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '订单金额',
  `paid_amount` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '实收金额',
  `profit_amount` decimal(10,2) DEFAULT NULL COMMENT '订单毛利',
  `commission_base_amount` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '计佣基数',
  `commission_rate` decimal(8,4) DEFAULT NULL COMMENT '使用的分佣比例',
  `commission_amount` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '应结佣金',
  `currency` char(4) NOT NULL DEFAULT 'USD' COMMENT '币种',
  `status` tinyint(2) unsigned NOT NULL DEFAULT '0' COMMENT '状态: 0待确认 10可结算 20已结算 30已付款 80已作废',
  `settlement_id` int(11) unsigned DEFAULT NULL COMMENT '结算单ID',
  `settlement_detail_id` int(11) unsigned DEFAULT NULL COMMENT '结算明细ID',
  `adjust_amount` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '调整金额',
  `adjust_reason` varchar(500) DEFAULT NULL COMMENT '调整原因',
  `admin_remark` varchar(500) DEFAULT NULL COMMENT '备注',
  `create_admin_id` int(11) unsigned DEFAULT NULL COMMENT '创建人',
  `edit_admin_id` int(11) unsigned DEFAULT NULL COMMENT '编辑人',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `update_time` datetime DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uniq_order` (`company_id`, `sale_order_id`),
  KEY `idx_customer_status` (`customer_id`, `status`),
  KEY `idx_settlement` (`settlement_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='红人订单佣金';
```

说明：

- `commission_amount` 为规则计算金额。
- `adjust_amount` 为人工调整金额。
- 实际进入结算单的金额 = `commission_amount + adjust_amount`。
- 同一销售订单第一阶段只允许归因一个红人；多红人拆佣可后续扩展。

### 3. 红人分佣结算单表

```sql
CREATE TABLE `hg_influencer_commission_settlement` (
  `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
  `company_id` char(18) NOT NULL COMMENT '公司ID',
  `settlement_no` varchar(64) NOT NULL COMMENT '结算单号',
  `customer_id` int(11) unsigned NOT NULL COMMENT '红人客户ID',
  `period` varchar(32) NOT NULL COMMENT '结算周期，如 2026-08',
  `currency` char(4) NOT NULL DEFAULT 'USD' COMMENT '币种',
  `order_count` int(11) unsigned NOT NULL DEFAULT '0' COMMENT '订单数量',
  `commission_amount` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '佣金合计',
  `adjust_amount` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '调整合计',
  `payable_amount` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '应付金额',
  `paid_amount` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '已付金额',
  `status` tinyint(2) unsigned NOT NULL DEFAULT '0' COMMENT '状态: 0草稿 10待审核 20已确认 30部分付款 40已付款 80已作废',
  `cost_id` int(11) unsigned DEFAULT NULL COMMENT '关联付款费用ID',
  `pay_time` datetime DEFAULT NULL COMMENT '付款时间',
  `trade_no` varchar(128) DEFAULT NULL COMMENT '付款流水号',
  `admin_remark` varchar(500) DEFAULT NULL COMMENT '备注',
  `create_admin_id` int(11) unsigned DEFAULT NULL COMMENT '创建人',
  `edit_admin_id` int(11) unsigned DEFAULT NULL COMMENT '编辑人',
  `audit_admin_id` int(11) unsigned DEFAULT NULL COMMENT '审核人',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `update_time` datetime DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uniq_settlement_no` (`settlement_no`),
  KEY `idx_customer_period` (`customer_id`, `period`),
  KEY `idx_status` (`status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='红人分佣结算单';
```

### 4. 红人分佣结算明细表

```sql
CREATE TABLE `hg_influencer_commission_settlement_detail` (
  `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
  `company_id` char(18) NOT NULL COMMENT '公司ID',
  `settlement_id` int(11) unsigned NOT NULL COMMENT '结算单ID',
  `commission_order_id` int(11) unsigned NOT NULL COMMENT '订单佣金ID',
  `sale_order_id` int(11) unsigned NOT NULL COMMENT '销售订单ID',
  `order_amount` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '订单金额',
  `paid_amount` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '实收金额',
  `commission_base_amount` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '计佣基数',
  `commission_amount` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '佣金金额',
  `adjust_amount` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '调整金额',
  `settle_amount` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '本次结算金额',
  `currency` char(4) NOT NULL DEFAULT 'USD' COMMENT '币种',
  `admin_remark` varchar(500) DEFAULT NULL COMMENT '备注',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `update_time` datetime DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_settlement` (`settlement_id`),
  KEY `idx_order` (`sale_order_id`),
  KEY `idx_commission_order` (`commission_order_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='红人分佣结算明细';
```

## 六、状态流转

### 订单佣金状态

```text
待确认(0)
  -> 可结算(10)
  -> 已结算(20)
  -> 已付款(30)
  -> 已作废(80)
```

说明：

- 订单未达到结算节点前为待确认。
- 发货、完成或售后期结束后变为可结算。
- 加入结算单并确认后变为已结算。
- 结算单付款后变为已付款。
- 订单取消、退款全额冲销时变为已作废。

### 结算单状态

```text
草稿(0)
  -> 待审核(10)
  -> 已确认(20)
  -> 部分付款(30)
  -> 已付款(40)
  -> 已作废(80)
```

说明：

- 草稿状态允许增删明细。
- 已确认后锁定明细。
- 已付款后生成或关联 `cost`。
- 已付款结算单不允许删除，只允许通过冲销或负数调整处理。

## 七、佣金计算规则

### 1. 固定金额

```text
commission_amount = rule.commission_amount
```

适合单次合作固定返佣。

### 2. 订单实收比例

```text
commission_base_amount = sale_order.real_amount
commission_amount = commission_base_amount * commission_rate / 100
```

适合按成交额返佣。

### 3. 订单毛利比例

```text
commission_base_amount = sale_order.profit_amount
commission_amount = commission_base_amount * commission_rate / 100
```

适合控制返佣不超过利润空间。

### 4. 商品金额比例

```text
commission_base_amount = 可计佣商品明细金额合计
commission_amount = commission_base_amount * commission_rate / 100
```

适合排除运费、税费、折扣、不可计佣商品。

### 5. 手工指定

```text
commission_amount = 人工录入金额
```

适合早期上线、特殊合作和补录历史订单。

## 八、退款和售后处理

### 1. 未结算前退款

如果订单未进入结算单：

- 全额退款：订单佣金作废。
- 部分退款：重新计算计佣基数和佣金。

### 2. 已结算未付款退款

如果结算单已确认但未付款：

- 允许财务退回草稿或新增调整金额。
- 调整后重新确认。

### 3. 已付款后退款

如果结算单已付款：

- 不修改历史已付款结算单。
- 在下一期生成负数调整明细。
- 或生成红人佣金冲销记录。

推荐第一阶段使用“下一期负数调整”。

## 九、与现有模块关系

### 1. 与 customer

- 红人仍使用 `customer` 表。
- `customer.type = 3` 表示红人。
- 分佣规则和结算单通过 `customer_id` 关联红人。

### 2. 与 sale_order

需要在销售订单上保留红人归因信息。

第一阶段可通过扩展字段或现有 extra 保存：

```json
{
  "influencer_customer_id": 123,
  "influencer_source_type": "manual",
  "influencer_source_value": "ERP手工选择"
}
```

如果后续频繁查询，建议在 `sale_order` 增加结构化字段：

```sql
ALTER TABLE hg_sale_order
ADD COLUMN influencer_customer_id int(11) unsigned DEFAULT NULL COMMENT '归因红人客户ID',
ADD COLUMN influencer_source_type tinyint(2) unsigned DEFAULT NULL COMMENT '红人归因来源',
ADD COLUMN influencer_source_value varchar(255) DEFAULT NULL COMMENT '红人归因值';
```

### 3. 与 cost

`cost` 继续作为实际费用记录。

红人佣金付款后写入：

- `type = COST_TYPE_INFLUENCER_COMMISSION`
- `pm = PM_OUT`
- `customer_id = 红人 customer.id`

已有常量：

```php
BillSet::COST_TYPE_INFLUENCER_COMMISSION
BillSet::COST_TYPE_INFLUENCER_COOPERATION
BillSet::COST_TYPE_INFLUENCER_OTHER
```

### 4. 与 bill_sheet

现有 `bill_sheet` 更偏客户/供应商账单生成，可长期复用账单展示能力。

但红人分佣需要独立状态、订单佣金、退款调整和付款闭环，建议先新增专用结算单表，不直接复用 `bill_sheet` 作为主结算模型。

后续如果要统一财务入口，可在财务页面把红人结算单和普通账单并列展示。

## 十、接口建议

### 1. 红人分佣规则

```text
GET  /admin/influencer-commission-rule/index?customer_id={红人ID}
GET  /admin/influencer-commission-rule/detail?id={id}
POST /admin/influencer-commission-rule/add
POST /admin/influencer-commission-rule/edit
POST /admin/influencer-commission-rule/delete
```

### 2. 订单佣金

```text
GET  /admin/influencer-commission-order/index
POST /admin/influencer-commission-order/recalculate
POST /admin/influencer-commission-order/adjust
POST /admin/influencer-commission-order/void
```

### 3. 分佣结算单

```text
GET  /admin/influencer-commission-settlement/index
GET  /admin/influencer-commission-settlement/detail?id={id}
POST /admin/influencer-commission-settlement/generate
POST /admin/influencer-commission-settlement/submit
POST /admin/influencer-commission-settlement/audit
POST /admin/influencer-commission-settlement/pay
POST /admin/influencer-commission-settlement/void
```

### 4. 红人详情聚合数据

红人详情页可增加：

```text
GET /admin/customer/influencer-commission-summary?id={customer_id}
```

返回：

- 累计销售金额。
- 累计应结佣金。
- 已结算佣金。
- 已付款佣金。
- 待结算佣金。
- 最近结算周期。
- 当前生效分佣规则。

## 十一、页面建议

### 红人详情页

增加分佣区块：

- 当前分佣规则。
- 待结算佣金。
- 已结算佣金。
- 已付款佣金。
- 订单佣金列表。
- 结算单列表。

### 红人分佣订单页

字段建议：

- 红人名称。
- 销售订单号。
- 订单金额。
- 实收金额。
- 计佣基数。
- 分佣比例。
- 应结佣金。
- 调整金额。
- 状态。
- 归因来源。

### 红人结算单页

字段建议：

- 结算单号。
- 红人。
- 周期。
- 订单数量。
- 佣金合计。
- 调整合计。
- 应付金额。
- 已付金额。
- 状态。
- 付款流水号。

## 十二、权限控制

1. 红人负责人可查看自己负责红人的分佣数据。
2. 财务可查看和处理所有红人结算单。
3. 普通员工只能查看自己创建或归因权限范围内的红人订单，不可查看付款流水。
4. 红人客户不允许导出客户列表的规则继续保留。
5. 分佣结算导出只允许财务或管理员操作。

## 十三、实施顺序

### 第一阶段：手工归因 + 手工/比例分佣

1. 新增分佣规则表。
2. 新增订单佣金表。
3. 支持 ERP 手工选择红人归因。
4. 支持固定金额、订单实收比例、手工佣金。
5. 支持订单佣金列表和人工调整。

### 第二阶段：结算单和付款

1. 新增结算单和结算明细表。
2. 支持按红人和周期生成结算单。
3. 支持审核确认。
4. 支持付款后生成 `cost`。
5. 红人详情页展示分佣汇总。

### 第三阶段：自动归因和复杂规则

1. 对接 Shopify 折扣码。
2. 对接推广链接和 UTM 参数。
3. 支持毛利比例、商品范围、阶梯分佣。
4. 支持退款后负数调整。
5. 支持多红人拆佣。

## 十四、最终口径

红人佣金不是简单一个金额字段。

完整分佣信息应包含：

- 分佣规则。
- 订单归因。
- 佣金计算结果。
- 人工调整。
- 结算单。
- 付款记录。

现有 `cost` 只作为最终付款和营销成本归集，不负责分佣规则和结算状态。新增分佣结算层后，既能满足红人管理查看合作效果，也能满足财务对账和订单利润统计。