241 lines
18 KiB
Markdown
241 lines
18 KiB
Markdown
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 |
|