aurak/docs/debugging-checklist.md

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 - 类型定义