2026-04-29-22-49-38 - 修复WebSocket连接+项目状态异常+导入按钮无响应+后端WS路由

工程分析/实现方案-2026-04-29-22-49-38.md

@@ -0,0 +1,51 @@
+# 实现方案 - 2026-04-29-22-49-38
+
+## 对应需求
+- 需求分析文档: `需求分析-2026-04-29-22-49-38.md`
+
+## 方案概述
+修复 4 个关联缺陷：WebSocket 连接地址错误、后端缺少 WebSocket 路由、导入按钮无交互、项目状态映射不匹配。
+
+## 修改文件清单
+
+### 文件 1: `src/lib/websocket.ts`（修改）
+- **修改类型**: 修改 URL
+- **修改内容**: `ws://localhost:8000/ws/progress` → `ws://192.168.3.11:8000/ws/progress`
+
+### 文件 2: `backend/main.py`（修改）
+- **修改类型**: 新增 WebSocket 路由
+- **修改内容**: 添加 `@app.websocket("/ws/progress")` 路由，支持：
+  - 客户端连接/断开日志
+  - 接收前端订阅消息
+  - 定期推送心跳（可选）
+  - 通过 Redis 发布/订阅桥接解析进度（预留接口）
+
+### 文件 3: `src/components/ProjectLibrary.tsx`（修改）
+- **修改类型**: 添加文件导入交互
+- **修改内容**:
+  - 添加 `fileInputRef` 引用
+  - 为"导入多媒体资源"按钮添加 `onClick` 触发文件选择器
+  - 添加隐藏的 `<input type="file">`，支持 `accept="video/*,image/*"`
+  - `onChange` 时调用 `uploadMedia` API 上传文件
+  - 上传成功后刷新项目列表
+
+### 文件 4: `backend/models.py`（修改）
+- **修改类型**: 修改默认值
+- **修改内容**: `Project.status` 默认值从 `"pending"` 改为 `"Ready"`
+- **替代方案**: 若数据库已创建，同时修改 `schemas.py` 中返回状态映射
+
+### 文件 5: `src/components/ProjectLibrary.tsx`（修改状态显示）
+- **修改类型**: 扩展状态分支
+- **修改内容**: 增加对 `'pending'` 状态的显示（"待处理"）
+
+## 新增依赖
+无
+
+## 兼容性分析
+- WebSocket 为新增路由，不影响现有 HTTP API
+- 文件上传复用已有 `uploadMedia` API
+- 状态默认值修改仅影响新项目
+
+## 预估工作量
+- 代码修改: 10 分钟
+- 重启验证: 5 分钟

工程分析/测试方案-2026-04-29-22-49-38.md

@@ -0,0 +1,47 @@
+# 测试方案 - 2026-04-29-22-49-38
+
+## 对应实现方案
+- 实现方案文档: `实现方案-2026-04-29-22-49-38.md`
+
+## 测试范围
+- WebSocket 连接可达性
+- 文件导入按钮交互
+- 项目状态显示正确性
+
+## 测试用例
+
+### 用例 1: WebSocket 连接测试
+- **前置条件**: 前后端均运行
+- **操作步骤**:
+  ```bash
+  curl -s -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
+    -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
+    -H "Sec-WebSocket-Version: 13" \
+    http://192.168.3.11:8000/ws/progress
+  ```
+- **预期结果**: 返回 101 Switching Protocols
+- **通过标准**: HTTP 101，连接建立
+
+### 用例 2: 文件导入按钮交互验证（浏览器）
+- **前置条件**: 前端运行
+- **操作步骤**:
+  1. 打开项目库页面
+  2. 点击"导入多媒体资源"按钮
+- **预期结果**: 弹出系统文件选择器
+- **通过标准**: 文件选择器出现，支持选择视频/图片
+
+### 用例 3: 新建项目状态显示
+- **前置条件**: 后端运行
+- **操作步骤**:
+  1. 创建新项目
+  2. 查看项目卡片状态标签
+- **预期结果**: 状态显示为"已就绪"（绿色）
+- **通过标准**: 非"异常"（红色）
+
+## 回归测试
+- [ ] localhost 开发方式不受影响
+- [ ] 现有项目列表加载正常
+
+## 测试环境
+- 浏览器: Chrome
+- 访问地址: http://192.168.3.11:3000

工程分析/经验记录.md

@@ -142,4 +142,34 @@ AI 助手运行的容器/环境与项目实际开发环境分离，后者才装
 
 ---
 
