From bfba0ef8b86c293d172bc36a0e7c0ecba6b0c3e1 Mon Sep 17 00:00:00 2001
From: AI Clinical Dev Team <dev@ai-clinical.com>
Date: Fri, 10 Oct 2025 21:28:49 +0800
Subject: [PATCH] docs: add frontend data fetching troubleshooting guide

---
 解决方案-前端获取数据失败.md | 272 +++++++++++++++++++++++++++++++++++
 1 file changed, 272 insertions(+)
 create mode 100644 解决方案-前端获取数据失败.md

diff --git a/解决方案-前端获取数据失败.md b/解决方案-前端获取数据失败.md
new file mode 100644
index 00000000..7fe978cb
--- /dev/null
+++ b/解决方案-前端获取数据失败.md
@@ -0,0 +1,272 @@
+# 🔧 解决方案：前端获取数据失败
+
+## ✅ 当前系统状态（全部正常）
+
+经过检查，系统状态如下：
+
+```
+✅ 后端服务运行正常（端口3001）
+✅ 后端健康检查通过
+✅ 后端API测试成功：
+   - GET /api/v1/projects ✅ 返回项目列表
+   - POST /api/v1/projects ✅ 创建项目成功
+✅ 前端服务运行正常（端口3000）
+✅ 前端页面可访问
+```
+
+**结论：** 后端和前端服务都正常，问题可能在浏览器端。
+
+---
+
+## 🎯 解决方案（按顺序尝试）
+
+### 方案1：清除浏览器缓存并刷新 ⭐ 优先尝试
+
+**步骤：**
+1. 打开浏览器（http://localhost:3000）
+2. 按 **Ctrl + Shift + R**（强制刷新，清除缓存）
+3. 或者按 **F12** 打开开发者工具
+4. 右键点击刷新按钮，选择"清空缓存并硬性重新加载"
+
+**预期结果：**
+- 页面重新加载
+- 项目列表应该正常显示
+- 可以创建新项目
+
+---
+
+### 方案2：检查浏览器控制台错误
+
+**步骤：**
+1. 按 **F12** 打开开发者工具
+2. 切换到 **Console** 标签
+3. 清空之前的错误（点击🚫图标）
+4. 刷新页面
+5. 查看是否有新的错误信息
+
+**如果看到错误，请告诉我具体内容**
+
+---
+
+### 方案3：检查Network请求
+
+**步骤：**
+1. 按 **F12** 打开开发者工具
+2. 切换到 **Network** 标签
+3. 勾选 "Preserve log"
+4. 刷新页面
+5. 查找 `/api/v1/projects` 请求
+6. 点击该请求，查看：
+   - **Status**: 应该是 200
+   - **Preview**: 查看响应内容
+   - **Headers**: 查看请求头
+
+**如果Status不是200，请告诉我具体状态码**
+
+---
+
+### 方案4：完全重启浏览器
+
+**步骤：**
+1. 关闭浏览器（完全关闭，不要只关标签页）
+2. 重新打开浏览器
+3. 访问 http://localhost:3000
+4. 测试功能
+
+---
+
+### 方案5：使用无痕/隐私模式
+
+**步骤：**
+1. 打开浏览器无痕模式：
+   - Chrome: **Ctrl + Shift + N**
+   - Edge: **Ctrl + Shift + N**
+   - Firefox: **Ctrl + Shift + P**
+2. 访问 http://localhost:3000
+3. 测试功能
+
+**如果无痕模式正常：** 说明是浏览器缓存或扩展插件问题
+
+---
+
+### 方案6：检查项目选择器状态
+
+有时项目列表加载了，但需要**手动选择项目**才能使用智能体。
+
+**步骤：**
+1. 查看页面左上角或侧边栏
+2. 是否有"项目选择器"或"当前项目"下拉框？
+3. 如果有，请选择一个项目
+4. 然后再尝试使用智能体
+
+---
+
+### 方案7：重启所有服务
+
+**步骤：**
+```powershell
+# 步骤1：停止所有服务
+双击运行：停止所有服务.bat
+
+# 步骤2：等待3秒
+
+# 步骤3：重新启动
+双击运行：一键启动.bat
+
+# 步骤4：等待10秒，浏览器会自动打开
+
+# 步骤5：测试功能
+```
+
+---
+
+## 🧪 验证API是否正常
+
+### 手动测试后端API
+
+**测试1：健康检查**
+```
+浏览器访问：http://localhost:3001/health
+```
+**预期结果：**
+```json
+{"status":"ok","database":"connected","timestamp":"..."}
+```
+
+**测试2：获取项目列表**
+```
+浏览器访问：http://localhost:3001/api/v1/projects
+```
+**预期结果：**
+```json
+{"success":true,"data":[...]}
+```
+
+**测试3：获取智能体列表**
+```
+浏览器访问：http://localhost:3001/api/v1/agents
+```
+**预期结果：**
+```json
+{"success":true,"data":[{"id":"topic-evaluation",...}]}
+```
+
+**如果以上任何一个失败，请告诉我具体的错误信息**
+
+---
+
+## 🔍 详细诊断步骤
+
+如果以上方案都不行，请按照以下步骤收集信息：
+
+### 步骤1：后端日志
+查看后端启动终端，复制最近的日志（包括任何错误）
+
+### 步骤2：前端控制台
+1. F12 → Console标签
+2. 复制所有错误信息（红色的）
+
+### 步骤3：Network请求
+1. F12 → Network标签
+2. 找到失败的请求（红色）
+3. 点击后查看：
+   - Request URL
+   - Status Code
+   - Response（响应内容）
+   - 截图发给我
+
+### 步骤4：浏览器信息
+告诉我：
+- 使用的浏览器（Chrome/Edge/Firefox）
+- 浏览器版本
+
+---
+
+## 💡 可能的原因分析
+
+### 原因1：时序问题
+- 前端加载太快，后端还没完全启动
+- **解决：** 等待10秒后刷新页面
+
+### 原因2：CORS问题
+- 跨域请求被阻止
+- **检查：** 浏览器控制台是否有CORS错误
+- **解决：** 后端已配置CORS，应该不会有此问题
+
+### 原因3：代理配置
+- Vite代理配置失效
+- **检查：** Network标签中请求URL是否正确
+- **解决：** 重启前端服务
+
+### 原因4：防火墙/杀毒软件
+- 拦截了本地请求
+- **解决：** 临时关闭防火墙测试
+
+---
+
+## 🎯 推荐的完整测试流程
+
+```powershell
+# 1. 停止所有服务
+双击：停止所有服务.bat
+
+# 2. 检查端口是否释放
+双击：查看端口占用.bat
+# 应该显示：端口3000和3001都空闲
+
+# 3. 启动服务
+双击：一键启动.bat
+
+# 4. 等待15秒（让服务完全启动）
+
+# 5. 打开无痕模式浏览器
+Ctrl + Shift + N
+
+# 6. 访问系统
+http://localhost:3000
+
+# 7. 按F12打开开发者工具
+
+# 8. 刷新页面（Ctrl + Shift + R）
+
+# 9. 查看Console是否有错误
+
+# 10. 查看Network请求状态
+```
+
+---
+
+## 📋 快速自检清单
+
+测试前，请确认：
+
+- [ ] ✅ 后端终端显示"服务器启动成功"
+- [ ] ✅ 前端终端显示"Local: http://localhost:3000/"
+- [ ] ✅ 访问 http://localhost:3001/health 返回正常
+- [ ] ✅ 访问 http://localhost:3001/api/v1/projects 返回正常
+- [ ] ✅ 浏览器已清除缓存（Ctrl + Shift + R）
+- [ ] ✅ 开发者工具Network显示请求成功（200）
+- [ ] ✅ 开发者工具Console没有错误
+
+---
+
+## 🆘 如果仍然失败
+
+请提供以下信息：
+
+1. **浏览器控制台截图**（F12 → Console标签）
+2. **Network请求详情截图**（F12 → Network标签 → 失败的请求）
+3. **后端终端日志**（最近20行）
+4. **前端终端日志**（最近20行）
+5. **运行结果：**
+   ```
+   浏览器访问 http://localhost:3001/health
+   浏览器访问 http://localhost:3001/api/v1/projects
+   ```
+
+---
+
+**🎯 第一步：请先尝试 Ctrl + Shift + R 强制刷新浏览器！**
+
+这通常能解决90%的问题！
+