forked from hangshuo652/aurak
Developer
0a9588abb7
- Add pagination support to findAll (page, limit query params) - Add findByTemplateId method to service - Add GET /by-template/:templateId endpoint to controller - Service already includes CRUD for QuestionBank and QuestionBankItem
298 lines
8.2 KiB
Markdown
298 lines
8.2 KiB
Markdown
# 飞书机器人与人才测评集成 - 实现总结
|
||
|
||
> **文档版本**: v1.0
|
||
> **创建日期**: 2026-03-17
|
||
> **状态**: 实现完成
|
||
|
||
---
|
||
|
||
## 一、实现概述
|
||
|
||
### 已完成的功能
|
||
1. ✅ **知识库选择机制** - 飞书机器人支持配置特定知识库或知识组
|
||
2. ✅ **命令解析器** - 支持多种语言的测评命令识别
|
||
3. ✅ **测评会话管理** - 完整的会话生命周期管理
|
||
4. ✅ **飞书卡片交互** - 友好的问题展示和结果报告
|
||
|
||
### 架构图
|
||
```
|
||
用户消息
|
||
↓
|
||
FeishuController._handleMessage()
|
||
↓
|
||
[命令识别] → 是测评命令? → FeishuAssessmentService.handleCommand()
|
||
↓ ↓
|
||
否 命令解析器
|
||
↓ ↓
|
||
FeishuService.processChatMessage() 执行对应操作
|
||
↓ ↓
|
||
ChatService.streamChat() [开始/回答/状态/结果]
|
||
↓ ↓
|
||
RAG搜索 + LLM生成 AssessmentService
|
||
↓ ↓
|
||
飞书消息回复 飞书消息回复
|
||
```
|
||
|
||
---
|
||
|
||
## 二、数据库变更
|
||
|
||
### 1. FeishuBot 实体新增字段
|
||
**文件**: `server/src/feishu/entities/feishu-bot.entity.ts`
|
||
|
||
```typescript
|
||
@Column({ name: 'knowledge_base_id', nullable: true, length: 36 })
|
||
knowledgeBaseId: string;
|
||
|
||
@Column({ name: 'knowledge_group_id', nullable: true, length: 36 })
|
||
knowledgeGroupId: string;
|
||
```
|
||
|
||
### 2. 新增测评会话表
|
||
**文件**: `server/src/feishu/entities/feishu-assessment-session.entity.ts`
|
||
|
||
```sql
|
||
CREATE TABLE feishu_assessment_sessions (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
bot_id VARCHAR(36) NOT NULL,
|
||
open_id VARCHAR(255) NOT NULL,
|
||
assessment_session_id VARCHAR(36) NOT NULL,
|
||
status ENUM('active', 'completed', 'cancelled') DEFAULT 'active',
|
||
current_question_index INT DEFAULT 0,
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
INDEX idx_bot_open (bot_id, open_id),
|
||
INDEX idx_assessment_session (assessment_session_id),
|
||
CONSTRAINT fk_feishu_assessment_bot
|
||
FOREIGN KEY (bot_id)
|
||
REFERENCES feishu_bots(id)
|
||
ON DELETE CASCADE
|
||
);
|
||
```
|
||
|
||
### 3. 迁移脚本
|
||
- `1773200000000-AddFeishuBotKnowledgeFields.ts` - 添加知识库字段
|
||
- `1773200000001-CreateFeishuAssessmentSessionTable.ts` - 创建测评会话表
|
||
|
||
---
|
||
|
||
## 三、核心组件实现
|
||
|
||
### 1. 命令解析器 (AssessmentCommandParser)
|
||
**文件**: `server/src/feishu/services/assessment-command.parser.ts`
|
||
|
||
**功能**：
|
||
- 识别测评命令前缀：`/assessment`, `/测评`, `/eval`, `/测评评估`
|
||
- 支持多语言命令：start/开始, answer/回答, status/状态, result/结果
|
||
- 解析命令参数
|
||
|
||
**示例**：
|
||
```typescript
|
||
const parser = new AssessmentCommandParser();
|
||
const command = parser.parse('/assessment start kb_xxx');
|
||
// 结果: { type: 'start', parameters: ['kb_xxx'], ... }
|
||
```
|
||
|
||
### 2. 测评服务 (FeishuAssessmentService)
|
||
**文件**: `server/src/feishu/services/feishu-assessment.service.ts`
|
||
|
||
**核心方法**：
|
||
- `handleCommand()` - 处理测评命令
|
||
- `startAssessment()` - 开始测评会话
|
||
- `submitAnswer()` - 提交答案
|
||
- `getStatus()` - 获取测评状态
|
||
- `getResult()` - 获取测评结果
|
||
- `cancelAssessment()` - 取消测评
|
||
|
||
**会话流程**：
|
||
1. 用户发送 `/assessment start`
|
||
2. 系统创建测评会话，发送第一个问题卡片
|
||
3. 用户回复答案（直接回复或 `/assessment answer`）
|
||
4. 系统评估答案，发送下一个问题
|
||
5. 重复步骤3-4直到完成
|
||
6. 系统发送测评结果报告
|
||
|
||
### 3. 集成到 FeishuService
|
||
**文件**: `server/src/feishu/feishu.service.ts`
|
||
|
||
**新增方法**：
|
||
```typescript
|
||
isAssessmentCommand(message: string): boolean {
|
||
const trimmed = message.trim().toLowerCase();
|
||
const commandPrefixes = ['/assessment', '/测评', '/eval', '/测评评估'];
|
||
return commandPrefixes.some(prefix => trimmed.startsWith(prefix.toLowerCase()));
|
||
}
|
||
```
|
||
|
||
### 4. 集成到 FeishuController
|
||
**文件**: `server/src/feishu/feishu.controller.ts`
|
||
|
||
**修改 _handleMessage 方法**：
|
||
```typescript
|
||
if (this.feishuService.isAssessmentCommand(userText)) {
|
||
// 委托给测评服务
|
||
await this.feishuAssessmentService.handleCommand(bot, openId, userText);
|
||
} else {
|
||
// 使用默认聊天处理
|
||
await this.feishuService.processChatMessage(bot, openId, messageId, userText);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、API 接口更新
|
||
|
||
### 1. 创建/更新飞书机器人
|
||
**端点**: `POST /feishu/bots`
|
||
|
||
**请求体**：
|
||
```json
|
||
{
|
||
"appId": "cli_xxx",
|
||
"appSecret": "xxx",
|
||
"botName": "测评机器人",
|
||
"knowledgeBaseId": "kb_xxx", // 可选：特定知识库
|
||
"knowledgeGroupId": "group_xxx" // 可选：知识组
|
||
}
|
||
```
|
||
|
||
### 2. 更新知识库配置
|
||
**端点**: `PATCH /feishu/bots/:id/knowledge`
|
||
|
||
**请求体**：
|
||
```json
|
||
{
|
||
"knowledgeBaseId": "kb_xxx",
|
||
"knowledgeGroupId": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、命令参考
|
||
|
||
### 支持的命令前缀
|
||
- `/assessment`
|
||
- `/测评`
|
||
- `/eval`
|
||
- `/测评评估`
|
||
|
||
### 命令列表
|
||
| 命令 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `start [kbId\|templateId]` | 可选 | 开始测评 |
|
||
| `answer [answer]` | 必需 | 提交答案 |
|
||
| `status` | - | 查看状态 |
|
||
| `result` | - | 获取结果 |
|
||
| `help` | - | 显示帮助 |
|
||
| `cancel` | - | 取消测评 |
|
||
|
||
### 使用示例
|
||
```
|
||
用户: /assessment start
|
||
系统: [发送第一个问题卡片]
|
||
|
||
用户: 这是我的答案
|
||
系统: [评估答案并发送下一个问题]
|
||
|
||
用户: /assessment status
|
||
系统: 测评状态: 进度 3/10, 状态: 进行中
|
||
|
||
用户: /assessment result
|
||
系统: [发送测评结果报告]
|
||
```
|
||
|
||
---
|
||
|
||
## 六、文件清单
|
||
|
||
### 新增文件
|
||
1. `server/src/feishu/dto/assessment-command.dto.ts` - 命令DTO
|
||
2. `server/src/feishu/entities/feishu-assessment-session.entity.ts` - 测评会话实体
|
||
3. `server/src/feishu/services/assessment-command.parser.ts` - 命令解析器
|
||
4. `server/src/feishu/services/feishu-assessment.service.ts` - 测评服务
|
||
5. `server/src/migrations/1773200000000-AddFeishuBotKnowledgeFields.ts` - 迁移脚本1
|
||
6. `server/src/migrations/1773200000001-CreateFeishuAssessmentSessionTable.ts` - 迁移脚本2
|
||
|
||
### 修改文件
|
||
1. `server/src/feishu/entities/feishu-bot.entity.ts` - 添加知识库字段
|
||
2. `server/src/feishu/dto/create-bot.dto.ts` - 添加知识库配置字段
|
||
3. `server/src/feishu/feishu.service.ts` - 添加命令识别方法
|
||
4. `server/src/feishu/feishu.controller.ts` - 集成测评服务
|
||
5. `server/src/feishu/feishu.module.ts` - 注册新服务
|
||
|
||
---
|
||
|
||
## 七、实施步骤
|
||
|
||
### 阶段 1: 基础架构 ✅
|
||
- [x] 创建数据库迁移脚本
|
||
- [x] 更新 FeishuBot 实体和 DTO
|
||
- [x] 修改 FeishuService 支持知识库选择
|
||
|
||
### 阶段 2: 测评集成 ✅
|
||
- [x] 创建测评会话实体
|
||
- [x] 实现命令解析器
|
||
- [x] 实现测评服务
|
||
- [x] 集成到 FeishuService 和 Controller
|
||
|
||
### 阶段 3: 测试优化 ⏳
|
||
- [ ] 运行数据库迁移
|
||
- [ ] 测试命令解析功能
|
||
- [ ] 测试完整测评流程
|
||
- [ ] 性能测试和优化
|
||
|
||
---
|
||
|
||
## 八、安全考虑
|
||
|
||
1. **多租户隔离**：所有查询包含 `userId` 和 `tenantId` 过滤
|
||
2. **命令验证**：白名单命令验证，防止注入攻击
|
||
3. **会话超时**：建议设置测评会话超时时间（如 24 小时）
|
||
4. **数据隐私**：测评结果仅对授权用户可见
|
||
|
||
---
|
||
|
||
## 九、下一步工作
|
||
|
||
1. **运行数据库迁移**
|
||
```bash
|
||
yarn migration:run
|
||
```
|
||
|
||
2. **测试命令解析**
|
||
```bash
|
||
node test-feishu-assessment.js
|
||
```
|
||
|
||
3. **集成测试**
|
||
- 创建飞书机器人
|
||
- 配置知识库
|
||
- 发送 `/assessment start` 命令
|
||
- 完成测评流程
|
||
|
||
4. **文档完善**
|
||
- 更新用户使用文档
|
||
- 添加 API 文档
|
||
- 编写故障排除指南
|
||
|
||
---
|
||
|
||
## 十、总结
|
||
|
||
本次实现完成了飞书机器人与人才测评的完整集成：
|
||
|
||
1. **知识库选择**：飞书机器人现在可以配置特定知识库或知识组
|
||
2. **命令解析**：支持多语言的测评命令识别
|
||
3. **会话管理**：完整的测评会话生命周期管理
|
||
4. **交互体验**：友好的飞书卡片交互
|
||
|
||
系统架构清晰，代码结构良好，易于维护和扩展。
|
||
|
||
---
|
||
|
||
**相关文档**:
|
||
- [完整设计文档](./feishu-assessment-integration-design.md)
|
||
- [设计摘要](./feishu-assessment-integration-summary.md)
|
||
- [快速参考](./QUICK-REFERENCE.md)
|