UTM 渠道归因分析器（Edu UTM Attribution）
功能概述
面向没有数据团队的教培小机构（5-30 人），把"校长月末凭感觉分预算"变成"说一句话拿到渠道 ROI 矩阵与砍/优化/加码建议"。
核心能力一句话：多平台线索表导入 → 手机号哈希去重 → 首触/末触双归因（五级置信度）→ 渠道投入台账 → ROI 矩阵 → 月度复盘 HTML 报告。全流程本地处理，明文手机号不落盘，数据不出工作区。
解决的核心痛点：微信会剥离 utm_* 参数导致归因失效——本 skill 不假装解决，而是用「规范 UTM 链接 + 渠道专属二维码参数（qr=渠道ID）+ 首问补采话术」三层补偿策略，并诚实标注每条归因的置信度与全量归因覆盖率。
使用前提
- 运行环境：Python 3.8+（WorkBuddy 内置运行时即可）；二维码 PNG 自动生成需
pip install qrcode[pil]（可选，未安装时输出参数贴纸）； - 连接器/API Key：均无需，零外部依赖；
- 前置数据：各投放平台后台导出的线索表（CSV/XLSX，需含手机号列；姓名/时间/来源/备注列自动识别）；
- 数据范围：单次导入建议 ≤5000 条。
快速开始
- 说："初始化归因台账" → 建立运行时目录与空台账；
- 说："建一个抖音渠道，预算 2 万，责任人小王" → 渠道建档；
- 拖入线索 Excel，说："导入本月抖音线索" → 自动清洗、去重、归因；
- 说："4 月抖音广告花了 2 万，投手人力 3000" → 投入台账登记；
- 说："出 4 月渠道复盘报告" → 生成 HTML 报告（ROI 矩阵+建议+预警）；
- （可选）说："跑个归因演示" → 30 秒内置样例走通全流程。
使用手册
核心功能与操作示例
功能 1：渠道建档与链接生成
- 触发方式：说"建一个 XX 渠道"/"给 XX 生成链接/二维码"
- 渠道类目六选一：线上投放 / 微信私域 / 线下地推 / 转介绍 / 异业合作 / 自然到访
- 操作示例：
> 用户：建一个抖音信息流渠道，预算 2 万，责任人小王
> 技能：✅ 渠道已建档：ch_online_ads_01「抖音信息流」（线上投放），月预算 ¥20,000 - 链接生成：活动名自动转规范 slug（中文/空格自动转连字符）；同渠道+同活动重复生成自动复用
- 渠道二维码：在任意落地页 URL 后追加
?qr=<渠道ID>即可被归因引擎识别（微信内发二维码而非长链接，规避参数剥离）
功能 2：线索导入与自动归因
- 触发方式：拖入 CSV/XLSX + 说"导入本月 XX 线索"
- 自动能力：中英文列名映射（姓名/手机号/时间/来源/备注）、手机号格式归一化（+86/空格/横线）、非法号码剔除、同号 90 天窗口合并、重复导入幂等跳过
- 归因规则（五级置信度，写入每条线索）：
| 归因方法 | 触发条件 | 置信度 |
|---|---|---|
| utm_auto | 来源列含平台名（匹配渠道名）或 utm_source | high |
| qrcode | 来源列含 qr=<渠道ID>（扫码进入） |
high |
| manual | 顾问首问补采/人工申诉 | high |
| fuzzy_match | 无源老线索后续触点补上来源 | medium（报表建议复核） |
| unattributed | 无任何依据 → 挂起，不参与 ROI 分母 | low |
- 操作示例：
> 用户：导入本月线索（附：leads.csv）
> 技能：✅ 新增 10 / 合并 2 / 重复跳过 0 / 无效 1；当前无源挂起 3 条，可说"列出无源线索"逐条首问补采
功能 3：跟进流转与成交登记
- 触发方式：说"李同学约了周六试听" / "李同学 4/28 签约 8800" / "张同学退费了" / "这条是同学妈妈转介绍的"
- 状态机：new → attributed → followed → trial → signed（成交）/ lost（流失）/ refunded（退费）/ invalid（作废），非法迁移自动拦截
- 末触锁定：成交后新增触点不再改写末触渠道；退费自动从 ROI 分子剔除并重算
- 操作示例：
> 用户：尾号 8899 的李同学 4 月 28 日签约 8800 元
> 技能：✅ 成交登记完成：¥8,800（2026-04-28）。末触渠道已锁定（成交后新增触点不再改写末触）。
> 用户：张同学说他是同学妈妈转介绍的
> 技能：✅ 归因已更新：首问补采 → 老带新转介绍渠道（manual，置信度 high）。
功能 4：投入台账与 ROI 复盘
- 触发方式：说"4 月抖音广告花了 2 万" / "出 4 月渠道复盘报告"
- 投入四类：ad 广告费 / labor 人力折算 / material 物料 / reward 转介绍奖励（老带新单列核算的关键）
- 月度报告内容：KPI 总览 → 数据质量预警 → 首触/末触双视角 ROI 矩阵（CPL/CAC/ROI/建议）→ 双视角分歧解读 → 口径说明
- 建议规则（行业 1.2 万家机构验证，可配置）：ROI < 1:3 🔴 建议砍 / 1:3~1:5 🟡 优化 / > 1:5 🟢 加码；归因覆盖率 < 60% 时提示暂缓砍渠道决策
- 操作示例：
> 用户：4 月抖音广告花了 2 万，投手人力折算 3000
> 技能：✅ 投入已登记：2026-04 抖音信息流 广告费 ¥20,000 + 人力折算 ¥3,000。
> 用户：出 4 月渠道复盘报告
> 技能：📊 报告已生成：线索 9（覆盖率 89%）→ 成交 4 单，投入 ¥37,500，产出 ¥37,800。转介绍 ROI 1:8.2 🟢 建议加码；抖音 ROI 1:0.4 🔴 建议砍。
功能 5：演示与配置
- 说"跑个归因演示"：内置 6 渠道+10 线索样例，30 秒走通建渠道→导入→归因→成交→报告全流程（独立临时目录，不污染正式台账）
- 说"把砍渠道阈值改成 2.5"：调整 config；说"查看配置"：显示当前规则
- 操作示例：
> 用户：跑个归因演示
> 技能：🎬 演示完成：6 渠道 → 10 线索 → 4 成交 → 月报已生成（含 ROI 矩阵与建议）。正式使用请说"初始化归因台账"。
数据说明
运行时台账文件（安装后自动创建于工作区 utm-attribution/ 目录）：
| 文件 | 内容 | 关键字段 |
|---|---|---|
| channels.json | 渠道档案 | channel_id（如 ch_online_ads_01）/名称/类目（六类）/责任人/月预算/状态 |
| links.json | 追踪链接档案 | 目标页/utm_source~content/短码/full_url/qr_param |
| leads.csv | 线索台账（脱敏） | phone_hash（SHA256）/phone_tail/name_masked（张**）/首触末触渠道/归因方法/置信度/生命周期状态/成交金额 |
| touchpoints.csv | 触点记录 | lead_id/channel_id/触点时间/触点类型/来源指纹（幂等去重） |
| spend_ledger.csv | 投入台账 | 月份×渠道×类型（ad广告/labor人力/material物料/reward转介绍奖励）/金额 |
| config.json | 归因规则 | 去重窗口 90 天/ROI 阈值（砍 1:3、加码 1:5）/预警阈值（可对话修改） |
| reports/ | 月度 HTML 报告+快照 | 报告含 KPI 总览/预警/双视角 ROI 矩阵/口径说明；快照锁定当月口径 |
数据流转：导入线索表 → 清洗去重（手机号哈希）→ 触点表 → 首触/末触归因写入线索 → 状态流转（跟进/试听/成交）→ 投入登记 → 月度聚合出报告。字段级口径详见 references/schema.md。
常见问题
- 微信内发的链接归因丢了？ 微信内置浏览器会剥离 utm_* 参数（行业事实）。对策：线下/私域场景一律用渠道二维码（
?qr=渠道ID写入落地页）；确实丢了的线索走首问补采，不猜渠道。 - 同一个人在两个渠道都留了资？ 90 天窗口内自动合并为一条线索、两个触点：首触算最早渠道，末触算最新渠道，两边功劳都记。
- 手机号安全吗？ 台账只存 SHA256 哈希+脱敏姓名（张女士→张**），明文不落盘；imports/ 存原始导入表仅供追溯，建议 30 天清理。
- 上月报告出了又来新数据？ 月报生成时锁定当月快照；后到线索计入次月，重算需显式确认（口径可复现）。
技术指令（开发者参考）
1. 目录结构
utm-attribution/
├── SKILL.md ← 本文件
├── scripts/
│ ├── utm_core.py ← 核心引擎：数据模型/导入清洗/归因/ROI计算/HTML渲染
│ └── cli.py ← CLI 入口：init/channel/link/leads/lead/spend/report/config/demo
├── references/
│ └── schema.md ← 数据模型与字段口径
└── tests/
└── run_tests.py ← UAT 自测（32 项断言，对应 PRD 验收标准）
运行时数据目录（用户工作区内自动创建）：
utm-attribution/
├── channels.json / links.json ← 渠道/链接档案
├── leads.csv / touchpoints.csv ← 线索台账（脱敏）/触点记录
├── spend_ledger.csv / audit.csv ← 投入台账/操作日志
├── config.json ← 归因规则配置
├── imports/ qrcodes/ ← 原始导入表（定期清理）/二维码
└── reports/ (+snapshots/) ← 月度 HTML 报告/数据快照
2. 核心工作流（对话 → CLI 映射）
| 用户意图 | CLI 命令 |
|---|---|
| 初始化 | python scripts/cli.py init（默认运行时 ./utm-attribution） |
| 建渠道 | cli.py channel add 抖音信息流 --category online_ads --owner 小王 --budget 20000 |
| 生成链接 | cli.py link create ch_online_ads_01 --url https://xueye.cn/spring --campaign spring26 |
| 渠道二维码 | cli.py qrcode ch_offline_ditui_01 --url https://xueye.cn/spring |
| 导入线索 | cli.py leads import ./leads.csv --channel ch_online_ads_01（--channel 整表显式归属，可选） |
| 查线索档案 | cli.py lead show 8899（线索 ID 或手机尾号） |
| 补归因/申诉 | cli.py lead attribute 8899 ch_referral_01 --note "同学妈妈转介绍" |
| 状态流转 | cli.py lead status 8899 trial / cli.py lead sign 8899 --amount 8800 / cli.py lead refund 8899 |
| 登记投入 | cli.py spend add 2026-04 ch_online_ads_01 ad 20000 --note 巨量引擎 |
| 月度报告 | cli.py report --month 2026-04 |
| 查状态/配置/日志 | cli.py status / cli.py config show / cli.py audit |
| 演示 | cli.py demo |
3. 交互约束（务必遵守）
- 不猜渠道：来源无法识别的线索一律 unattributed 挂起并生成首问补采任务，绝不按类目关键词乱归因；
- 手机号脱敏：所有输出（对话/台账/报告）不得出现明文手机号，只用尾号 4 位或哈希索引；
- 状态机严格校验：非法迁移（如 signed→followed）直接拒绝并向用户解释允许的迁移；
- 幂等：同文件重复导入 0 新增；月报快照锁定后重算需用户显式确认；
- 口径透明：ROI 报告必须同时展示首触/末触双视角+归因覆盖率+medium 置信度条数，建议措辞用"建议"而非"指令"。
4. 验收自检（安装后验证）
python tests/run_tests.py
# 预期：32 项断言全部通过（渠道/链接/导入/去重/归因/状态机/报表/日志）
# 再执行 cli.py demo 预期：6 渠道 → 10 线索 → 4 成交 → 报告含 ROI 矩阵与建议
