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 |
