PPT/openspec/changes/dialogue-chat-engine/design.md

Context

当前 DialogueChatView.vue 是一个 1041 行的单文件组件，所有对话逻辑（状态管理、录音模拟、评估生成、UI 渲染）全部内联在一个文件中，使用硬编码的 dialogueScript 数组驱动对话轮次。

现有架构问题：

• 无真实录音能力，录音按钮仅切换 isRecording 布尔值
• AI 回复来自本地脚本数组，无 LLM 调用
• 评估数据由 generateMockEvaluation() 随机生成
• 无异常处理（网络断开、请求超时、消息重发）
• 无消息状态管理（无法区分消息是发送中、流式中还是失败）
• UI 和业务逻辑完全耦合，难以测试和维护

技术约束：

• 前端：Vue 3 + TypeScript + Composition API，优先使用浏览器原生 API
• 后端：独立项目 cococlass-english-speaking-api（Python + FastAPI）
• LLM 通过 One-Hub 统一网关调用（Chat Completions API）
• ASR 和发音评估使用 Azure Speech

Goals / Non-Goals

Goals:

• 将对话引擎从 UI 组件中解耦为独立的 composable + service 三层架构
• 实现完整的消息状态机（loading / done / error）
• 支持 LLM 流式输出（fetch streaming），逐 token 渲染
• 实现异常处理：请求失败 → 显示重试按钮 → 重新发送
• 封装录音采集（MediaRecorder）为独立 composable，含权限处理
• 设计 API 抽象层，支持 mock adapter 和真实 API adapter 无缝切换
• 后端实现对话编排服务，提供 session/speak/report 三个接口

Non-Goals:

• 不重新设计 UI 外观——保留现有的视觉样式，仅重构逻辑层
• 不涉及离线模式或本地缓存
• 不做自动重试 / 指数退避（v1 先不做，反馈后迭代）
• 不做服务端 TTS（v1 用前端 Web Speech API）

---

前端架构

Decision 1: 三层架构（Service → Composable → Component）

选择: llmService（通信层）→ useDialogueEngine（状态编排层）→ DialogueChatView（UI 层）

理由:

• Service 层不依赖 Vue，可单元测试，也可在其他场景复用
• Composable 层用 Vue 的 ref/reactive 管理状态
• Component 层变为纯粹的展示层

Decision 2: 使用 fetch + ReadableStream

选择: fetch() + response.body.getReader() 实现流式读取

理由: EventSource 只支持 GET，fetch streaming 支持 POST + AbortController + 自定义 headers

Decision 3: 消息状态简化为 3 个

选择: loading | done | error，不细分内部阶段

理由:

• 用户不关心是 ASR 阶段还是 LLM 阶段，只关心"在处理/好了/出错了"
• 错误处理统一：出错 → 显示重试按钮 → 重新调 /speak
• 第一版先简单，反馈后再迭代更精细的状态

Decision 4: 录音使用浏览器原生 MediaRecorder API

选择: 直接封装 MediaRecorder，不引入第三方录音库

理由: 现代浏览器兼容性已足够，避免额外依赖

Decision 5: API Adapter 对接后端 3 个接口

选择: DialogueAPI 接口对应后端的 session / speak / report

interface DialogueAPI {
  createSession(config: SessionConfig): Promise<SessionInfo>
  speak(sessionId: string, audioBlob: Blob, signal: AbortSignal): AsyncGenerator<SSEEvent>
  getReport(sessionId: string): Promise<Report>
}

实现: MockDialogueAPI（开发用）和 RealDialogueAPI（对接真实后端） 通过前端 prop mode: 'preview' | 'real' 切换

Decision 6: TTS 使用前端 Azure TTS

选择: AI 消息 done 后，前端整段文本调用 Azure TTS 合成语音并播放

理由:

• 前端已通过 SSE 接收完整文本，直接调 Azure TTS 最简单
• AI 回复限定 1-2 句（system prompt 约束），不需要分句 TTS
• 不做服务端 TTS，后端不涉及语音合成

---

后端架构

项目：cococlass-english-speaking-api

独立编排服务，串联 Azure Speech 和 One-Hub，管理对话 session 状态。

前端
  │
  ▼
cococlass-english-speaking-api（编排层）
  ├──→ Azure Speech     ASR + 发音评估
  ├──→ One-Hub          LLM 流式对话（Chat Completions）
  ├──→ MySQL            session + 消息 + 评估结果
  └──→ S3               音频文件存储

技术栈

层	选择
框架	FastAPI + uvicorn
LLM	Chat Completions via One-Hub（openai SDK）
ASR	Azure Speech（纯转录模式）
发音评估	Azure Speech Pronunciation Assessment（后台）
SSE	FastAPI 原生 EventSourceResponse + ServerSentEvent
数据库	MySQL + asyncmy + SQLAlchemy 2.0
存储	S3（boto3）
配置	pydantic-settings + python-dotenv

Decision 7: 不使用 Assistants API

理由: 口语对话是简单一问一答，不需要 Thread/Run 机制。对话历史要存自己 DB，Assistants 的 Thread 管理是重复功能。

Decision 8: 后端统一编排，前端只发一个请求

理由: 前端不应知道后端内部有几步（ASR/LLM/评估）。音频只上传一次，错误处理统一。

Decision 9: 对话中不展示评分

理由: 保证练习流畅度。发音评估后台静默执行，结果页才展示。

Decision 10: Protocol + 依赖注入

ASRProvider / LLMProvider / PronunciationAssessor / AudioStorage 四个 Protocol 接口，具体实现可替换可测试。

Decision 11: 不用 Redis

理由: 3 轮对话只有 3 次 DB 查询，不值得加缓存层。

API 设计

POST /api/speaking/dialogue/session   → JSON { sessionId, aiMessage }
POST /api/speaking/dialogue/speak     → SSE { transcript, token, done }
GET  /api/speaking/dialogue/report    → JSON { 对话历史 + 评分 + LLM 总结 }

数据模型

• DialogueSession: id, user_id, topic, role_config, total_rounds, current_round, status, system_prompt, expires_at, summary, created_at, completed_at
• DialogueMessage: id, session_id, round, role, content, audio_url, created_at
• PronunciationEvaluation: id, message_id, session_id, round, status, accuracy/fluency/completeness/prosody scores, word_analysis, created_at, completed_at

---

Risks / Trade-offs

• [MediaRecorder 格式兼容性] → Safari 不支持 webm，需 fallback 到 mp4/wav
• [流式解析差异] → 在 adapter 层做格式解析，engine 层只关心 token string
• [录音权限拒绝] → composable 暴露 permissionState，UI 显示引导提示
• [内存泄漏] → 在 composable 的 onUnmounted 中统一清理录音 Blob
• [后台评估未完成] → 前端轮询 GET /report（每 2 秒），30 秒超时后展示已有结果，缺失的标记为"评估不可用"。评估记录在 speak 主流程中创建（保证记录一定存在），后台任务只负责更新结果
• [定时结束] → 后端通过 expires_at 判断，/speak 时检查是否超时。前端用 expires_at 显示倒计时，不再是纯前端控制