SMS 持久化可行性分析¶
分析日期：2026-02-14
所属阶段：Phase 1.5（数据基础增强） 前置条件：无（可独立实施） 相关文档：PhoneBook 数据库 · 产品闭环分析
现状¶
当前 SMS 消息采用临时缓存策略：
- 缓存表：
studio-Cache-{env}（DynamoDB） - 缓存 Key 格式：
MSG#{storeId}#{queryHash} - 三层缓存：内存（5分钟）→ DynamoDB（10分钟）→ RingCentral API
- 代码位置：
studio-api/apps/api/src/services/message-cache.ts
存在的问题：
| 问题 | 影响 |
|---|---|
| 缓存 10 分钟过期后重新调 API | 响应慢、浪费 API 配额 |
| 受 RingCentral API 限速影响 | 高并发时 SMS 页面加载失败 |
| RingCentral 服务不可用时无法查看历史 | 业务中断风险 |
| 缓存按查询整包存储 | 不同查询条件产生重复数据，空间浪费 |
核心矛盾：SMS 是高频使用功能，但数据完全依赖第三方 API 实时拉取，没有自主存储。
2. 代价¶
2.1 开发成本¶
| 步骤 | 工作量 | 难度 |
|---|---|---|
| CDK 新建 DynamoDB 表 | 0.5 天 | 低 |
| WebhookReceiver 增加 SMS 写入逻辑 | 1 天 | 低 |
| studio-api 查询改为读新表 | 1-2 天 | 中 |
| 历史数据回填脚本 | 1 天 | 中 |
| 移除旧缓存逻辑 | 0.5 天 | 低 |
| 合计 | 4-5 天 | — |
2.2 基础设施成本¶
| 项目 | 现在（缓存模式） | 持久化后 |
|---|---|---|
| DynamoDB 存储 | 缓存 10 分钟后删除，数据量极小 | 永久存储，但 SMS 文本数据量很小（几千条/月 ≈ 几 MB） |
| DynamoDB 写入 | 每次用户查询都写缓存 | 只在新 SMS 来时写一次，更少 |
| DynamoDB 读取 | 差不多 | 差不多 |
| RingCentral API 调用 | 缓存过期后频繁调用 | 几乎不调，显著减少 |
| 总计 | 基准 | 持平或更低（约 $0-2/月增量） |
2.3 运维成本¶
- 无新增运维负担：使用现有 DynamoDB + Lambda 基础设施
- Webhook 管道已有，只是新增一个事件类型的处理
3. 收益¶
| 收益 | 说明 |
|---|---|
| 查询更快 | 直接读 DynamoDB（<10ms），无需等 RingCentral API 响应（200-500ms） |
| 不受限速 | 不再依赖 RingCentral API 做 SMS 查询，高并发无问题 |
| 高可用 | RingCentral 故障时历史消息仍可查看 |
| 数据自主 | SMS 数据掌握在自己手中，便于后续做搜索、分析、导出等功能 |
| 完善客户画像 | SMS 持久化后可补充 PhoneBook 的 SMS 维度，完善客户 360 视图 |
4. 重要性¶
高。SMS 持久化可增强以下功能：
- PhoneBook 的 SMS 维度：持久化后 PhoneBook 可关联完整的 SMS 历史，而非仅统计计数
- 客户 360 视图：需要将 SMS 记录与通话、线索关联展示
- 报表分析：需要 SMS 交互数据参与统计
注意：PhoneBook 不依赖 SMS 持久化即可独立实施（通话 + 线索已足够），但 SMS 持久化可补全客户画像的短信维度。
5. 紧迫性¶
中。建议在 PhoneBook 之后实施。
| 时间因素 | 评估 |
|---|---|
| 当前是否有生产问题？ | 有——RingCentral API 偶发限速导致 SMS 页面加载慢 |
| 是否阻塞其他计划？ | 否——PhoneBook 可独立实施，SMS 持久化可后续补充 |
| 是否有外部截止日期？ | 无，但越早做越多数据被保留 |
| 技术债务风险 | 低——改动范围小，不会引入新技术栈 |
6. 风险分析¶
| 风险 | 概率 | 影响 | 对策 |
|---|---|---|---|
| 历史回填时触发 RingCentral API 限速 | 中 | 低 | 限制回填速率（如每秒 5 次），使用指数退避 |
| Webhook 事件丢失导致 SMS 缺失 | 低 | 中 | 设置定时对账任务，周期性从 API 补漏 |
| 新表 Schema 设计不当导致后续返工 | 低 | 中 | 参考成熟的 SMS 数据模型，预留扩展字段 |
| 与现有缓存逻辑并行期间数据不一致 | 低 | 低 | 上线后先双写观察，确认无误后移除旧缓存 |
总体风险：低。现有基础设施（Webhook、DynamoDB、CDK）均已就绪，无技术探索成本。
7. 实施计划¶
7.1 数据写入：利用现有 Webhook 基础设施¶
系统已有 WebhookReceiver Lambda 接收 RingCentral 事件。SMS 事件走同样的路：
RingCentral 发送SMS事件通知
↓
WebhookReceiver Lambda（已有）
↓
新增：写入 SMS 持久化表（DynamoDB）
↓
后续查询直接读 DynamoDB，不再调 RingCentral API
7.2 数据存储：新建独立 DynamoDB 表¶
| 字段 | 说明 |
|---|---|
| PK | STORE#{storeId} |
| SK | MSG#{creationTime}#{messageId} |
| messageId | RingCentral 消息唯一ID（用于去重） |
| direction | inbound / outbound |
| phoneNumber | 对方号码 |
| subject | 消息内容 |
| conversationId | 会话ID |
| readStatus | 已读/未读 |
| creationTime | 消息创建时间 |
| TTL | 无（永久存储） |
7.3 实施步骤¶
| 阶段 | 步骤 | 难度 | 说明 |
|---|---|---|---|
| 第 1 周 | CDK 新建 DynamoDB 表 | 低 | 在 studio-api infra 中加表定义 |
| 第 1 周 | WebhookReceiver 增加 SMS 写入逻辑 | 低 | 识别 SMS 事件类型，写入新表 |
| 第 2 周 | studio-api 查询改为读新表 | 中 | 改查询逻辑，优先查持久化表 |
| 第 2 周 | 历史数据回填 | 中 | 一次性从 RingCentral API 拉取历史 SMS 存入 |
| 第 3 周 | 移除旧缓存逻辑 | 低 | 持久化上线后，SMS 缓存可以去掉 |
8. 结论¶
推荐实施。
| 维度 | 评估 |
|---|---|
| 开发成本 | 低（4-5 天） |
| 基础设施成本 | 持平或更低 |
| 技术风险 | 低 |
| 收益 | 高（性能提升 + 高可用 + 数据自主） |
| 依赖关系 | 无硬依赖；可补全 PhoneBook 的 SMS 维度和客户 360 视图 |
- 查询更快：直接读 DynamoDB，无需等 RingCentral API 响应
- 不受限速：不再依赖 RingCentral API 做 SMS 查询
- 高可用：RingCentral 故障时历史消息仍可查看
- 数据自主：SMS 数据掌握在自己手中，便于后续做分析、搜索等功能
风险¶
- 无明显风险：现有基础设施（Webhook、DynamoDB、CDK）均已就绪
- 唯一注意点：历史回填时需控制 RingCentral API 调用频率，避免一次性拉取过多
与其他计划的关联¶
CUSTOMER_HISTORY v2¶
产品闭环分析指出：当前 AI 分析 prompt 中的 CUSTOMER_HISTORY 只包含通话数据，不包含 SMS。原因正是 SMS 没有持久化（见闭环分析第五节注释）。
SMS 持久化完成后，可以实现 CUSTOMER_HISTORY v2——在 AI 分析 prompt 中注入最近的 SMS 交互记录，让 AI 了解客户的完整沟通历史（不仅是电话，还有短信）。
PhoneBook 客户档案¶
PhoneBook 数据库设计中包含 smsCount 字段（短信条数）。SMS 持久化是 PhoneBook smsCount 准确计算的前提。两个方案建议在 Phase 1.5 中同步实施。
结论¶
推荐实施。技术难度低、费用不增反降、收益明确。核心改动集中在 WebhookReceiver 和 studio-api 两处，现有架构完全支持。建议在 PhoneBook 实施完成后作为第二优先级启动。