> 输入：上游渠道报价矩阵 + 收益率（加成率）→ 输出：用户价 + 分组倍率 + 渠道配置矩阵（分组 / Priority / Weight）。
>
> 报价矩阵告诉平台「成本是多少」，收益率告诉平台「想赚多少」。两者结合定用户价，其余（CE 倍率、HP 倍率、分组归属、Priority、Weight）全部推导。

## 核心公式链

```
用户价[m]   = round(median(成本[m]) × (1 + 收益率), 取整粒度)   # 收益率是平台的利润目标输入
CE 倍率     = max(第N便宜成本[m] / 用户价[m]) + 缓冲, 封顶 0.95  # N=3 保冗余
HP 倍率     = 1 + 溢价                                         # 默认 10%

利润[渠道][模型][分组] = 用户价[模型] × 分组倍率[分组] − 渠道成本[渠道][模型]
利润 > 0 → 该 渠道×模型 可加入该分组

同 group + model 下：
  Priority: 按利润降序、三等分 → 3/2/1（值越大越优先）
  Weight:  同 Priority 层内，weight = round(100 × 利润 ÷ 层内最大利润)
```

> **专业定价策略**：成本加成法（cost-plus）。25% 加成和 10% HP 溢价是 API 转售行业标准，CE 倍率完全由报价矩阵约束推导。只需一个输入（报价矩阵），即可产出完整定价与路由配置。

---

## 一、输入

本方案有两个输入：**报价矩阵**（事实输入）和**收益率**（战略输入）。

### 输入 1：渠道报价矩阵（CSV）

一行一个上游渠道，一列一个模型。空白 = 该渠道不支持该模型。

```csv
渠道, M1, M2, M3, M4, M5, M6
甲, 8.0, 15.0, 12.0, 14.0, 13.0, 16.0
乙, 9.0, 10.0,, 11.0, 12.0,
丙, 11.0, 12.0, 13.0, 12.0,, 15.0
丁,, 9.0, 15.0, 13.0, 16.0, 12.0
戊, 10.0, 11.0, 14.0,, 9.0, 14.0
己, 12.0, 13.0, 10.0, 16.0, 11.0,
```

### 输入 2：收益率（加成率）

平台的目标利润率，决定用户价高度。`用户价 = 中位成本 × (1 + 收益率)`。

- 收益率 = 0.20：保守，用户价低，竞争力强，利润薄
- 收益率 = 0.25：API 转售行业标准（本文默认）
- 收益率 = 0.35：激进，用户价高，利润厚但可能流失价格敏感用户

> 收益率无法从上游成本推导——它是平台的商业决策。本文示例取 **0.25**。

### 结构性默认（一般无需修改）

| 参数 | 默认值 | 说明 |
|------|--------|------|
| HP 溢价 `hp_premium` | 0.10 | HP 倍率 = 1 + 溢价，高性能档结构性溢价 |
| CE 冗余 `min_redundancy` | 3 | CE 组每模型至少 N 个盈利渠道 |
| CE 缓冲 `ce_buffer` | 0.03 | CE 下限之上加 3% 安全余量 |
| 取整粒度 | 0.5 | 用户价取整到最近的 0.5 |

### 如何确定分组倍率

**CE 倍率由报价矩阵推导**：保证折扣后每模型至少 N 个渠道仍盈利。

```
ce_ratio ≥ max(第N便宜成本[m] ÷ 用户价[m])  for all models m
```

本例 N=3，各模型计算：

| 模型 | 用户价 | 成本排序 | 第 3 便宜 | 下限 |
|------|--------|---------|----------|------|
| M1 | 12.5 | 8, 9, 10, 11, 12 | 10.0 | 10.0/12.5 = **0.80** |
| M2 | 14.5 | 9, 10, 11, 12, 13, 15 | 11.0 | 11.0/14.5 = **0.76** |
| M3 | 16.5 | 10, 12, 13, 14, 15 | 13.0 | 13.0/16.5 = **0.79** |
| M4 | 16.5 | 11, 12, 13, 14, 16 | 13.0 | 13.0/16.5 = **0.79** |
| M5 | 15.0 | 9, 11, 12, 13, 16 | 12.0 | 12.0/15.0 = **0.80** |
| M6 | 18.0 | 12, 14, 15, 16 | 15.0 | 15.0/18.0 = **0.83** |

