商品推广运营台

定位

商家有货，缺的是把货卖出去的动作。本技能把「推广」拆成五步可执行闭环，每一步都有确定的产出物与判断标准，并直接落到目标商城的数据库上。

设计要点：推三返一不是拍脑袋定个比例，而是一道成本题。
行业里最常见的错误是拿三档比例的算术平均（[10,20,70] → 33.3%）当成本率——
真实成本取决于推荐完成度分布（多数人推不满 3 单），后者通常比算术平均低十几个百分点。
本技能一律用 scripts/fission_design.py 的完成度加权口径测算，并同时给出保守口径兜底。
方法论详见 references/fission-design.md。

边界

本技能不改动商城源码，只做运营动作与数据读写。

接入配置

• 目标商城应用 ID：wbapp_uSbaPA5pmHm7BI6xMGVnc4（换目标商城时改这里）
• 数据读写通道：优先使用云服务数据库 MCP 工具（workbuddy_cloudservice_db_*），
  不要求商家提供任何密钥，也不得把密钥写入本技能的任何文件。

五步闭环

第 1 步 · 选品、定价与裂变方案测算（极致版推三返一）

输入：商品清单（CSV/Excel/JSON 或人工口述）+ 成本与售价。

动作：
1. 用 scripts/normalize_products.py 把任意格式的商品源规范化
2. 按 references/playbook.md 的选品标准筛掉不适合做分销的品
3. 用 scripts/fission_design.py 出方案（不是手算）：

python scripts/fission_design.py --cost 40 --price 99 --merchant \
  --platform-rate 15 --commission-rate 10 --goal balanced --completion medium

它会一次给出六件东西：成本三口径（预期/保守）、推荐档位曲线、定价体检、
三方分账表（商家净利 / 推广者收益 / 平台抽成）、裂变预测、行动清单。
加 --json 拿结构化结果；退出码非 0 表示存在红线问题。

可选参数：
- --goal growth|balanced|profit 经营目标（决定目标净利率）
- --completion low|medium|high 推荐完成度预期（新客盘/常规老客/门店熟客）
- --curve front|classic|back|balanced|light 强制指定档位曲线
- --merchant 商家品（计提平台抽成）；不加则为平台自营品

产出：可导入的商品 JSON + 定价与佣金建议表 + 三方分账方案。

判断标准：返利 + 佣金 + 平台抽成之和不得超过毛利率；且保守口径（所有参与者都推满 3 单）
下也不能亏。超过就提价、换品或降佣金。

第 2 步 · 物料生产

输入：第 1 步定稿的商品与其卖点。

动作：
1. 按 references/copy-templates.md 的模板批量生成多平台物料，同类目可一次生成多品。
2. 生成后必须过一遍合规预检：

python scripts/compliance_check.py --text-file copy.md \
  --commission-rate 10 --ratios 10,20,70 --margin 60

命中红线词或参数越线时退出码非 0，必须改完再交付。

产出：每个商品一套物料——朋友圈文案、社群话术、私聊破冰、短视频口播脚本、海报主副标题。

判断标准：文案必须包含一个具体的使用场景和一个可证实的利益点，禁止堆砌形容词；
且不得出现收益承诺、层级激励、诱导分享、绝对化用语四类违规表达。

第 3 步 · 投放分销

输入：定稿商品 JSON + 佣金/返利方案。

动作：
1. 用 scripts/normalize_products.py 把商品整理成 JSON，再调 import_products 写入商品库。
三个必须知道的点：仅管理员可调；每条 item 必须显式带 source（缺省会被
服务端落成 store，导致来源与去重键全错）；按「名称 + 来源」去重，重复导入是幂等的，
返回里的 skipped 就是被跳过的条数。
2. 用管理权限更新 settings 表：rebate_rule（三档返利比例）、rebate_commission_mode
（exclusive 佣金与返利二选一 / both 两者都给）、default_commission_rate。
改之前先实读当前值，不要把文档里的快照当现值用。
3. 生成招募话术，指导商家发动已有的推广员/商家账号去分享

