广告ROI测算

给电商投手和店长的广告账计算器：ROI 是多少、保本线在哪、加预算该加给谁，全部用透明口径算给你看。

为什么需要它

平台后台只告诉你 ROI = 4，但不告诉你退货 20% 之后还剩多少、佣金扣完还赚不赚。本技能把"表面 ROI"还原成"到手净利"，并算出你的保本 ROI 线——低于这条线，ROI 再好看也是亏的。

四个子命令

calc —— 单计划 ROI 全套核算

# 主用例：花费 1 万，GMV 4 万，毛利率 40%，退货率 20%，佣金 5%
python3 scripts/ad_roi_calculator.py calc --spend 10000 --gmv 40000 \
    --margin 40% --refund 20% --commission 5%

输出：ROI、有效 GMV、毛利、平台费用、净利、每元广告净利、净利率、保本 ROI（= 1 / ((1-退货率)x(毛利率-佣金率))）、安全边际；可选 --target-roi 做达标对照。

金额容忍 1万 / 10,000 / ￥10000；比率容忍 40% / 0.4 / 40。净利为负时退出码为 1（结果仍打印），方便脚本化告警。

metrics —— 漏斗指标换算

python3 scripts/ad_roi_calculator.py metrics --impressions 100000 --clicks 2000 \
    --orders 60 --spend 6000 --aov 150

输出 CTR / CPM / CPC / CVR / CPA / GMV / UV 价值 / ROI，缺哪项输入就跳过哪项指标。

split —— 多渠道对比与预算再分配

# CSV（表头 name,spend,gmv）或逐条 --channel "名称,花费,GMV"
python3 scripts/ad_roi_calculator.py split --csv channels.csv \
    --margin 40% --refund 20% --commission 5% --budget 10000

输出各渠道 ROI / 净利 / 每元净利与判定（盈利/持平/亏损）；给 --budget 时按每元广告净利加权输出再分配参考（亏损渠道分配为 0）。这是计算参考，不是投放指令。

list —— 指标公式速查

python3 scripts/ad_roi_calculator.py list

14 项指标公式与口径提示（含 GMV 口径、退货率口径、归因窗口差异提醒）。

口径约定（详见 references/metrics-guide.md）

| 指标 | 公式 | |---|---| | ROI (= ROAS) | 成交金额 / 广告花费 | | 有效 GMV | GMV x (1 - 退货率) | | 毛利 | 有效 GMV x 毛利率 | | 平台费用 | 有效 GMV x 佣金率 | | 净利 | 毛利 - 平台费用 - 广告花费 - 其他固定成本 | | 保本 ROI | 1 / ((1 - 退货率) x (毛利率 - 佣金率)) | | 安全边际 | (实际 ROI - 保本 ROI) / 保本 ROI |

毛利率 <= 佣金率时保本点不存在（卖一单亏一单），脚本会显式提示而不是给一个假数字。

边界

只做核算与参考：不做投放操作建议、不预测流量、不构成投资建议。
毛利率 / 退货率 / 佣金率以商家后台实际数据为准；跨平台对比前先拉齐归因窗口与 GMV 口径。
纯标准库、不联网、不读取任何本地文件（除非你显式传 --csv）。