> CE 下限 = max(各模型下限) = **0.83**，+3% 缓冲 → **CE = 0.86**

**HP 倍率为溢价默认**：`HP = 1 + 10% = 1.1`。10% 是高性能档的行业惯例溢价——太小分组无意义，太大用户流失。

---

## 二、计算（收益率=0.25 / HP 溢价=0.10 / N=3）

### Step 1: 用户价（成本加成）

`用户价 = 中位成本 × (1 + 收益率)`，取整到 0.5。

| 模型 | 中位成本 | 计算值 | **用户价** |
|------|---------|--------|-----------|
| M1 | 10.0 | 12.50 | **12.5** |
| M2 | 11.5 | 14.38 | **14.5** |
| M3 | 13.0 | 16.25 | **16.5** |
| M4 | 13.0 | 16.25 | **16.5** |
| M5 | 12.0 | 15.00 | **15.0** |
| M6 | 14.5 | 18.13 | **18.0** |

### Step 2: 分组卖价

`分组卖价 = 用户价 × 分组倍率`（CE=0.86, HP=1.1）

| 模型 | 用户价 | **CE (×0.86)** | **HP (×1.1)** |
|------|--------|----------------|---------------|
| M1 | 12.5 | **10.75** | **13.75** |
| M2 | 14.5 | **12.47** | **15.95** |
| M3 | 16.5 | **14.19** | **18.15** |
| M4 | 16.5 | **14.19** | **18.15** |
| M5 | 15.0 | **12.90** | **16.50** |
| M6 | 18.0 | **15.48** | **19.80** |

### Step 3: 利润判断 → 分组归属

`利润 = 分组卖价 − 渠道成本`。利润 > 0 → 入组。

**M1 示例**（CE=10.75, HP=13.75）：

| 渠道 | 成本 | CE 利润 | HP 利润 | 归属 |
|------|------|---------|---------|------|
| 甲 | 8.0 | **+2.75** ✓ | **+5.75** ✓ | CE, HP |
| 乙 | 9.0 | **+1.75** ✓ | **+4.75** ✓ | CE, HP |
| 戊 | 10.0 | **+0.75** ✓ | **+3.75** ✓ | CE, HP |
| 丙 | 11.0 | −0.25 ✗ | **+2.75** ✓ | HP |
| 己 | 12.0 | −1.25 ✗ | **+1.75** ✓ | HP |
| 丁 | — | — | — | 不支持 |

全部模型汇总：

| 渠道 | CE 归属模型 | HP 归属模型 |
|------|------------|------------|
| 甲 | M1 M3 M4 | M1 M2 M3 M4 M5 M6 |
| 乙 | M1 M2 M4 M5 | M1 M2 M4 M5 |
| 丙 | M2 M3 M4 M6 | M1 M2 M3 M4 M6 |
| 丁 | M2 M4 M6 | M2 M3 M4 M5 M6 |
| 戊 | M1 M2 M3 M5 M6 | M1 M2 M3 M5 M6 |
| 己 | M3 M5 | M1 M2 M3 M4 M5 |

> 甲对 M2 在 CE 组亏损（12.47−15.0=−2.53）→ 只进 HP。同理各模型中亏损的渠道×模型组合均被自动剔除。

### Step 4: Priority 与 Weight

> 系统路由机制：同 `group × model` 下，渠道按 **Priority 降序**排列。优先层故障后才降级到下一层。**同 Priority 层内**按 Weight 加权随机分流。

**规则**：
- **Priority**：按利润降序排列，三等分 → 3（高利润）/ 2（中利润）/ 1（低利润兜底）
- **Weight**：`max(1, round(100 × 利润 ÷ 该层最大利润))`

**M1 结果**：