产出：上架完成的商品 + 生效的返利规则 + 招募话术。

判断标准：先在 orders 里造一笔真实测试单走完整链路，确认返利与佣金都正确落账，
再放量。

第 4 步 · 效果追踪

输入：时间区间。

动作：先从库里把订单与返利导成 JSON，再交给 scripts/promo_report.py 算报表。
字段名必须与脚本对齐，用下面这条已实测的语句导出（把 '2026-01-01' 换成区间起点）：

SELECT jsonb_build_object(
  'orders', COALESCE((SELECT jsonb_agg(jsonb_build_object(
              'owner_id', owner_id, 'product_name', product_name,
              'price', price, 'commission', commission,
              'platform_fee', platform_fee, 'status', status) ORDER BY id)
            FROM public.orders
           WHERE created_at >= '2026-01-01'), '[]'::jsonb),
  'rebates', COALESCE((SELECT jsonb_agg(jsonb_build_object(
              'owner_id', owner_id, 'from_order_id', from_order_id,
              'type', type, 'amount', amount, 'rate', rate) ORDER BY id)
            FROM public.rebate_records
           WHERE created_at >= '2026-01-01'), '[]'::jsonb),
  'settings', jsonb_build_object(
              'rebate_rule', (SELECT value::jsonb FROM public.settings WHERE key = 'rebate_rule'))
) AS payload;

把 payload 的值存成 .json 文件，然后：

python scripts/promo_report.py data.json --margin <毛利率>

产出：Markdown 报表，含已支付口径的成交明细、转化率、客单价、返利成本占比、ROI，以及针对性的下一步建议。

判断标准：返利成本占比 = 该期返利总额 / 该期成交总额。若连续两期高于毛利率，
说明档位设置过于激进，应调整 ratios。

第 5 步 · 三方收益分配与推广者工作台

输入：时间区间 + 推广者昵称映射（可选）。

动作：
1. 用下面这条语句一次导出三张表的所需字段（orders.id 不能漏——看板靠它做
「同单双发让利」的完整性检查）。把 '2026-01-01' 换成区间起点：

SELECT jsonb_build_object(
  'orders', COALESCE((SELECT jsonb_agg(jsonb_build_object(
              'id', id, 'owner_id', owner_id, 'promoter_id', promoter_id,
              'product_name', product_name, 'price', price,
              'commission', commission, 'platform_fee', platform_fee,
              'status', status) ORDER BY id)
            FROM public.orders WHERE created_at >= '2026-01-01'), '[]'::jsonb),
  'rebates', COALESCE((SELECT jsonb_agg(jsonb_build_object(
              'owner_id', owner_id, 'from_order_id', from_order_id,
              'type', type, 'amount', amount, 'rate', rate) ORDER BY id)
            FROM public.rebate_records WHERE created_at >= '2026-01-01'), '[]'::jsonb),
  'withdrawals', COALESCE((SELECT jsonb_agg(jsonb_build_object(
              'owner_id', owner_id, 'amount', amount, 'status', status) ORDER BY id)
            FROM public.withdrawals WHERE created_at >= '2026-01-01'), '[]'::jsonb),
  'names', COALESCE((SELECT jsonb_object_agg(owner_id, nickname)
            FROM public.profiles_public WHERE nickname <> ''), '{}'::jsonb)
) AS payload;

2. 交给看板脚本：

python scripts/revenue_board.py board.json --margin 55

产出：三方分账看板（商家净利 / 推广者返利与佣金 / 平台抽成三条线 + 占比）、
推广者收益榜（累计收益 / 已提现或审核中 / 可提现）、健康度告警与下一步建议。

判断标准：三条线同时为正才算机制健康；看板报红（商家净利为负、返利成本占比超毛利、
检出同单双发让利）时按 references/fission-design.md 第八节的顺序调优。
对「有余额未提现」的推广者主动提示去「我的钱包」提现——到账体验直接影响下一轮推荐意愿。

