aurak/docs/feishu-assessment-integration-summary.md

# 飞书机器人与人才测评集成 - 设计摘要

> **文档版本**: v1.0  
> **创建日期**: 2026-03-17  
> **完整文档**: [feishu-assessment-integration-design.md](./feishu-assessment-integration-design.md)

---

## 一、核心问题

### 1. 飞书机器人当前对接哪个知识库？
**答案**：当前使用**默认知识库**（用户的所有文件）

**原因**：在 `feishu.service.ts` 中调用 `chatService.streamChat()` 时，`selectedFiles` 和 `selectedGroups` 参数均为 `undefined`，导致搜索用户所有文件。

### 2. 如何与人才测评对接？
**答案**：通过**自然语言命令**触发测评功能

**命令格式**：
- `/assessment start [kbId|templateId]` - 开始测评
- `/assessment answer [answer]` - 提交答案
- `/assessment status` - 查看状态
- `/assessment result` - 获取结果

---

## 二、设计方案

### 方案 1：知识库选择机制

#### 数据库变更
在 `FeishuBot` 实体中新增字段：
```typescript
knowledgeBaseId: string;      // 特定知识库ID
knowledgeGroupId: string;     // 知识组ID
```

#### 选择逻辑
1. **配置了 knowledgeBaseId** → 搜索该知识库的文件
2. **配置了 knowledgeGroupId** → 搜索该知识组的文件
3. **都未配置** → 搜索用户所有文件（默认行为）

### 方案 2：测评集成

#### 架构设计
```
用户消息 → 命令解析器 → 测评服务 → 人才测评模块
                    ↓
                聊天服务（非测评消息）
```

#### 核心组件
1. **AssessmentCommandParser** - 命令解析器
2. **FeishuAssessmentService** - 测评服务
3. **FeishuAssessmentSession** - 会话实体

#### 交互流程
```
1. 用户: /assessment start
2. 系统: 创建测评会话，发送第一个问题卡片
3. 用户: 回复答案
4. 系统: 评估答案，发送下一个问题
5. ... 循环直到测评完成
6. 系统: 发送测评结果报告
```

---

## 三、实施步骤

### 阶段 1：基础架构（1-2 天）
- [ ] 添加数据库字段和迁移脚本
- [ ] 更新 FeishuBot 实体和 DTO
- [ ] 修改 FeishuService 支持知识库选择

### 阶段 2：测评集成（2-3 天）
- [ ] 创建测评会话实体和迁移
- [ ] 实现命令解析器
- [ ] 实现测评服务
- [ ] 设计飞书卡片模板

### 阶段 3：测试优化（1-2 天）
- [ ] 单元测试和集成测试
- [ ] 性能测试
- [ ] 文档编写

---

## 四、关键代码示例

### 4.1 知识库选择逻辑
```typescript
// feishu.service.ts
async processChatMessage(bot: FeishuBot, ...) {
    let selectedFiles: string[] | undefined;
    let selectedGroups: string[] | undefined;
    
    if (bot.knowledgeBaseId) {
        selectedFiles = await this.getFilesByKnowledgeBase(bot.knowledgeBaseId, ...);
    } else if (bot.knowledgeGroupId) {
        selectedGroups = [bot.knowledgeGroupId];
    }
    
    const stream = this.chatService.streamChat(
        userMessage,
        [],
        userId,
        llmModel,
        language,
        undefined,
        selectedGroups,  // 使用配置的知识组
        selectedFiles,   // 使用配置的知识库文件
        // ...
    );
}
```

### 4.2 命令处理逻辑
```typescript
// feishu-assessment.service.ts
async handleCommand(bot: FeishuBot, openId: string, message: string) {
    const command = this.commandParser.parse(message);
    
    if (!command) {
        // 非测评命令，使用默认聊天
        await this.feishuService.processChatMessage(bot, openId, '', message);
        return;
    }
    
    switch (command.type) {
        case AssessmentCommandType.START:
            await this.startAssessment(bot, openId, command.parameters);
            break;
        case AssessmentCommandType.ANSWER:
            await this.submitAnswer(bot, openId, command.parameters[0]);
            break;
        // ...
    }
}
```

---

## 五、API 接口

### 5.1 飞书机器人管理
```http
POST /feishu/bots
{
    "appId": "cli_xxx",
    "appSecret": "xxx",
    "knowledgeBaseId": "kb_xxx",      // 可选
    "knowledgeGroupId": "group_xxx"   // 可选
}
```

### 5.2 测评会话管理
```http
POST /feishu/assessment/start
{
    "botId": "bot_xxx",
    "openId": "ou_xxx",
    "knowledgeBaseId": "kb_xxx",
    "templateId": "tmpl_xxx"
}
```

---

## 六、安全考虑

1. **多租户隔离**：所有查询必须包含 `userId` 和 `tenantId`
2. **命令验证**：白名单命令验证，防止注入
3. **会话超时**：测评会话设置 24 小时超时
4. **数据隐私**：测评结果仅对授权用户可见

---

## 七、文件清单

### 需要创建的文件
1. `server/src/feishu/entities/feishu-assessment-session.entity.ts`
2. `server/src/feishu/dto/assessment-command.dto.ts`
3. `server/src/feishu/services/assessment-command.parser.ts`
4. `server/src/feishu/services/feishu-assessment.service.ts`
5. `server/src/migrations/XXXXXX-AddFeishuBotKnowledgeFields.ts`
6. `server/src/migrations/XXXXXX-CreateFeishuAssessmentSessionTable.ts`

### 需要修改的文件
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.module.ts`

---

## 八、总结

| 问题 | 答案 |
|------|------|
| 飞书机器人当前对接哪个知识库？ | 默认知识库（用户所有文件） |
| 如何配置特定知识库？ | 在 FeishuBot 实体中设置 knowledgeBaseId 或 knowledgeGroupId |
| 如何与人才测评对接？ | 通过 `/assessment` 命令触发测评功能 |
| 实施周期 | 5-7 天 |

---

**完整设计文档**: [feishu-assessment-integration-design.md](./feishu-assessment-integration-design.md)