| 组 | Pri | 渠道 | 利润 | Weight |
|----|-----|------|------|--------|
| CE | 3 | 甲 | 2.75 | 100 |
| CE | 2 | 乙 | 1.75 | 100 |
| CE | 1 | 戊 | 0.75 | 100 |
| HP | 3 | 甲 | 5.75 | 100 |
| HP | 2 | 乙 | 4.75 | 100 |
| HP | 1 | 戊 | 3.75 | 100 |
| HP | 1 | 丙 | 2.75 | 73 |
| HP | 1 | 己 | 1.75 | 47 |

全部模型同样处理 → 进入输出。

---

## 三、输出：渠道配置矩阵

每个渠道按分组拆成独立条目（复用同一上游 key），绑定多个模型。条目的 Priority 和 Weight 取该条目所有 profitable 模型的**平均值**。

| 条目 | 上游Key | 分组 | 模型 | Pri | Wt |
|------|--------|------|------|-----|----|
| **甲-CE** | 甲 | cost-effective | M1,M3,M4 | 2 | 72 |
| **甲-HP** | 甲 | high-performance | M1,M2,M3,M4,M5,M6 | 2 | 78 |
| **乙-CE** | 乙 | cost-effective | M1,M2,M4,M5 | 2 | 100 |
| **乙-HP** | 乙 | high-performance | M1,M2,M4,M5 | 2 | 96 |
| **丙-CE** | 丙 | cost-effective | M2,M3,M4,M6 | 1 | 83 |
| **丙-HP** | 丙 | high-performance | M1,M2,M3,M4,M6 | 1 | 91 |
| **丁-CE** | 丁 | cost-effective | M2,M4,M6 | 2 | 100 |
| **丁-HP** | 丁 | high-performance | M2,M3,M4,M5,M6 | 2 | 74 |
| **戊-CE** | 戊 | cost-effective | M1,M2,M3,M5,M6 | 2 | 83 |
| **戊-HP** | 戊 | high-performance | M1,M2,M3,M5,M6 | 2 | 96 |
| **己-CE** | 己 | cost-effective | M3,M5 | 2 | 100 |
| **己-HP** | 己 | high-performance | M1,M2,M3,M4,M5 | 2 | 78 |

> 若同一条目内模型利润差异较大，可拆分为多个条目获得更精确的 Priority/Weight 控制。

---

## 四、系统路由机制

上一节输出的 Priority 和 Weight，直接对应系统的渠道路由参数。本节解释它们如何在请求链路中起作用。

### 整体路由流程

```
用户请求
  │
  ├─ Key.group = "cost-effective"  →  只在 CE 组内选渠道（Priority 降序 + 分层降级）
  ├─ Key.group = "high-performance" →  只在 HP 组内选渠道（同上）
  └─ Key.group = "auto"            →  按 AutoGroups 顺序依次尝试各组
                                        当前：CE 组 →（穷尽）→ HP 组
```

### auto 模式的详细路由

Key 为 auto 时，路由分两层：
1. **组间顺序**：先遍历 AutoGroups 中的第一个组（CE）；该组全部渠道尝试失败后，再切换到下一组（HP）
2. **组内路由**：在同一组内，严格按照 Priority + Weight 两层规则选择渠道

这意味着 auto Key 的**实付价格不是固定值**：路由到 CE 渠道时，按 CE 的 GroupRatio（0.86）计费；路由到 HP 渠道时，按 HP 的 GroupRatio（1.1）计费。系统按利润导向将最合适的渠道优先路由给 auto 用户。

### Priority（优先级）：第一层路由——利润分层

同一 `group × model` 下，所有渠道按 **Priority 降序**排列：

```
Priority = 3  ←─  请求先尝试这一层（retry=0）
Priority = 2  ←─  上层全部失败后才到这一层（retry=1）
Priority = 1  ←─  继续降级（retry=2），兜底
```

- 高利润渠道挂 Priority=3，优先被选中，最大化平台收益
- 请求重试（retry 递增）逐级降级：Priority=3 全部失败 → Priority=2 → Priority=1
- Priority=1 是**兜底层**，保证即使高利润渠道全挂，仍有渠道可用

### Weight（权重）：第二层路由——同层利润分流

同一 Priority 层级内有多个渠道时，按 **Weight 加权随机**分流：

