系统架构总览¶
1. 架构图¶
源文件：backend-data-pipeline.drawio（用 draw.io 打开编辑）
1.1 图例¶
节点颜色
| 属性 | 颜色 | 对应组件 |
|---|---|---|
| 外部服务 | 蓝色 | RingCentral API、Lark Suite / Gmail、Deepgram、Amazon Bedrock |
| 自有代码（部署在 AWS） | 橙色 + 绿色粗边框 | 所有 Lambda 函数、Prompt 配置文件 —— 代码存放在 GitHub，通过 CDK 部署到 AWS 运行 |
| 自有代码（未部署到 AWS） | 橙色（无绿边） | studio-website-monorepo 的 apps/web（部署在 Cloudflare） |
| 共享库 | 灰色 | callytics-common |
| AWS 托管服务 | 绿色 / 青色 | DynamoDB（绿色圆柱）、SQS（绿色长方体）、S3（青色圆柱） |
| 文档 | 蓝灰色 | docs |
连线颜色
| 数据流 | 颜色 | 路径 |
|---|---|---|
| 通话语音流 | 浅蓝色粗实线 | RingCentral → Webhook接收 → SQS队列 → 下载录音 → S3 |
| AI 分析流 | 深蓝色粗实线 | Deepgram转录 → SQS → 结果处理 → Bedrock AI分析 → DynamoDB |
| 修复管道 | 紫色线 | 每日凌晨检测遗漏通话 → 修复任务队列 → 修复Worker → 注入回主队列重新处理 |
| SMS 数据流 | 品红色粗实线 | RingCentral → apps/api → SMS缓存 |
| 线索数据流 | 绿色粗实线 | 邮箱 → lead-tracking → 线索数据库 |
| 应用层查询 | 黑色粗实线 | 数据库/S3 → apps/api → apps/web |
| 依赖/配置 | 灰色虚线 | 服务间引用、OAuth认证、Prompt配置、Lambda调用 |
2. 四条数据线¶
系统有四条并行的数据线路：
2.1 线路一：通话分析（主动推送） 浅蓝色 + 深蓝色¶
对应图例：通话语音流（ 浅蓝色）+ AI 分析流（ 深蓝色）
客户打电话 → RingCentral 记录 → Webhook 通知
→ ringcentralSubscriptionService 贴标签
→ SQS 队列（等5分钟）
→ callytics-infrastructure 转录 + AI 分析
→ DynamoDB 存储结果
→ apps/api 查询 → apps/web 展示
2.2 线路二：修复管道（定时检测） 紫色¶
对应图例：修复管道（ 紫色）
每日凌晨定时触发
→ 检测前一天遗漏/失败的通话记录
→ 生成修复任务 → 修复任务队列
→ 修复 Worker 逐条处理
→ 注入回主队列（线路一）重新转录 + AI 分析
→ 补全 DynamoDB 中缺失的分析结果
2.3 线路三：线索采集（定时轮询） 绿色¶
对应图例：线索数据流（ 绿色）
潜在客户在健身房网站填表
→ 系统发通知邮件到指定邮箱
→ lead-tracking 每5分钟轮询邮箱（IMAP）
→ 解析邮件提取：姓名、电话、邮箱、预约时间
→ DynamoDB LeadTracking-v2 表存储
→ apps/api 按电话号码关联通话记录
→ apps/web 展示线索跟踪
2.4 线路四：SMS 短信（按需拉取） 品红色¶
对应图例：SMS 数据流（ 品红色）
客户发短信到 RingCentral 号码
→ 短信存储在 RingCentral 云端
→ 用户打开消息页面时触发拉取
→ apps/api 调用 RingCentral /message-store API
→ 三层缓存：内存(5分钟) → DynamoDB studio-Cache(10分钟) → API
→ 按 conversationId 分组成对话线程
→ apps/web 展示（聊天气泡、已读/未读、MMS图片）
四条线路在 studio-monorepo 汇合——后端通过电话号码把"谁打了电话"、"哪些通话被修复补全了"、"谁是网站来的线索"、"谁发过短信"关联起来，帮助健身房全面了解每个客户的互动记录。
3. 仓库说明¶
| 仓库 | 角色 | 说明 |
|---|---|---|
| studio-website-monorepo | 前端 + 后端 | Turborepo monorepo——apps/web 是用户看到的网页，apps/api 是后端服务，负责查询数据库并关联通话与线索 |
| callytics-infrastructure | AI 工厂 | 录音进去，分析结果出来。Prompt 文件在这里驱动 AI 分析 |
| ringcentralSubscriptionService | 接线员 | 接收 RingCentral 电话通知，贴标签后丢进队列 |
| lead-tracking | 线索采集员 | 每5分钟轮询邮箱，解析潜在客户表单邮件，提取姓名/电话/预约信息存入数据库 |
| callytics-common | 公共工具箱 | 错误处理、日志、重试等公共能力，被后端和 AI 工厂共同依赖 |
| docs | 内部知识库 | 产品设计、架构文档、业务背景知识 |
4. 技术栈总览¶
| 层级 | 技术 |
|---|---|
| 前端 | Vue 3 + Vite + Tailwind CSS + shadcn-vue + ECharts |
| 前端部署 | Cloudflare Pages |
| 后端 | Hono + TypeScript + AWS Lambda |
| 数据库 | DynamoDB (10+ 张表) |
| 存储 | S3 (录音 + 配置) |
| 消息队列 | SQS |
| AI 分析 | AWS Bedrock (Kimi K2 / Claude) |
| 语音转录 | Deepgram |
| 邮件采集 | IMAP (Lark Suite) + Google Apps Script |
| 认证 | AWS Cognito + RingCentral OAuth |
| 基础设施 | AWS CDK (TypeScript) |
| 监控 | CloudWatch + Sentry + Discord/飞书通知 |
5. 外部依赖¶
| 服务 | 用途 |
|---|---|
| RingCentral | 电话数据来源（通话记录、录音、SMS） |
| AWS | 全套云服务（Lambda、DynamoDB、S3、SQS、Cognito、Bedrock） |
| Deepgram | 语音转文字 |
| Lark Suite | 邮箱服务（线索邮件接收） |
| Cloudflare | 前端托管 + 文档托管 |
| Sentry | 错误追踪 |
| Discord / 飞书 | 告警通知 |