# 录音详情高级操作代码拆分方案

## 修改日期
2026-06-25

## 修改状态
✅ **已完成** - 2026-06-25

## 修改完成记录

### 修改内容摘要
- ✅ 创建组合式函数文件 `templates/index/src/composables/useRecordingOperations.js`
- ✅ 在 `main.js` 中添加导入语句 `import { useRecordingOperations } from './composables/useRecordingOperations.js'`
- ✅ 在 `setup()` 中调用组合式函数，传入必要的依赖
- ✅ 删除原 1537-2657 行约 1120 行旧代码
- ✅ 创建函数引用保持模板兼容性
- ✅ 更新 return 对象使用 `recordingOps.xxx` 格式

### 代码行数变化
- **修改前**: `main.js` 约 7989 行
- **修改后**: `main.js` 约 6928 行
- **减少**: 约 1061 行
- **新增文件**: `useRecordingOperations.js` 约 1250 行

### 影响范围
- ✅ 不影响 HTML 模板文件（所有函数和状态名保持不变）
- ✅ `index.html` 无需修改
- ✅ `index copy.html` 无需修改  
- ✅ `account.html` 不受影响（独立脚本）

### 测试状态
- [ ] 等待按照下方测试用例清单进行测试验证

### 回滚方案
如出现问题，可直接：
1. 删除 `useRecordingOperations.js` 文件
2. 从 git 历史恢复 `main.js` 的原始代码
3. 删除 `main.js` 中的导入语句
4. 重新加载页面验证

## 修改目标
将 `templates/index/src/main.js` 中过于庞大的 **录音详情高级操作** 代码块（约 1120 行）拆分为独立的 Vue Composition Function，提高代码可维护性。

## 原始代码位置
- **文件**: `templates/index/src/main.js`
- **起始行**: 1537 行 (`//------------------- 录音详情高级操作 start------------------`)
- **结束行**: 2657 行 (`//--------------------录音详情高级操作 end------------------`)
- **代码行数**: 约 1120 行

## 拆分方案

### 方案类型
Vue 3 Composition Function (组合式函数)

### 新文件结构
```
templates/index/src/
├── main.js                      # 主入口文件（精简后）
├── composables/                 # 新增组合式函数目录
│   └── useRecordingOperations.js # 录音操作组合式函数
└── docs/
    └── refactor-recording-operations.md  # 本文档
```

### 依赖关系映射

#### 外部依赖（从主文件传入）
| 依赖项 | 类型 | 用途 |
|-------|------|------|
| `recordings` | Ref | 录音列表数据 |
| `selectedRecording` | Ref | 当前选中录音 |
| `selectedTab` | Ref | 当前选中的标签页 |
| `uploadQueue` | Ref | 上传/处理队列 |
| `currentlyProcessingFile` | Ref | 当前正在处理的文件 |
| `processingProgress` | Ref | 处理进度 |
| `processingMessage` | Ref | 处理状态消息 |
| `progressPopupMinimized` | Ref | 进度弹窗最小化状态 |
| `progressPopupClosed` | Ref | 进度弹窗关闭状态 |
| `showToast` | Function | 显示 Toast 提示 |
| `setGlobalError` | Function | 设置全局错误 |
| `resetCurrentFileProcessingState` | Function | 重置当前文件处理状态 |

