Developer
8686d101cd
## 已实现功能 - 题库管理后端API完整实现 - 模板管理页面(Settings-测评模板) - 评估统计页面 - 人才测评页面(AssessmentView) - QuestionBank前端服务层 ## 技术栈 - 后端: Node.js + NestJS + TypeORM - 前端: React + TypeScript - 容器化: Docker Compose ## 已知待完善 - 题库列表页缺少删除按钮 - 题库详情页未实现(题目管理/AI生成/审核)
176 lines
4.8 KiB
Markdown
176 lines
4.8 KiB
Markdown
# 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` - 类型定义 |