diff --git a/docs/recording-library-diarization-development-plan.md b/docs/recording-library-diarization-development-plan.md
new file mode 100644
index 0000000..dd4f6db
--- /dev/null
+++ b/docs/recording-library-diarization-development-plan.md
@@ -0,0 +1,1460 @@
+# 录音资料库、说话人分离与反馈素材编排开发计划
+
+- 状态：待评审
+- 编制日期：2026-07-23
+- 适用仓库：`teaching-feedback-assistant`
+- 目标部署：Ryzen 7 5700U、CPU FunASR、远程 PostgreSQL、Docker Compose
+- 计划性质：产品、交互、数据、API、转录、迁移、测试和发布的统一实施基线
+
+## 1. 执行摘要
+
+本次改造不应继续把录音能力作为“反馈生成”页面中的一个折叠区域扩展。目标能力已经包含录音和文件上传、长期管理、音频播放、异步转录、说话人分离、角色映射、逐段选择、跨录音选择、AI 总结、总结预览和写入反馈输入框，实际边界是一个独立的“录音资料库”子系统。
+
+最终产品职责划分如下：
+
+```text
+现场录音 / 上传音频
+          |
+          v
+      录音资料库
+          |
+          v
+  转录 + 说话人分离
+          |
+          v
+  对话校对、角色映射、片段选择
+       /                     \
+      v                       v
+直接加入反馈输入框       多录音或片段交给 AI
+                                  |
+                                  v
+                             总结预览
+                                  |
+                                  v
+                             写入反馈输入框
+```
+
+本计划采用以下总体策略：
+
+1. 录音从 `feedback_session` 的附属数据升级为用户拥有的独立资产。
+2. 反馈页面只负责编辑反馈、选择素材、预览总结和保存结果。
+3. 录音列表、录音详情和反馈素材选择使用独立页面，不以大弹窗承载主流程。
+4. 说话人分离只产生匿名说话人簇，教师、学生、家长等业务角色由用户确认。
+5. AI 总结使用选中对话的不可变快照，避免转录重跑或角色修改改变历史结果。
+6. 数据库按 expand、backfill、switch、contract 渐进迁移，旧链路在切换完成前始终可回退。
+7. FunASR 说话人能力先通过 5700U CPU 技术预研门槛，再决定 CAM++ 或 ERes2NetV2，不直接在生产中试错。
+8. 音频默认保留到用户主动删除；自动保留期限作为后续可配置能力，不在首版擅自清理历史录音。
+
+## 2. 当前状态与约束
+
+### 2.1 当前业务链路
+
+当前链路为：
+
+```text
+反馈草稿
+  -> 创建 feedback_session
+  -> 创建 lesson_session
+  -> 小程序每 8 分钟录制一个音频片段
+  -> 上传 audio_segment
+  -> Rust worker 调用 FunASR
+  -> audio_segment 写入纯文本 transcript
+  -> 用户按 lesson_session 整节选择
+  -> summary worker 生成总结
+  -> 用户确认后替换反馈输入框
+  -> 保存反馈并将 feedback_session 标记 finalized
+```
+
+现有能力中可以复用的部分：
+
+- 微信小程序录音权限、8 分钟自动切片和失败上传本地保留。
+- Rust API 的用户认证、owner 隔离和请求 ID。
+- 音频持久化目录和 Docker 命名卷。
+- PostgreSQL 异步转录队列、租约、重试和失败状态。
+- FunASR Paraformer、FSMN-VAD 和标点模型服务。
+- 总结任务的幂等键、后台 worker、轮询、预览和应用流程。
+- Grafana、Loki 和结构化日志规范。
+
+### 2.2 当前结构性限制
+
+1. `lesson_sessions.feedback_session_id` 非空，录音不能脱离反馈草稿独立存在。
+2. 录音查询、重试和删除接口只允许访问 `active` 反馈批次。
+3. 保存反馈后批次变为 `finalized`，当前小程序没有独立入口重新管理其录音。
+4. `audio_segments.transcript` 只有纯文本，没有开始时间、结束时间、说话人或置信信息。
+5. 当前总结来源表只关联整节 `lesson_session`，不支持逐段选择。
+6. Rust API 成功转录后保留原始音频，但没有认证播放接口和统一保留策略。
+7. 数据库级联删除和重复序号上传可能留下磁盘孤儿文件。
+8. 当前本地 ASR 响应只有 `text`、`duration_ms` 和 `request_id`。
+9. 腾讯备用实现明确关闭 `speaker_diarization`，不能承担当前目标。
+10. `recording_routes.rs` 已承载过多职责，继续叠加录音库接口会提高回归风险。
+
+### 2.3 固定部署约束
+
+- API 和 FunASR 使用 `compose.deploy.yml` 部署。
+- FunASR 不暴露宿主机端口，只允许 API 通过 Compose 网络访问。
+- PostgreSQL 使用现有远程数据库，不新增数据库容器。
+- 首发继续使用 CPU 推理，不假设 CUDA、ROCm 或独立 GPU。
+- 默认单 FunASR 进程和单转录 worker，模型对象不在多线程中并发调用。
+- 模型缓存和音频必须继续使用持久化卷。
+- 不得把音频、模型、数据库凭据、微信密钥或 `.env` 提交到 Git。
+- 日志不得包含转录正文、总结正文、学生姓名、原始文件名或真实磁盘路径。
+
+### 2.4 已知但尚未获得的生产基线
+
+编码前应从部署服务器补齐以下数据；缺少数据不阻止建表和接口开发，但阻止容量结论和自动清理上线：
+
+- PostgreSQL 版本、现有表行数、数据库总大小和每日增长量。
+- `teaching-feedback-audio` 卷当前文件数、容量和每日增长量。
+- 录音平均时长、P95 时长、平均文件大小和最大文件大小。
+- 单日录音数量、并发教师数量和转录队列 P95 等待时间。
+- 5700U 上当前模型的 P50/P95 RTF、峰值内存和失败率。
+- 用户期望的录音保留期限和可接受的删除恢复窗口。
+
+## 3. 产品目标与非目标
+
+### 3.1 首个完整版本目标
+
+用户能够：
+
+1. 在录音资料库中查看现场录音和上传录音。
+2. 按学生、日期、来源和处理状态筛选录音。
+3. 查看录音时长、文件状态、转录状态、说话人数和失败原因。
+4. 播放本人录音，并从对话时间点跳转播放。
+5. 上传支持格式的音频文件并在后台完成转录。
+6. 查看按时间排序、按说话人分组标识的对话文本。
+7. 将匿名说话人映射为教师、学生、家长或自定义显示名。
+8. 选择整份录音、某位说话人的全部对话或若干对话片段。
+9. 将选择内容直接追加到反馈输入框，受 2000 字限制保护。
+10. 选择一份或多份录音的部分或全部对话生成 AI 总结。
+11. 预览总结，确认后替换反馈输入框。
+12. 重试失败转录、重新转录、修改录音标题和删除录音。
+13. 在退出页面、应用切后台或请求重试后恢复可恢复的任务状态。
+
+### 3.2 首版明确不做
+
+- 不做实时字幕和实时说话人分离。
+- 不自动断言“Speaker 0 就是教师”。
+- 不做人脸、声纹实名识别或跨用户声纹库。
+- 不在不同录音之间自动确认同一个自然人。
+- 不做多人协作编辑、公开分享或外链下载。
+- 不做音频裁剪、拼接、降噪参数编辑等专业音频编辑器。
+- 不做波形级标注工作台；首版使用时间轴和播放进度定位。
+- 不删除现有 `lesson_sessions`、`audio_segments` 或旧总结来源表。
+- 不在没有代表性样本验证的情况下升级 FunASR 或切换识别模型。
+- 不在首版启用自动到期删除，除非用户另行确认保留规则。
+
+### 3.3 后续可选能力
+
+- 用户手工修订转录文本并保留修订历史。
+- 针对固定教师的声纹登记和跨录音角色建议。
+- 自动提取课堂主题、作业、错误点和后续建议。
+- 录音标签、收藏、批量归档和导出。
+- 对象存储替代本地卷，以及分层存储和归档。
+- Web 管理端或桌面端长文本校对工作台。
+
+## 4. 信息架构与页面计划
+
+### 4.1 页面边界
+
+计划新增以下页面：
+
+| 页面 | 路径建议 | 职责 |
+|---|---|---|
+| 录音资料列表 | `pages/recordings/index` | 管理、筛选、批量选择、录音和上传入口 |
+| 录音详情 | `pages/recordings/detail` | 播放、说话人映射、对话浏览、选择、重试和删除 |
+| 反馈素材选择 | `pages/recordings/select` | 从反馈页进入，选择录音或对话片段并返回反馈草稿 |
+
+弹窗只用于：
+
+- 删除录音确认。
+- 重新转录确认。
+- 总结覆盖输入框确认。
+- 简短标题修改。
+- 说话人显示名的单字段输入。
+
+不得使用弹窗承载完整录音列表、长对话浏览或批量选择。
+
+### 4.2 底部导航决策
+
+产品目标上，“录音资料”是一级能力。实现前进行一次 5 项底部导航真机评审：
+
+```text
+反馈生成 | 录音资料 | 学生档案 | 反馈记录 | 我的
+```
+
+通过条件：
+
+- 320px 宽度真机上文字和图标不截断。
+- 各入口点击区域满足现有小程序交互尺寸。
+- 当前 tab 状态不会因从选择页返回而错乱。
+
+若 5 项导航不通过，首版不强行增加 tab，改为在反馈页和“我的”页面提供录音资料入口；页面和后端边界保持不变，后续再调整导航。
+
+### 4.3 录音资料列表页
+
+页面结构：
+
+```text
+标题与状态统计
+筛选栏：学生 / 日期 / 来源 / 状态
+录音列表
+  - 标题和日期
+  - 学生或未关联
+  - 现场录音或上传文件
+  - 时长、说话人数、字数
+  - 转录状态和失败操作
+底部主操作：录音或上传
+```
+
+交互要求：
+
+- 内容列表是主区域，工具栏保持紧凑，不使用大面积装饰卡片。
+- 使用稳定高度的列表行，状态文字变化不能引起明显布局跳动。
+- 支持下拉刷新和游标分页，不一次加载全部历史录音。
+- 处理中项目按更新时间刷新；就绪项目不进入高频轮询。
+- 批量模式下显示已选数量和一个明确的主操作。
+- 失败项目提供“重试”和“删除”，不使用含糊的通用“处理”按钮。
+- 删除入口必须显示是否会影响已生成反馈；历史总结只保留快照，不依赖原录音继续存在。
+
+### 4.4 录音详情工作页
+
+页面结构：
+
+```text
+顶部导航：返回 / 标题 / 更多
+紧凑播放器：播放、暂停、进度、当前时间、总时长
+说话人映射栏：Speaker 0 -> 教师，Speaker 1 -> 学生
+对话工具栏：全选、按说话人筛选、仅看已选
+对话主区域：
+  [复选框] [00:12-00:18] [教师] 对话文本
+  [复选框] [00:19-00:27] [学生] 对话文本
+固定底栏：已选 N 段 / 加入反馈或生成总结
+```
+
+交互要求：
+
+- 对话内容占据主要视觉面积，播放器和筛选工具保持安静、紧凑。
+- 点击时间范围后从对应位置播放。
+- 播放进度变化只更新当前行状态，不重新渲染完整对话列表。
+- 选择状态由 `turn_id` 管理，不能依赖数组位置。
+- 支持按说话人全选和取消，结果仍展开为具体 `turn_id` 提交。
+- 角色映射修改不改写历史总结快照。
+- 转录失败时不渲染空工作台，直接显示失败原因、重试和删除。
+- 说话人数量异常时允许保留“未知”角色，不强制映射为教师或学生。
+
+### 4.5 反馈素材选择页
+
+从反馈页打开，必须携带目标 `feedback_session_id`。该页复用录音列表和对话选择组件，但使用独立路由，以避免 tab 页面承担临时返回状态。
+
+支持两种选择方式：
+
+1. 整份录音：服务端解析为该录音当前就绪转录版本的全部对话。
+2. 部分对话：提交明确的 `turn_id` 集合。
+
+返回反馈页前显示：
+
+- 录音数量。
+- 对话片段数量。
+- 字符数估算。
+- 选择范围中是否包含“未知说话人”。
+
+选择草稿以 `feedback_session_id` 为键暂存在小程序本地存储，页面返回或小程序短时退出后可恢复；提交总结时服务端重新校验所有权、状态和转录版本。
+
+### 4.6 反馈生成页调整
+
+现有展开式“语音记录”区域改为紧凑的素材区：
+
+- `开始录音`。
+- `从录音资料选择`。
+- `已选 2 个录音 / 18 段 / 1260 字`。
+- `查看选择`。
+- `生成总结`。
+- 总结状态和预览。
+
+现有按整节加入和总结能力在兼容期保留；新能力开关启用后，页面优先走录音资料选择链路。确认稳定后再删除旧前端入口，后端旧接口继续保留一个发布周期。
+
+### 4.7 页面状态矩阵
+
+| 状态 | 列表页 | 详情页 | 可用操作 |
+|---|---|---|---|
+| 上传中 | 进度或等待 | 不进入对话区 | 取消 |
+| 排队中 | 排队状态 | 音频可播放 | 删除 |
+| 转录中 | 处理中 | 音频可播放 | 删除 |
+| 待确认 | 显示说话人数 | 对话可查看和映射 | 映射、选择、完成确认 |
+| 已就绪 | 正常状态 | 全部能力 | 选择、总结、重转录、删除 |
+| 失败 | 错误分类 | 错误详情 | 重试、删除 |
+| 删除中 | 从正常列表隐藏 | 禁止进入 | 后台重试清理 |
+
+## 5. 目标领域模型
+
+### 5.1 设计原则
+
+- 录音资产由用户拥有，反馈会话只引用素材，不拥有素材。
+- 原始音频、转录运行、说话人和对话片段职责分离。
+- 每次重新转录创建新版本，不原地覆盖已用于总结的版本。
+- 总结来源在任务创建时展开并快照，worker 不读取会变化的最新文本。
+- 用户删除录音后，历史总结仍可解释其来源数量和快照，但不能再播放音频。
+- 所有查询都显式包含 `owner_id` 边界，不依赖前端传入的用户标识。
+- 删除必须同时覆盖数据库引用和物理文件，不再依赖数据库级联完成文件清理。
+
+### 5.2 关系图
+
+```text
+users
+  |
+  +-- recordings
+        |
+        +-- recording_audio_parts
+        |
+        +-- transcription_runs
+               |
+               +-- recording_speakers
+               |
+               +-- transcript_turns
+
+feedback_sessions
+  |
+  +-- feedback_summary_runs
+         |
+         +-- feedback_summary_run_sources
+                -> nullable transcript_turn reference
+                -> immutable text/speaker/time snapshot
+```
+
+### 5.3 `recordings`
+
+职责：一份逻辑录音资产，不等同于某个 8 分钟物理片段。
+
+建议字段：
+
+| 字段 | 约束与用途 |
+|---|---|
+| `id UUID` | 主键 |
+| `owner_id UUID` | 非空，引用 `users ON DELETE RESTRICT`；账号删除前必须完成受控录音清理 |
+| `profile_id UUID` | 可空，引用学生档案；学生删除时建议 `SET NULL`，不连带删除录音 |
+| `title VARCHAR(120)` | 非空，服务端生成默认标题，允许用户修改 |
+| `source VARCHAR(16)` | `live`、`upload`、`legacy` |
+| `recorded_at TIMESTAMPTZ` | 课堂或文件代表的录制时间 |
+| `ingest_status VARCHAR(16)` | `uploading`、`complete`、`failed` |
+| `duration_ms BIGINT` | 非负，所有 part 汇总 |
+| `byte_size BIGINT` | 非负，所有 part 汇总 |
+| `audio_format VARCHAR(8)` | 逻辑主格式，混合 part 时使用规范化输出格式 |
+| `current_transcription_run_id UUID` | 可空，指向当前展示版本，扩展迁移后补 FK |
+| `legacy_lesson_id UUID` | 可空且唯一，仅用于迁移追踪，后续可保留 |
+| `delete_requested_at TIMESTAMPTZ` | 可空，存在时从正常列表隐藏 |
+| `created_at/updated_at` | 非空 |
+
+关键约束与索引：
+
+- `CHECK (char_length(title) BETWEEN 1 AND 120)`。
+- `CHECK (source IN ('live', 'upload', 'legacy'))`。
+- `CHECK (ingest_status IN ('uploading', 'complete', 'failed'))`。
+- `CHECK (duration_ms >= 0 AND byte_size >= 0)`。
+- 列表索引：`(owner_id, created_at DESC, id DESC) WHERE delete_requested_at IS NULL`。
+- 学生筛选索引：`(owner_id, profile_id, created_at DESC, id DESC) WHERE delete_requested_at IS NULL`。
+- `legacy_lesson_id` 唯一索引仅覆盖非空值。
+- `current_transcription_run_id` 不能只使用单列 FK；应以
+  `(id, current_transcription_run_id)` 复合引用
+  `transcription_runs(recording_id, id)`，保证当前 run 一定属于当前 recording。
+
+### 5.4 `recording_audio_parts`
+
+职责：保存现场录音切片或上传文件经过规范化后的物理音频单元。
+
+建议字段：
+
+| 字段 | 约束与用途 |
+|---|---|
+| `id UUID` | 主键 |
+| `recording_id UUID` | 非空，引用 `recordings ON DELETE RESTRICT` |
+| `sequence INTEGER` | 从 1 开始，录音内唯一 |
+| `duration_ms INTEGER` | 大于 0 |
+| `byte_size BIGINT` | 大于 0 |
+| `audio_format VARCHAR(8)` | `mp3`、`aac`、`wav`、`m4a`、`amr` |
+| `storage_key TEXT` | 非空，只存内部相对键，不向客户端返回 |
+| `sha256 CHAR(64)` | 非空，用于上传幂等和文件核验 |
+| `created_at` | 非空 |
+
+关键约束与索引：
+
+- `UNIQUE (recording_id, sequence)`。
+- `UNIQUE (storage_key)`。
+- `CHECK (sequence > 0 AND duration_ms > 0 AND byte_size > 0)`。
+- 为 `recording_id` 建普通索引，支持删除和顺序读取。
+
+### 5.5 `transcription_runs`
+
+职责：一次可审计、可重试、不可原地覆盖的转录版本。
+
+建议字段：
+
+| 字段 | 约束与用途 |
+|---|---|
+| `id UUID` | 主键 |
+| `recording_id UUID` | 非空，引用 `recordings` |
+| `revision INTEGER` | 从 1 开始，录音内唯一 |
+| `status VARCHAR(16)` | `queued`、`processing`、`ready`、`failed`、`superseded` |
+| `provider VARCHAR(32)` | 例如 `local-funasr` |
+| `asr_model TEXT` | 实际模型标识 |
+| `speaker_model TEXT` | 可空，实际说话人模型标识 |
+| `config_version VARCHAR(32)` | 转录配置版本 |
+| `source_hash CHAR(64)` | 输入 part 顺序、hash 和配置的摘要 |
+| `attempts INTEGER` | 非负 |
+| `processing_started_at` | 租约和恢复 |
+| `completed_at` | 就绪或失败完成时间 |
+| `error_class VARCHAR(64)` | 稳定错误分类 |
+| `error_message TEXT` | 面向用户的脱敏错误信息 |
+| `created_at/updated_at` | 非空 |
+
+关键约束与索引：
+
+- `UNIQUE (recording_id, revision)`。
+- `UNIQUE (recording_id, id)`，供 recording 当前 run 的复合 FK 使用。
+- `UNIQUE (recording_id, source_hash)`，相同输入和配置重复请求返回既有 run。
+- 队列部分索引：`(created_at, id) WHERE status IN ('queued', 'processing')`。
+- 状态结果约束保证 `ready` 时 `completed_at` 非空，`failed` 时 `error_class` 非空。
+
+### 5.6 `recording_speakers`
+
+职责：保存某次转录运行产生的匿名说话人簇及用户业务映射。
+
+建议字段：
+
+| 字段 | 约束与用途 |
+|---|---|
+| `id UUID` | 主键 |
+| `transcription_run_id UUID` | 非空，引用 `transcription_runs` |
+| `provider_label VARCHAR(32)` | 例如 `SPK0`，run 内唯一 |
+| `role VARCHAR(16)` | `teacher`、`student`、`guardian`、`unknown`、`other` |
+| `display_name VARCHAR(60)` | 可空，例如“学生甲” |
+| `created_at/updated_at` | 非空 |
+
+约束：
+
+- `UNIQUE (transcription_run_id, provider_label)`。
+- `UNIQUE (transcription_run_id, id)`，供 turn 的复合 FK 使用。
+- 映射只改变业务显示，不修改模型原始 `provider_label`。
+- 首次生成时全部为 `unknown`，不得自动写入 `teacher`。
+
+### 5.7 `transcript_turns`
+
+职责：一条连续说话人对话，是播放定位和选择的最小单位。
+
+建议字段：
+
+| 字段 | 约束与用途 |
+|---|---|
+| `id UUID` | 主键 |
+| `transcription_run_id UUID` | 非空，引用 `transcription_runs` |
+| `speaker_id UUID` | 非空，引用 `recording_speakers` |
+| `sequence INTEGER` | 从 1 开始，run 内唯一 |
+| `start_ms BIGINT` | 非负 |
+| `end_ms BIGINT` | 大于 `start_ms` |
+| `text TEXT` | 非空且去除首尾空白后有内容 |
+| `created_at` | 非空 |
+
+约束与索引：
+
+- `UNIQUE (transcription_run_id, sequence)`。
+- `(transcription_run_id, speaker_id)` 复合引用
+  `recording_speakers(transcription_run_id, id)`，禁止 turn 引用其他 run 的 speaker。
+- `CHECK (start_ms >= 0 AND end_ms > start_ms)`。
+- `CHECK (char_length(btrim(text)) > 0)`。
+- `(transcription_run_id, start_ms, id)` 支持时间排序。
+- `(speaker_id, start_ms, id)` 支持按说话人筛选。
+
+首版不允许直接编辑 `text`。若后续增加校对，新增修订表或明确的 `edited_text` 和审计字段，不在本次建表中预留含糊字段。
+
+### 5.8 `feedback_summary_run_sources`
+
+职责：冻结 AI 实际接收的来源，保证重跑、删除和转录升级后仍可审计。
+
+建议字段：
+
+| 字段 | 约束与用途 |
+|---|---|
+| `summary_run_id UUID` | 引用 `feedback_summary_runs` |
+| `source_order INTEGER` | 从 1 开始，run 内唯一 |
+| `recording_id UUID` | 可空，删除录音后 `SET NULL` |
+| `transcript_turn_id UUID` | 可空，删除转录后 `SET NULL` |
+| `recording_title_snapshot TEXT` | 非空 |
+| `speaker_label_snapshot TEXT` | 非空 |
+| `start_ms_snapshot BIGINT` | 非负 |
+| `end_ms_snapshot BIGINT` | 大于开始时间 |
+| `text_snapshot TEXT` | 非空，是 worker 唯一读取的正文 |
+| `created_at` | 非空 |
+
+主键建议为 `(summary_run_id, source_order)`。创建总结任务时在同一事务中：
+
+1. 校验所有录音属于当前 owner。
+2. 校验所有 turn 属于对应录音的当前就绪 run。
+3. 将整份录音选择展开为 turn。
+4. 按录音时间和 turn 时间排序。
+5. 写入快照。
+6. 计算 source hash。
+7. 创建或复用幂等总结任务。
+
+worker 只读取 `text_snapshot`，不得再次 join 最新 `transcript_turns.text`。
+
+## 6. 录音和转录状态机
+
+### 6.1 录音采集状态
+
+```text
+uploading
+  | complete upload/finalize
+  v
+complete
+
+uploading --validation/storage error--> failed
+failed --retry upload--> uploading
+```
+
+规则：
+
+- `complete` 后 part 集合默认不可变；补传必须在 finalize 前完成。
+- finalize 是幂等操作，重复调用返回同一结果。
+- live 录音停止后只有全部 part 成功上传才允许 finalize。
+- 上传文件校验失败不得创建可见的半成品录音；失败记录只用于恢复时才保留。
+
+### 6.2 转录运行状态
+
+```text
+queued -> processing -> ready
+   |          |
+   |          +-> failed
+   +------------> failed
+
+ready --create new revision--> new queued run
+old ready --new run promoted--> superseded
+```
+
+规则：
+
+- worker 使用 `FOR UPDATE SKIP LOCKED` 和租约领取任务。
+- 进程异常后超过租约的 `processing` 可重新领取。
+- 只有完整写入 speakers 和 turns 后才能把 run 标为 `ready` 并切换 `current_transcription_run_id`。
+- speakers、turns、run ready 和 current pointer 在一个数据库事务中提交。
+- 新 run 失败时旧 ready run 仍保持当前展示版本。
+- 重试同一个 failed run 可增加 attempts；用户主动“重新转录”创建新 revision。
+
+### 6.3 删除状态
+
+删除采用“先隐藏、后物理清理”：
+
+1. DELETE 接口校验 owner 并写入 `delete_requested_at`。
+2. 列表和详情立即隐藏该录音。
+3. cleanup worker 删除所有物理文件。
+4. 删除 speakers、turns、runs、parts 和 recording 行。
+5. summary source 的快照保留，外键设空。
+6. 文件删除失败时保留待清理记录并指数退避重试。
+
+不得先删数据库行再尝试删除文件，否则会再次制造不可追踪孤儿文件。
+
+## 7. 音频存储与播放
+
+### 7.1 存储键
+
+新文件使用：
+
+```text
+/data/audio/{owner_uuid}/{recording_uuid}/{part_uuid}.{format}
+```
+
+要求：
+
+- 路径不包含学生姓名、上传原始文件名或业务标题。
+- 数据库只保存相对 `storage_key`；运行时在受控根目录下解析。
+- 写入临时文件后执行原子 rename，数据库只引用完成文件。
+- 校验解析后路径仍位于 `AUDIO_STORAGE_DIR`，防止目录穿越。
+- 上传原始文件名只在确有 UI 需求时保存为脱敏元数据，默认不保存。
+
+### 7.2 上传与格式规范化
+
+现有 15 MB 内存读取方式不适合长文件上传。新接口必须流式写磁盘：
+
+- 请求体按块写临时文件，不能一次读入 `Vec<u8>`。
+- 同步计算 SHA-256 和字节数。
+- 使用文件头和解码结果验证格式，不能只信扩展名和 MIME。
+- 通过 ffmpeg/ffprobe 获取真实时长、采样率和声道数。
+- 超限立即停止写入并清理临时文件。
+- 首版支持 `mp3`、`aac`、`wav`、`m4a` 和 `amr`，以实际 ffmpeg 镜像能力为准。
+
+初始限制建议：
+
+- 单文件最大 200 MiB。
+- 单份录音最大 4 小时。
+- 单用户同时上传 1 个文件。
+- 限制值通过环境变量配置，并在 5700U 压测后确认。
+
+如果微信小程序文件选择或上传通道的真机限制低于服务端限制，前端显示实际可选范围；不得用健康检查代替真机上传验证。
+
+### 7.3 认证播放
+
+新增 `GET /api/v1/recordings/{recording_id}/audio`：
+
+- 必须认证并校验 owner。
+- 支持 HTTP Range、`206 Partial Content`、`Content-Range` 和正确 MIME。
+- 不返回磁盘路径和永久公开 URL。
+- 不在日志中记录 Range 内容、标题、文件名或路径。
+- 对已请求删除或文件校验失败的录音返回稳定错误。
+- 播放请求不触发转录或改变录音状态。
+
+### 7.4 保留、容量和孤儿治理
+
+首版默认保留到用户主动删除。上线前完成：
+
+- 音频卷每日容量统计。
+- 每用户录音数、总时长和总字节统计。
+- 数据库 part 与磁盘文件双向巡检。
+- 孤儿文件仅报告，不在首轮自动删除。
+- 确认备份是否同时覆盖 PostgreSQL 和音频卷，以及二者恢复时间点如何对应。
+
+自动保留策略后续通过配置和用户确认实现，不能仅靠 cron 删除文件。
+
+## 8. FunASR 说话人分离技术计划
+
+### 8.1 官方能力与本项目风险
+
+FunASR 官方仓库当前说明 Paraformer 可组合 `spk_model`，模型列表包含 CAM++；官方教程还给出了 ERes2NetV2 说话人模型和带 speaker 的 ASR 示例。官方当前接口可返回句子级时间和说话人信息。
+
+本项目不能直接据此上线，原因是：
+
+- 仓库固定 `funasr==1.3.14`，官方 `main` 文档可能对应更高版本。
+- 当前服务只读取结果中的 `text`，没有验证 `sentence_info` 契约。
+- 当前 8 分钟片段分别转录，匿名 speaker 编号可能跨片段互换。
+- 教室噪声、重叠说话、远场麦克风和多学生会显著影响 diarization。
+- 增加 speaker 模型会改变 CPU、内存、模型缓存和推理耗时。
+
+### 8.2 技术预研候选
+
+候选 A：当前 Paraformer + FSMN-VAD + CT-PUNC + CAM++。
+
+- 优点：官方快速示例直接支持，CAM++ 参数量较小，适合作为 CPU 首选候选。
+- 风险：短句、重叠语音和跨片段聚类质量必须实测。
+
+候选 B：当前 Paraformer + FSMN-VAD + CT-PUNC + ERes2NetV2。
+
+- 优点：官方教程将其作为改进的短时说话人特征候选。
+- 风险：CPU 成本、FunASR 固定版本兼容性和模型缓存增加必须实测。
+
+候选 C：独立 diarization pipeline。
+
+- 只有 A、B 未达到质量门槛时评估。
+- 不在首轮同时引入第二套大型框架，避免镜像、许可和运维复杂度失控。
+
+### 8.3 预研实施步骤
+
+1. 建立不提交真实敏感音频的本地测试清单和标注格式。
+2. 在独立分支为 `asr-service` 增加实验开关，不修改生产默认值。
+3. 先测试固定 `funasr==1.3.14` 是否支持所需 `spk_model` 和输出字段。
+4. 若固定版本不支持，再验证最小兼容升级，并记录依赖 diff 和模型版本。
+5. 对相同音频分别运行无 speaker、CAM++、ERes2NetV2。
+6. 保存脱敏指标，不保存或提交真实转录正文。
+7. 在 5700U 单进程 CPU 环境测量 RTF、峰值内存、缓存大小和稳定性。
+8. 选择通过门槛的候选；均不通过时停止正式开发并重新评估方案。
+
+### 8.4 测试语料矩阵
+
+至少包含经授权的以下场景：
+
+| 场景 | 最低样本 |
+|---|---:|
+| 两人、安静、轮流说话 | 3 |
+| 两人、真实教室噪声 | 3 |
+| 三人及以上 | 2 |
+| 明显重叠说话 | 2 |
+| 跨 8 分钟切片同一说话人 | 2 |
+| 上传的 mp3/m4a/wav | 每种至少 1 |
+| 30 分钟以上长录音 | 2 |
+
+需要人工标注说话人区间和参考文本，才能计算说话人错误率和识别退化。
+
+### 8.5 预研通过门槛
+
+以下门槛为首轮工程门槛，样本不足时不得宣称达标：
+
+- 所有支持格式无崩溃、无内存持续增长、无空结构化结果。
+- 两人安静样本的中位 DER 不高于 15%。
+- 两人真实教室样本的中位 DER 不高于 25%。
+- 跨 8 分钟边界的同人 cluster 一致率不低于 90%。
+- 加入 speaker 模型后，中文转录错误率相对当前基线恶化不超过 5 个百分点。
+- 5700U 上 P95 RTF 不高于 0.5，即 1 小时音频在 30 分钟内处理完成。
+- 单 FunASR 进程峰值内存不超过 12 GiB，且连续 20 次任务后不持续增长。
+- 失败必须返回稳定错误分类，不能导致 API 或 worker 重启循环。
+
+如质量达标但性能未达标，应保持异步处理并评估独立 speaker worker；不得简单提高同一模型实例并发。
+
+### 8.6 跨切片说话人一致性
+
+首选方案是把一份逻辑录音的 part 按顺序规范化并作为一次完整 diarization 输入，使 speaker cluster 在录音级生成。不得把每个 8 分钟 part 的 `SPK0` 直接视为同一人。
+
+若长音频一次处理超出内存或模型限制，再实现：
+
+1. 每个 part 提取 speaker embedding。
+2. 在 recording 级对相邻 part 的 cluster 做相似度匹配。
+3. 设置信心阈值，低信心时生成新的匿名 speaker。
+4. 保存原始 provider label 和合并后的 recording speaker，不覆盖原始输出。
+
+该备选方案必须单独评审，不能在首版临时拼接字符串完成。
+
+### 8.7 ASR 服务响应契约
+
+新响应建议：
+
+```json
+{
+  "text": "完整转录文本",
+  "duration_ms": 480000,
+  "request_id": "uuid",
+  "model": "paraformer-zh",
+  "speaker_model": "cam++",
+  "speakers": [
+    { "key": "SPK0" },
+    { "key": "SPK1" }
+  ],
+  "turns": [
+    {
+      "sequence": 1,
+      "start_ms": 1200,
+      "end_ms": 6800,
+      "speaker_key": "SPK0",
+      "text": "今天先检查上节课的内容。"
+    }
+  ]
+}
+```
+
+契约要求：
+
+- `turns` 按时间排序。
+- 时间统一使用整数毫秒。
+- `speaker_key` 必须能在 `speakers` 中找到。
+- 相邻且同 speaker、间隔很短的句子可按明确规则合并，但必须保持时间有序。
+- 无法分离时返回一个 `SPK0`，而不是伪造多说话人。
+- `text` 是 turns 文本的兼容聚合，不是新的独立事实来源。
+- Rust 必须校验时间范围、顺序、空文本和 speaker 引用，再写数据库。
+
+## 9. API 设计
+
+### 9.1 录音列表
+
+`GET /api/v1/recordings`
+
+查询参数：
+
+- `cursor`：基于 `(created_at, id)` 的不透明游标。
+- `limit`：默认 20，最大 100。
+- `profile_id`：可选。
+- `source`：`live` 或 `upload`。
+- `status`：API 派生状态。
+- `date_from/date_to`：可选。
+
+响应只包含列表需要的字段，不返回 turns 和 storage key。
+
+### 9.2 创建和上传
+
+`POST /api/v1/recordings`
+
+- 创建逻辑录音，参数包含 `source`、可选 `profile_id`、标题和 `recorded_at`。
+- 支持 `Idempotency-Key`，防止页面重试创建重复录音。
+
+`POST /api/v1/recordings/{id}/parts`
+
+- multipart 流式上传。
+- 参数包含 `sequence`、`duration_ms`、`audio_format` 和 `audio`。
+- `(recording_id, sequence)` 唯一；相同 hash 重试返回原 part，不同 hash 冲突返回 409。
+
+`POST /api/v1/recordings/{id}/complete`
+
+- 校验 part 连续、文件存在、时长和大小一致。
+- 原子地把 ingest 标为 complete 并创建首个 transcription run。
+- 重复调用幂等。
+
+上传单文件在客户端表现为一个 recording；服务端可按解码和 ASR 限制生成内部 part，但不把内部切分暴露为多份用户录音。
+
+### 9.3 详情和播放
+
+- `GET /api/v1/recordings/{id}`：录音元数据、当前 run、speakers 和分页/分块 turns。
+- `GET /api/v1/recordings/{id}/turns?cursor=&speaker_id=`：长对话分页。
+- `GET /api/v1/recordings/{id}/audio`：认证 Range 播放。
+- `PATCH /api/v1/recordings/{id}`：修改标题、学生关联和录制日期。
+- `DELETE /api/v1/recordings/{id}`：进入删除队列。
+
+### 9.4 说话人映射和重转录
+
+- `PATCH /api/v1/recordings/{recording_id}/speakers/{speaker_id}`：更新 role 和 display name。
+- `POST /api/v1/recordings/{id}/transcription-runs`：创建新 revision。
+- `POST /api/v1/transcription-runs/{id}/retry`：重试 failed run。
+
+角色更新使用乐观并发字段或 `updated_at` 前置条件，避免两个页面互相覆盖。
+
+### 9.5 直接加入反馈
+
+`POST /api/v1/feedback-sessions/{session_id}/recording-sources/apply`
+
+建议请求：
+
+```json
+{
+  "mode": "append",
+  "selections": [
+    { "recording_id": "uuid", "selection": "all" },
+    {
+      "recording_id": "uuid",
+      "selection": "turns",
+      "turn_ids": ["uuid", "uuid"]
+    }
+  ]
+}
+```
+
+服务端负责：
+
+- 校验 session active、owner、run ready 和 turn 归属。
+- 按时间顺序格式化带角色的文本。
+- 检查合并后不超过 2000 字。
+- 在一个事务中更新反馈草稿和记录来源应用状态。
+- 返回更新后的 `FeedbackSession`。
+
+### 9.6 创建总结任务
+
+扩展现有 summary run 请求，使用同一 `selections` 结构。服务端在创建 run 的事务中展开并写入 `feedback_summary_run_sources`。
+
+兼容策略：
+
+- 新请求写 `feedback_summary_run_sources`。
+- 旧 `lesson_ids` 请求继续写 `feedback_summary_run_lessons`。
+- summary worker 优先读取新 sources；没有新 sources 时走旧 lesson 查询。
+- 新旧请求都保留现有幂等键和 2000 字结果约束。
+
+新总结的来源和模型预算规则：
+
+- 单次最多选择 20 份录音。
+- 单次最多展开 2000 个 turn。
+- source snapshot 总字符数初始上限为 200,000，通过环境变量配置。
+- 超限时返回明确的 `summary_source_too_large`，不能静默截断或丢弃尾部 turn。
+- worker 按录音和时间顺序格式化来源，例如
+  `[00:12-00:18][教师] 对话文本`，匿名角色使用 `Speaker 0` 等稳定标签。
+- 每份录音先按不拆分 turn 的原则组成有限字符块，再生成录音级摘要，最后结合
+  `existing_content` 生成不超过 2000 字的总反馈。
+- `prompt_version` 升级为新的明确版本；旧 run 继续保留原版本。
+- 转录文本按不可信输入处理，使用清晰分隔符包裹，并在系统提示中明确禁止执行转录内容中的指令。
+- 记录 source turn 数、source 字符数、模型请求次数和输出字符数，但不记录正文。
+
+### 9.7 错误语义
+
+至少定义稳定错误分类：
+
+- `recording_not_ready`
+- `recording_upload_incomplete`
+- `recording_audio_missing`
+- `recording_format_unsupported`
+- `recording_too_large`
+- `recording_duration_exceeded`
+- `transcription_unavailable`
+- `transcription_failed`
+- `diarization_failed`
+- `speaker_mapping_conflict`
+- `transcript_version_changed`
+- `summary_source_unavailable`
+- `audio_storage_delete_failed`
+
+HTTP 状态和用户提示在 API 文档中逐项映射，前端不能依赖错误字符串包含关系判断业务状态。
+
+## 10. 后端模块拆分
+
+避免继续扩大单个 `recording_routes.rs`，建议按职责拆分：
+
+```text
+server/src/recordings/
+  mod.rs
+  routes.rs            # 列表、详情、元数据、删除
+  upload.rs            # 流式上传、格式校验、finalize
+  playback.rs          # owner 校验和 Range 响应
+  selection.rs         # 选择展开、格式化和快照
+
+server/src/transcription_worker.rs
+server/src/recording_cleanup_worker.rs
+server/src/summary_worker.rs
+server/src/speech.rs
+```
+
+拆分原则：
+
+- 不为每条 SQL 创建无意义 repository trait。
+- 跨路由复用的 owner 校验、选择展开和存储键解析提取为明确函数。
+- 网络调用不放在数据库事务中。
+- 上传文件写入和数据库提交之间保留可恢复状态。
+- worker 状态转换使用条件 UPDATE，防止重复 worker 覆盖完成结果。
+
+### 10.1 预计文件变更矩阵
+
+| 文件或目录 | 计划变更 |
+|---|---|
+| `server/migrations/0006_recording_library.sql` | 新录音、run、speaker、turn 和 summary source 表 |
+| `server/src/recordings/` | 列表、上传、播放、选择和删除路由 |
+| `server/src/routes.rs` | 合并新 router，健康能力字段和 OpenAPI 注册 |
+| `server/src/main.rs` | cleanup worker、配置和共享状态接线 |
+| `server/src/config.rs` | 功能开关、上传限制、speaker 模型和 cleanup 配置 |
+| `server/src/transcription_worker.rs` | 新 run 领取、结构化结果事务写入和版本切换 |
+| `server/src/recording_cleanup_worker.rs` | 物理文件清理、重试和孤儿巡检 |
+| `server/src/summary_worker.rs` | 新 source snapshot 读取和分层总结，保留旧来源兼容 |
+| `server/src/speech.rs` | 解析 speakers/turns，兼容纯文本响应 |
+| `server/src/bin/migrate-recording-library.rs` | legacy backfill 和一致性报告 |
+| `server/API.md`、`server/API_GUIDE.md` | 新接口、错误语义和示例 |
+| `asr-service/app.py` | speaker 模型、结构化响应、长音频处理和校验 |
+| `asr-service/requirements.txt` | 只在阶段 0 证明必要时锁定兼容升级 |
+| `asr-service/README.md` | 模型、环境变量、响应和性能说明 |
+| `asr-service/Dockerfile` | speaker 模型所需依赖和 ffmpeg 能力核验 |
+| `pages/recordings/` | 列表、详情和选择页面 |
+| `components/recording-*` | 经确认的列表行、播放器和 turn 复用组件 |
+| `pages/feedback/index.*` | 精简语音区域并接入录音素材选择 |
+| `utils/types.ts`、`utils/api.ts` | 新类型、API 和上传认证恢复 |
+| `app.json`、`custom-tab-bar/` | 页面注册；tab 仅在真机决策通过后修改 |
+| `tests/` | 选择、状态和前端恢复测试 |
+| `DEBUG_GUIDE.md`、`DEPLOY_5700U.md` | 调试、部署、模型缓存和验收更新 |
+| `docs/observability-runbook.md` | 新事件、查询和故障定位 |
+
+## 11. 小程序实现计划
+
+### 11.1 类型和 API
+
+在 `utils/types.ts` 增加：
+
+- `RecordingSummary`
+- `RecordingDetail`
+- `RecordingSpeaker`
+- `TranscriptTurn`
+- `TranscriptionRun`
+- `RecordingSelection`
+- `RecordingListPage`
+
+在 `utils/api.ts` 增加对应请求和 snake_case 映射。上传复用认证刷新逻辑，必须覆盖 `wx.uploadFile` token 失效重试和幂等键。
+
+### 11.2 可复用组件
+
+只为真实复用点增加组件：
+
+- `components/recording-list-item`：列表页和选择页复用。
+- `components/transcript-turn`：详情页和选择预览复用。
+- `components/recording-player`：详情页复用，封装播放和时间跳转。
+
+筛选栏和固定底栏先保留为页面局部结构，避免过早抽象。
+
+### 11.3 性能要求
+
+- turns 使用分页或分块加载，不一次 `setData` 数百条完整对象。
+- 选择状态使用 ID 集合并只更新受影响行。
+- 播放时间更新节流，不以 100ms 频率调用整页 `setData`。
+- 页面隐藏时停止播放进度更新和高频轮询。
+- 只轮询 queued/processing run；ready/failed 停止轮询。
+- 列表空态、失败态和加载骨架使用稳定尺寸，避免布局跳动。
+
+### 11.4 可访问性和视觉约束
+
+- 对话内容是详情页主要区域，工具栏和状态栏保持紧凑。
+- 一个区域内只保留一个蓝色主操作。
+- 使用白、石墨和浅灰中性色，不新增装饰渐变和重阴影。
+- 控件圆角遵循当前小程序设计，不用夸张胶囊按钮。
+- 播放、删除、重试等按钮提供明确 `aria-label`。
+- 说话人不能只靠颜色区分，同时显示角色文字。
+- 长标题、长角色名和 2000 字边界在最小真机宽度验证。
+
+## 12. 数据迁移与兼容发布
+
+### 12.1 Expand
+
+新增迁移建议从 `0006_recording_library.sql` 开始：
+
+1. 创建 `recordings`、`recording_audio_parts`、`transcription_runs`、`recording_speakers`、`transcript_turns`。
+2. 创建 `feedback_summary_run_sources`。
+3. 创建所有 CHECK、UNIQUE、FK 和必要索引。
+4. `recordings.current_transcription_run_id` 在 run 表创建后再添加 FK。
+5. 不修改现有表的非空约束，不删除旧表或旧索引。
+
+迁移必须在真实规模副本上测量锁时间。大表索引若不能在事务迁移中安全创建，应拆分为运维步骤并使用 PostgreSQL `CREATE INDEX CONCURRENTLY`。
+
+### 12.2 Backfill
+
+新增可重复运行的 `migrate-recording-library` 二进制或受控迁移任务：
+
+1. 每个 `lesson_session` 创建一个 `source='legacy'` recording。
+2. `legacy_lesson_id` 唯一保证重复执行不重复创建。
+3. 每个 `audio_segment` 创建一个 recording part；先将现有绝对 `audio_path` 规范化并验证位于
+   `AUDIO_STORAGE_DIR` 内，再转换为相对 storage key。目录外路径只报告，不自动导入。
+4. ready segment 的纯文本转为一个 `unknown` speaker 下的 turn。
+5. turn 的时间范围按 segment 顺序和 duration 累计估算，并标记为 legacy 导入，不伪装成模型级精确时间。
+6. processing/failed segment 保留原状态映射，是否重转录由用户或后续任务决定。
+7. 每批固定数量提交，输出游标、成功数、跳过数和失败数。
+8. 回填不移动物理文件，避免大批量 I/O 和回滚困难。
+
+一致性检查：
+
+- legacy recording 数等于 lesson 数。
+- part 数等于 audio segment 数。
+- 每个 ready legacy segment 至少有一个非空 turn。
+- duration 和 byte size 汇总无负值。
+- 所有 storage key 可解析且文件存在，缺失文件单独报告。
+
+### 12.3 双读和切换
+
+1. API 上线新表和新接口，功能开关默认关闭。
+2. 完成 backfill 并运行一致性报告。
+3. 录音资料列表先只对测试账号开放。
+4. 新现场录音写新表；兼容期如仍需旧页面显示，显式双写映射关系，不复制音频文件。
+5. summary worker 支持新 sources 和旧 lessons 两条读取路径。
+6. 小程序启用新页面和选择流程。
+7. 观察一个完整发布周期后，停止旧前端创建 lesson 链路。
+8. 旧 API 和表至少再保留一个发布周期。
+
+### 12.4 Contract
+
+只有满足以下条件才进入 contract：
+
+- 没有旧版本小程序仍在产生新 lesson 数据。
+- 新录音、重试、删除、总结和回滚均通过生产验证。
+- legacy 一致性报告无未解释差异。
+- 已完成数据库和音频卷可恢复备份。
+
+contract 阶段另建计划，不在本次直接安排删除 `lesson_sessions` 或 `audio_segments`。
+
+### 12.5 回滚
+
+- 关闭 `RECORDING_LIBRARY_ENABLED`，反馈页恢复旧语音入口。
+- 关闭 `ASR_DIARIZATION_ENABLED`，新转录回退纯文本模式。
+- 关闭 `RECORDING_UPLOAD_ENABLED`，保留已上传数据但隐藏新上传入口。
+- API 旧路由、旧 worker 查询和旧表保持可用。
+- 新表保留，不在应用回滚时执行 down migration。
+- 新录音数据不得自动反向写成不完整 lesson；需要时提供显式兼容导出任务。
+- 回滚过程中不删除任何音频文件。
+
+## 13. 功能开关和配置
+
+建议增加：
+
+```env
+RECORDING_LIBRARY_ENABLED=false
+RECORDING_UPLOAD_ENABLED=false
+ASR_DIARIZATION_ENABLED=false
+ASR_SPEAKER_MODEL=cam++
+MAX_RECORDING_UPLOAD_BYTES=209715200
+MAX_RECORDING_DURATION_SECONDS=14400
+RECORDING_CLEANUP_ENABLED=false
+```
+
+要求：
+
+- 开关在健康接口中只返回启用状态，不返回敏感配置。
+- 小程序根据 health capability 决定展示入口。
+- speaker 模型变化必须更新 `config_version`，不能静默改变同一 run 的结果。
+- cleanup 首次上线保持关闭，只运行 dry-run 巡检。
+
+## 14. 可观测性计划
+
+### 14.1 新事件
+
+- `recording_created`
+- `recording_part_uploaded`
+- `recording_completed`
+- `recording_upload_failed`
+- `recording_playback_failed`
+- `transcription_run_queued`
+- `transcription_run_started`
+- `transcription_run_finished`
+- `transcription_run_failed`
+- `speaker_mapping_updated`
+- `recording_delete_requested`
+- `recording_cleanup_finished`
+- `recording_cleanup_failed`
+- `recording_selection_applied`
+- `summary_sources_snapshotted`
+
+### 14.2 允许记录的字段
+
+- `recording_id`
+- `transcription_run_id`
+- `feedback_session_id`
+- `summary_run_id`
+- `owner` 不记录真实 ID 之外的身份信息；需要统计时使用不可逆聚合方式。
+- `status`、`error_class`、`attempt`。
+- `audio_size_bytes`、`audio_duration_ms`、`turn_count`、`speaker_count`。
+- `queue_wait_ms`、`inference_latency_ms`、`rtf`、`cleanup_latency_ms`。
+- `provider`、`asr_model`、`speaker_model`、`config_version`。
+
+禁止记录：
+
+- 对话正文、总结正文和文件内容。
+- 学生姓名、录音标题、说话人显示名。
+- 原始文件名、绝对路径和 storage key。
+- 上传请求体和第三方原始错误响应。
+
+### 14.3 生产观察指标
+
+- queued/processing run 数量和最老任务等待时间。
+- 转录成功率、diarization 失败率和按 error_class 分布。
+- P50/P95 RTF、内存峰值和音频时长分布。
+- 每日上传字节、音频卷增长和剩余空间。
+- cleanup 待处理数量、最老任务年龄和失败次数。
+- 总结来源 turn 数、字符数和总结失败率。
+- API 列表、详情、播放首字节和上传完成延迟。
+
+## 15. 安全与隐私
+
+录音和对话属于敏感教学数据，必须满足：
+
+1. 每个录音、speaker、turn、播放和总结来源查询都通过 recording owner 反查授权。
+2. 不接受前端传入 `owner_id` 作为授权依据。
+3. 上传文件执行大小、时长、格式和解码验证。
+4. ffmpeg 处理设置超时、资源上限和受控临时目录。
+5. 临时文件在成功、失败、超时和进程恢复路径都能清理。
+6. 播放接口不生成永久免认证 URL。
+7. 删除操作提供清晰确认并记录稳定审计事件，不记录正文。
+8. 数据库备份和音频卷备份使用相同的访问权限和恢复演练要求。
+9. 产品界面明确录音用途和删除后果，遵循微信麦克风权限说明。
+10. 不以说话人 embedding 建立跨录音身份库，除非后续完成单独隐私评审。
+
+## 16. 分阶段实施与提交计划
+
+每个阶段独立提交、可测试、可回滚。不得把数据库、ASR、全部页面和切换一次性合并为一个提交。
+
+### 阶段 0：基线和技术预研
+
+交付：
+
+- 代表性音频测试清单和本地标注格式。
+- 固定 FunASR 版本的 CAM++/ERes2NetV2 兼容性结论。
+- 5700U CPU 质量、RTF、内存和缓存报告。
+- 最终 speaker 模型和输出契约决定。
+
+建议提交：
+
+- `test(asr): add diarization evaluation fixtures`
+- `docs(asr): record speaker diarization benchmark`
+
+退出条件：第 8.5 节门槛通过，或形成明确否决结论。
+
+### 阶段 1：数据和存储基础
+
+交付：
+
+- 新表、约束和索引。
+- 流式 part 上传和 finalize。
+- 新存储键、hash、时长和大小校验。
+- 认证 Range 播放。
+- cleanup worker 和 dry-run 孤儿报告。
+
+建议提交：
+
+- `feat(recordings): add recording library schema`
+- `feat(recordings): stream audio parts to storage`
+- `feat(recordings): add authenticated audio playback`
+- `feat(recordings): add deferred audio cleanup`
+
+退出条件：上传、播放、删除、失败恢复和 owner 隔离集成测试通过。
+
+### 阶段 2：结构化转录和说话人分离
+
+交付：
+
+- ASR 新响应契约。
+- speaker 模型配置和健康信息。
+- transcription run 版本、队列和原子写入 speakers/turns。
+- 重试和重转录。
+- 模型错误分类和指标。
+
+建议提交：
+
+- `feat(asr): return timestamped speaker turns`
+- `feat(voice): persist versioned transcript turns`
+- `fix(voice): recover expired diarization jobs`
+
+退出条件：技术预研样本和端到端 DB 写入均通过。
+
+### 阶段 3：录音资料页面
+
+交付：
+
+- 列表 API 和游标分页。
+- 详情、turn 分页和 speaker 映射 API。
+- 录音列表页、详情页和播放器。
+- 处理状态、失败重试、删除和角色映射。
+
+建议提交：
+
+- `feat(recordings): add recording library APIs`
+- `feat(miniprogram): add recording library page`
+- `feat(miniprogram): add transcript review workspace`
+
+退出条件：真机可浏览、播放、映射、重试和删除录音。
+
+### 阶段 4：素材选择和总结
+
+交付：
+
+- 反馈素材选择页。
+- 选择本地恢复。
+- 直接加入反馈接口。
+- summary source 快照。
+- summary worker 新旧来源兼容。
+- 反馈页精简和总结预览接入。
+
+建议提交：
+
+- `feat(feedback): select recording transcript turns`
+- `feat(summary): snapshot selected transcript sources`
+- `feat(feedback): compose feedback from recording library`
+
+退出条件：未选中的 turn 不进入输入框或 AI 请求，历史总结不受重转录影响。
+
+### 阶段 5：历史回填和灰度切换
+
+交付：
+
+- 可重复运行的 legacy backfill。
+- 一致性报告。
+- 测试账号功能开关。
+- 生产灰度、监控和回滚演练。
+- 小程序导航最终决策。
+
+建议提交：
+
+- `feat(recordings): backfill legacy voice lessons`
+- `chore(recordings): enable recording library rollout`
+- `docs(recordings): add operations runbook`
+
+退出条件：一个完整发布周期无高严重度数据或隐私问题。
+
+## 17. 测试计划
+
+### 17.1 Rust 单元测试
+
+- 存储键只解析到允许目录。
+- Range 请求边界、无效范围和完整下载。
+- 选择展开排序、去重和所有权校验。
+- 整份录音选择正确展开全部当前 turns。
+- 2000 字限制和角色格式化。
+- source hash 对顺序、文本和版本变化敏感。
+- 状态机拒绝非法转换。
+- 同一幂等键返回同一录音或总结任务。
+
+### 17.2 PostgreSQL 集成测试
+
+- 所有 CHECK、UNIQUE 和 FK 生效。
+- 不同 owner 无法查询、播放、修改、选择或删除彼此录音。
+- worker 并发领取不重复处理。
+- ready run 原子切换 current pointer。
+- 新 run 失败不覆盖旧 ready run。
+- summary source 在录音删除后保留快照。
+- cleanup 失败不会丢失待处理记录。
+- backfill 重跑不产生重复 recording、part 或 turn。
+- 游标分页无重复和遗漏。
+
+### 17.3 Python/ASR 测试
+
+- 无 speaker 模式保持当前响应兼容。
+- speaker 模式返回合法 speakers 和 turns。
+- 空语音、单人、多人、重叠语音和损坏音频。
+- 所有支持格式和长音频。
+- 临时文件在每条失败路径清理。
+- 连续 20 次推理无内存持续增长。
+- request ID 从 API 传播到 ASR 日志。
+
+### 17.4 小程序测试
+
+- 列表筛选、分页、刷新和空态。
+- 上传成功、网络中断、认证刷新和重试。
+- 播放、暂停、拖动、跳到 turn 时间。
+- speaker 映射和按 speaker 全选。
+- 跨页面返回后选择恢复。
+- 后台转录完成后的状态刷新。
+- 失败重试和删除确认。
+- 直接加入超过 2000 字时不修改草稿。
+- 总结 ready 后预览和替换输入框。
+- 320px 宽度、常见安卓机和 iPhone 真机布局。
+
+### 17.5 端到端验收场景
+
+1. 现场录制 20 分钟两人对话，跨越至少两个 part。
+2. 后台转录并保持同一说话人跨 part 一致。
+3. 用户映射教师和学生角色。
+4. 只选择学生的若干 turn 直接加入反馈。
+5. 再选择两份录音生成总结。
+6. 验证 AI 输入不包含未选 turn。
+7. 预览后替换输入框并保存反馈。
+8. 在录音库仍可查看录音；删除录音后历史反馈和总结仍存在。
+9. 重启 API 和 FunASR 后任务恢复，模型不重复下载，音频仍存在。
+
+### 17.6 常规校验命令
+
+开发提交前至少执行：
+
+```bash
+npm test
+cd server && cargo fmt --check
+cd server && cargo test
+cd server && cargo clippy --all-targets --all-features -- -D warnings
+python3 -m py_compile asr-service/app.py asr-service/logging_config.py
+docker compose -f compose.deploy.yml config
+```
+
+涉及 FunASR 依赖变更时还要在镜像内执行 `pip check` 和真实音频推理，不能只做 Python 语法检查。
+
+## 18. 部署与发布计划
+
+### 18.1 发布前
+
+1. 备份远程 PostgreSQL，并记录可恢复时间点。
+2. 备份或快照 `teaching-feedback-audio` 卷。
+3. 记录当前镜像 tag、Git SHA、模型缓存大小和健康状态。
+4. 在生产规模副本验证迁移锁时间和 backfill 批次。
+5. 确认新 speaker 模型缓存所需磁盘和首次下载时间。
+6. 功能开关全部保持关闭。
+
+### 18.2 发布顺序
+
+1. 拉取已经测试并推送的提交。
+2. 构建 API 和 FunASR 新镜像，不停止现有容器。
+3. 运行 expand migration。
+4. 启动新 API 和 FunASR，保持新功能关闭。
+5. 验证健康检查、旧录音链路和旧总结链路。
+6. 运行 legacy backfill dry-run，再执行正式 backfill。
+7. 对测试账号启用录音资料和 diarization。
+8. 完成真实录音、上传、播放、选择、总结和删除验收。
+9. 扩大灰度范围。
+10. 最后发布使用新入口的小程序版本。
+
+### 18.3 回滚触发条件
+
+出现以下任一情况立即关闭对应功能：
+
+- 数据跨 owner 暴露或未授权播放。
+- 新转录覆盖或丢失既有 ready 转录。
+- 删除流程造成不可恢复的非目标音频删除。
+- worker 重复处理导致队列持续增长。
+- FunASR 容器内存持续增长或反复重启。
+- speaker 输出结构错误导致批量任务失败。
+- 新总结包含未选中的对话。
+- 数据库迁移或查询导致生产明显锁等待和超时。
+
+## 19. 验收标准
+
+### 19.1 产品验收
+
+- 用户可以独立进入录音资料，不依赖未保存反馈草稿。
+- 现场录音和上传文件出现在统一列表。
+- 用户可以播放、筛选、重试、重转录和删除本人录音。
+- 详情页按时间和匿名说话人展示对话。
+- 用户可以映射角色并按 turn 选择。
+- 用户可以选择整份录音或多份录音生成总结。
+- 总结可预览，确认后才写入反馈输入框。
+- 录音保存、反馈保存和录音删除互不错误级联。
+
+### 19.2 数据完整性验收
+
+- recording、part、run、speaker、turn 数量关系满足约束。
+- 所有 ready recording 都有 current ready run 和至少一个非空 turn。
+- 所有 summary run 的新来源均有完整快照。
+- legacy backfill 可重复执行且结果一致。
+- 删除后无数据库悬挂 part，失败删除仍有可重试记录。
+- 孤儿巡检结果为零或每一项都有已记录处置。
+
+### 19.3 安全验收
+
+- 两个测试用户之间录音列表、详情、播放和选择完全隔离。
+- 伪造 recording、speaker、turn ID 均返回 404 或等价资源不可见响应。
+- 日志检索不到标题、学生姓名、转录文本、原始文件名和路径。
+- Range 播放必须携带有效认证。
+- 上传恶意扩展名、损坏文件和超限文件被拒绝且临时文件清理。
+
+### 19.4 性能验收
+
+- 录音列表 20 条 P95 API 延迟目标低于 300ms，不含公网网络时间。
+- 详情元数据 P95 低于 300ms；turn 分页 P95 低于 500ms。
+- 音频 Range 首字节在局域网 P95 低于 500ms。
+- 数据库查询计划使用 owner + 时间游标索引，无全量 offset 扫描。
+- diarization 达到第 8.5 节质量和资源门槛。
+- summary worker 在 100 份录音或大量 turns 输入时受明确字符/token 预算限制。
+
+### 19.5 运维验收
+
+- API、FunASR、migration 和 cleanup 状态可从结构化日志定位。
+- 容器重启后 queued/processing 任务可恢复。
+- 模型缓存和音频卷重启后保持。
+- PostgreSQL 与音频卷完成一次关联恢复演练。
+- 回滚开关和旧链路在生产实际演练成功。
+
+## 20. 风险清单
+
+| 风险 | 严重度 | 应对 |
+|---|---|---|
+| 说话人分离质量不足 | 高 | 技术预研门槛、匿名标签、用户映射、允许 unknown |
+| 跨 8 分钟 speaker 编号互换 | 高 | 录音级 diarization，禁止直接拼接 part 标签 |
+| 数据库记录与文件不一致 | 高 | 受控删除队列、hash、巡检和恢复状态 |
+| 跨用户音频泄露 | 阻断 | 每条接口 owner 反查、Range 集成测试 |
+| 总结包含未选内容 | 高 | 事务内展开 turn 并快照，worker 只读快照 |
+| 大文件占满内存或磁盘 | 高 | 流式上传、限额、临时目录和磁盘告警 |
+| FunASR 升级引入回归 | 高 | 固定版本优先、对照基线、独立镜像 tag 和回滚 |
+| 新旧表迁移丢失历史 | 高 | expand/backfill/一致性报告，不提前 contract |
+| 长对话导致小程序卡顿 | 中 | turn 分页、局部 setData、节流播放进度 |
+| 五项 tab 拥挤 | 中 | 真机决策门槛，不通过则普通页面入口 |
+| 自动角色识别误导用户 | 中 | 不自动断言角色，必须用户确认 |
+| 存储长期增长 | 中 | 容量监控、配额、后续保留策略 |
+
+## 21. 开工前需要确认的产品决定
+
+以下决定有推荐默认值，不应在实现中隐式猜测：
+
+| 决定 | 推荐默认值 |
+|---|---|
+| 录音保留期限 | 保留到用户主动删除 |
+| 学生档案删除时录音处理 | 录音保留，`profile_id` 置空 |
+| 说话人角色 | 教师、学生、家长、其他、未知，允许自定义显示名 |
+| 是否自动认定教师 | 否 |
+| 首版是否允许修改转录文本 | 否，只允许角色映射 |
+| 上传限制 | 200 MiB、4 小时，完成真机和服务端验证后确认 |
+| 录音删除后历史总结 | 保留来源快照，不再提供播放 |
+| 底部导航 | 真机通过后增加“录音资料”，否则保留普通页面入口 |
+| diarization 模型 | 预研后在 CAM++ 和 ERes2NetV2 中选择 |
+
+## 22. Definition of Done
+
+只有同时满足以下条件，本功能才算完成：
+
+1. 本文档中首版目标均有对应实现或明确批准的范围变更。
+2. 数据库迁移、backfill、API、worker、小程序和部署文档全部合并。
+3. 自动测试、代表性音频评测和真机端到端测试通过。
+4. owner 隔离、日志脱敏和删除恢复通过安全验收。
+5. 5700U CPU 上 diarization 达到质量和资源门槛。
+6. 生产完成灰度、监控、回滚和一次容器重启恢复验证。
+7. API 文档、调试指南、部署指南和观测 runbook 已同步更新。
+8. 所有提交使用仓库现有 Conventional Commit 风格并已推送。
+9. 服务器可通过 `git pull --ff-only` 获取确定的 Git SHA 重新部署。
+10. 未完成项、残余风险和生产开关状态在发布报告中明确列出。
+
+## 23. 参考资料
+
+项目内依据：
+
+- `README.md`
+- `DEBUG_GUIDE.md`
+- `DEPLOY_5700U.md`
+- `server/API.md`
+- `server/migrations/0002_voice_feedback_sessions.sql`
+- `server/migrations/0003_async_transcription_jobs.sql`
+- `server/migrations/0005_feedback_summary_runs.sql`
+- `server/src/recording_routes.rs`
+- `server/src/transcription_worker.rs`
+- `server/src/summary_worker.rs`
+- `server/src/speech.rs`
+- `asr-service/app.py`
+- `pages/feedback/index.ts`
+- `pages/feedback/index.wxml`
+
+官方技术依据，均应在实际实现时锁定到使用版本对应的文档或提交：
+
+- [FunASR 官方仓库与 Paraformer speaker model 示例](https://github.com/modelscope/FunASR)
+- [FunASR 官方教程中的 Speaker Verification / Diarization](https://github.com/modelscope/FunASR/blob/main/docs/tutorial/README.md)
+- [FunASR 官方 Paraformer 实现说明](https://github.com/modelscope/FunASR/blob/main/funasr/models/paraformer/model.py)
+
+官方 `main` 分支能力不等于本项目固定 `funasr==1.3.14` 已验证能力；阶段 0 的固定版本兼容测试是正式开发的阻断门槛。