+## 2026-04-29-22-49-38 — WebSocket 404 + 项目状态异常 + 导入按钮无响应
+
+### A. 具体问题
+1. 控制台报错 `WebSocket connection to 'ws://localhost:8000/ws/progress' failed`
+2. 项目库中"测试视频项目"状态显示为"异常"（红色）
+3. "导入多媒体资源"按钮点击无反应
+
+### B. 产生原因
+1. `websocket.ts` 仍为 `ws://localhost:8000/ws/progress`，未随前端 baseURL 一起改为服务器 IP
+2. FastAPI 后端未实现 `/ws/progress` WebSocket 路由
+3. Uvicorn 缺少 WebSocket 支持库（`websockets` 或 `wsproto` 未安装）
+4. 后端 `Project` 模型默认状态为 `"pending"`，前端只识别 `"Ready"` / `"Parsing"`，其他状态均显示"异常"
+5. `ProjectLibrary.tsx` 中"导入多媒体资源"按钮为纯静态 `<button>`，无 `onClick` 事件和隐藏的 `<input type="file">`
+
+### C. 解决方案
+1. `websocket.ts` URL 改为 `ws://192.168.3.11:8000/ws/progress`
+2. `backend/main.py` 添加 `@app.websocket("/ws/progress")` 路由 + `ConnectionManager` 连接管理
+3. `pip install websockets` 为 Uvicorn 提供 WebSocket 协议支持
+4. 后端 `Project.status` 默认值从 `"pending"` 改为 `"Ready"`
+5. 前端增加 `'pending'` / `'Pending'` 状态分支显示"待处理"
+6. 为导入按钮添加 `onClick` + `useRef<HTMLInputElement>` + 隐藏文件输入框，调用 `uploadMedia` API
+
+### D. 后续如何避免问题
+1. 任何涉及网络地址的配置（HTTP / WebSocket）必须同步修改，不能遗漏
+2. 新增 WebSocket 功能时，同步检查 Uvicorn 是否安装了协议支持库
+3. 前后端状态枚举值必须对齐，或后端返回时做映射转换
+4. 所有按钮类 UI 元素必须绑定事件处理器，禁止纯装饰性按钮
+
+---
+
 > 新增经验请追加到文件末尾，保持时间倒序或正序均可，但需确保每条经验包含完整的 A/B/C/D 四段。

工程分析/需求分析-2026-04-29-22-49-38.md

@@ -0,0 +1,48 @@
+# 需求分析 - 2026-04-29-22-49-38
+
+## 需求来源
+- 提出时间: 2026-04-29-22-49-38
+- 需求类型: 缺陷修复
+
+## 原始需求描述
+1. 项目库中视频显示"异常"，且无法点击导入多媒体资源
+2. 控制台 WebSocket 报错：
+   - `WebSocket connection to 'ws://localhost:8000/ws/progress' failed`
+   - `WebSocket is closed before the connection is established`
+
+## 需求拆解
+
+### 需求 1: 修复 WebSocket URL（localhost → IP）
+- **详细描述**: `websocket.ts` 硬编码 `ws://localhost:8000/ws/progress`，浏览器解析为客户端本地地址导致连接失败
+- **优先级**: P0-阻塞
+- **影响范围**: `src/lib/websocket.ts`
+- **验收标准**: WebSocket 连接到服务器实际 IP
+
+### 需求 2: 后端添加 WebSocket 路由
+- **详细描述**: FastAPI 后端未实现 `/ws/progress` WebSocket endpoint，前端连接被拒绝
+- **优先级**: P0-阻塞
+- **影响范围**: `backend/main.py`
+- **验收标准**: 后端接受 WebSocket 连接，可推送解析进度消息
+
+### 需求 3: 修复"导入多媒体资源"按钮点击
+- **详细描述**: `ProjectLibrary.tsx` 中按钮为纯静态 UI，无 `onClick` 事件和文件输入框
+- **优先级**: P0-阻塞
+- **影响范围**: `src/components/ProjectLibrary.tsx`
+- **验收标准**: 点击按钮弹出文件选择器，可选择视频/图片文件
+
+### 需求 4: 修复项目状态显示"异常"
+- **详细描述**: 后端数据库项目默认状态为 `'pending'`，前端只识别 `'Ready'` 和 `'Parsing'`，其他状态均显示"异常"
+- **优先级**: P0-阻塞
+- **影响范围**: `backend/models.py` 或 `src/components/ProjectLibrary.tsx`
+- **验收标准**: 新建项目默认显示正确状态（非"异常"）
+
+## 约束条件
+- 保持中文界面
+- 最小修改原则
+- 不破坏现有 API 契约
+
+## 风险评估
+| 风险点 | 影响 | 缓解措施 |
+|--------|------|----------|
+| WebSocket 实现复杂度高 | 中 | 先实现基础连接和心跳，进度推送后续完善 |
+| 文件上传无后端对接 | 低 | 前端先实现文件选择器，调用已有 uploadMedia API |