# 定价工具需求

> 状态：讨论中。本文件定义产品交互、输入输出和规则边界；不在本阶段确定数据库、接口或具体费用数值。

## 1. 定位

“定价工具”是同一个定价引擎的两个入口，不应建设两套公式：

1. **即时试算**：不依赖已有商品，用户输入类目、成本和包裹数据，比较同一跨境物流商下不同运输方式的报价、成本与利润。
2. **定价方案**：面向门店保存可复用的扣费与物流选择。商品编辑页的 SKU 引用方案后，只需补充采购成本、包裹重量和尺寸，即可计算销售价和划线价。

两种入口均调用同一版本的费用规则和计算引擎；每一次确认用于 SKU 的结果都必须保存完整输入、规则版本、汇率和费用拆分，不能只保存一个最终价格。

## 2. Ozon 类目佣金结论

现有项目中的 Ozon Seller API 文档包含类目树、类目属性、商品导入、商品查询和仓库接口；未包含“按类目获取佣金”的接口。商品导入也不返回可用于报价的类目佣金。

因此第一期在**当前平台内维护独立的佣金类目树与平台佣金规则表**：用户选择平台商品类目后，系统通过同平台映射找到对应的平台佣金类目，再按已维护且有生效日期的阶梯佣金规则取值。每条结果必须显示佣金来源和版本：

- `manual_rule`：运营维护的类目佣金规则，首期唯一可靠来源；
- `competitor_capture`：从友商页面抓取的待审核规则来源；审核通过并发布版本后，才可作为正式报价规则；
- `platform_sync`：未来若 Ozon 提供稳定接口后同步；
- `product_observed`：未来从已上架商品的实际费用回填，仅作参考，不能覆盖正式规则。

没有覆盖该类目的规则时，系统不得自动套用相邻类目或旧比例：显示“缺少佣金规则”，允许在即时试算中临时填写佣金率并清楚标记为临时值；SKU 定价确认则需要人工补齐规则或明确使用一次性覆盖值。

### 2.1 已获得的佣金数据

已获得一份从友商页面抓取的 Ozon 佣金数据。其结构是“佣金一级类目 → 佣金二级类目 → 销售价区间/佣金比例”，例如：

```jsonc
{
  "label": "服装",
  "cate_id": 15621031,
  "children": [{
    "label": "配饰",
    "cate_id": 41777465,
    "children": [
      { "label": "售价 ≤ 1500₽ (12.00%)", "value": "1,12.00" },
      { "label": "1500₽ < 售价 ≤ 5000₽ (14.00%)", "value": "2,14.00" },
      { "label": "售价 > 5000₽ (20.50%)", "value": "3,20.50" }
    ]
  }]
}
```

约定如下：

- `label` 是展示名称；`cate_id`、层级 `id` 和叶子 `value` 是抓取来源字段，保留为来源标识，不能假设它们等同于 Ozon 商品类目 API 的 ID。
- 叶子 `value` 的格式目前为 `档位序号,佣金百分比`；实际价格下界/上界以 `label` 解析或人工录入为准，导入时要转换为结构化的最小值、最大值、边界包含方式和佣金率，不能长期依赖字符串解析计算。
- 该数据源标记为 `competitor_capture`，不是 Ozon 官方实时接口。导入时必须记录抓取日期、适用市场/履约模式、审核状态和生效版本；未经业务确认的版本只能用于参考试算，不能默认为正式发布报价依据。

### 2.2 平台商品类目与平台佣金类目的映射

平台商品类目与平台佣金类目是同一平台内的两套独立体系；它们都必须归属一个平台，禁止以相同名称或 ID 自动等同，也不能跨平台复用。一个平台佣金类目可对应多个平台商品类目；一个平台商品类目也可能因履约模式、市场或规则变更而在不同时期映射到不同的平台佣金类目。

维护“商品类目 → 佣金类目”的显式映射，并为映射保存平台、履约模式、适用市场、生效区间、优先级、来源和审核状态。报价时只取当前平台、市场、履约模式和日期下唯一有效的映射；没有唯一映射就要求人工选择，不作猜测。

### 2.3 阶梯佣金与反算售价

佣金率会随最终销售价变化，而销售价又受佣金影响。因此不能先随意选一档佣金后只算一次。报价引擎必须逐档计算候选销售价，并验证候选价是否落入该档价格区间；满足区间的候选即为有效结果。例如先按“≤1500₽、12%”求价，若结果超过 1500₽，则该档无效，继续按下一档重算。

结果卡必须展示命中的佣金类目、价格档位、佣金率、规则版本和边界条件。若某一档的计算结果恰好在边界，按规则中保存的包含/排除定义处理，而不是使用前端浮点数比较。

## 3. 页面信息架构

点击左侧“定价工具”进入一个页面，顶部使用三个页签：

