Add under-anything knowledge dashboard

wishfulfilled-wiki/05_需求文档/04-子系统-多渠道触达引擎.md

@@ -0,0 +1,240 @@
+     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 |