功能地图¶

从用户视角出发，梳理系统每个页面的功能，以及背后由哪些前端组件、后端 API、数据库共同实现。

1. 页面总览¶

登录页 (/auth/sign-in)
  │
  ▼ 登录成功
┌─────────────────────────────────────────────────┐
│  侧边栏                     主内容区              │
│ ┌───────────┐  ┌──────────────────────────────┐ │
│ │ 门店切换   │  │                              │ │
│ ├───────────┤  │   当前选中页面的内容            │ │
│ │ 常用功能   │  │                              │ │
│ │  仪表盘    │  │                              │ │
│ │  门店活动  │  │                              │ │
│ │  通话列表  │  │                              │ │
│ │  消息中心  │  │                              │ │
│ │  线索跟踪  │  │                              │ │
│ ├───────────┤  │                              │ │
│ │ 设置      │  │                              │ │
│ │  门店管理  │  │                              │ │
│ │  营业时间  │  │                              │ │
│ │  权限管理  │  │                              │ │
│ ├───────────┤  │                              │ │
│ │ 用户菜单   │  │                              │ │
│ │  个人设置  │  │                              │ │
│ │  退出登录  │  │                              │ │
│ └───────────┘  └──────────────────────────────┘ │
└─────────────────────────────────────────────────┘

2. 登录¶

用户看到什么：邮箱 + 密码登录表单

流程：

用户输入邮箱密码
    → AWS Cognito 验证
    → 获取 JWT Token（存 localStorage）
    → 拉取用户所属门店列表
    → 跳转到仪表盘

如果是首次登录且 Cognito 要求改密码，会跳转到修改密码页面。

层级	实现
前端页面	`studio-web/src/pages/auth/sign-in.vue`
前端组件	`EmailLoginForm`
状态管理	`auth.ts` store（Pinia，持久化 Token）
认证服务	AWS Cognito（用户池）
路由守卫	`auth-guard.ts` — 未登录自动跳转到登录页

3. 仪表盘（Dashboard）¶

路径：/dashboard

用户看到什么：

未连接 RingCentral 时：引导页，提示连接 RingCentral 账号（OAuth 授权流程）
已连接后：数据分析仪表盘
- 顶部：日期范围选择器
- 指标卡片：总通话数、接通率、平均通话时长等
- 图表区域：趋势折线图、分类圆环图、跟进原因分布、收入桑基图
- 员工绩效排行榜
- 快照导出功能（截图分享）

层级	实现
前端页面	`pages/dashboard/index.vue`
前端组件	`DashboardOnboarding`（引导页）、`DashboardAnalytics`（分析面板）
图表组件	`MetricCard`、`ChartCard`、`MetricTrendChart`、`DonutChartCategories`、`FollowUpReasons`、`RevenueWaterfallSankey`、`StaffPerformance`、`SnapshotPreviewDialog` 等 18+ 个
状态管理	`ringcentral.ts` store（连接状态）、`date-range.ts` store（日期范围）
后端 API	`GET /v2/calls`（通话数据）、`GET /v2/phone-numbers`（电话号码）
数据库	call-analysis 表（通话记录 + AI 分析结果）

4. 门店活动（Store Activity）¶

路径：/store-activity

用户看到什么：

顶部：周选择器（可前后翻页）
主体：一周的活动时间线（按天分列）
- 每个时间段聚合显示：通话、短信、语音留言、线索等事件
- 灰色区域标记停业时段（Blackout）
点击事件聚合卡片，弹出抽屉显示详情：
- 通话详情抽屉
- 消息线程抽屉
- 线索详情抽屉（内嵌电话活动面板）

层级	实现
前端页面	`pages/store-activity/index.vue`
前端组件	`ActivityTimelineWeekView`、`ActivityClusterDrawer`、`CallDetailDrawer`、`MessageThreadDrawer`、`LeadDetailDrawer`、`PhoneActivityInline`
数据聚合	`useActivityTimeline()` composable — 合并通话 + 短信 + 线索数据
后端 API	`GET /v2/calls`、`GET /v2/messages-store`、`GET /v2/lead/calls`、`GET /v2/operating-hours/effective`
数据库	call-analysis 表、LeadTracking-v2 表、RingCentral API（SMS）、OperatingHours 表、BlackoutPeriods 表

5. 通话列表（Call Table）¶

路径：/calls

用户看到什么：

顶部：日期范围选择器 + 刷新按钮
左侧：通话数据表格
- 列：时间、方向（呼入/呼出）、来电号码、时长、分类、结果、员工
- 支持排序、筛选、分页
- URL 同步（筛选条件保存在地址栏）
右侧：可调宽度的通话详情面板（点击某行展开）
手机端：点击后跳转到独立详情页

层级	实现
前端页面	`pages/calls/index.vue`
前端组件	`DataTable`、`DataTableToolbar`、`CallDetailPage`（内嵌面板）
交互逻辑	`useTableUrlSync()` — 表格状态 ↔ URL 双向同步
后端 API	`GET /v2/calls?startDate=...&endDate=...&storeId=...`
数据库	call-analysis 表（按 siteId + callStartTime 索引查询）

