ColaFlow/DEBUGGING_GUIDE.md

# ColaFlow API 连接问题诊断指南

## 修复完成时间
2025-11-03

## 问题描述
项目列表页面无法显示项目数据，前端可以访问但无法连接到后端 API。

## 已实施的修复

### 1. 增强 API 客户端调试（lib/api/client.ts）
- 添加了 API URL 的控制台日志输出
- 为每个请求添加详细的日志记录
- 增强错误处理和错误信息输出
- 捕获网络错误并输出详细信息

### 2. 改进项目页面错误显示（app/(dashboard)/projects/page.tsx）
- 显示详细的错误信息（而不是通用消息）
- 显示当前使用的 API URL
- 添加故障排查步骤
- 添加重试按钮
- 添加控制台调试日志

### 3. 增强 useProjects Hook（lib/hooks/use-projects.ts）
- 添加详细的日志记录
- 减少重试次数以更快失败（从 3次 降至 1次）
- 捕获并记录所有错误

## 如何使用调试功能

### 步骤 1: 重启前端开发服务器
```bash
cd colaflow-web
npm run dev
```

重启是必要的，因为 Next.js 需要重新加载以应用环境变量更改。

### 步骤 2: 打开浏览器开发工具
1. 访问 http://localhost:3000/projects
2. 按 F12 打开开发者工具
3. 切换到 Console 标签页

### 步骤 3: 查看控制台输出
你应该看到以下日志：

```
[API Client] API_URL: http://localhost:5167/api/v1
[API Client] NEXT_PUBLIC_API_URL: http://localhost:5167/api/v1
[useProjects] Fetching projects... {page: 1, pageSize: 20}
[API Client] Request: {method: 'GET', url: 'http://localhost:5167/api/v1/projects?page=1&pageSize=20', endpoint: '/projects?page=1&pageSize=20'}
```

如果出现错误，你会看到：
```
[API Client] Network error: {url: '...', error: 'Failed to fetch', errorObject: ...}
[useProjects] Fetch failed: TypeError: Failed to fetch
[ProjectsPage] Error loading projects: TypeError: Failed to fetch
```

### 步骤 4: 检查网络请求
1. 在开发者工具中切换到 Network 标签页
2. 刷新页面
3. 查找对 `http://localhost:5167/api/v1/projects` 的请求
4. 检查请求状态：
   - **失败/红色**: 服务器未响应
   - **404**: 路由不存在
   - **500**: 服务器错误
   - **CORS错误**: 跨域配置问题

### 步骤 5: 查看错误屏幕
如果 API 无法连接，页面会显示详细的错误卡片：
- **Error Details**: 具体的错误消息
- **API URL**: 当前配置的 API 地址
- **Troubleshooting Steps**: 故障排查步骤
- **Retry按钮**: 点击重试

## 常见问题诊断

### 问题 1: "Failed to fetch" 错误
**原因**: 后端服务器未运行或无法访问

**解决方案**:
```bash
# 检查后端是否在运行
curl http://localhost:5167/api/v1/health

# 如果失败，启动后端服务器
cd ColaFlow.Api
dotnet run
```

### 问题 2: API URL 使用默认端口 5000
**原因**: 环境变量未正确加载

**解决方案**:
1. 检查 `.env.local` 文件是否存在且包含：
   ```
   NEXT_PUBLIC_API_URL=http://localhost:5167/api/v1
   ```
2. 重启 Next.js 开发服务器
3. 确保没有 `.env` 文件覆盖设置

### 问题 3: CORS 错误
**原因**: 后端未配置允许前端域名

**解决方案**: 检查后端 CORS 配置（ColaFlow.Api/Program.cs）:
```csharp
builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowFrontend", policy =>
    {
        policy.WithOrigins("http://localhost:3000")
              .AllowAnyMethod()
              .AllowAnyHeader();
    });
});
```

### 问题 4: 404 错误
**原因**: API 路由不存在或路径不正确

**解决方案**:
1. 检查后端路由配置
2. 确认 API 前缀是 `/api/v1`
3. 检查控制器路由是否正确

## 验证修复

### 成功的日志输出示例
```
[API Client] API_URL: http://localhost:5167/api/v1
[useProjects] Fetching projects...
[API Client] Request: GET http://localhost:5167/api/v1/projects?page=1&pageSize=20
[API Client] Response: {url: '...', status: 200, data: [...]}
[useProjects] Fetch successful: [...]
[ProjectsPage] State: {isLoading: false, error: null, projects: [...]}
```

### 检查清单
- [ ] 控制台显示正确的 API URL (5167端口)
- [ ] 网络请求显示 200 状态码
- [ ] 控制台显示成功的响应数据
- [ ] 页面显示项目列表或"No projects yet"消息
- [ ] 没有错误消息或红色日志

## 下一步行动

### 如果问题仍然存在：
1. **检查后端日志**: 查看后端控制台输出
2. **测试 API 直接访问**: 使用 curl 或 Postman 测试 API
3. **检查防火墙**: 确保端口 5167 未被阻止
4. **检查端口冲突**: 确认没有其他程序使用 5167 端口

### 如果问题已解决：
1. 移除调试日志（生产环境）
2. 添加更好的错误处理
3. 考虑添加 API 健康检查端点
4. 实施重试逻辑和超时处理

## 相关文件
- `colaflow-web/lib/api/client.ts` - API 客户端配置
- `colaflow-web/lib/hooks/use-projects.ts` - Projects 数据 hook
- `colaflow-web/app/(dashboard)/projects/page.tsx` - 项目列表页面
- `colaflow-web/.env.local` - 环境变量配置

## Git 提交
- Commit: `fix(frontend): Add comprehensive debugging for API connection issues`
- Branch: main
- Files changed: 3 (client.ts, use-projects.ts, page.tsx)

---

**注意**: 这些调试日志在开发环境很有用，但在生产环境应该移除或使用日志级别控制。