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

前端

1. 类型定义与基础设施

• 1.1 扩展 PreviewChatMessage 类型：新增 status（loading/done/error）、error、audioBlob 字段
• 1.2 定义 DialogueAPI 接口：createSession / speak / getReport 方法
• 1.3 定义 SSE 事件类型：TranscriptEvent / TokenEvent / DoneEvent
• 1.4 创建 composables 和 services 目录结构

2. API 通信层（llmService.ts）

• 2.1 实现 SSE 响应解析器：根据 event type 解析 transcript / token / done
• 2.2 实现 RealDialogueAPI：fetch + ReadableStream，对接后端 3 个接口
• 2.3 实现 MockDialogueAPI：模拟 transcript + 逐 token 输出
• 2.4 实现 AbortController 支持

3. 录音采集（useAudioRecorder.ts）

• 3.1 实现麦克风权限请求与状态管理
• 3.2 实现 MediaRecorder 封装：start / stop，自动检测 mimeType
• 3.3 实现录音计时器
• 3.4 实现资源清理：onUnmounted 中释放 MediaStream

4. 对话引擎（useDialogueEngine.ts）

• 4.1 实现消息列表管理：messages ref
• 4.2 实现 sendStudentMessage(audioBlob)：添加学生消息 → 调 speak → 流式消费 → 完成/失败
• 4.3 实现重试：学生消息失败 → 用缓存 audioBlob 重新调 speak
• 4.4 实现重新生成：AI 消息中断 → 清空内容重新调 speak
• 4.5 实现轮次推进：收到 done 事件后判断是否结束
• 4.6 实现录音按钮锁定：loading 时禁用
• 4.7 实现 adapter 注入：通过 mode prop 选择 Mock/Real
• 4.8 实现 TTS：AI 消息 done 后调用 Azure TTS 合成语音并播放
• 4.9 实现倒计时 UI：用后端返回的 expires_at 显示倒计时
• 4.10 实现报告页轮询：每 2 秒轮询 GET /report，30 秒超时兜底

5. 重构 DialogueChatView.vue

• 5.1 移除所有 mock 逻辑，改为从 useDialogueEngine 获取状态
• 5.2 接入 useAudioRecorder：录音按钮绑定 start/stop
• 5.3 新增错误状态 UI：error 消息显示「重试」/「重新生成」按钮
• 5.4 新增流式输出 UI：loading 消息显示 typing 动画
• 5.5 实现自动滚动
• 5.6 接入麦克风权限引导 UI

6. 前端验证

• 6.1 编译验证：无 TypeScript 错误
• 6.2 Mock 模式端到端：录音 → 发送 → 流式回复 → 轮次推进
• 6.3 异常场景验证：模拟请求失败、重试

---

后端（cococlass-english-speaking-api）

7. 项目搭建

• 7.1 初始化项目：uv init + 安装依赖
• 7.2 创建目录结构
• 7.3 配置 pydantic-settings + .env
• 7.4 配置 SQLAlchemy 2.0 async engine + 数据模型

8. Provider 实现

• 8.1 定义 Protocol 接口（ASR / LLM / PronunciationAssessor / AudioStorage）
• 8.2 实现 Azure Speech ASR Provider
• 8.3 实现 Azure Speech Pronunciation Assessment Provider
• 8.4 实现 One-Hub LLM Provider（Chat Completions 流式）
• 8.5 实现 S3 Audio Storage Provider

9. 核心服务

• 9.1 实现 DialogueService.create_session
• 9.2 实现 DialogueService.speak（ASR → SSE transcript → LLM 流式 → SSE token/done）
• 9.3 实现后台发音评估（asyncio.create_task）
• 9.4 实现 DialogueService.get_report（延后，结果页方案待确认）

10. API 路由

• 10.1 实现 POST /api/speaking/dialogue/session
• 10.2 实现 POST /api/speaking/dialogue/speak（StreamingResponse）
• 10.3 实现 GET /api/speaking/dialogue/report（延后）

11. 后端验证

• 11.1 启动验证：uvicorn 启动无报错
• 11.2 接口验证：用 httpx/curl 测试 3 个接口
• 11.3 前后端联调：前端 RealDialogueAPI 对接后端