# AuraK 系统调试检查清单

## 一、数据库问题

### 1.1 SQLite 类型兼容
- [ ] Entity 使用 `simple-enum` 而非 `enum`
- [ ] 移除 `@Column` 的 `default` 值（SQLite不支持enum默认值）
- [ ] 所有 `@Column` 必须指定 `type`（如 `type: 'text'`）

### 1.2 Null 值处理
- [ ] 查询时处理 null：`WHERE column IS NULL` 而非 `= NULL`
- [ ] Service 方法处理 `tenantId: null` 情况
- [ ] Entity 字段标记 `nullable: true`

### 1.3 数据库重置
- [ ] 删除数据库后重新创建会导致所有数据丢失
- [ ] 确认是否有备份或可以恢复

---

## 二、API 前后端一致性

### 2.1 HTTP 方法
- [ ] POST 创建资源
- [ ] PUT 更新资源
- [ ] GET 获取资源
- [ ] DELETE 删除资源

### 2.2 端点匹配
- [ ] 前端 service 调用的端点与后端 controller 一致
- [ ] 特别注意：后端用 PUT 但前端用 POST 的情况
- [ ] 检查新增的 API 路由是否已添加

### 2.3 路由传参
- [ ] RESTful 路径参数：`:id`, `:bankId`
- [ ] Query 参数：`?page=1&limit=10`
- [ ] Body 参数：JSON 请求体

---

## 三、题库模块检查点

### 3.1 后端 Entity
- [ ] `QuestionBank` - simple-enum 类型，无默认值
- [ ] `QuestionBankItem` - 所有 enum 字段使用 simple-enum
- [ ] `status` 字段必须有默认值（在 service 层设置）

### 3.2 后端 Service
- [ ] `create()` - 验证 name 不为空
- [ ] `addItem()` - 验证 questionText 不为空，设置 status 默认值
- [ ] `generateQuestions()` - AI 生成时设置 status
- [ ] `findAll()` - 处理 tenantId 为 null 的查询
- [ ] `create()` - 处理 tenantId 为 null 的创建

### 3.3 后端 Controller
- [ ] GET `/items` 路由存在
- [ ] 路由方法与 service 方法匹配（PUT vs POST）

### 3.4 前端 Service
- [ ] `submitForReview` - 使用 PUT
- [ ] `approveBank/rejectBank` - 使用 `/review` 端点
- [ ] `publishBank` - 使用 PUT
- [ ] `getBankItems` - 调用正确的端点

### 3.5 前端 Component
- [ ] 组件已正确 export
- [ ] 路由已添加到 index.tsx
- [ ] Service 调用正确

---

## 四、评估流程检查点

### 4.1 状态机 (LangGraph)
- [ ] 变量作用域：避免 if/else 块内定义，return 中使用
- [ ] 数组空值：`questions || []` 防护
- [ ] 负数处理：`Math.max(0, remaining)`

### 4.2 API 一致性
- [ ] 前端使用 `/answer` 还是 `/answer-stream`
- [ ] 后端响应格式与前端期望一致

---

## 五、模型配置检查点

### 5.1 LLM 配置
- [ ] Base URL 正确（官方API vs 本地部署）
- [ ] Model ID 正确
- [ ] API Key 配置

### 5.2 Embedding 配置
- [ ] 向量维度匹配（Ollama nomic-embed-text 为 768维）
- [ ] 服务可访问（IP/端口映射）

---

## 六、调试技巧

### 6.1 日志添加
- [ ] 后端：console.log 在关键方法
- [ ] 前端：console.log 在 API 调用前后
- [ ] 日志包含关键变量值

### 6.2 检查步骤
1. 查看 Docker logs：`docker compose logs server --tail 50`
2. 查看前端 Console（F12）
3. 查看 Network 面板请求响应
4. 直接调用 API 测试

### 6.3 常见症状
- [ ] 弹窗显示成功但数据未更新 → API 可能失败，检查返回数据格式
- [ ] 页面空白无数据 → 检查 API 是否被调用，参数是否正确
- [ ] 403 权限错误 → 检查用户角色是否匹配

---

## 七、重启前检查清单

### 代码层面
- [ ] 所有修改的文件已保存
- [ ] 没有语法错误
- [ ] import 语句正确

### 构建层面
- [ ] `docker compose build` 成功
- [ ] 无新增的编译错误

### 测试层面
- [ ] 服务启动成功
- [ ] 登录功能正常
- [ ] 目标功能可访问

---

## 八、典型问题模式

### 问题1：新增功能不工作
**检查顺序：**
1. 后端 entity 是否注册到 app.module
2. 后端 service 是否在 module 中提供
3. 后端 controller 是否有对应路由
4. 前端 service 是否调用正确端点
5. 前端 component 是否正确 import 和 export
6. 前端 route 是否添加

### 问题2：数据创建成功但查询不到
**检查顺序：**
1. tenantId 是否正确设置
2. 查询条件是否匹配（== vs IS NULL）
3. 权限是否正确

### 问题3：类型不匹配
**检查顺序：**
1. 后端 entity 类型
2. 后端 DTO 类型
3. 前端 service 接口类型
4. 前端 types 定义
5. API 响应格式

---

## 九、相关文件位置

### 后端核心
- `server/src/app.module.ts` - Entity 注册
- `server/src/assessment/assessment.module.ts` - 模块配置
- `server/src/assessment/entities/` - 数据实体
- `server/src/assessment/services/question-bank.service.ts` - 业务逻辑
- `server/src/assessment/controllers/question-bank.controller.ts` - API 路由

### 前端核心
- `web/index.tsx` - 路由配置
- `web/services/questionBankService.ts` - API 调用
- `web/components/views/QuestionBankView.tsx` - 页面组件
- `web/types.ts` - 类型定义