1|# 子系统 04 — 多渠道触达引擎 (`outreach`) v1.0 2| 3|## 子系统概述 4| 5|| 维度 | 说明 | 6|| --- | --- | 7|| 代号 | `outreach` | 8|| 核心职责 | 渠道路由决策、渠道去重、IM/EDM/APP Push/TEL 渠道调度执行、触达历史管理 | 9|| 数据所有权 | `channel_route_decisions`, `channel_dedup_records`, `im_interaction_records`, `im_flow_tags`, `edm_message_events`, `edm_user_behavior_profiles`, `app_touch_events`, `tel_call_records` | 10|| 启动依赖 | identity / planning / quota（均为软依赖） | 11|| 外部系统依赖 | JOYHUB（IM 通道）、ESP（EDM）、FCM/APNs（APP Push）、电话系统（TEL） | 12| 13|--- 14| 15|## 1. 模块划分 16| 17|``` 18|┌─────────────────────────────────────────────────────────────┐ 19|│ outreach 子系统 │ 20|│ │ 21|│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ 22|│ │ M1: 渠道路由 │ │ M2: 渠道去重 │ │ M3: IM 执行 │ │ 23|│ │ + 优先级 │→│ │→│ 引擎 │ │ 24|│ └──────────────┘ └──────────────┘ └──────┬───────┘ │ 25|│ │ │ 26|│ ┌──────────────┐ ┌──────────────┐ ┌──────┴───────┐ │ 27|│ │ M4: EDM 执行 │ │ M5: APP Push │ │ M6: TEL 执行 │ │ 28|│ │ 引擎 │ │ 引擎 │ │ 引擎 │ │ 29|│ └──────────────┘ └──────────────┘ └──────────────┘ │ 30|│ │ 31|│ ┌──────────────┐ ┌──────────────┐ │ 32|│ │ M7: 触达历史 │ │ M8: 对外 API │ │ 33|│ │ 服务 │ │ Gateway │ │ 34|│ └──────────────┘ └──────────────┘ │ 35|│ │ 36|└─────────────────────────────────────────────────────────────┘ 37|``` 38| 39|| # | 模块 | 职责 | 40|| --- | --- | --- | 41|| M1 | 渠道路由+优先级 | 按用户状态路由到最优渠道（APP活跃→IM优先 / 未注册→EDM优先 / 高价值无响应→TEL / C类→IM免评卡片） | 42|| M2 | 渠道去重 | 同一计划同一用户不重复走多渠道路由；工单中暂停自动触达；已提交待核验暂停催评 | 43|| M3 | IM 执行引擎 | IM 推送、用户分层（A未参与/B参与过/C长期测评人）、回评/测评/免评卡片推送、催评、提交核验、返款通知 | 44|| M4 | EDM 执行引擎 | EDM 发送、送达/打开/点击追踪、行为画像、节奏控制、退订/硬退信处理 | 45|| M5 | APP Push 引擎 | APP 推送、触发源管理（绑定玩具/不活跃/计划到期/Listing紧急/活动）、响应追踪 | 46|| M6 | TEL 执行引擎 | 电话任务生成、拨打前准备（用户画像+风险检查+历史沟通）、通话记录、重试策略 | 47|| M7 | 触达历史服务 | 统一触达历史查询（跨渠道聚合）、供 quota（频控）、identity（上下文卡）调用 | 48|| M8 | 对外 API Gateway | 统一对外 API | 49| 50|--- 51| 52|## 2. 各模块内外说明 53| 54|### 2.1 M1: 渠道路由+优先级 55| 56|| 维度 | 说明 | 57|| --- | --- | 58|| **对内** | 接收 planning 的已批准计划，按用户状态矩阵决定渠道：APP活跃+已绑定→IM首选；APP低活跃→EDM补充+APP Push召回；未注册→EDM首选→引导注册后转IM；高价值+多次无响应→TEL；C类（累计≥12）→IM免评卡片+KOC/KOL协同 | 59|| **对外接口** | `POST /api/outreach/route` — 输入计划+用户，返回路由决策 | 60|| **数据写入** | `channel_route_decisions` | 61|| **依赖** | `GET /api/identity/context/{person_id}` — 用户状态 | 62| 63|### 2.2 M2: 渠道去重 64| 65|| 维度 | 说明 | 66|| --- | --- | 67|| **对内** | 执行去重规则（同一计划同一用户首选渠道、工单中暂停、已提交评价暂停、退订某渠道永久排除、强关联风险全暂停、弱关联降频+提示） | 68|| **对外接口** | `GET /api/outreach/dedup-check?person_id=&plan_id=` | 69|| **数据写入** | `channel_dedup_records` | 70|| **依赖** | `GET /api/tickets?person_id=&status=open`（support）；`GET /api/risk/check/{person_id}`（risk） | 71| 72|### 2.3 M3: IM 执行引擎 73| 74|| 维度 | 说明 | 75|| --- | --- | 76|| **对内** | 用户分层逻辑（A未参与/B参与过但<12/C≥12长期测评人）；分层推送策略（A推回评卡片/B先催评再二次转化/C仅免评）；提交后的核验与流转（订单号核实→登记→补全信息→返款→二次转化）；标签管理（9 种核心标签如「xx产品已回评用户」「xx产品测评待返款用户」等） | 77|| **对外接口** | `POST /api/outreach/im/send` — 发送 IM 消息 | 78|| **数据写入** | `im_interaction_records`, `im_flow_tags` | 79|| **依赖** | JOYHUB（IM 通道）；`GET /api/quota/check/{person_id}` | 80|| **待确认** | IM 是 WhatsApp 还是自研 IM？通道对接方式？ | 81| 82|### 2.4 M4: EDM 执行引擎 83| 84|| 维度 | 说明 | 85|| --- | --- | 86|| **对内** | 推送前检查（身份→风险→退订→资格→国家）；行为筛选（打开/点击/回复/频率）；节奏判断（适合触达/需降频/不适合）；发送后追踪（送达→打开→点击→回复→退订）；转化路径（下载注册APP→转IM / 直接回复邮件→生成客服工单 / 未响应→再触达队列） | 87|| **对外接口** | `POST /api/outreach/edm/send` — 发送 EDM | 88|| **数据写入** | `edm_message_events`, `edm_user_behavior_profiles` | 89|| **依赖** | ESP 邮件服务 | 90|| **待确认** | EDM 模板在哪里管理？模板变量（用户名/产品名/链接）如何填充？ | 91| 92|### 2.5 M5: APP Push 引擎 93| 94|| 维度 | 说明 | 95|| --- | --- | 96|| **对内** | 5 种触发源（绑定新玩具/不活跃/计划到期/Listing紧急/活动）；推送前过滤（身份+风险+频控+标签）；响应追踪（点击打开→落地页 / 忽略→短期不重复推 / 卸载→转EDM候选池）；APP 内动作分流（提交回评/测评→IM核验 / 联系客服→工单 / 浏览→更新活跃标签） | 97|| **对外接口** | `POST /api/outreach/app/push` — 发送 APP Push | 98|| **数据写入** | `app_touch_events` | 99|| **依赖** | FCM/APNs | 100|| **待确认** | 是否复用 JOYHUB 现有 Push 通道？ | 101| 102|### 2.6 M6: TEL 执行引擎 103| 104|| 维度 | 说明 | 105|| --- | --- | 106|| **对内** | 7 种触发场景（答应配合超时/高价值跟进/复杂售后/多次无响应/紧急Listing/Amazon来电/外呼任务）；拨打前准备 5 步（查用户完整画像→查风险→查历史沟通→准备话术→生成电话工单）；通话结果 5 种（售后问题解决→引导回评 / 直接配合→登记答应配合 / 拒绝→记录 / 疑似诈骗→转风险 / 未接通→重试）；重试策略（<3次重拨 / ≥3次降级EDM或关闭） | 107|| **对外接口** | `POST /api/outreach/tel/task` — 创建 TEL 任务 | 108|| **数据写入** | `tel_call_records` | 109|| **依赖** | 电话系统（外呼/来电） | 110| 111|### 2.7 M7: 触达历史服务 112| 113|| 维度 | 说明 | 114|| --- | --- | 115|| **对内** | 跨渠道聚合触达历史（IM/EDM/APP/TEL）；提供统一查询接口供 quota（频控）和 identity（上下文卡）消费 | 116|| **对外接口** | `GET /api/outreach/history/{person_id}` | 117|| **数据写入** | 只读聚合 | 118| 119|--- 120| 121|## 3. 对外 API 契约（草案） 122| 123|| 接口 | 方法 | 输入 | 输出 | 消费者 | 124|| --- | --- | --- | --- | --- | 125|| 触达历史 | `GET /api/outreach/history/{person_id}` | person_id | `{im[], edm[], app[], tel[]}` | quota（频控）, identity（上下文卡） | 126|| 执行触达 | `POST /api/outreach/send` | `{plan_id, person_ids[], channel, content}` | `{task_id, status}` | planning | 127|| 渠道路由决策 | `POST /api/outreach/route` | `{person_id, plan_id}` | `{recommended_channel, alternatives[]}` | planning | 128|| IM 消息发送 | `POST /api/outreach/im/send` | `{person_id, msg_type, content}` | `{message_id}` | 内部 | 129| 130|--- 131| 132|## 4. 数据对象 133| 134|| 对象 | 核心字段 | 说明 | 135|| --- | --- | --- | 136|| `channel_route_decisions` | decision_id, person_id, plan_id, selected_channel, reason, decided_at | 渠道路由决策 | 137|| `channel_dedup_records` | dedup_id, person_id, plan_id, channel, status(BLOCKED/ALLOWED), block_reason | 渠道去重记录 | 138|| `im_interaction_records` | interaction_id, person_id, msg_type(PUSH_CARD/REVIEW_CARD/EXEMPTION_CARD/REMINDER/REFUND_NOTICE), direction(OUTBOUND/INBOUND), content, status, created_at | IM 交互记录 | 139|| `im_flow_tags` | tag_id, person_id, tag_type, tag_value, tagged_at | IM 流程标签（如 xx产品待返款等） | 140|| `edm_message_events` | event_id, person_id, email, event_type(SENT/DELIVERED/OPENED/CLICKED/REPLIED/UNSUBSCRIBED/HARD_BOUNCED), occurred_at | EDM 事件 | 141|| `edm_user_behavior_profiles` | profile_id, person_id, email, last_opened_at, total_opens, consecutive_no_open, last_replied_at, monthly_received, status | EDM 用户行为画像 | 142|| `app_touch_events` | event_id, person_id, trigger_type, push_status, response, occurred_at | APP Push 事件 | 143|| `tel_call_records` | call_id, person_id, ticket_id, direction(OUTBOUND/INBOUND), call_status, duration, outcome, retry_count, recorded_at | TEL 通话记录 | 144| 145|--- 146| 147|## 5. 业务澄清问题清单 — outreach 148| 149|### 5.1 渠道优先级路由（4 项） 150| 151|| # | 问题 | 优先级 | 152|| --- | --- | --- | 153|| O-01 | 路由规则是否可配置？（例如针对某个站点用户调整 IM > EDM 的优先级）配置界面在 outreach 内还是在独立配置管理？ | **P0** | 154|| O-02 | 「APP 低活跃」的判定标准是什么？（N 天未打开？N 天未点击推送？）阈值是否可配置？ | P1 | 155|| O-03 | 高优先级渠道发送失败（退信/未送达）后，是否自动降级到下一渠道？降级是否有冷却时间？ | P1 | 156|| O-04 | C 类用户（累计≥12）只推免评——如果免评计划也没有，是完全不推还是推品牌/活动内容？ | P2 | 157| 158|### 5.2 IM 通道（4 项） 159| 160|| # | 问题 | 优先级 | 161|| --- | --- | --- | 162|| O-05 | IM 使用的具体平台是什么？（WhatsApp Business API / 自研 JOYHUB IM / Messenger？）不同平台的 API 能力和限制？ | **P0** | 163|| O-06 | IM 的「分层」是系统自动判断还是人工可干预？（一个 B 类用户会不会被错误标记为 C 类？如何修正？） | **P0** | 164|| O-07 | IM 推送中「测评卡片」的具体形式是什么？（带按钮的消息模板？需要用户填表单？）模板在哪里管理？ | P1 | 165|| O-08 | IM 中的「订单号核实」——核实的数据源是什么？（比对内部订单表？Amazon 订单 API？）核实失败的转人工流程？ | P1 | 166| 167|### 5.3 EDM 通道（4 项） 168| 169|| # | 问题 | 优先级 | 170|| --- | --- | --- | 171|| O-09 | 当前使用的邮件服务是什么？（SendGrid/Mailchimp/SES/自建？）有没有现成 API 和 Webhook 追踪？ | **P0** | 172|| O-10 | EDM 模板（邮件内容、样式、多语言）在哪里管理？属于 outreach 还是独立内容管理子系统？ | P1 | 173|| O-11 | 「EDM 行为画像」中的「最近 3/5 次 0 打开」——3 次和 5 次是两个独立指标还是二选一？各自对应什么策略？ | P1 | 174|| O-12 | EDM 发送量和频控——单日最大发送量有限制吗？（ESP 的每日限额？） | P1 | 175| 176|### 5.4 APP Push（3 项） 177| 178|| # | 问题 | 优先级 | 179|| --- | --- | --- | 180|| O-13 | APP Push 是否复用 JOYHUB 的现有推送通道？还是需要独立接入 FCM（Android）和 APNs（iOS）？ | **P0** | 181|| O-14 | APP Push 和 IM 消息的分工——文档第 11.2 节给了对照表，但边界是否绝对？（例如"计划到期提醒"是否可能同时走 APP Push 和 IM？） | P1 | 182|| O-15 | APP 落地页——推送点击后跳转到哪个页面？（APP 内的测评页？IM 对话页？）落地页由哪个团队/子系统负责？ | P2 | 183| 184|### 5.5 TEL 通道（3 项） 185| 186|| # | 问题 | 优先级 | 187|| --- | --- | --- | 188|| O-16 | 电话系统使用什么方案？（自建 SIP PBX / Twilio / 其他云呼叫中心？）是否已有通话记录？ | **P0** | 189|| O-17 | 「拨打前准备」第 2 步「查风险：强关联命中→暂停拨打→先复核」——复核由谁来做？（风险人员？客服组长？）复核时长预期？ | P1 | 190|| O-18 | 电话中「尽量确认」的字段（购买平台、订单号、产品型号、购买时间、问题类型、凭证）如果用户不愿意/无法提供——哪些是必须确认的？哪些可以跳过？ | P1 | 191| ### 5.6 消息内容与合规（4 项） | # | 问题 | 优先级 | | --- | --- | --- | | O-19 | 消息内容是否需要审核？（IM 推送文案、EDM 邮件内容、APP Push——上线前是否需要审核？审核流程？） | P1 | | O-20 | EDM 合规要求——是否遵守 CAN-SPAM Act（美国）、GDPR（欧洲）、CASL（加拿大）？退订机制是否满足法律要求？ | P1 | | O-21 | IM 平台的合规限制——WhatsApp 等平台禁止垃圾消息和特定类型内容（如测评引导）——是否有合规风险？ | P1 | | O-22 | 消息发送的时区感知——美国用户、英国用户、德国用户的推送时间是否需要本地化？（用户当地时间的白天而非半夜） | P1 | ### 5.7 消息策略与实验（3 项） | # | 问题 | 优先级 | | --- | --- | --- | | O-23 | 是否需要 A/B 测试能力？（同一计划的两组用户收到不同文案/不同发送时间——对比转化率？） | P2 | | O-24 | 消息打开率/点击率/转化率的追踪和报表？是否需要自动优化发送策略（高打开率的文案模板优先使用）？ | P2 | | O-25 | 用户反馈「消息太频繁/内容不相关」——是否有投诉/退订统计和预警？（投诉率超过 X% 暂停该类型推送？） | P1 | ### 5.8 IM 通道补充（3 项） | # | 问题 | 优先级 | | --- | --- | --- | | O-26 | IM 消息的「已读」状态是否能获取？（WhatsApp 的蓝色双勾——能否用于判断用户是否看到消息？） | P1 | | O-27 | IM 用户提交的「评论截图/链接」——如何自动验证截图的真实性？（防止用户 PS 假截图？是否需要 OCR 识别截图内容？） | P1 | | O-28 | IM 中的返款通知——返款是系统自动触发还是人工触发？返款状态如何回写到 outreach？ | P1 | ### 5.9 EDM 通道补充（3 项） | # | 问题 | 优先级 | | --- | --- | --- | | O-29 | EDM 的「硬退信」和「投诉」是否自动同步到 identity 的风险标记？（硬退信用户是否需要进入风险观察？） | P1 | | O-30 | EDM 引导用户下载 APP——是否在邮件中嵌入归因链接（deferred deep link）以追踪转化来源？ | P2 | | O-31 | EDM 的发送域名和 IP 预热策略？（新域名/IP 直接大批量发送会被 ESP 判定为垃圾邮件——需要渐进式预热？） | P2 | ### 5.10 TEL 通道补充（3 项） | # | 问题 | 优先级 | | --- | --- | --- | | O-32 | 电话录音是否需要存储？存储多久？谁有权调取录音？（涉及合规和隐私） | P1 | | O-33 | 不同国家的电话合规要求——美国需提前告知录音、德国的 GDPR 限制——如何处理？ | P1 | | O-34 | TEL 任务的优先级和分配——多个外呼任务同时存在时，客服按什么顺序拨打？（先打高价值用户？先打答应配合超时的？） | P1 | ### 5.11 实施层面（4 项） | # | 问题 | 优先级 | | --- | --- | --- | | O-35 | 各外部通道的 rate limit 和计费模式？（WhatsApp 按消息数计费？EDM 按发送量计费？）是否需要成本控制？ | P1 | | O-36 | 消息发送是同步还是异步？（用户点「发送」后立即返回还是后台队列处理？失败重试策略？） | P1 | | O-37 | 多渠道消息的发送顺序保证？（「先发 IM 提醒→24h 后无回复再发 EDM」——这种时序依赖如何实现？定时任务？延迟队列？） | P2 | | O-38 | 异常场景——如果某渠道 100% 发送失败（ESP 宕机/WhatsApp API 限流）——是否自动切换备用渠道？ | P2 |