```
Priority=3 层:  甲(wt=100) ──────────── 吃 100/(100+83)=55% 流量
                乙(wt=83)  ──────────── 吃 83/(100+83)=45% 流量

Priority=1 层:  戊(wt=100) ──────────── 吃 100/(100+73+47)=45% 流量
                丙(wt=73)  ──────────── 吃 73/220=33% 流量
                己(wt=47)  ──────────── 吃 47/220=21% 流量
```

- Weight=0 表示等权（该层所有渠道等效 100）
- 利润越高的渠道 Weight 越大 → 同层内也倾向高利润渠道
- 同层多渠道实现了负载分散 + 冗余

### Priority 分层的可靠性

单用 Weight 的缺陷：如果最高利润渠道故障，所有流量涌向次高渠道（即便它的 Weight 很低），可能把次高渠道也压垮。**Priority 分层**解决了这个问题：高利润层整体故障后，才整体降级到下一层，而不是逐个渠道雪崩。

### 参数映射速查

| 本文概念 | 系统参数 | 存储位置 |
|---------|---------|------|
| 用户价 | ModelRatio | `options` 表 |
| 分组倍率 | GroupRatio | `options` 表 |
| 渠道分组归属 | Channel.group + Channel.models | `channels` 表 |
| 利润分层 | Channel.priority | `channels` 表 |
| 同层分流 | Channel.weight | `channels` 表 |
| auto 路由顺序 | AutoGroups | `options` 表 |

---

## 五、说明

### 分组设计

| 分组 | 倍率 | 含义 |
|------|------|------|
| **cost-effective** | 0.8~0.95（本例 0.86） | 折扣组，倍率由矩阵推导，需便宜上游才能在折扣下仍盈利 |
| **high-performance** | 1.05~1.2（本例 1.1） | 溢价组，10% 溢价，可接入更多渠道（含略贵的） |

> auto 不是独立倍率组：auto Key 的实付倍率 = 路由到的实际渠道所在组的倍率。

### 约束

- 每个模型在每组至少保留 **≥2 个渠道**（防单点故障）
- CE 倍率若被推到 ≥1.0，说明加成过高或渠道成本集中，应降低加成
- 调整加成/溢价后需重跑利润判断，确认无组内亏损渠道

---

## 六、公式速查

| 步骤 | 公式 |
|------|------|
| 用户价 | `price[m] = round( median(cost[m]) × (1+收益率), grain )` |
| CE 倍率 | `ce = min(0.95, max(Nth_cheapest[m] / price[m]) + buffer)` |
| HP 倍率 | `hp = 1 + hp_premium` |
| 分组卖价 | `sell[m][g] = price[m] × ratio[g]` |
| 入组判断 | `profit[c][m][g] = sell[m][g] − cost[c][m] > 0` |
| Priority | 按 profit 降序三等分 → 3/2/1，值越大越优先 |
| Weight | `max(1, round(100 × profit / max_in_tier))` |

---

## 七、代码工具

```bash
# 两个输入：报价矩阵 + 收益率
python3 scripts/channel_pricing_plan.py prices.csv --markup 0.25

# 不指定 --markup 时使用行业默认 0.25
python3 scripts/channel_pricing_plan.py prices.csv

# 输出 Markdown 报告 + 结构化 JSON
python3 scripts/channel_pricing_plan.py prices.csv --markup 0.25 --out plan.md --json plan.json

# 调整收益率对比方案（保守 vs 激进）
python3 scripts/channel_pricing_plan.py prices.csv --markup 0.20 --out plan_conservative.md
python3 scripts/channel_pricing_plan.py prices.csv --markup 0.35 --out plan_aggressive.md

# 结构性默认覆盖（一般不需要）
python3 scripts/channel_pricing_plan.py prices.csv --hp-premium 0.15 --min-redundancy 4
```

输入：渠道报价矩阵 CSV（空白 = 该渠道不支持该模型）+ 收益率（`--markup`，默认 0.25）。  
输出：用户价表 + 分组倍率 + 渠道配置矩阵（每个条目的 group/models/priority/weight）。