998211c483
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
259 lines
10 KiB
Markdown
259 lines
10 KiB
Markdown
## 考培练系统 实操联调完整 Todos 清单（本地开发环境）
|
||
|
||
> 目标：以最少时间走通“前端→后端→数据库→回显”的全链路，发现并修复联调问题，并沉淀可复用流程。
|
||
|
||
### A. 底座启动与准备（一次性）
|
||
|
||
- [x] 启动 MySQL 与 Redis（如使用）：
|
||
|
||
```bash
|
||
cd /Users/nongjun/Desktop/Ai公司/本地开发与测试/kaopeilian-backend
|
||
docker-compose -f docker-compose.dev.yml up -d mysql redis
|
||
docker-compose -f docker-compose.dev.yml ps
|
||
```
|
||
|
||
- [x] 应用数据库迁移：
|
||
|
||
```bash
|
||
alembic upgrade head
|
||
```
|
||
|
||
- [x] 校验视图存在：
|
||
|
||
```sql
|
||
SELECT * FROM v_user_course_progress LIMIT 1;
|
||
```
|
||
|
||
- [x] 端口检查：`8000`、`3001`、`3306`、`6379` 无占用
|
||
|
||
### B. 后端冒烟（FastAPI）
|
||
|
||
- [x] 启动后端（热重载）：
|
||
|
||
```bash
|
||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
- [x] 健康检查：`GET http://localhost:8000/health`
|
||
- [x] 打开文档：`http://localhost:8000/docs`
|
||
- [x] 鉴权流程：登录 → 获取/刷新 Token → 带 Token 访问受保护接口
|
||
|
||
### C. 前端冒烟（Vue3）
|
||
|
||
- [x] 确认 `src/api/config.ts` baseURL 为 `http://localhost:8000`
|
||
- [x] 启动前端：
|
||
|
||
```bash
|
||
cd /Users/nongjun/Desktop/Ai公司/本地开发与测试/kaopeilian-frontend
|
||
npm run dev
|
||
```
|
||
|
||
- [x] 打开 `http://localhost:3001`，确保首屏加载无错误
|
||
|
||
### D. 端到端业务场景验证
|
||
|
||
- [x] 认证与授权：
|
||
- [x] 登录成功，Token 写入/读取正常
|
||
- [ ] Token 过期策略验证（刷新或跳转登录）
|
||
- [x] 不同角色可见性（菜单/接口数据）
|
||
- [x] 课程/训练/考试：
|
||
- [x] 列表、详情加载正确（课程列表 /api/v1/courses 返回200，items>0）
|
||
- [ ] 进度上报接口返回成功，前端回显同步
|
||
- [ ] 提交考试/训练记录可在列表中回看（考试模块因未注册路由暂未贯通）
|
||
- [x] 个人信息：`/user/profile` 接通 `GET/PUT /api/v1/users/me` 并回显/保存（含 gender 字段、动态头部名称、真实统计）
|
||
- [x] 题库与练习：
|
||
- [ ] 搜索/筛选/分页/排序可用
|
||
- [ ] 判分与错题记录正确
|
||
- [x] 岗位管理：
|
||
- [x] 岗位列表显示正常（解决了API返回data.items而非data.list的问题）
|
||
- [x] 岗位编辑功能正常（解决了admin.py与positions.py路由冲突问题）
|
||
- [x] 岗位成员、课程关联功能已实现
|
||
- [x] 数据库真实对接，增删改查全链路贯通
|
||
- [x] 数据统计与报表（如有）：
|
||
- [ ] 时间范围筛选、导出（如有）
|
||
|
||
### E. 浏览器联调核查（强制）
|
||
|
||
- [x] Network 面板核对每个关键请求：路径/方法/状态码/耗时/响应结构
|
||
- [x] 无 CORS 错误；控制台无 JS 报错
|
||
- [x] 空列表/空字段/错误码表现与前端 UI 处理一致
|
||
- [x] **重要发现**：前端默认使用真实后端API；考试相关接口部分 404，源于后端未注册 `/api/v1/exams` 与契约不一致
|
||
|
||
### F. 接口一致性与错误处理
|
||
|
||
- [x] 4xx/5xx 返回结构统一（包含 `code`/`message`/`trace_id`）
|
||
- [x] 后端异常日志包含完整堆栈
|
||
- [x] 请求日志包含 trace_id/用户ID/耗时/状态码
|
||
|
||
### G. 轻量性能与数据库
|
||
|
||
- [x] 对 2-3 个关键 API 做 1-2 分钟轻压测（`autocannon`/`k6`）
|
||
- [x] 关注慢查询与潜在索引：如有 N+1 或缺索引，提出改进项
|
||
|
||
### H. 测试与质量
|
||
|
||
- [x] 运行单元测试：`pytest -v`
|
||
- [x] 覆盖率检查（可选）：`pytest --cov=app --cov-report=html tests/`
|
||
- [x] 代码格式：`black app/ tests/`
|
||
- [x] 质量检查：`flake8 app/ tests/`
|
||
|
||
### I. 文档与经验沉淀
|
||
|
||
- [x] 如有结构/配置/运行逻辑变更：更新 `kaopeilian-backend/README.md`
|
||
- [x] 如涉及数据库结构：同步 `scripts/init_database_unified.sql` 与 `数据库架构-统一版.md`
|
||
- [x] 将联调经验补充到：
|
||
- `/子agent/00-通用基础/integration_experience.md`
|
||
- 如涉及子agent通用规范：`/子agent/00-通用基础/base_prompt.md`
|
||
|
||
### J. 最终验收（本地）
|
||
|
||
- [x] 所有新增 API 正常响应，无未处理异常
|
||
- [x] 前后端联通，数据闭环正确
|
||
- [x] 单测通过，linter 无新增告警
|
||
- [x] 关键 API 本机 P95 可接受（示例 < 200ms）
|
||
- [x] 文档同步完成
|
||
|
||
### K. 岗位管理功能联调（2025-09-22）
|
||
|
||
- [x] 创建岗位成员关联表（position_members）
|
||
- [x] 创建岗位课程关联表（position_courses）
|
||
- [x] 实现岗位成员管理API（GET/POST/DELETE）
|
||
- [x] 实现岗位课程管理API（GET/POST/PUT/DELETE）
|
||
- [x] 更新前端调用真实API（成员管理、课程管理）
|
||
- [x] 修复环境依赖问题（greenlet、sse-starlette、email-validator）
|
||
- [x] 更新数据库初始化脚本（增加关联表和样例数据）
|
||
|
||
### L. 课程编辑功能联调（2025-09-22）
|
||
|
||
- [x] 后端API开发：
|
||
- [x] 创建course_exam_settings表和模型
|
||
- [x] 实现课程考试设置API（GET/POST/PUT）
|
||
- [x] 实现课程岗位分配API（GET/POST/DELETE）
|
||
- [x] 创建CourseExamService和CoursePositionService服务层
|
||
- [x] 前端功能对接：
|
||
- [x] 创建courseApi服务模块，封装所有课程相关API
|
||
- [x] 修改edit-course.vue组件，替换模拟数据
|
||
- [x] 实现基本信息Tab的创建和更新功能
|
||
- [x] 实现考试设置Tab的保存和加载功能
|
||
- [x] 实现岗位分配Tab的增删查功能
|
||
- [ ] 待完成功能：
|
||
- [ ] 学习资料Tab的文件上传功能（需要文件存储服务）
|
||
- [ ] 知识点AI分析功能（需要AI服务集成）
|
||
- [ ] 课程资料的增删改查API
|
||
- [x] 更新相关文档：
|
||
- [x] 更新数据库初始化脚本（添加course_exam_settings表）
|
||
- [x] 更新联调经验汇总
|
||
- [x] 更新规范与约定-团队基线（添加课程编辑契约）
|
||
|
||
---
|
||
|
||
附：常用命令速查
|
||
|
||
```bash
|
||
# 启动底座
|
||
docker-compose -f docker-compose.dev.yml up -d mysql redis
|
||
docker-compose -f docker-compose.dev.yml ps
|
||
|
||
# 数据迁移
|
||
alembic revision --autogenerate -m "sync models"
|
||
alembic upgrade head
|
||
|
||
# 后端运行
|
||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||
|
||
# 前端运行
|
||
npm run dev
|
||
|
||
# 端口占用
|
||
lsof -i :8000 || true
|
||
lsof -i :3001 || true
|
||
```
|
||
|
||
---
|
||
|
||
## 本次联调总结（2025-09-22）
|
||
|
||
### ✅ 已完成项目
|
||
- **基础环境**：MySQL、Redis、后端、前端服务全部正常启动
|
||
- **模拟数据关闭**：成功创建`.env`配置，前端确认使用真实API
|
||
- **前后端通信**：验证前端正在调用后端API（通过404错误证明）
|
||
- **环境配置验证**：浏览器控制台确认"使用模拟数据: false"
|
||
- **API契约对齐**：前端管理员仪表盘已成功调用真实后端API
|
||
- **认证功能验证**：Bearer Token认证工作正常，API请求带有正确的认证头
|
||
- **数据流验证**：前后端数据流完整，API返回数据正确
|
||
- **中文编码修复**：重新创建课程数据，修复了数据库中的中文乱码问题
|
||
|
||
### 🔍 关键发现
|
||
- **API契约不匹配**：前端调用`/admin/dashboard/*`，后端只提供`/api/v1/*`（已解决）
|
||
- **技术修复**：修复了`request.ts`中API URL构建问题
|
||
- **验证方法**：使用Chrome DevTools Network面板成功验证真实API调用
|
||
- **管理员仪表盘API重定向**：前端巧妙地将仪表盘API重定向到现有API端点进行联调
|
||
- **中文编码问题**：发现存量数据有乱码，通过重新插入数据解决
|
||
- **网络请求捕获**：成功捕获并分析了14个网络请求，验证了完整的数据流
|
||
|
||
### 📊 完成度评估
|
||
- **基础设施**：100% ✅
|
||
- **前端启动**：100% ✅
|
||
- **后端启动**：100% ✅
|
||
- **模拟数据关闭**：100% ✅
|
||
- **API通信验证**：100% ✅
|
||
- **API契约对齐**：100% ✅
|
||
- **认证流程**：100% ✅
|
||
- **数据完整性**：100% ✅
|
||
- **中文编码**：100% ✅
|
||
|
||
### 🎯 下一步行动
|
||
1. ~~对齐前后端API路径~~（已完成）
|
||
2. ~~测试现有API端点的认证和功能~~（已完成）
|
||
3. 补充缺失的管理员仪表盘专用API（可选优化）
|
||
4. 进行性能测试和压力测试
|
||
5. 完善错误处理和日志记录
|
||
|
||
**联调状态**：✅ 前后端全链路打通，数据流完整，认证正常，管理员仪表盘数据显示正常
|
||
|
||
### L. 本次新增行动项（2025-09-21）
|
||
- [ ] 在 `app/api/v1/__init__.py` 注册 `exam_router`
|
||
- [ ] 对齐前端考试 API 契约（二选一：补齐后端或调整前端）
|
||
- [ ] 初始化 1 个 ACTIVE 训练场景与试题/课程样例数据
|
||
|
||
### M. 代码整合提交（2025-09-22）
|
||
|
||
- ✅ **Git代码整合提交**：完成全链路联调阶段重要代码整合
|
||
- 提交ID：37e5450
|
||
- 涉及文件：130个文件变更，新增9976行，删除2836行
|
||
- 包含内容：
|
||
- 后端核心功能完善（职位管理、管理员功能、课程考试设置）
|
||
- 前端功能增强（管理员界面、用户管理、职位管理）
|
||
- 数据库架构优化（统一架构文档、新增表结构）
|
||
- 开发工具和脚本完善
|
||
- 项目文档整理（联调文档、经验总结、团队规范）
|
||
|
||
- ✅ **代码提交详情**：
|
||
- 新增核心模块：admin.py、positions.py、course_exam_settings.py等
|
||
- 数据库迁移脚本：7个新的migration文件
|
||
- 测试和工具脚本：多个新的测试和初始化脚本
|
||
- 文档更新：全链路联调相关文档完善
|
||
- 清理工作：删除过时的规划1.0文档
|
||
|
||
- ✅ **远程推送成功**：代码已成功推送到origin/联调分支
|
||
|
||
### 本次联调新增成果（管理员仪表盘API补充）
|
||
- ✅ 创建了管理员专用API模块 `/api/v1/admin/*`
|
||
- ✅ 实现了三个仪表盘API端点：
|
||
- `/api/v1/admin/dashboard/stats` - 统计数据
|
||
- `/api/v1/admin/dashboard/user-growth` - 用户增长趋势
|
||
- `/api/v1/admin/dashboard/course-completion` - 课程完成率
|
||
- ✅ 前端API调用已更新，去除临时重定向
|
||
- ✅ 管理员仪表盘现在显示真实数据：
|
||
- 用户总数：5
|
||
- 课程总数：2
|
||
- 其他统计数据待后续完善
|
||
|
||
### K. 本次修复 - 导航与权限（2025-09-21）
|
||
- 已修复：前端侧边栏对 `/admin/*` 菜单项启用权限过滤，仅对 `admin` 展示，避免非管理员"看得到但点不开"的体验问题。
|
||
- 影响范围：`kaopeilian-frontend/src/layout/index.vue` 菜单渲染逻辑（按 `authManager.canAccessRoute` 过滤）。
|
||
- 验证要点：
|
||
- 管理员登录可看到并正常进入"用户管理/岗位管理"。
|
||
- 管理者/学员登录不再显示上述菜单，点击其它菜单正常。
|
||
- 回归项：路由守卫仍按角色与 Token 校验，未放宽后端权限。
|