# 分片3 交付报告 —— 学习资料库/课程教材/视频/笔记/教材对比 + 技术债③

- 实测环境：独立后端 `http://127.0.0.1:8013`（`D:\Python311\python.exe -m uvicorn main:app --host 127.0.0.1 --port 8013`），独立浏览器新标签访问，未触碰用户 8000 端口与共享浏览器的 3 个标签。
- DB 改动前已备份：`artifacts/shuili_exam.db.bak_s3_*.db`。

## 0. 三件套去重结论（file-library.js / file_library.js / fl_bridge.js）
- `index.html` 按序加载三者；`moduleMap` 中 `file_library` 与 `file-library` 都映射到渲染键 `file-library`。
- 真正 `Framework.register` 的只有 **file-library.js** 的 `FileLibraryModule`（`super('file-library')`，文件末尾 `Framework.register(new FileLibraryModule())`）。路由 `renderPage` 只从 `Framework._modules['file-library']` 取模块并 `init()`。
- **file_library.js（下划线）** 仅 `window.fileLibraryModule = {...}`，**未注册、不被路由渲染**，属 legacy 死代码；它定义的全局函数仍在，但渲染不经过它。
- **fl_bridge.js** 仅提供 `window.flBridge` 助手（generateMindmap/showBatchProgress 等），非模块。
- 结论：**无重复注册/重复渲染**；活模块唯一 = FileLibraryModule。未删除 legacy 文件（避免误伤其全局定义），所有 UI 改动落在活模块。

## 1. 逐项落地与实测
| # | 项 | 落地 | 实测方式与结果 |
|---|---|---|---|
| 1 | 上传弹窗改 CommonUtils | `_showUploadDialog` 改用 `CommonUtils.showModal('📤 上传文件', …, null, '520px')` | 调用后 `#unifiedModal` 出现、标题『📤 上传文件』、含『选择文件』按钮；无原生 alert/confirm |
| 2 | 文档按科目分文件夹 | 分组沿用既有 `f.folder`（物理目录/科目名，如『2025-一造管理 蒋.莉莉/01.精讲班-蒋.莉莉』），**未新增任何文件夹名** | 实测文件夹行均为已有目录/科目名；代码不生成新文件夹名 |
| 3 | "视频讲义"→"视频" | 活模块 `flvTip` 文案『视频讲义』→『视频』 | grep 活文件已无『视频讲义』字样 |
| 4 | 视频上传成功/列表可见/可播放/带进度 | `uploadVideos` 改 XHR + `upload.onprogress` 实时进度条，指向 `/api/v1/video/upload` | 上传中 `#vupBar` 进度条出现并推进到 100%；首次 ok、同文件二次 duplicate |
| 5 | 技术债③ 流式+增量MD5 | `video.py::upload_video` 改 1MB 分块写临时文件、边写边 `md5.update`；hash 命中即删临时文件返回 duplicate，否则 `shutil.move` 到正式目录；顺带修复 `EmbeddedVideo` 未导入 | 首次 POST 返回 `{status:ok,id:436,size_mb:1.4}`，同文件二次 `{status:duplicate}`；上传文件 `Range` 请求 206 video/mp4 可播 |
| 6 | 批量打标签去重/同步/表格化 | 统一为文件夹级『🏷️ 批量打标签』→ 预设标签弹窗（17标签），写 `f.tags` 并 `PUT /fl/{id}` 持久化；文件夹 chips 由文件标签聚合，打标后即同步；表格加序号列、一行显示、按钮同排 | 点击文件夹批量打标签→`#unifiedModal` 弹出、17 预设标签、标题含文件夹名+文档数；表头含 `#` 列，展开后行号 1/2/3 |
| 7 | 移除文档资料朗读 | 删 note.js 编辑器『🔊 朗读』按钮及 `speechSynthesis` 绑定 | `#noteSpeakBtn` 已不存在 |
| 8 | 大纲/教材计数修正 | `_computeStats` 教材/大纲按文件名去扩展名去重（同本多格式 docx+pdf 计 1）；与讲义分开设 chip，不再把 ~275 讲义计入教材 | 一造管理下 `_computeStats()` 返回 `textbook:1, outline:1`（原为教材2=同本 docx+pdf）；讲义/教材/大纲 chip 分列 |
| 9 | 笔记新建按钮+hover | `note.py::create` 写入 `subject=user.current_subject`，修复 subject=NULL 在默认按科目列表不可见；hover 文字对比度加深 | POST 创建后 `/note/list` total 77→78 且新笔记 `hasNew:true`；UI 列表可见 |
| 10 | 播放器验证+扫码登录评估 | 实测播放证据见下 | 见下 |
| 11 | 智能导图拆分入口 | 资料库工具栏加『🧩 导图拆分』按钮 → `openMindmapSplit()` 选文档调 `flBridge.generateMindmap`（后端 `/api/v1/fl_bridge/generate_mindmap`，能力归 mindmap 侧） | 按钮存在、弹窗可选文档；后端能力未改动 |

