Browse Source

docs: add WIP code disposition guide for implementation kickoff

Add §11.1 explicit disposition guide for the exploratory code
captured in the prior WIP checkpoint (commit 2ce4e49). The next
session must know which files to rewrite vs. evaluate-for-reuse,
so stale implementations based on the superseded design
(old 'homeworkContext' inject, role fields, /report/stream) are
not mistaken for a viable starting point.

- Per-file status + action for types, composables, services, and
  preview components
- Recommended kickoff flow: diff vs. prior checkpoint, git checkout
  clean state for files tagged "重写", then implement per §11 main
  table from zero
- Keep infrastructure files (audio worklet, recorder) pending until
  corresponding porting stage
jimmylee 2 weeks ago
parent
commit
92c09e590b
1 changed files with 18 additions and 1 deletions
  1. 18 1
      doc/EnglishSpeakingIntegration.md

+ 18 - 1
doc/EnglishSpeakingIntegration.md

@@ -462,7 +462,24 @@ is_complete = session.current_round > session.total_rounds
 | 提示弹窗、实时反馈条等辅助 UI 按 §5.4 映射移植 | `src/views/Editor/EnglishSpeaking/preview/HintDialog.vue` / `RealtimeFeedback.vue` |
 | 提示弹窗、实时反馈条等辅助 UI 按 §5.4 映射移植 | `src/views/Editor/EnglishSpeaking/preview/HintDialog.vue` / `RealtimeFeedback.vue` |
 | `types/englishSpeaking.ts`:加 `timeLimitSeconds?: number`;清理 role.identity / personality / speakingStyle / speed 等不需要的字段 | `src/types/englishSpeaking.ts` |
 | `types/englishSpeaking.ts`:加 `timeLimitSeconds?: number`;清理 role.identity / personality / speakingStyle / speed 等不需要的字段 | `src/types/englishSpeaking.ts` |
 
 
-### 11.1 teacher-table 侧
+### 11.1 WIP 代码处置(开发起步前先做)
+
+上一次提交(`2ce4e49 chore: WIP checkpoint before english-speaking redesign`)里保留了一批探索性代码,基于已被推翻的旧设计(老 inject key `'homeworkContext'`、老 role 字段、SSE `/report/stream` 等)。新会话开始实现前应做**显式处置**,避免误把 WIP 当成可用基础。
+
+| 文件 | 状态 | 建议 |
+|---|---|---|
+| `src/types/englishSpeaking.ts` | 含已废弃字段(`Role.identity` / `Role.personality` / `PreviewAIRole.speakingStyle` / `PreviewAIRole.speed`) | 按 §11 表的"清理" + 加 `timeLimitSeconds` 项执行;读 §5.3 Props 对齐 |
+| `src/views/Editor/EnglishSpeaking/composables/useAudioRecorder.ts` | 录音封装,基础设施类 | **通读 + 评估复用**:录音本身与设计无耦合,若实现干净可保留;若依赖老类型则重写 |
+| `src/views/Editor/EnglishSpeaking/composables/useDialogueEngine.ts` | 引用老类型 `PreviewChatMessage / SessionConfig / DialogueReport` + 老 `MockDialogueAPI/RealDialogueAPI` 抽象 | **重写**。新设计里对话引擎的状态由 `DialogueChatView` + `SpeakingRunnerContext` 承载,不需要独立 engine composable(或 composable 要按新 inject 模式重构) |
+| `src/views/Editor/EnglishSpeaking/services/llmService.ts` | `parseSSEStream` 逻辑本身可能可复用;API_BASE 硬编码需改 env | **SSE 解析保留 / 其余重写**。新设计没有 `report/stream`,只有 `/session` + `/speak` + `/report` 三个 endpoint |
+| `src/views/Editor/EnglishSpeaking/preview/DialogueChatView.vue` | 基于旧 Props(有 role 字段)+ 旧状态机 | **重写**(§11 主表已标明)。按 §5.4 从 enspeak TSX 1:1 移植 |
+| `src/views/Editor/EnglishSpeaking/preview/TopicDiscussionPreview.vue` | 基于旧流程(无 B1 resume / 无 runner context) | **重写**。按 §5.1 / §6.1 承担 runner context 注入 + B1 分支路由 |
+| `public/pcm-recorder-worklet.js` | Audio worklet,基础设施类 | 若 enspeak 没对应 worklet(enspeak 用浏览器原生 MediaRecorder),按 §5.4 移植时对齐选择;目前文件保留 |
+| `vite.config.ts` 改动 | 应该是为了 worklet / 路径别名 | 先看 diff 决定是否保留 |
+
+**推荐动作**:新会话开始时先 `git diff 500179d HEAD -- src/` 回顾 WIP 改动;把"直接重写"的文件先 `git checkout 500179d -- <path>` 恢复到 checkpoint 前状态(干净起点),再按 §11 主表从零实现。保留性工具(worklet / recorder)先不动,实现到对应环节再决定。
+
+### 11.2 teacher-table 侧
 
 
 | 改动 | 位置 |
 | 改动 | 位置 |
 |---|---|
 |---|---|