#### 内部定义的状态（原属于高级操作模块）
| 状态名 | 类型 | 用途 |
|-------|------|------|
| `showReprocessModal` | Ref | 重处理模态框显示状态 |
| `reprocessType` | Ref | 重处理类型（transcription/summary） |
| `reprocessRecording` | Ref | 待重处理的录音 |
| `asrReprocessOptions` | Ref | ASR 重处理选项 |
| `showTextEditorModal` | Ref | 文本编辑器模态框 |
| `editingTranscriptionContent` | Ref | 正在编辑的转写内容 |
| `showAsrEditorModal` | Ref | ASR 编辑器模态框 |
| `editingSegments` | Ref | 正在编辑的段落 |
| `availableSpeakers` | Ref | 可用说话人列表 |
| `showSpeakerModal` | Ref | 说话人模态框 |
| `speakerMap` | Ref | 说话人映射 |
| `speakerDisplayMap` | Ref | 说话人显示映射 |
| `modalSpeakers` | Ref | 模态框中的说话人 |
| `identifiedSpeakers` | Ref | 已识别的说话人 |
| `regenerateSummaryAfterSpeakerUpdate` | Ref | 更新说话人后是否重新生成总结 |
| `speakerSuggestions` | Ref | 说话人建议 |
| `loadingSuggestions` | Ref | 建议加载状态 |
| `activeSpeakerInput` | Ref | 当前激活的说话人输入 |
| `isAutoIdentifying` | Ref | 是否正在自动识别 |
| `highlightedSpeaker` | Ref | 高亮的说话人 |
| `currentSpeakerGroupIndex` | Ref | 当前说话人组索引 |
| `speakerGroups` | Ref | 说话人组 |
| `reprocessingPolls` | Ref(Map) | 轮询任务 Map |
| `recordingToReset` | Ref | 待重置状态的录音 |
| `showResetModal` | Ref | 重置确认模态框 |

#### 计算属性
| 属性名 | 依赖 | 用途 |
|-------|------|------|
| `identifiedSpeakersInOrder` | `processedTranscription` | 按顺序排列的已识别说话人 |
| `hasSpeakerNames` | `speakerMap` | 是否有输入的说话人名称 |
| `highlightedTranscript` | `selectedRecording`, `highlightedSpeaker` | 高亮转写内容 |

### 模块功能划分

#### 1. 重处理功能模块
- `reprocessTranscription()` - 重处理转写
- `reprocessSummary()` - 重处理总结
- `confirmReprocess()` - 确认重处理
- `cancelReprocess()` - 取消重处理
- `executeReprocess()` - 执行重处理
- `performReprocessTranscription()` - 执行转写重处理
- `performReprocessSummary()` - 执行总结重处理
- `showProgressModalForReprocessing()` - 显示重处理进度模态框

#### 2. 转写编辑模块
- `openTranscriptionEditor()` - 打开转写编辑器
- `openTextEditorModal()` - 打开文本编辑器
- `closeTextEditorModal()` - 关闭文本编辑器
- `saveTranscription()` - 保存转写
- `openAsrEditorModal()` - 打开 ASR 编辑器
- `closeAsrEditorModal()` - 关闭 ASR 编辑器
- `saveAsrTranscription()` - 保存 ASR 转写
- `adjustTime()` - 调整时间
- `filterSpeakers()` - 过滤说话人
- `openSpeakerSuggestions()` - 打开说话人建议
- `closeSpeakerSuggestions()` - 关闭说话人建议
- `selectSpeaker()` - 选择说话人
- `addSegment()` - 添加段落
- `removeSegment()` - 删除段落
- `saveTranscriptionContent()` - 保存转写内容

#### 3. 说话人管理模块
- `openSpeakerModal()` - 打开说话人模态框
- `closeSpeakerModal()` - 关闭说话人模态框
- `saveSpeakerNames()` - 保存说话人名称
- `searchSpeakers()` - 搜索说话人
- `selectSpeakerSuggestion()` - 选择说话人建议
- `closeSpeakerSuggestionsOnClick()` - 点击时关闭建议
- `highlightSpeakerInTranscript()` - 高亮转写中的说话人
- `focusSpeaker()` - 聚焦说话人输入
- `blurSpeaker()` - 失焦说话人输入
- `clearSpeakerHighlight()` - 清除说话人高亮
- `findSpeakerGroups()` - 查找说话人组
- `navigateToNextSpeakerGroup()` - 导航到下一个说话人组
- `navigateToPrevSpeakerGroup()` - 导航到上一个说话人组
- `autoIdentifySpeakers()` - 自动识别说话人

#### 4. 状态管理模块
- `generateSummary()` - 生成总结
- `resetRecordingStatus()` - 重置录音状态
- `confirmReset()` - 确认重置
- `cancelReset()` - 取消重置
- `executeReset()` - 执行重置