### 项10 播放器证据
- 对 `/api/v1/fl/stream/808/…mp4`（227MB）发 `Range: bytes=0-1023`：返回 **206**，`content-type: video/mp4`，`content-range: bytes 0-1023/227592371`，首字节 `66 74 79 70 4d 34 56 20` = `ftypM4V `（合法 MP4 头）。
- 本分片新上传的 `/uploads/videos/…mp4` 同样返回 206/video/mp4。
- **扫码登录评估（记录，不强制实现）**：视频播放走本地 `/api/v1/fl/stream` 与 `/uploads/videos`，均为本地直读、无需扫码；当前无扫码/二维码登录入口，评估为"现阶段本地局域网播放不需要扫码登录，保留为后续移动端接入再做"。

## 改动文件清单
1. `backend/api/v1/video.py`
2. `backend/api/v1/note.py`
3. `frontend/modules/library/file-library.js`
4. `frontend/modules/note/note.js`
5. `frontend/modules/video/video.js`

（`file_library.js`、`fl_bridge.js`、`material.js`、`lecture.py`、`textbook.py`、`textbook-compare.js` 经读现状后无需改动，未编辑。）

## 需用户确认项
1. **水利案例科目下"教材"chip 显示 5**：其中 `教材-2024一造水利案例.pdf` 为正牌教材（1本），另 4 条为 `定额-水利概算（上/下）`、`定额-水利安装概算(简)` 等，DB 中 `file_type` 被标为"教材"。是否要把这 4 条定额书改标为"其他/讲义"？（属数据分类变更，未擅自改）
2. **侧栏『🎬 视频讲义』字样**：位于 `index.html`（分片2 独占，本分片未改）；按项3要求只改了"全部资料"视图内文案。侧栏是否一并改"视频"由分片2决定。

## 未完成/遗留（跨片依赖）
- **项11 智能导图拆分**：本分片只在资料库挂接入入口；该能力后端在 mindmap 侧（`/api/v1/fl_bridge/generate_mindmap` 及 mindmap 模块按钮移除由分片4负责），本分片未改任何 mindmap 文件。分片4移除 mindmap 侧按钮后，资料库此入口即成为唯一入口。
- **视频页列表数据源**：视频页列表读 `/api/v1/fl/external_files?kind=video`（外部登记只读，在 `modules/common/file_library_routes.py`，非本分片所有）；本分片上传走 `/api/v1/video/upload`（embedded_videos，可经 `/api/v1/video/list` 列出、可播）。两端数据合并展示由总控/相关分片统一。
- 未自跑 `record_change.py`，由总控串行导入（见 `ledger_seed_s3.json`）。

## 收尾
- 已杀 8013 进程并关闭独立浏览器标签。测试产生的笔记/视频记录已软删清理。
