# 子Agent开发完成后的本地集成Todos清单

## 使用说明

完成子agent后端开发并手动Apply Changes Locally后，将此清单直接粘贴给子agent执行。
**重点：前端已开发完成，需要验证后端API与前端页面的完整对接。**

集成经验（必读）：/Users/nongjun/Desktop/Ai公司/本地开发与测试/考培练系统规划/后端开发拆分策略/子agent/00-通用基础/integration_experience.md

---

## 📋 集成Todos清单

### 🔧 配置检查与修复

- [ ] 检查并创建.env文件（如不存在则从.env.example复制）
- [ ] 确认数据库配置：`DATABASE_URL=mysql+aiomysql://root:root@localhost:3306/kaopeilian?charset=utf8mb4`
- [ ] 安装/更新Python依赖：`pip install -r requirements/dev.txt`
- [ ] 检查是否有新模型文件在 `app/models/`目录

### 🗄️ 数据库迁移（注意：数据库已按设计对齐，无需重复初始化与插入内置测试数据）

- [ ] 如有新模型，生成迁移：`alembic revision --autogenerate -m "add new models"`
- [ ] 查看迁移文件：`ls migrations/versions/`
- [ ] 应用迁移：`alembic upgrade head`
- [ ] 校验视图存在：`SELECT * FROM v_user_course_progress LIMIT 1;`

> 说明：
> - 已存在并对齐的基础表（users/teams/user_teams/courses/.../training_*）不应被重复创建或清空。
> - 如需新增表或字段，请仅通过 Alembic 迁移进行增量更新。

### 🚀 服务启动

- [ ] 在 `kaopeilian-backend/`目录执行以下命令
- [ ] 启动MySQL和Redis：`docker-compose -f docker-compose.dev.yml up -d mysql redis`
- [ ] 验证服务状态：`docker-compose -f docker-compose.dev.yml ps`
- [ ] 启动后端服务：`uvicorn app.main:app --reload --host 0.0.0.0 --port 8000`
- [ ] 可选：使用Makefile快捷命令：`make migrate`、`make run`

### ✅ 后端API验证

- [ ] 健康检查：`curl http://localhost:8000/health`
- [ ] 访问API文档：`http://localhost:8000/docs`
- [ ] 测试新开发的API端点（依据OpenAPI文档与 `app/contracts`中的模块契约）
- [ ] 验证API响应格式：确保返回的JSON结构符合前端预期
- [ ] 测试认证授权：确认JWT token验证正常工作
- [ ] 测试错误处理：验证4xx/5xx错误返回格式正确

### 🌐 前后端对接验证（重要：前端已开发完成）

- [ ] 确认CORS配置：检查 `app/config/settings.py`中的 `CORS_ORIGINS`包含 `http://localhost:3001`
- [ ] 启动前端服务：`cd ../kaopeilian-frontend && npm run dev`
- [ ] 访问前端页面：`http://localhost:3001`
- [ ] 确认前端 `src/api/config.ts`的 `baseURL`为 `http://localhost:8000`
- [ ] 验证API接口对接：在前端页面测试新开发的后端功能
- [ ] 检查浏览器网络面板：确认API请求/响应格式正确
- [ ] 检查浏览器控制台：无CORS错误、无JS错误
- [ ] 测试前端页面功能：登录、数据加载、操作反馈等
- [ ] 验证数据流：前端操作→后端API→数据库→返回前端显示

### 🧪 测试验证

- [ ] 运行单元测试：`pytest tests/ -v`
- [ ] 检查测试覆盖率：`pytest --cov=app --cov-report=html tests/`
- [ ] 代码格式化：`black app/ tests/`
- [ ] 代码质量检查：`flake8 app/ tests/`

### 📝 文档更新

- [ ] 检查是否需要更新 `README.md`
- [ ] 检查是否需要更新 `数据库架构.md`
- [ ] 如有架构调整、配置变更、运行逻辑变更，必须更新相关文档

### 💾 代码提交

- [ ] 查看变更：`git status && git diff`
- [ ] 添加变更：`git add .`
- [ ] 提交变更：`git commit -m "feat(module): 描述变更内容"`
- [ ] 推送代码：`git push origin main`

### ⚠️ 问题排查（如遇到问题时执行）

- [ ] 数据库连接失败：检查 `docker-compose -f docker-compose.dev.yml logs mysql`
- [ ] CORS错误：检查 `app/config/settings.py`中的 `CORS_ORIGINS`
- [ ] 前端API调用失败：检查浏览器网络面板，确认请求URL和方法正确
- [ ] 前端页面显示异常：检查API返回的数据格式是否符合前端预期
- [ ] 认证问题：确认JWT token格式和过期时间设置正确
- [ ] 依赖冲突：删除venv重新创建虚拟环境
- [ ] 端口占用：`lsof -i :8000` 查看端口占用情况

---

## 🎯 最终验收标准

- [ ] 所有新增API端点正常响应
- [ ] 数据库迁移成功应用（无重复初始化）
- [ ] 单元测试通过率≥80%
- [ ] 前后端对接完全正常
- [ ] 文档已更新（如有架构/配置变更）
- [ ] 代码已提交到版本控制

---

**注意：此清单适用于考培练系统(Python+Vue3+MySQL+FastAPI)的本地开发测试环境**