必须掌握的业务规则

这些规则直接决定返利算得对不对，写死在本技能里，避免每次重新推断：

• 佣金归推荐人，不归买家。 订单佣金按买家的 referrer_id 找人，且只有当该推荐人的
  role 属于 promoter / merchant / admin 时才计提。普通用户推荐不会产生佣金。
• 佣金率取值优先级：商品 commission_rate → 推荐人 commission_rate →
  settings.default_commission_rate。前一个为空才用后一个。
• 费率填 0 等于没填：取值链用的是 NULLIF(rate, 0)，0 会被当成空值继续往下回退
  到 default_commission_rate。想「这个品不返佣」不能靠把费率设成 0，只能让推荐人不具备
  推广身份（role = 'user'），或把 default_commission_rate 一起降下来。
• 佣金在下单时按商品当时价格算好并固化到 orders.commission，之后改价不影响已生成的订单。
• 佣金在结算时还会用推荐人的「当前」角色再复核一次。若下单后把推荐人降成普通用户，
  这笔佣金就不会发放。做人员调整时要注意未支付订单。
• 平台抽成只在商品有 merchant_id 时计提，按 settings.platform_commission_rate 算。
  平台自营品（merchant_id 为空）不抽。
• 三档返利是循环的，不是递进封顶。 设 ratios = [10,20,70]，推荐人的第 N 个合格下线
  对应档位 ((N-1) mod 3) + 1，即第 1 单 10%、第 2 单 20%、第 3 单 70%、
  第 4 单回到 10%，以此类推。
• 返利基数取推荐人自己的首单价格，不是下线订单金额。
• 返利只在下线首次成交时触发；同一下线后续订单不再产生返利。
• rebate_commission_mode = 'exclusive'（默认）下，若该单已发佣金则不再发返利；
  both 则两张都发。这会显著影响成本，改档位前先算清楚。

详细字段定义见 references/schema.md，运营方法论见 references/playbook.md，
推三返一极致化设计与合规边界见 references/fission-design.md。

合规红线（2026 年版，越线即封号）

监管环境已变化：《禁止传销条例》2026 年首次大修征求意见稿新增「网络传销」专门定义，
资金链路成为执法抓手；微信 2026 年 5 月官方答复明确包括二级分销在内的多级代理均属违规。
因此本技能只做一级直推，且返利只由真实成交触发。

交付任何物料前跑一次 compliance_check.py。四类必须清掉的表达：
收益承诺（躺赚/稳赚不赔/日入过千）、多层级激励（团队计酬/无限代/见点奖）、
诱导分享（分享得红包/助力砍价/集赞/分享解锁）、绝对化用语（最好/第一/国家级）。

资源索引

常见错误

• 把 stock = -1 当成负库存——它是不限量的哨兵值。
• 直接读 profiles 基表——普通用户与匿名角色无权读取，公开信息走 profiles_public 视图。
• 试图用客户端角色写 products——受行级安全策略限制，铺货必须走 import_products。
• 给「普通用户」身份的人算佣金——佣金只算给具备推广/商家身份的人，这是设计而非缺陷。
• 拿三档比例的算术平均当成本率——[10,20,70] 的真实预期成本通常是 20% 上下，
  不是 33.3%；用错会白白少赚十几个百分点。始终用 fission_design.py 的完成度加权口径。
• 只算预期口径就定生死价——预期口径是运营看利润用的；定价必须用保守口径
  （所有人推满 3 单）体检，否则一次集中爆发式推荐就能把利润吃光。
• 把「分享得红包」写进文案——这是微信明令的诱导分享，会限制分享与支付能力。
  激励只能挂在真实成交上。
• 让活动期首单价过低——返利基数取推荐人首单价，首单打到 9.9 元会让返利金额小到无感，
  裂变直接熄火；用礼包价抬高基数才是正解。