更新

Docs/BACKEND_DEV.md

@@ -19,7 +19,6 @@
 - **repositories/**：数据读写（Supabase），不包含业务逻辑。
 - **services/**：外部依赖与基础能力（TTS、Storage、Remotion 等）。
 - **core/**：配置、安全、依赖注入、统一响应。
-- **api/**：仅做 router 透传，保持 `/api/*` 路由稳定。
 
 ---
 
@@ -28,9 +27,8 @@
 ```
 backend/
 ├── app/
-│   ├── api/                 # 兼容路由入口，透传到 modules
 │   ├── core/                # config、deps、security、response
-│   ├── modules/             # 业务模块
+│   ├── modules/             # 业务模块（路由 + 逻辑）
 │   │   ├── videos/
 │   │   ├── materials/
 │   │   ├── publish/

Docs/BACKEND_README.md

@@ -13,7 +13,6 @@
 ```
 backend/
 ├── app/
-│   ├── api/              # 兼容路由入口 (透传到 modules)
 │   ├── core/             # 核心配置 (config.py, security.py, response.py)
 │   ├── modules/          # 业务模块 (router/service/workflow/schemas)
 │   ├── repositories/     # Supabase 数据访问
@@ -148,7 +147,7 @@ uvicorn app.main:app --host 0.0.0.0 --port 8006 --reload
 1.  在 `app/services/` 下创建新的 Service 类 (如 `NewTTSService`)。
 2.  实现 `generate` 方法，可以使用 subprocess 调用，也可以是 HTTP 请求。
 3.  **重要**: 如果模型占用 GPU，请务必使用 `asyncio.Lock` 进行并发控制，防止 OOM。
-4.  在 `app/api/` 中添加对应的路由调用。
+4.  在 `app/modules/` 下创建对应模块，添加 router/service/schemas，并在 `main.py` 注册路由。
 
 ### 添加定时任务
 

Docs/DevLogs/Day20.md

@@ -64,3 +64,27 @@ pm2 restart vigent2-backend
 pm2 restart vigent2-latentsync
 # Remotion 已自动编译
 ```
+
+### 🐛 缺陷修复与回归治理 (17:30)
+
+#### 严重缺陷修复
+- [x] **BUG-1**: Remotion 渲染脚本路径解析错误 (导致标题字幕丢失)
+    - *原因*: `render.js` 预编译后使用了 `__dirname`，在 `dist` 目录下寻找源码失败。
+    - *修复*: 修改 `render.ts` 使用 `process.cwd()` 动态解析路径，并重新编译。
+
+- [x] **BUG-2**: 发布页视频选择持久化失效 (Auth 异步竞态)
+    - *原因*: 页面加载时 `useAuth` 尚未返回用户 ID，导致使用 `guest` Key 读取不到记录，随后被默认值覆盖。
+    - *修复*: 引入 `isVideoRestored` 状态机，强制等待 Auth 完成且 Video 列表加载完毕后，才执行恢复逻辑。
+
+#### 回归问题治理
+- [x] **REG-1**: 首页历史作品 ID 恢复后内容不显示
+    - *原因*: 持久化模块恢复了 ID，但 `useGeneratedVideos` 未监听 ID 变化同步 URL。
+    - *修复*: 新增 `useEffect` 监听 `selectedVideoId` 变化并同步 `generatedVideo` URL。
+
+- [x] **REG-2**: 首页/发布页“默认选中第一个”逻辑丢失
+    - *原因*: 重构移除旧逻辑后，新用户或无缓存用户进入页面无默认选中。
+    - *修复*: 在 `isRestored` 且无选中时，增加兜底逻辑自动选中列表第一项。
+
+- [x] **REF-1**: 持久化逻辑全站收敛
+    - *优化*: 清理 `useBgm`, `useGeneratedVideos`, `useTitleSubtitleStyles` 中的冗余 `localStorage` 读取。
+    - *优化*: 修复 `useMaterials` 中的闭包陷阱（使用函数式更新），防止覆盖已恢复的状态。

Docs/DevLogs/Day21.md

@@ -0,0 +1,92 @@
+## 🐛 缺陷修复：视频生成与持久化回归 (Day 21)
+
+### 概述
+本日修复 Day 20 优化后引入的 3 个回归缺陷：Remotion 渲染崩溃容错、首页作品选择持久化、发布页作品选择持久化。
+
+---
+
+### 已完成修复
+
+#### BUG-1: Remotion 渲染进程崩溃导致标题/字幕丢失
+- **现象**: 视频生成后没有标题和字幕，回退到纯 FFmpeg 合成。
+- **根因**: Remotion Node.js 进程在渲染完成（100%）后以 SIGABRT (code -6) 退出，Python 端将其视为失败。
+- **修复**: `remotion_service.py` 在进程非零退出时，先检查输出文件是否存在且大小合理（>1KB），若存在则视为成功。
+- **文件**: `backend/app/services/remotion_service.py`
+
+```python
+if process.returncode != 0:
+    output_file = Path(output_path)
+    if output_file.exists() and output_file.stat().st_size > 1024:
+        logger.warning(
+            f"Remotion process exited with code {process.returncode}, "
+            f"but output file exists ({output_file.stat().st_size} bytes). Treating as success."
+        )
+        return output_path
+    raise RuntimeError(...)
+```
+
+#### BUG-2: 首页历史作品选择刷新后不保持
+- **现象**: 用户选择某个历史作品后刷新页面，总是回到第一个视频。
+- **根因**: `fetchGeneratedVideos()` 在初始加载时无条件自动选中第一个视频，覆盖了 `useHomePersistence` 的恢复值。
+- **修复**: `fetchGeneratedVideos` 增加 `preferVideoId` 参数，仅在明确指定时才自动选中；新增 `"__latest__"` 哨兵值用于生成完成后选中最新。
+- **文件**: `frontend/src/features/home/model/useGeneratedVideos.ts`, `frontend/src/features/home/model/useHomeController.ts`
+
+```typescript
+// 任务完成 → 自动选中最新
+useEffect(() => {
+  if (prevIsGenerating.current && !isGenerating) {
+    if (currentTask?.status === "completed") {
+      void fetchGeneratedVideos("__latest__");
+    } else {
+      void fetchGeneratedVideos();
+    }
+  }
+  prevIsGenerating.current = isGenerating;
+}, [isGenerating, currentTask, fetchGeneratedVideos]);
+```
+
+#### BUG-3: 发布页作品选择刷新后不保持（根因：签名 URL 不稳定）
+- **现象**: 发布管理页选择视频后刷新，选择丢失（无任何视频被选中）。
+- **根因**: 后端 `/api/videos/generated` 返回的 `path` 是 Supabase 签名 URL，每次请求都会变化。发布页用 `path` 作为选择标识存入 localStorage，刷新后新的 `path` 与保存值永远不匹配。首页不受影响是因为使用稳定的 `video.id`。
+- **修复**: 发布页全面改用 `id`（稳定标识）替代 `path`（签名 URL）进行选择、持久化和比较。
+- **文件**:
+  - `frontend/src/shared/types/publish.ts` — `PublishVideo` 新增 `id` 字段
+  - `frontend/src/features/publish/model/usePublishController.ts` — `selectedVideo` 存储 `id`，发布时根据 `id` 查找 `path`
+  - `frontend/src/features/publish/ui/PublishPage.tsx` — `key`/`onClick`/选中比较改用 `v.id`
+  - `frontend/src/features/home/model/useHomeController.ts` — 预取缓存加入 `id` 字段
+
+```typescript
+// 类型定义新增 id
+export interface PublishVideo {
+    id: string;    // 稳定标识符
+    name: string;
+    path: string;  // 签名 URL（仅用于播放/发布）
+}
+
+// 发布时根据 id 查找 path
+const video = videos.find(v => v.id === selectedVideo);
+await api.post('/api/publish', { video_path: video.path, ... });
+```
+
+---
+
+### 涉及文件汇总
+
+| 文件 | 变更 |
+|------|------|
+| `backend/app/services/remotion_service.py` | Remotion 崩溃容错 |
+| `frontend/src/features/home/model/useGeneratedVideos.ts` | 首页视频选择不自动覆盖 |
+| `frontend/src/features/home/model/useHomeController.ts` | 任务完成监听 + 预取缓存加 id |
+| `frontend/src/shared/types/publish.ts` | PublishVideo 新增 id 字段 |
+| `frontend/src/features/publish/model/usePublishController.ts` | 选择/持久化/发布改用 id |
+| `frontend/src/features/publish/ui/PublishPage.tsx` | UI 选择比较改用 id |
+
+### 关键教训
+
+> **签名 URL 不可作为持久化标识**。Supabase Storage 的签名 URL 包含时间戳和签名参数，每次请求都不同。任何需要跨请求/跨刷新保持的标识，必须使用后端返回的稳定 `id` 字段。
+
+### 重启要求
+```bash
+pm2 restart vigent2-backend    # Remotion 容错
+npm run build && pm2 restart vigent2-frontend  # 前端持久化修复
+```

Docs/FRONTEND_DEV.md

@@ -15,7 +15,7 @@ frontend/src/
 │   └── ...
 ├── lib/                # 公共工具函数
 │   ├── axios.ts        # Axios 实例（含 401/403 拦截器）
-│   ├── auth.ts         # 认证相关函数
+│   ├── auth.ts         # 认证相关函数（统一使用 axios）
 │   └── media.ts        # API Base / URL / 日期等通用工具
 └── proxy.ts            # 路由代理（原 middleware）
 ```
@@ -256,6 +256,7 @@ import { formatDate } from '@/shared/lib/media';
 - **恢复先于保存**：恢复完成前禁止写入（`isRestored` 保护）。
 - 避免默认值覆盖用户选择（优先读取已保存值）。
 - 优先使用 `useHomePersistence` 集中管理恢复/保存，页面内避免分散的 localStorage 读写。
+- **禁止使用签名 URL 作为持久化标识**：Supabase Storage 签名 URL 每次请求都变化，必须使用后端返回的稳定 `id` 字段。
 - 如需新增持久化字段，必须加入恢复与保存逻辑，并更新本节。
 
 ---
@@ -273,7 +274,8 @@ import { formatDate } from '@/shared/lib/media';
 ## 发布页交互规则
 
 - 发布按钮在未选择任何平台时禁用
-- 仅保留“立即发布”，不再提供定时发布 UI/参数
+- 仅保留"立即发布"，不再提供定时发布 UI/参数
+- **作品选择持久化**：使用 `video.id`（稳定标识）而非 `video.path`（签名 URL）进行选择、比较和 localStorage 存储。发布时根据 `id` 查找对应 `path` 发送请求。
 
 ---
 

Docs/FRONTEND_README.md

@@ -17,6 +17,7 @@ ViGent2 的前端界面，采用 Next.js 16 + TailwindCSS 构建。
 - **作品预览**: 生成完成后直接播放下载（作品预览 + 历史作品）。
 - **预览优化**: 预览视频 `metadata` 预取，首帧加载更快。
 - **本地保存**: 文案/标题/偏好由 `useHomePersistence` 统一持久化，刷新后恢复 (Day 14/17)。
+- **选择持久化**: 首页/发布页作品选择均使用稳定 `id` 持久化，刷新保持用户选择；新视频生成后自动选中最新 (Day 21)。
 
 ### 2. 全自动发布 (`/publish`) [Day 7 新增]
 - **多平台管理**: 统一管理抖音、微信视频号、B站、小红书账号状态。
@@ -26,6 +27,7 @@ ViGent2 的前端界面，采用 Next.js 16 + TailwindCSS 构建。
   - Cookie 自动保存与状态同步。
 - **发布配置**: 设置视频标题、标签、简介。
 - **作品选择**: 卡片列表 + 搜索 + 预览弹窗。
+- **选择持久化**: 使用稳定 `video.id` 持久化选择，刷新保持；新视频生成自动选中最新 (Day 21)。
 - **预览兼容**: 签名 URL / 相对路径均可直接预览。
 - **发布方式**: 仅支持 "立即发布"。
 

Docs/task_complete.md

@@ -1,8 +1,8 @@
 # ViGent2 开发任务清单 (Task Log)
 
-**项目**: ViGent2 数字人口播视频生成系统  
-**进度**: 100% (Day 20 - 代码质量与安全优化)  
-**更新时间**: 2026-02-07
+**项目**: ViGent2 数字人口播视频生成系统
+**进度**: 100% (Day 21 - 缺陷修复与持久化回归治理)
+**更新时间**: 2026-02-08
 
 ---
 
@@ -10,12 +10,19 @@
 
 > 这里记录了每一天的核心开发内容与 milestone。
 
-### Day 20: 代码质量与安全优化 (Current)
+### Day 21: 缺陷修复与持久化回归治理 (Current)
+- [x] **Remotion 崩溃容错**: 渲染进程 SIGABRT 退出时检查输出文件，避免误判失败导致标题/字幕丢失。
+- [x] **首页作品选择持久化**: 修复 `fetchGeneratedVideos` 无条件覆盖恢复值的问题，新增 `preferVideoId` 参数控制选中逻辑。
+- [x] **发布页作品选择持久化**: 根因为签名 URL 不稳定，全面改用 `video.id` 替代 `path` 进行选择/持久化/比较。
+- [x] **预取缓存补全**: 首页预取发布页数据时加入 `id` 字段，确保缓存数据可用于持久化匹配。
+
+### Day 20: 代码质量与安全优化
 - [x] **功能性修复**: LatentSync 回退逻辑、任务状态接口认证、User 类型统一。
 - [x] **性能优化**: N+1 查询修复、视频上传流式处理、httpx 异步替换、GLM 异步包装。
 - [x] **安全修复**: 硬编码 Cookie 配置化、日志敏感信息脱敏、ffprobe 安全调用、CORS 配置化。
 - [x] **配置优化**: 存储路径环境变量化、Remotion 预编译加速、LatentSync 绝对路径。
 - [x] **文档更新**: 更新 Doc_Rules.md 清单，补齐后端与部署文档；更新 SUBTITLE_DEPLOY.md, FRONTEND_DEV.md, implementation_plan.md。
+- [x] **缺陷修复**: 修复 Remotion 路径解析、发布页持久化竞态、首页选中回归、素材闭包陷阱。
 
 ### Day 19: 自动发布稳定性与发布体验优化 🚀
 - [x] **抖音发布稳定性**: 上传入口、封面流程、发布重试、登录失效识别与网络失败快速返回全面增强。