## 考培练系统 一次性完成度核对清单（本地开发环境）

> 目的：在进入全链路联调前，快速、一次性核对系统完成度与基础环境是否准备就绪。

### 1. 仓库与分支

- [ ] 后端 `kaopeilian-backend` 在最新分支（如 `main`/`dev`），本地已拉取最新代码（`git pull`）
- [ ] 前端 `kaopeilian-frontend` 在最新分支（如 `main`/`dev`），本地已拉取最新代码

注意：以本地代码为准

### 2. 依赖与运行时

- [ ] Python 已安装（建议 3.10+），虚拟环境已激活
- [ ] 后端依赖已安装：

```bash
cd kaopeilian-backend
pip install -r requirements/dev.txt
```

- [ ] Node.js 已安装（建议 18+），前端依赖已安装：

```bash
cd ../kaopeilian-frontend
npm i
```

### 3. 环境变量与配置（仅本地 localhost 场景）

- [ ] 后端 `kaopeilian-backend/.env` 存在（如无请从 `.env.example` 复制）
- [ ] 数据库 URL 指向本地：
  - `DATABASE_URL=mysql+aiomysql://root:root@localhost:3306/kaopeilian?charset=utf8mb4`
- [ ] 鉴权配置存在：
  - `JWT_SECRET_KEY` 已设置（本地可使用安全的随机字符串）
  - `ACCESS_TOKEN_EXPIRE_MINUTES` 已设置
- [ ] 缓存配置（如使用）：
  - `REDIS_URL=redis://localhost:6379/0`
- [ ] CORS 配置：`CORS_ORIGINS` 包含 `http://localhost:3001`
- [ ] 日志级别：开发环境设置为 `INFO` 或 `DEBUG`；确保错误日志包含完整堆栈

### 4. 底座与数据库状态

- [ ] 使用 Docker 启动 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
```

- [ ] 数据迁移已到最新：

```bash
cd /Users/nongjun/Desktop/Ai公司/本地开发与测试/kaopeilian-backend
alembic upgrade head
```

- [ ] 关键视图/表可用，例如：

```sql
SELECT 1;
SELECT * FROM v_user_course_progress LIMIT 1;
```

- [ ] 已有模拟数据可查询（核心业务表存在数据）

### 5. 端口占用与网络

- [ ] 本机端口未被占用：`8000`（后端）、`3001`（前端）、`3306`（MySQL）、`6379`（Redis）

```bash
lsof -i :8000 || true
lsof -i :3001 || true
```

### 6. 后端（FastAPI）健康状况

- [ ] 以热重载启动后端（仅本地）：

```bash
cd /Users/nongjun/Desktop/Ai公司/本地开发与测试/kaopeilian-backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

- [ ] 健康检查通过：

```bash
curl http://localhost:8000/health
```

- [ ] 文档可访问：`http://localhost:8000/docs`
- [ ] 鉴权流程冒烟通过（登录/刷新/权限校验）

### 7. 前端（Vue3）配置与可用性

- [ ] `src/api/config.ts` 中 `baseURL` 为 `http://localhost:8000`
- [ ] 启动开发服务：

```bash
cd /Users/nongjun/Desktop/Ai公司/本地开发与测试/kaopeilian-frontend
npm run dev
```

- [ ] 访问 `http://localhost:3001` 正常

### 8. 前后端通信一致性

- [ ] 浏览器网络面板无 CORS 报错
- [ ] API 请求响应结构（字段名/层级/空值规则）与前端预期一致
- [ ] Token 持久化/刷新逻辑正常（过期后可刷新或正确跳转登录）

### 9. 日志与错误处理

- [ ] 后端日志区分级别（DEBUG/INFO/WARNING/ERROR）
- [ ] 关键操作（DB连接、外部调用）错误日志包含完整堆栈
- [ ] 有统一请求日志（含 trace_id/用户ID/耗时/状态码）便于排障

### 10. 质量与文档

- [ ] 单元测试可运行：`pytest -v` 通过
- [ ] 代码格式与质量：`black` 与 `flake8` 通过
- [ ] 如有结构/配置/运行逻辑变更：
  - 已更新 `kaopeilian-backend/README.md`
  - 如涉及数据库结构：已同步 `scripts/init_database_unified.sql` 与 `数据库架构-统一版.md`
  - 经验沉淀至：`子agent/00-通用基础/integration_experience.md`

### 11. 轻量性能与验收阈值（本地）

- [ ] 针对 2-3 个关键 API 做 1-2 分钟轻量压测（如 `autocannon` 或 `k6`）
- [ ] 本机 P95 延迟可接受（示例阈值：< 200ms），无错误峰值

---

完成以上核对后，可进入“实操联调完整 Todos 清单”。
