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

工程分析/经验记录.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 四段。