D10 通知与触达 · 设计文档

本域总览见《账号计费中心 · 结构大纲》。本文为该域完整设计：定位与边界 / 角色与依赖 / 数据模型 / 核心流程 / 接口契约 / 关键约束与验收标准。 排序理由：先数据模型（事实结构）→ 再核心流程（运行路径）→ 最后接口契约（流程的对外投影）。

1. 定位与边界

本域回答四件事：通道怎么配、模板怎么管、消息怎么发、发得怎么样。触达形态为短信、邮件、站内信三种。

本域不管什么：资金与账务属 D04；计量聚合属 D05；账户状态与准入属 D06；风控与实名属 D09；支付渠道属 D03。运营面端点的语义细节写在本文，索引统一登记在 D11；门户侧消费体验见 D12。

2. 角色与依赖

上游依赖：

下游被引用：

3. 数据模型

customers 与 users 由本域只读引用，不新增外键到本域；授权主体与权限范围由 D11 定义。

3.3 表清单

• 单次尝试超时：首选 5 秒、备用 3 秒、兜底 2 秒；整体硬预算 10 秒，超出即停止选路直接失败。
• 降级触发两类：通道返回 false（业务拒绝 / 配置不全）与抛出异常（网络 / 传输 / 超时），两者都记失败并计入熔断窗口；降级成功事件记 outcome=fallback_ok 与 fallback_from。
• 白名单属本地永久性错误：不进入选路、不产生事件、不耗通道配额。无任何启用行且兜底未配时，非开发环境如实返回未发送，绝不上报已发送；开发环境只打日志并省略正文，避免验证码明文入日志。

• 邮件模板与通道无关，渲染在选路之前完成；未知场景在渲染阶段即拒绝，不进入可重试语义。
• 邮件侧渠道路径失败一律上抛异常，故降级只由超时与异常触发；rejected 用于凭据不全与配额耗尽。
• 同一场景的短信与邮件变量名完全一致；超文本与纯文本版本由同一渲染函数产出、逐句一致。

• 熔断键为「通道类型 + 配置行标识」；兜底通道的配置行标识为空，与配置行各自独立计数。
• 冷却态为进程内内存态：多副本各自计数、各自熔断，不共享、不落库；健康概览读当前进程快照。
• 配置问题绝不熔断：场景缺绑定记 rejected 供排障，但不计入熔断窗口，避免若干条邀请消息缺绑定就把通道冷却 60 秒、连带验证码一起被跳过。
• 冷却期内不写事件（触发熔断的那次失败已落库）；逐次决策、非持久切换，到期无需人工回切。

• 判定优先级固定：未启用 → disabled；启用且用量达 daily_limit → quota_exhausted；启用且冷却中 → cooldown；启用且为默认通道 → active；其余启用行 → standby。
• 默认通道 = 启用行中 priority 最小者（并列取 created_at、id 更小者）；无启用行时无默认通道。
• 徽标是读侧派生值，不落库：由「启用位 + 优先级 + 当日聚合用量 + 进程内冷却快照」算出。
• 停用短信通道后若已无「启用且凭据完整」的通道，自动关闭手机认证开关，防止「开关开着却发不出短信」。

• 只有 ok 与 fallback_ok 计入；rejected / failed 不计；测试发送（is_test）一律不计。
• 计数按 channel_type + config_id 维度聚合，批量读一次算全部通道；事件经独立短会话即时提交，聚合读已提交真值。
• 取值域：daily_limit 1～100000（短信默认 1000、邮件默认 200）；interval_seconds 30～3600；并发下允许 1～2 笔超限竞态，不上分布式锁。