6. 通话详情（Call Detail）¶

路径：/call/:telephonySessionId（独立页面）或嵌入在通话列表右侧面板

用户看到什么：

头部：来电号码、通话方向、时长、时间
音频播放器：播放通话录音
转录时间线：按说话人分段显示文字，与音频同步高亮
AI 分析标签页（由 Manifest 动态驱动）：
- 通话信息
- 对话内容
- 执行摘要
- 客户画像
- 跟进建议（如需要）
- 改进建议
置信度评分徽章

层级	实现
前端页面	`pages/call/[telephonySessionId].vue`
前端组件	`CallDetailHeader`、`CallAudioPlayer`、`CallTranscriptTimeline`、`CallAnalysisManifest`（动态标签页引擎）
分析面板	`MetricsGridSection`、`CoachingCardSection`、`AlertListSection`、`ProcessChecklistSection`、`TextPanelSection` — 由 JSON Manifest 驱动渲染
后端 API	`GET /v2/calls/:telephonySessionId`（通话 + AI 分析）、`GET /v2/recordings/:recordingId`（录音流）
数据库	call-analysis 表（分析结果）、S3（录音文件 + 转录文本 + 分析 JSON）
AI 分析	Amazon Bedrock（分析结果在通话入库时已预计算）

7. 消息中心（Messages）¶

路径：/messages

用户看到什么：

顶部：日期范围选择器 + 刷新按钮
左侧：对话列表
- 按 conversationId 分组（同一号码的多条消息归为一个对话）
- 筛选器：状态（全部/未读）、类型（SMS/语音留言/传真）、联系人（全部/线索）
- 统计摘要：总对话数、未读数
- 置顶对话（存 localStorage）
右侧：选中对话的消息详情
- 聊天气泡样式（发送/接收区分）
- 已读/未读标记
- MMS 图片展示
- 语音留言播放器
点击电话号码：弹出电话活动面板（该号码的所有通话 + 线索记录）

层级	实现
前端页面	`pages/messages/index.vue`
前端组件	`ConversationCard`、`ConversationDetail`、`ConversationFilters`、`ConversationStats`、`PhoneActivityPanel`
数据获取	`useMessagesStore()` — 单次请求获取对话 + 消息
后端 API	`GET /v2/messages-store?storeId=...&dateFrom=...&dateTo=...`（统一接口）、`GET /v2/media/messages/:id/content/:attachmentId`（媒体流）
数据来源	RingCentral API（实时拉取）→ studio-Cache 表（DynamoDB 缓存，10 分钟 TTL）→ 返回前端
线索关联	`POST /v2/lead/check-phones`（批量检查号码是否为线索）

8. 线索跟踪（Lead Tracker）¶

路径：/lead-tracker

用户看到什么：

顶部：日期范围选择器 + 刷新按钮
主体：线索数据表格
- 列：电话号码、姓名、最后活动、SLA 状态（响应时间）、通话次数、短信次数、语音留言、处理结果
- SLA 计算：基于营业时间内的首次响应时长
点击电话号码：弹出电话活动面板
处理结果更新：可标记为"已联系"、"需跟进"等

层级	实现
前端页面	`pages/lead-tracker/index.vue`
前端组件	`DataTable`、`PhoneActivityPanel`
数据获取	`useLeadCalls()` composable（5 分钟缓存，因为 API 较慢）、`useEffectiveHours()`（营业时间）
后端 API	`GET /v2/lead/calls?storeId=...&startDate=...&endDate=...`（线索 + 关联通话）、`GET /v2/operating-hours/effective`（营业时间）
数据库	LeadTracking-v2 表（线索记录，来自邮件解析）、call-analysis 表（通话记录，按电话号码关联）
数据来源	lead-tracking Lambda 每 5 分钟轮询邮箱 → 解析表单邮件 → 写入 LeadTracking-v2

9. 门店管理（Stores & Groups）¶

路径：/stores

用户看到什么：

RingCentral 连接状态（已连接/未连接）
"连接 RingCentral"按钮（触发 OAuth 授权流程）
已同步的电话号码列表（按连接分组）
每个号码的门店分配状态
未分配号码区域
创建/编辑门店向导（基本信息 → 分配电话 → 定价方案 → 员工配置）

层级	实现
前端页面	`pages/stores/index.vue`
前端组件	`ConnectionsSection`、`PhoneNumbersCard`、`UnassignedPhonesSection`、`StoreConfigWizard`（4 步向导：`StepBasicInfo` → `StepPhoneNumbers` → `StepPricing` → `StepStaffAddons`）
后端 API	`POST /v2/auth/initiate`（OAuth）、`GET /v2/connections`、`GET /v2/phone-numbers`、`GET /v2/stores`、`POST /v2/stores`、`PUT /v2/stores/:id`、`DELETE /v2/stores/:id`
数据库	UserConnections 表（OAuth Token）、PhoneNumbers 表、PhoneStoreAssignments 表、StoresV2 表
外部服务	RingCentral OAuth 2.0 授权

