atlas-seller-kit/docs/requirements/pricing-tool.md

定价工具需求

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

1. 定位

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

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

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

2. Ozon 类目佣金结论

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

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

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

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

2.1 已获得的佣金数据

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

{
  "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。在其中的源表疑点、计费重粒度和实际账单复算完成前，首期不得把这些费率作为正式生产报价启用。

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 的空运、陆空、陆运价表和计费规则（计费重、体积重除数、阶梯、附加费、限制、生效日期）；拿到后再将其整理为可录入的规则模板。