• 新建与改配按通道标识分别校验必填：短信侧校验签名与凭据（通道特定字段按通道补足），邮件侧按两类凭据组各自校验；不过即 422。
• 优先级重排提交重复值 → 422 priority_invalid；未提及的行保持现值。删除启用中的行 → 409 active_config_delete_forbidden；行不存在 → 404 sms_config_not_found / email_config_not_found。
• 一期兼容的激活 / 停用只等价于启用 / 停用，不再停用其他行；默认通道由优先级决定。短信模板按通道 × 场景绑定；模板型通道缺绑定视为配置不全并降级；通道级单值列仅播种验证码与邀请两个同构场景，换绑安全通知契约不同、须显式绑定。预览以假数据渲染，有效期取系统当前真实值，与真实发送同口径。

• 订阅开关即客户的余额阈值列：阈值 0 = 关闭该客户余额告警。
• 去重窗口 24 小时，键为「客户 + 同类型」；重复扫描不重复发，端点幂等。已读态组织共享；个人收件行非空时按收件人个人可见与个人已读。
• 事件保留 30 天，写入时节流触发惰性清理（至多每小时一次）；清理只删保窗之外的行，与告警扫描互不影响。

4.8 事件归类、脱敏与探活口径

5. 接口契约

5.1 内部短信（前缀 /internal/sms，16 条）

5.2 内部邮件（前缀 /internal/email，17 条）

5.3 内部通道与告警扫描（前缀 /internal/channels、/internal/alerts）

5.4 运营面通道（前缀 /api/account/ops/channels，32 条）

运营面与内部面共用同一套实现（单一真相不双轨）：运营面以门户令牌与渠道运营权限码鉴权，内部面以内部令牌鉴权；语义以 5.1～5.3 为准，端点索引登记见 D11。

6. 关键约束与验收标准

6.1 约束

1. 顺序可复现：选路与列表顺序均由「优先级升序 + 创建时间升序 + 标识升序」共同确定，同一批通道的尝试顺序唯一。
2. 降级必有痕迹：每次降级成功写 fallback_ok 并记录原定通道；每次跳过（冷却、配额、缺绑定）都能被事件或徽标解释。
3. 配额只算成功：失败、拒绝与测试发送都不消耗通道当日配额；配额是「已成功触达」的计数，不是调用次数。
4. 白名单是硬闸：发送路径与测试发送共用同一判定，白名单外一律不实发，且不进入选路、不产生事件、不耗配额。
5. 错误分类不掩盖真相：四类错误必须分开落库；配置类问题（缺绑定、凭据不全、配额耗尽）与通道故障（超时、网络）分开，前者不计熔断。
6. 凭据只写不读：任何读接口不得回传凭据明文，其存在范围限于单次发送或探活调用的内存快照。
7. 脱敏不可逆：事件、日志与查询响应中的地址一律为脱敏形态，且脱敏在写事件之前完成。
8. 模板契约前置：邮件的必需占位符在保存时校验，短信的必需变量在配置界面前置展示；渲染期未提供的占位符渲染为空串。同一场景的短信与邮件变量名完全一致，邮件超文本与纯文本版本逐句一致。
9. 无通道不谎报：无可用通道时如实返回未发送，非开发环境绝不返回成功。
10. 变更留痕且探活不发送：通道与模板的创建、改配、启停、调序、删除、绑定变更、测试发送均与操作日志同事务落库；只读动作不留痕，探活不产生事件、不耗配额、不写审计。

6.2 验收标准

6.3 待后续设计细化的开放项

1. 多副本熔断口径：冷却与失败计数为进程内内存态，负载不均时可能出现「同一通道在一个副本冷却、在另一个副本仍被选中」；共享态方案需单独立项，并明确读取失败时的降级语义。
2. 事件长周期观测：保留窗口为固定值，未设计按通道分级的保留策略与聚合归档，长周期降级率分析缺数据底座。
3. 个人级已读与模板版本：已读态为组织共享，个人视角的细粒度已读待演进；在线模板修改为原地覆盖，未设计版本留存与一键回滚。
4. 配额与限速的执行面：配额在发送侧执行、限速由消费方读取后自行执行，两者的联合语义与违约处置待明确。