| 页签 | 用途 | 首期 |
|---|---|---|
| 即时试算 | 临时输入并横向比较运输方式 | 是 |
| 定价方案 | 管理门店可复用的默认扣费和物流偏好 | 是 |
| 试算记录 | 查看、复制和复算已保存的结果 | 后续，可先只保留 SKU 的计算快照 |

“物流服务商的价格表”和“类目佣金规则”属于后台可配置资料，不应让普通卖家在每次试算中编辑。第一期仅内置 `CEL`，但所有选择器、规则和结果都以“服务商 + 运输方式 + 规则版本”表达，后续可增加其他服务商而不用改商品或 SKU 结构。

## 4. 即时试算

### 4.1 输入区

页面采用左侧输入、右侧结果的布局。目标平台与当前店铺不在此重复选择：它们来自页头全局工作上下文。平台是必选上下文；不同平台拥有独立的类目、佣金规则、跨境物流商和运输方式。输入分为以下四组：

| 分组 | 字段 | 规则 |
|---|---|---|
| 目标市场 | 履约模式、当前平台商品类目 | 当前平台和当前店铺从页头读取；店铺自动带入币种和默认定价方案。平台商品类目和平台佣金类目均强绑定当前平台；履约模式首期预留 FBS/FBO，实际可用项由该平台的佣金规则决定。 |
| 商品与包裹 | 采购成本、包裹实重、长/宽/高 | 采购成本首期以 CNY 输入；重量以 g、尺寸以 cm 或 mm 输入。体积由三边自动计算，不能只存一个孤立体积值。允许显示并在必要时人工确认体积重。 |
| 定价目标 | 期望加价率、划线折扣率、广告费占比、其他占比 | 所有比例必须明确单位为 `%`。期望加价率与划线折扣率的计算口径见第 7 节。 |
| 费用与物流 | 跨境物流商、运输方式、国内运费+代贴单、尾程（Ozon 代理费）、提现费、汇率 | 默认选择 CEL 并同时勾选其可用运输方式；用户可比较全部方式。国内运费+代贴单为固定金额；尾程、提现费为比例；汇率必须显示来源、值和更新时间，允许本次覆盖。 |

“其他”可先作为单一百分比输入，展示名称为“其他（提醒、货损等）”。规则模型必须支持将来拆成多项费用，例如货损、退款准备金、保险、税费，而不改变最终报价结构。

### 4.2 结果区

每种被选择的运输方式生成一张可比较的结果卡（桌面端可横向表格、移动端可纵向卡片）。默认按建议销售价升序，并突出推荐方式；推荐只依据完整成本、目标利润和规则有效性，不代表物流时效承诺。

每张结果必须同时展示：

- 建议销售价和划线价（目标币种）；
- 毛利金额、毛利率、目标利润达成情况；
- 采购成本；
- 平台佣金（比例、金额、规则来源和版本）；
- 跨境物流费（实重、不计抛）以及实际计费重、抛重差额和最终跨境物流费；
- 国内运费 + 代贴单；
- 广告费；
- 尾程（Ozon 代理费）；
- 提现费；
- 其他（货损等）；
- 总成本、扣费总额、汇率与生效规则版本。

利润和建议价格一律按**最终跨境物流费**计算；“不计抛物流费”只是透明的对照项，不能错误地当成成本。用户点击“展开计算过程”后看到每一步公式、阈值、取整方式和输入来源；点击“保存为定价方案”可把当前可复用参数带到方案编辑器，但商品成本、尺寸和单次临时佣金覆盖不应成为默认值。

### 4.3 缺失与异常

- 缺少类目佣金、有效运价、汇率、采购成本或有效包裹数据时，不输出建议售价，指出缺失项。
- 包裹尺寸不适用于某个运输方式、超过重量/尺寸上限或无法得到计费重时，该方式单独标为不可报价，不影响其他方式。
- 临时覆盖的佣金、汇率或运价必须以醒目标记，并且保存结果时固化为快照。

## 5. 定价方案

### 5.1 作用与范围

定价方案属于全局当前店铺；一个门店可以维护多个方案，例如“CEL 常规”“CEL 大件”“测试利润率”。门店可设置一个默认方案，商品编辑页的新 SKU 自动引用它。方案修改只影响后续试算；已有 SKU 的确认价格保留原快照，不能静默重算。

方案的可配置字段：

| 字段 | 说明 |
|---|---|
| 方案名称、备注、启用状态 | 用于识别和管理。 |
| 目标店铺、币种、履约模式 | 与平台规则、汇率和发布上下文绑定。 |
| 跨境物流商 | 首期 CEL；未来可扩展。 |
| 默认运输方式 | 空运、陆空、陆运之一；只可选择该服务商当前可用的运输方式。 |
| 参与比较的运输方式 | 即时试算默认勾选项；不等于 SKU 自动采用的方式。 |
| 国内运费 + 代贴单 | 固定金额。 |
| 广告费占比 | 销售价的百分比。 |
| 尾程（Ozon 代理费） | 销售价的百分比。 |
| 提现费 | 销售价的百分比。 |
| 其他（货损等） | 销售价的百分比；后续可拆项。 |
| 期望加价率 | 见第 7 节的统一口径。 |
| 划线折扣率 | 见第 7 节的统一口径。 |
| 汇率策略 | 使用系统汇率、固定汇率，或允许每次报价覆盖。 |