10. 营业时间（Store Schedule）¶

路径：/store-schedule

用户看到什么：

门店基本信息编辑（时区、地址）
每周营业时间模板（可视化周视图）
特殊日期覆盖（单日调整营业时间）
停业时段管理（Blackout）
- 创建：选择日期范围 + 原因
- 编辑/删除已有停业时段
- 支持重复规则

层级	实现
前端页面	`pages/store-schedule/index.vue`、`pages/calendar/index.vue`
前端组件	`WeekTimelineView`、`ScheduleEditDialog`、`BlackoutEditDialog`、`BlackoutCard`、`OverrideEditDialog`
数据获取	`useCalendar()`、`useBlackouts()`、`useOperatingHours()`
后端 API	`GET/POST/DELETE /v2/stores/:storeId/operating-hours/`（排班 CRUD）、`GET/POST/PUT/DELETE /v2/stores/:storeId/blackouts/`（停业 CRUD）
数据库	OperatingHours 表（排班规则）、BlackoutPeriods 表（停业时段）

11. 权限管理（Access Management）¶

路径：/access-management

用户看到什么：

组织卡片列表（每个门店/门店组一张卡片）
每张卡片显示：门店名称 + 已授权用户列表 + 角色（Owner/Editor/Viewer）
批量授权对话框：一次性给多个用户添加多个门店的权限

层级	实现
前端页面	`pages/access-management/index.vue`
前端组件	`OrganizationCard`、`BatchGrantDialog`
后端 API	`GET /v2/access-management/view`（整合视图）、`POST /v2/stores/batch-grant`（批量授权）、`GET/DELETE /v2/sub-accounts`（子账号管理）
数据库	StoresV2 表、UserStore 表（用户-门店权限映射）、SubAccounts 表（父子账号关系）

12. 个人设置（Settings）¶

路径：/settings、/settings/change-password

用户看到什么：

个人资料表单（邮箱、姓名）
外观设置（亮色/暗色/跟随系统）
显示偏好
通知设置
修改密码

层级	实现
前端页面	`pages/settings/index.vue`、`pages/settings/change-password.vue`
前端组件	`ProfileForm`、`AppearanceForm`、`DisplayForm`、`NotificationsForm`
状态管理	`auth.ts` store、`theme.ts` store（持久化主题偏好）
认证服务	AWS Cognito（修改密码）

13. 全局功能¶

除了上述页面功能外，以下功能贯穿整个应用：

13.1 侧边栏与门店切换¶

用户可以随时通过侧边栏顶部的下拉菜单切换当前门店，切换后所有页面数据自动刷新。

层级	实现
前端组件	`app-sidebar/index.vue`、`team-switcher.vue`、`nav-team.vue`、`nav-footer.vue`
状态管理	`stores.ts` store（当前门店 ID 持久化到 localStorage）
导航数据	`useSidebar()` composable

13.2 日期范围选择¶

大多数数据页面共享同一套日期范围组件，切换页面时自动保持选中的日期范围。

层级	实现
前端组件	`DateRangeDropdown`
状态管理	`date-range.ts` store — URL query 是唯一数据源（`?startDate=...&endDate=...`）
路由行为	带 `preserveDateRange: true` meta 的页面跳转时保留日期参数

13.3 电话活动面板¶

在多个页面中（消息中心、线索跟踪、门店活动），点击电话号码会弹出统一的电话活动面板，展示该号码的所有互动历史。

层级	实现
前端组件	`PhoneActivityPanel`、`PhoneActivityList`、`CallActivityCard`、`SmsActivityCard`、`VoicemailActivityCard`、`LeadActivityCard`
后端 API	`GET /v2/phone/:phoneNumber/activity`（跨源聚合：通话 + 短信 + 线索）
数据库	call-analysis 表（通话）、RingCentral API（短信）、LeadTracking-v2 表（线索）

13.4 命令面板¶

按 Cmd+K（Mac）或 Ctrl+K 打开全局搜索/命令面板，快速跳转到任意页面。

层级	实现
前端组件	`command-palette/`

13.5 主题切换¶

支持亮色/暗色/跟随系统三种模式，在个人设置中配置，顶部栏也有快捷切换按钮。

层级	实现
状态管理	`theme.ts` store（持久化到 localStorage）

14. 技术栈速查¶

类别	技术	用途
UI 框架	Vue 3 + Composition API	前端框架
构建工具	Vite	开发服务器 + 打包
样式	Tailwind CSS	原子化 CSS
组件库	shadcn-vue（227 文件，40+ 种组件）	Button、Card、Badge 等基础组件
图表	ECharts	仪表盘图表（折线、圆环、桑基图等）
数据获取	TanStack Vue Query	缓存、自动刷新、loading 状态管理
状态管理	Pinia（持久化插件）	全局状态（认证、门店、日期范围、主题）
路由	Vue Router + unplugin-vue-router	基于文件的自动路由生成
布局	vite-plugin-vue-layouts	自动布局切换（default / blank / marketing）
监控	Sentry + GA4	错误追踪 + 用户行为分析