#### 5. 标记功能模块
- `toggleInbox()` - 切换收件箱状态
- `toggleHighlight()` - 切换高亮状态

#### 6. 轮询监控模块
- `startReprocessingPoll()` - 开始重处理轮询
- `stopReprocessingPoll()` - 停止重处理轮询
- `updateReprocessingProgress()` - 更新重处理进度

## 修改步骤

### 步骤 1: 创建组合式函数文件
创建 `templates/index/src/composables/useRecordingOperations.js`，包含所有录音操作相关函数和状态。

### 步骤 2: 修改主文件
在 `main.js` 中：
1. 导入新的组合式函数
2. 移除原 1537-2657 行的代码块
3. 在 `setup()` 中调用组合式函数
4. 将返回的状态和方法展开到 return 对象中

### 步骤 3: 测试验证
按照下方的测试用例逐一验证功能正常。

## 风险评估

### 高风险
1. **响应式状态同步**: 确保传入的 Ref 对象在组合式函数中的修改能正确触发 UI 更新
2. **轮询内存泄漏**: `reprocessingPolls` Map 需要正确清理，避免内存泄漏
3. **DOM 查询依赖**: `findSpeakerGroups()` 函数直接查询 DOM，需确保调用时 DOM 已就绪

### 中风险
1. **事件监听器**: `closeSpeakerSuggestionsOnClick` 依赖全局点击事件，需确保正确绑定和解绑
2. **循环依赖**: `performReprocessTranscription/Summary` 调用 `startReprocessingPoll`，需确保函数定义顺序正确

### 低风险
1. **外部函数调用**: `showToast`、`setGlobalError` 等函数通过参数传入，确保传入正确即可

## 回滚方案
如出现问题，可直接：
1. 删除 `useRecordingOperations.js` 文件
2. 恢复 `main.js` 的原始代码（从 git 历史恢复）
3. 重新加载页面验证

---

## 测试用例清单

### 功能测试

#### 1. 重处理功能测试
- [ ] **测试 1.1**: 点击"重新处理转写"按钮，确认模态框弹出
- [ ] **测试 1.2**: 在重处理模态框中选择语言和说话人数量，点击确认
- [ ] **测试 1.3**: 验证进度模态框显示，进度条更新
- [ ] **测试 1.4**: 等待处理完成，验证录音状态变为"已完成"
- [ ] **测试 1.5**: 点击"重新处理总结"按钮，验证总结重新生成
- [ ] **测试 1.6**: 取消重处理操作，验证模态框关闭，无请求发送

#### 2. 转写编辑功能测试
- [ ] **测试 2.1**: 打开录音详情，点击"编辑转写"
- [ ] **测试 2.2**: 对于文本格式转写，验证文本编辑器弹出
- [ ] **测试 2.3**: 修改文本内容，点击保存，验证转写内容更新
- [ ] **测试 2.4**: 对于 JSON 格式转写，验证 ASR 编辑器弹出
- [ ] **测试 2.5**: 在 ASR 编辑器中修改说话人、时间和内容
- [ ] **测试 2.6**: 点击段落的时间调整按钮（+/- 0.5秒），验证时间更新
- [ ] **测试 2.7**: 在说话人输入框中输入，验证下拉建议出现
- [ ] **测试 2.8**: 选择建议中的说话人，验证赋值正确
- [ ] **测试 2.9**: 添加新段落，验证段落添加到末尾
- [ ] **测试 2.10**: 删除段落，验证段落被移除
- [ ] **测试 2.11**: 保存 ASR 转写，验证数据正确提交
- [ ] **测试 2.12**: 关闭编辑器不保存，验证数据未变更

#### 3. 说话人管理功能测试
- [ ] **测试 3.1**: 点击"管理说话人"按钮，验证说话人模态框弹出
- [ ] **测试 3.2**: 验证模态框中显示的说话人与转写中的一致
- [ ] **测试 3.3**: 在输入框中输入说话人名称，验证输入正常
- [ ] **测试 3.4**: 点击"自动识别"按钮，验证自动识别功能调用
- [ ] **测试 3.5**: 如果成功，验证说话人名称被自动填充
- [ ] **测试 3.6**: 聚焦某个说话人输入框，验证转写中该说话人的段落高亮
- [ ] **测试 3.7**: 点击上下导航箭头，验证高亮区域跳转
- [ ] **测试 3.8**: 勾选"重新生成总结"，验证选项被记录
- [ ] **测试 3.9**: 点击保存，验证说话人映射正确提交
- [ ] **测试 3.10**: 如果勾选了重新生成总结，验证总结开始重新生成
- [ ] **测试 3.11**: 关闭模态框，验证状态正确清理