类目佣金不建议固定写死在方案中：它随商品类目选择；方案只允许设“无规则时的临时覆盖是否可用”。

### 5.2 商品编辑页的 SKU 定价

SKU 的“定价”按钮打开轻量报价抽屉/弹窗，而不是跳转到完整工具页。流程：

1. 自动读取当前商品的 Ozon 类目、目标店铺、SKU 采购成本和**有效包装物流规格**。
2. 自动加载店铺默认方案；用户可临时切换至该店铺其他启用方案，也可临时改变运输方式。
3. 显示默认运输方式的结果，并可展开比较该方案中允许的其他方式。
4. 用户确认一项运输方式和结果后，回填 SKU 的销售价、划线价、采用的运输方式及不可变更的报价快照。

临时切换方案或运输方式只影响本次 SKU 报价和确认后的报价快照，不会修改门店默认方案。SKU 缺少采购成本、包装重量或包装长宽高时，不能使用父商品的实物规格替代；若存在父商品的包装默认规格，则按既有继承规则先解析为有效包装规格。缺失或口径待确认时只允许修正数据，不允许确认价格。

## 6. 物流服务商与运价规则的预留

第一期 UI 仅暴露 CEL，但规则层必须支持以下信息，以适配不同服务商和运输方式：

| 维度 | 需要预留的信息 |
|---|---|
| 服务商 | 名称、代码、状态、结算币种、适用目的地/仓、备注、生效时间。 |
| 运输方式 | 名称、代码（如 air/land_air/land）、时效说明、状态、可承运类目或限制。 |
| 计费重量 | 实重单位、体积重公式/除数、计费规则（实重、体积重、两者取大、阶梯等）、进位粒度和最小计费重。 |
| 运价阶梯 | 起止计费重、固定费、每 kg/每续重单价、最低收费、币种、生效区间。 |
| 附加费 | 偏远地区、燃油、超长超重、带电/敏感货、保险、清关等；支持固定额或比例、是否纳入利润计算。 |
| 限制 | 重量/尺寸/体积上限、禁运类目、运输方式特有的校验与错误信息。 |
| 版本与来源 | 规则来源、文件/人工录入、创建人、审核状态、生效时间；任何报价引用准确版本。 |

CEL 的 Ozon-rFBS 资费表已提取为待审核规则，见 [`cel-ozon-rfbs-rates-review.md`](./cel-ozon-rfbs-rates-review.md)。在其中的源表疑点、计费重粒度和实际账单复算完成前，首期不得把这些费率作为正式生产报价启用。

## 7. 已确认的两个公式口径

旧项目试算页的“净利率”是以采购成本为基数的加价率，且以固定 15.5%/21.5% 的平台抽成估算。新工具要拆开佣金、广告、物流和其他费用，不能继续沿用该固定比例。

| 字段 | 建议定义 | 建议公式 |
|---|---|---|
| 期望加价率 | 净利润相对采购成本的比例 | `目标净利润 = 采购成本 × 期望加价率`。建议销售价由“固定成本 + 目标净利润”除以 `1 − 平台佣金率 − 广告费率 − 尾程费率 − 提现费率 − 其他费率` 得到；采购成本按汇率转换到销售币种。 |
| 划线折扣率 | 买家相对划线价实际享受的折扣率 | `划线价 = 销售价 ÷ (1 − 划线折扣率)`；折扣必须大于等于 0 且小于 100%。 |

其中固定成本为：采购成本（按汇率换算）+ 最终跨境物流费 + 国内运费/代贴单 + 所有固定附加费。平台佣金、广告费、尾程、提现和其他百分比费用均以销售价为基数。

新项目只使用“划线折扣率”，不保留、不兼容也不迁移旧试算页的“划线价倍数/售价加价率”计算方式。所有新报价均按 `划线价 = 销售价 ÷ (1 − 划线折扣率)` 计算并保存快照。

## 8. 与旧试算页的继承关系

旧项目的计价模块可以复用其“按 SKU 用包装规格计算、保存报价快照、单个 SKU 出错不阻断其他 SKU”的经验；但不复用以下业务常量：物流等级 `low/high/high2`、固定平台佣金 12%/18%、固定“提现费及其他”约 3.5%，以及将实物尺寸当物流尺寸的旧数据。

Atlas 的定价工具以服务商运输方式、类目佣金、包裹物流规格和版本化费率为唯一依据。

## 9. 待确认事项

1. 请提供首批 CEL 的空运、陆空、陆运价表和计费规则（计费重、体积重除数、阶梯、附加费、限制、生效日期）；拿到后再将其整理为可录入的规则模板。