转介绍裂变系统（referral-fission）
功能概述
为小机构（教培/健身/美容/宠物/兴趣班等，5-30 人团队）打造的「老带新·双面激励」转介绍裂变系统，解决"获客贵、转介绍全靠口头、奖励发不清楚"的痛点。覆盖完整闭环：建活动 → 发推荐码 → 登记归因 → 付费锁定奖励 → 满 7 天发放 → 退费自动冲减 → 看板复盘导出。奖励双面计算（推荐人 + 被推荐人立减），阶梯升级，预算封顶，风控防刷，全部操作留痕可审计。
使用前提
- 运行环境：Python 3.8+（仅使用标准库，零第三方依赖，无需 pip install）
- 连接器：无需任何连接器、无需 API Key
- 前置数据：无。
init命令初始化机构档案后即可使用；demo命令可一键加载演示数据先看效果 - 数据存储：本地 JSON 文件（默认技能包
data/fission_data.json），数据不出本机
快速开始
# 1. 初始化机构（或先跑 demo 看效果）
python scripts/fission.py init --org-name "XX教育"
# 2. 创建活动（三模板选一：standard 学费抵扣 / cash_rush 现金返现 / course_hours 课时赠送）
python scripts/fission.py campaign-create --name "秋季老带新" --template standard \
--start 2026-09-01 --end 2026-09-30 --budget 5000
# 3. 录入老学员并批量生成推荐码
python scripts/fission.py member-add --student 王强 --parent 王先生 --phone 13800000001
python scripts/fission.py member-code --campaign CP-0001 --batch-all
# 4. 新学员凭码登记 → 跟进 → 付费（奖励自动锁定）
python scripts/fission.py referral-register --campaign CP-0001 --code XY-9Q2M \
--referee 张晓明 --phone 13800000002
python scripts/fission.py referral-advance --id RF-0001 --stage paid --amount 5000
# 5. 看！复盘
python scripts/fission.py dashboard --campaign CP-0001
完整命令手册：python scripts/fission.py help。多校区/多机构用 --data-dir 或环境变量 FISSION_DATA_DIR 隔离数据；--actor 姓名 用于审计留痕。
使用手册
> 以下所有功能均可通过自然语言对话触发，也可直接运行对应命令。
功能 1：创建转介绍活动
- 触发方式：用户说"帮我搞个老带新活动""建一个转介绍活动""我们机构要做推荐有礼"
- 操作示例：
> 用户：帮我校区搞一个秋季老带新活动，预算 5000，推荐成功送学费抵扣
> 技能：campaign-create --name 秋季老带新 --template standard --start 2026-09-01 --end 2026-09-30 --budget 5000，创建活动 CP-0001，内置阶梯：推荐 1-2 人各得 200 元学费抵扣、累计 3-4 人升级 600 元、5 人及以上 1000 元现金；新学员报名立减 100 元 - 注意事项：模板参数在创建时快照进活动（后续改模板不影响已建活动）；
--budget 0表示不限预算；--draft可先建草稿。
功能 2：录入学员并发放推荐码
- 触发方式：用户说"给老学员发推荐码""录入学员""生成推荐海报"
- 操作示例：
> 用户：把这 5 个老学员录进去，都给他们生成推荐码
> 技能：逐个member-add后执行member-code --campaign CP-0001 --batch-all，输出 5 个推荐码（如 XY-8F3K）；加--poster out.html生成可转发海报，--copy moments,group生成朋友圈/群聊文案 - 注意事项：只有符合活动资格（如"在读满 1 个月"）的学员才会批量发码；单个停用用
code-disable --code XY-8F3K。
功能 3：登记推荐线索并自动归因
- 触发方式：用户说"有新家长拿着推荐码来报名了""登记一个转介绍线索"
- 操作示例：
> 用户：新学员张晓明，手机 13800000002，拿的是王强的码 XY-9Q2M
> 技能：referral-register --campaign CP-0001 --code XY-9Q2M --referee 张晓明 --phone 13800000002，归因到推荐人王强（MB-0001），生成推荐单 RF-0001；若码无效/手机号重复/自荐会自动拦截并说明原因 - 注意事项：无码线索可人工归因（
referral-manual --confirm，必须确认）；24h 内同一推荐人 ≥3 单会被标记风控，建议人工核实。
功能 4：跟进推进与退费作废
- 触发方式：用户说"这个推荐的学员约试听了""那个推荐单流失了""家长退费了"
- 操作示例：
> 用户：RF-0001 已经报名缴费 5000 了
> 技能：referral-advance --id RF-0001 --stage paid --amount 5000，双面奖励自动锁定（reward_locked，进入 7 天退费观察期）
> 用户：RF-0003 那个退费了
> 技能：referral-advance --id RF-0003 --stage void --reason "退费"，对应奖励自动作废、预算自动释放 - 注意事项：状态按 registered→contacted→trial→enrolled→paid 单向推进（允许跨级），作废需填 reason。
功能 5：奖励发放（人工确认闸门）
- 触发方式：用户说"奖励到期了该发了""帮我把可发放的奖励处理一下"
- 操作示例：
> 用户：RF-0001 付费满 7 天了，奖励可以发了
> 技能：reward-ready --id RF-0001转为「可发放」→reward-congrats --id RF-0001生成可转发给家长的恭喜文案 → 现金奖励reward-settle --id RW-0001 --confirm人工确认发放；学费抵扣reward-redeem --id RW-0002即时核销 - 注意事项：现金/礼品必须
--confirm人工确认后才能标记发放；reward-ready --force仅供演示跳过 7 天等待。
功能 6：看板复盘与导出
- 触发方式：用户说"这周转介绍效果怎么样""看看漏斗""导出数据给财务"
- 操作示例：
> 用户：秋季活动的转介绍数据怎么样？
> 技能：dashboard --campaign CP-0001输出概览（推荐数/付费数/CAC/ROI/预算使用率），funnel输出转化漏斗，leaderboard --top 5输出推荐达人榜，todos列出 3 天未跟进的推荐单
> 用户：把台账导出来给财务
> 技能：export-csv --campaign CP-0001 --dir ./out，生成 campaign/referral/reward 三类 CSV（UTF-8 BOM，Excel 直接打开不乱码） - 注意事项：CAC 口径为活动已承诺奖励总额 / 有效付费推荐数；预算使用率 ≥80% 会自动告警。
数据说明
所有数据存于单个 JSON 文件（默认 data/fission_data.json），核心实体与流转：
| 实体 | ID 前缀 | 状态机 |
|---|---|---|
| 活动 Campaign | CP-xxxx | draft → active → paused → ended |
| 学员 Member | MB-xxxx | active / inactive（推荐码 XY-8F3K 可停用） |
| 推荐单 Referral | RF-xxxx | registered → contacted → trial → enrolled → paid →（满7天）reward_locked → reward_ready / void |
| 奖励台账 Reward | RW-xxxx | locked → ready → paid（现金/礼品）/ redeemed（抵扣/积分核销）/ void |
流转逻辑：推荐单到 paid 时奖励引擎按阶梯锁定双面奖励（校验预算与单人上限）；锁定后满 settle_after_days（默认 7 天）无退费转 ready；期间推荐单作_void_则奖励联动作废并释放预算。所有写操作记录审计日志（audit 命令查看）。
常见问题
Q: 安装后怎么验证能用？
运行 python scripts/fission.py help 能输出命令手册即正常；python -m unittest discover -s tests 应 24 个测试全部通过。
Q: 需要联网或配置密钥吗？
不需要。纯本地运行，零第三方依赖，数据存本机 JSON。
Q: 想先看看效果，不污染正式数据？
python scripts/fission.py demo（演示数据写入默认 data/），或设置 FISSION_DATA_DIR 指向临时目录再跑 demo。
Q: 多个校区怎么隔离数据？
每个校区用独立数据目录：--data-dir D:\校区A数据 或环境变量 FISSION_DATA_DIR。
Q: 提示"预算不足，奖励被拦截"怎么办？
活动累计已承诺奖励 + 新奖励超过预算上限。可 campaign-update 提高预算（活动开始前）或新建预算更充足的活动。
Q: Excel 打开 CSV 乱码？
本技能导出的 CSV 已带 UTF-8 BOM，Excel 可直接双击打开；若仍异常请确认文件未被二次转存编码。
Q: 奖励规则想自定义怎么办？
编辑 config/campaign_templates.yaml 新增模板（tier_min/tier_max/type/value/unit/description），保存后对新建活动立即生效，不影响已建活动。
技能指令（开发者参考）
执行约定
- 所有命令通过
python scripts/fission.py <子命令>执行，全局参数--data-dir（数据目录）与--actor（操作人留痕）；完整命令手册见python scripts/fission.py help - 用户自然语言诉求 → 优先映射到命令执行，不确定参数时先询问（预算、奖励类型、活动周期为必问项）
- 生成海报/文案后，把文件路径告知用户供转发使用
安全红线（必须遵守）
- 合规：奖励规则必须与「新学员报名付费」绑定，禁止配置或建议"转发/分享即得奖"类规则（违反《微信外部链接内容管理规范》2.1.2）；仅两层推荐关系，不做多级分销
- 人工确认：
reward-settle（现金/礼品发放）与referral-manual（人工归因）必须向用户复述关键信息并获得明确确认后才加--confirm执行 - 数据安全：数据仅写入本地 JSON（原子写盘），不外传任何学员/家长个人信息；CSV 导出路径由用户指定
- 风控响应：登记时若返回风控标记（快速登记/跨活动重复），须提示用户人工核实后再继续，不得静默跳过
架构速览
scripts/fission.py CLI 入口（30+ 命令） scripts/demo.py 端到端演示
src/models.py 数据模型+三套状态机 src/store.py JSON 持久化+审计
src/campaign.py 活动管理 src/member.py 学员+推荐码+海报文案
src/referral.py 登记归因+状态推进 src/reward.py 奖励规则引擎+台账
src/risk.py 风控引擎 src/analytics.py 看板/漏斗/达人榜/待办
src/mini_yaml.py 零依赖 YAML 子集解析 config/*.yaml 模板/默认参数/风控规则
templates/ 分享海报+文案话术库 tests/test_core.py 24 个单元测试