#### 4. 状态管理功能测试
- [ ] **测试 4.1**: 点击"生成总结"按钮（针对没有总结的录音）
- [ ] **测试 4.2**: 验证状态变为"总结中"，轮询开始
- [ ] **测试 4.3**: 等待总结生成完成，验证总结内容显示
- [ ] **测试 4.4**: 点击"重置状态"按钮，验证确认模态框弹出
- [ ] **测试 4.5**: 确认重置，验证录音状态重置为待处理
- [ ] **测试 4.6**: 取消重置，验证状态未变更

#### 5. 标记功能测试
- [ ] **测试 5.1**: 在录音列表中点击星标图标，验证录音被标记为高亮
- [ ] **测试 5.2**: 再次点击星标，验证高亮被取消
- [ ] **测试 5.3**: 在录音列表中点击信封图标，验证录音被移入收件箱
- [ ] **测试 5.4**: 再次点击信封，验证录音被标记为已读
- [ ] **测试 5.5**: 在录音详情页使用相同的按钮，验证功能一致

#### 6. 轮询监控功能测试
- [ ] **测试 6.1**: 开始转写重处理，验证轮询请求每 3 秒发送一次
- [ ] **测试 6.2**: 在轮询过程中，验证录音状态和进度显示更新
- [ ] **测试 6.3**: 当处理完成时，验证轮询自动停止
- [ ] **测试 6.4**: 当处理失败时，验证错误信息显示，轮询停止
- [ ] **测试 6.5**: 切换页面或录音，验证轮询正确清理，无内存泄漏

### 回归测试

#### 7. 现有功能回归
- [ ] **测试 7.1**: 验证录音列表正常加载和显示
- [ ] **测试 7.2**: 验证录音详情正常打开和显示
- [ ] **测试 7.3**: 验证搜索和过滤功能正常
- [ ] **测试 7.4**: 验证分页功能正常
- [ ] **测试 7.5**: 验证上传功能正常
- [ ] **测试 7.6**: 验证深色模式切换正常

### 边缘情况测试

#### 8. 异常处理测试
- [ ] **测试 8.1**: 网络断开时发起重处理，验证错误提示显示
- [ ] **测试 8.2**: 服务器返回错误时，验证错误信息正确显示
- [ ] **测试 8.3**: 快速多次点击重处理按钮，验证不会发起多个请求
- [ ] **测试 8.4**: 在转写编辑中输入无效 JSON，验证错误提示
- [ ] **测试 8.5**: 说话人模态框打开时切换录音，验证状态正确重置

### 浏览器兼容性测试
- [ ] **测试 9.1**: Chrome 浏览器验证
- [ ] **测试 9.2**: Firefox 浏览器验证
- [ ] **测试 9.3**: Edge 浏览器验证

### 移动端测试（如适用）
- [ ] **测试 10.1**: 移动端说话人模态框显示正常
- [ ] **测试 10.2**: 移动端转写编辑器可用

---

## 验证清单

完成所有测试后，检查以下事项：

- [ ] 所有功能测试用例通过
- [ ] 浏览器控制台无错误输出
- [ ] 内存占用稳定（使用 Chrome DevTools Performance 监控）
- [ ] 网络请求正常，无 404/500 错误
- [ ] 用户界面响应迅速，无明显卡顿
- [ ] 代码审查通过，符合项目编码规范

---

## 备注

- 本次重构保持所有原有功能不变，仅调整代码组织结构
- 所有 API 调用路径和参数保持不变
- 所有 UI 交互和反馈保持不变
- 如有新功能需求，建议在拆分完成后添加
