feat: implement QuestionBank CRUD with pagination and template query

- 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
2026-04-23 17:19:11 +08:00
commit 0a9588abb7
492 changed files with 112453 additions and 0 deletions
@@ -0,0 +1,955 @@
+# Feishu Bot Integration Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Enable Feishu (飞书) bot integration as a standalone **Plugin** that users can manage via the system's "Plugins" menu. This allows users to bind bots, interact with RAG, and access assessment features in a modular, plug-and-play fashion.
+
+**Architecture:** Implement the integration as a pluggable `FeishuModule`. It acts as a bridge between Feishu Open Platform and AuraK's core services. The plugin is managed through the new `/plugins` workspace, isolating its UI and backend logic from the core system.
+
+**Tech Stack:**
+- NestJS (existing)
+- Feishu Open Platform APIs (im/v1/messages, auth/v3/tenant_access_token)
+- Event subscription (Webhooks)
+- Existing: ChatService, AssessmentService, JWT Auth
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────┐      ┌──────────────┐      ┌─────────────┐
+│  Feishu User│─────▶│ Feishu Server│─────▶│  AuraK API  │
+│  (User A)   │◀─────│   Webhook    │◀─────│  /feishu/*  │
+└─────────────┘      └──────────────┘      └─────────────┘
+                                                      │
+                                                      ▼
+                                              ┌─────────────┐
+                                              │ FeishuModule│
+                                              │ - Bot Entity│
+                                              │ - Message   │
+                                              │ - Events    │
+                                              └─────────────┘
+                                                      │
+                              ┌───────────────────────┼───────────────────────┐
+                              ▼                       ▼                       ▼
+                      ┌─────────────┐        ┌─────────────┐        ┌─────────────┐
+                      │ ChatService │        │AssessmentSvc│        │ PluginsSvc  │
+                      │  (RAG Q&A)  │        │ (评测对话)   │        │ (插件状态管理)│
+                      └─────────────┘        └─────────────┘        └─────────────┘
+```
+
+**Plugin Isolation Strategy:**
+- **Backend**: `FeishuModule` is a standalone NestJS module. It handles its own database entities and webhook logic.
+- **Frontend**: Integrated as a sub-view within `/plugins`. When the Feishu plugin is "enabled", its configuration UI is rendered.
+- **Decoupling**: Communicates with core services via standard service calls or an event-subscriber pattern.
+
+---
+
+## File Structure
+
+
+### New Files to Create
+
+```
+server/src/
+├── feishu/
+│   ├── feishu.module.ts              # Module definition
+│   ├── feishu.controller.ts          # Webhook endpoints
+│   ├── feishu.service.ts             # Business logic
+│   ├── feishu.gateway.ts             # Event handling (optional)
+│   ├── entities/
+│   │   └── feishu-bot.entity.ts      # Bot configuration entity
+│   ├── dto/
+│   │   ├── create-bot.dto.ts         # Create bot DTO
+│   │   ├── bind-bot.dto.ts           # Bind bot DTO
+│   │   └── feishu-webhook.dto.ts    # Webhook event DTO
+│   └── interfaces/
+│       └── feishu.interface.ts       # TypeScript interfaces
+```
+
+### Existing Files to Modify
+
+```
+server/src/
+├── app.module.ts                      # Import FeishuModule
+├── user/
+│   └── user.entity.ts                # Add one-to-many relation to FeishuBot
+├── user/user.service.ts               # Add methods to get/set Feishu binding
+```
+
+---
+
+## Chunk 1: Entity and DTO Definitions
+
+### Task 1.1: Create FeishuBot Entity
+
+**Files:**
+- Create: `server/src/feishu/entities/feishu-bot.entity.ts`
+
+- [ ] **Step 1: Create the FeishuBot entity file**
+
+```typescript
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  UpdateDateColumn,
+  ManyToOne,
+  JoinColumn,
+} from 'typeorm';
+import { User } from '../../user/user.entity';
+
+@Entity('feishu_bots')
+export class FeishuBot {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ name: 'user_id' })
+  userId: string; // Plugin manages its own relationship to the core User
+
+  @ManyToOne(() => User)
+  @JoinColumn({ name: 'user_id' })
+  user: User;
+
+  @Column({ name: 'app_id', length: 64 })
+  appId: string;
+// ... (rest of the fields as defined previously)
+}
+```
+
+- [ ] **Step 2: Decoupled Relation**
+Instead of modifying the core `User` entity directly, the `FeishuBot` entity maintains its own reference to `User`. This keeps the core system clean and allows the plugin to be purely optional.
+
+
+- [ ] **Step 3: Create DTOs**
+
+Create: `server/src/feishu/dto/create-bot.dto.ts`
+```typescript
+import { IsString, IsNotEmpty, IsOptional, IsBoolean } from 'class-validator';
+
+export class CreateFeishuBotDto {
+  @IsString()
+  @IsNotEmpty()
+  appId: string;
+
+  @IsString()
+  @IsNotEmpty()
+  appSecret: string;
+
+  @IsString()
+  @IsOptional()
+  verificationToken?: string;
+
+  @IsString()
+  @IsOptional()
+  encryptKey?: string;
+
+  @IsString()
+  @IsOptional()
+  botName?: string;
+
+  @IsBoolean()
+  @IsOptional()
+  enabled?: boolean;
+}
+```
+
+Create: `server/src/feishu/dto/bind-bot.dto.ts`
+```typescript
+import { IsString, IsNotEmpty, IsUUID } from 'class-validator';
+
+export class BindFeishuBotDto {
+  @IsUUID()
+  @IsNotEmpty()
+  botId: string;
+
+  @IsString()
+  @IsNotEmpty()
+  verificationCode?: string;  // Optional: 用于验证绑定关系
+}
+```
+
+---
+
+## Chunk 2: Core Service Implementation
+
+### Task 2.1: Create Feishu Service
+
+**Files:**
+- Create: `server/src/feishu/feishu.service.ts`
+
+- [ ] **Step 1: Implement FeishuService with token management and message sending**
+
+```typescript
+import { Injectable, Logger } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { ConfigService } from '@nestjs/config';
+import { HttpService } from '@nestjs/axios';
+import { FeishuBot } from './entities/feishu-bot.entity';
+import { CreateFeishuBotDto } from './dto/create-bot.dto';
+
+@Injectable()
+export class FeishuService {
+  private readonly logger = new Logger(FeishuService.name);
+  private readonly feishuApiBase = 'https://open.feishu.cn/open-apis';
+
+  constructor(
+    @InjectRepository(FeishuBot)
+    private botRepository: Repository<FeishuBot>,
+    private httpService: HttpService,
+    private configService: ConfigService,
+  ) {}
+
+  /**
+   * Create or update a Feishu bot for a user
+   */
+  async createBot(userId: string, dto: CreateFeishuBotDto): Promise<FeishuBot> {
+    // Check if bot already exists for this user with same appId
+    const existing = await this.botRepository.findOne({
+      where: { userId, appId: dto.appId },
+    });
+
+    if (existing) {
+      // Update existing bot
+      Object.assign(existing, dto);
+      return this.botRepository.save(existing);
+    }
+
+    // Create new bot
+    const bot = this.botRepository.create({
+      userId,
+      ...dto,
+    });
+    return this.botRepository.save(bot);
+  }
+
+  /**
+   * Get all bots for a user
+   */
+  async getUserBots(userId: string): Promise<FeishuBot[]> {
+    return this.botRepository.find({ where: { userId } });
+  }
+
+  /**
+   * Get bot by ID
+   */
+  async getBotById(botId: string): Promise<FeishuBot | null> {
+    return this.botRepository.findOne({ where: { id: botId } });
+  }
+
+  /**
+   * Get bot by appId
+   */
+  async getBotByAppId(appId: string): Promise<FeishuBot | null> {
+    return this.botRepository.findOne({ where: { appId } });
+  }
+
+  /**
+   * Get or refresh tenant_access_token
+   */
+  async getValidToken(bot: FeishuBot): Promise<string> {
+    // Check if token is still valid (expire in 2 hours, refresh at 1.5 hours)
+    if (
+      bot.tokenExpiresAt &&
+      bot.tenantAccessToken &&
+      new Date(bot.tokenExpiresAt) > new Date(Date.now() + 30 * 60 * 1000)
+    ) {
+      return bot.tenantAccessToken;
+    }
+
+    // Refresh token
+    const response = await this.httpService
+      .post(`${this.feishuApiBase}/auth/v3/tenant_access_token/internal`, {
+        app_id: bot.appId,
+        app_secret: bot.appSecret,
+      })
+      .toPromise();
+
+    if (response.data.code !== 0) {
+      throw new Error(`Failed to get token: ${response.data.msg}`);
+    }
+
+    const { tenant_access_token, expire } = response.data;
+
+    // Update bot with new token
+    bot.tenantAccessToken = tenant_access_token;
+    bot.tokenExpiresAt = new Date(Date.now() + expire * 1000);
+    await this.botRepository.save(bot);
+
+    return tenant_access_token;
+  }
+
+  /**
+   * Send message to Feishu user
+   */
+  async sendMessage(
+    bot: FeishuBot,
+    receiveIdType: 'open_id' | 'user_id' | 'union_id' | 'chat_id',
+    receiveId: string,
+    messageType: 'text' | 'interactive' | 'post',
+    content: any,
+  ): Promise<string> {
+    const token = await this.getValidToken(bot);
+
+    const response = await this.httpService
+      .post(
+        `${this.feishuApiBase}/im/v1/messages?receive_id_type=${receiveIdType}`,
+        {
+          receive_id: receiveId,
+          msg_type: messageType,
+          content: JSON.stringify(content),
+        },
+        {
+          headers: {
+            Authorization: `Bearer ${token}`,
+          },
+        },
+      )
+      .toPromise();
+
+    if (response.data.code !== 0) {
+      throw new Error(`Failed to send message: ${response.data.msg}`);
+    }
+
+    return response.data.data.message_id;
+  }
+
+  /**
+   * Send text message (convenience method)
+   */
+  async sendTextMessage(
+    bot: FeishuBot,
+    receiveIdType: 'open_id' | 'user_id' | 'chat_id',
+    receiveId: string,
+    text: string,
+  ): Promise<string> {
+    return this.sendMessage(bot, receiveIdType, receiveId, 'text', { text });
+  }
+
+  /**
+   * Reply to a message
+   */
+  async replyMessage(
+    bot: FeishuBot,
+    messageId: string,
+    messageType: 'text' | 'interactive' | 'post',
+    content: any,
+  ): Promise<string> {
+    const token = await this.getValidToken(bot);
+
+    const response = await this.httpService
+      .post(
+        `${this.feishuApiBase}/im/v1/messages/${messageId}/reply`,
+        {
+          msg_type: messageType,
+          content: JSON.stringify(content),
+        },
+        {
+          headers: {
+            Authorization: `Bearer ${token}`,
+          },
+        },
+      )
+      .toPromise();
+
+    if (response.data.code !== 0) {
+      throw new Error(`Failed to reply message: ${response.data.msg}`);
+    }
+
+    return response.data.data.message_id;
+  }
+
+  /**
+   * Upload image for sending
+   */
+  async uploadImage(
+    bot: FeishuBot,
+    imageType: 'message' | 'avatar',
+    image: Buffer,
+    imageName: string,
+  ): Promise<string> {
+    const token = await this.getValidToken(bot);
+
+    const FormData = require('form-data');
+    const form = new FormData();
+    form.append('image_type', imageType);
+    form.append('image', image, { filename: imageName });
+
+    const response = await this.httpService
+      .post(`${this.feishuApiBase}/im/v1/images`, form, {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          ...form.getHeaders(),
+        },
+      })
+      .toPromise();
+
+    if (response.data.code !== 0) {
+      throw new Error(`Failed to upload image: ${response.data.msg}`);
+    }
+
+    return response.data.data.image_key;
+  }
+
+  /**
+   * Delete bot
+   */
+  async deleteBot(botId: string): Promise<void> {
+    await this.botRepository.delete(botId);
+  }
+
+  /**
+   * Enable/disable bot
+   */
+  async setBotEnabled(botId: string, enabled: boolean): Promise<FeishuBot> {
+    const bot = await this.botRepository.findOne({ where: { id: botId } });
+    if (!bot) {
+      throw new Error('Bot not found');
+    }
+    bot.enabled = enabled;
+    return this.botRepository.save(bot);
+  }
+}
+```
+
+---
+
+## Chunk 3: Controller and Webhook Endpoints
+
+### Task 3.1: Create Feishu Controller
+
+**Files:**
+- Create: `server/src/feishu/feishu.controller.ts`
+
+- [ ] **Step 1: Implement webhook endpoints**
+
+```typescript
+import {
+  Controller,
+  Post,
+  Get,
+  Delete,
+  Body,
+  Param,
+  Query,
+  Headers,
+  UseGuards,
+  Request,
+  RawBodyRequest,
+  Req,
+} from '@nestjs/common';
+import { Request as ExpressRequest } from 'express';
+import { FeishuService } from './feishu.service';
+import { CreateFeishuBotDto } from './dto/create-bot.dto';
+import { JwtAuthGuard } from '../auth/jwt-auth.guard';
+import { CreateSignatureDto, VerifyWebhookDto } from './dto/webhook.dto';
+
+@Controller('feishu')
+export class FeishuController {
+  constructor(private readonly feishuService: FeishuService) {}
+
+  /**
+   * GET /feishu/bots - List user's bots
+   * Requires JWT auth
+   */
+  @Get('bots')
+  @UseGuards(JwtAuthGuard)
+  async listBots(@Request() req) {
+    const bots = await this.feishuService.getUserBots(req.user.id);
+    // Mask sensitive data
+    return bots.map((bot) => ({
+      id: bot.id,
+      appId: bot.appId,
+      botName: bot.botName,
+      enabled: bot.enabled,
+      isDefault: bot.isDefault,
+      createdAt: bot.createdAt,
+    }));
+  }
+
+  /**
+   * POST /feishu/bots - Create a new bot
+   * Requires JWT auth
+   */
+  @Post('bots')
+  @UseGuards(JwtAuthGuard)
+  async createBot(@Request() req, @Body() dto: CreateFeishuBotDto) {
+    const bot = await this.feishuService.createBot(req.user.id, dto);
+    return {
+      id: bot.id,
+      appId: bot.appId,
+      botName: bot.botName,
+      enabled: bot.enabled,
+    };
+  }
+
+  /**
+   * DELETE /feishu/bots/:id - Delete a bot
+   * Requires JWT auth
+   */
+  @Delete('bots/:id')
+  @UseGuards(JwtAuthGuard)
+  async deleteBot(@Request() req, @Param('id') botId: string) {
+    await this.feishuService.deleteBot(botId);
+    return { success: true };
+  }
+
+  /**
+   * POST /feishu/webhook - Feishu webhook endpoint
+   * Public endpoint - no auth required (uses verification token)
+   */
+  @Post('webhook')
+  async handleWebhook(
+    @Body() body: any,
+    @Headers('x-xsign') xSign?: string,
+    @Headers('x-timESTAMP') xTimestamp?: string,
+  ) {
+    this.logger.log(`Received webhook: ${JSON.stringify(body)}`);
+
+    const { type, schema, event } = body;
+
+    // Handle URL verification (飞书首次配置时验证)
+    if (type === 'url_verification') {
+      return {
+        challenge: body.challenge,
+      };
+    }
+
+    // Handle event callback
+    if (type === 'event_callback') {
+      const { event_type, token } = body;
+
+      // Verify token
+      if (token !== body?.verify_token) {
+        this.logger.warn('Webhook token verification failed');
+        return { success: false };
+      }
+
+      // Handle different event types
+      switch (event_type) {
+        case 'im.message.p2p_msg_received':
+          // Handle private message
+          await this.handleP2PMsg(event);
+          break;
+
+        case 'im.message.group_at_msg_received':
+          // Handle group @message
+          await this.handleGroupMsg(event);
+          break;
+
+        default:
+          this.logger.log(`Unhandled event type: ${event_type}`);
+      }
+    }
+
+    return { success: true };
+  }
+
+  /**
+   * Handle private message
+   */
+  private async handleP2PMsg(event: any) {
+    const { message } = event;
+    const { message_id, chat_id, sender, message_type, body } = message;
+
+    // Get message content
+    const content = JSON.parse(message.content || '{}');
+    const text = content.text || '';
+
+    // Find bot by app_id (from chat or event)
+    const openId = sender?.id?.open_id;
+    if (!openId) {
+      this.logger.warn('No sender open_id found');
+      return;
+    }
+
+    // Find user's bot
+    const bot = await this.feishuService.getBotByAppId(sender?.sender_id?.app_id);
+    if (!bot || !bot.enabled) {
+      this.logger.warn('Bot not found or disabled');
+      return;
+    }
+
+    // Process message through RAG/Chat service
+    await this.processMessage(bot, openId, message_id, text);
+  }
+
+  /**
+   * Handle group message (@bot)
+   */
+  private async handleGroupMsg(event: any) {
+    const { message } = event;
+    const { message_id, chat_id, sender, message_type, content } = message;
+
+    // Check if bot was mentioned
+    const msgContent = JSON.parse(content || '{}');
+    // Group messages often require specific handling
+
+    // Similar to P2P but with chat_id context
+    await this.handleP2PMsg(event);
+  }
+
+  /**
+   * Process message through ChatService
+   */
+  private async processMessage(
+    bot: any,
+    openId: string,
+    messageId: string,
+    text: string,
+  ) {
+    // TODO: Integrate with ChatService
+    // This will be implemented in Chunk 5
+
+    // For now, echo back (placeholder)
+    try {
+      await this.feishuService.sendTextMessage(
+        bot,
+        'open_id',
+        openId,
+        `Received: ${text}`,
+      );
+    } catch (error) {
+      this.logger.error('Failed to send response', error);
+    }
+  }
+}
+```
+
+- [ ] **Step 2: Create webhook DTOs**
+
+Create: `server/src/feishu/dto/webhook.dto.ts`
+```typescript
+import { IsString, IsOptional } from 'class-validator';
+
+export class CreateSignatureDto {
+  @IsString()
+  @IsOptional()
+  timestamp?: string;
+
+  @IsString()
+  @IsOptional()
+  nonce?: string;
+}
+
+export class VerifyWebhookDto {
+  @IsString()
+  token: string;
+
+  @IsString()
+  @IsOptional()
+  challenge?: string;
+}
+```
+
+---
+
+## Chunk 4: Plugin Registration
+
+### Task 4.1: Register Feishu Plugin
+**Note:** This module acts as an optional extension to the AuraK ecosystem.
+
+**Files:**
+- Create: `server/src/feishu/feishu.module.ts`
+- Modify: `server/src/app.module.ts`
+
+- [ ] **Step 1: Create FeishuModule with isolated exports**
+
+
+```typescript
+import { Module, forwardRef } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { HttpModule } from '@nestjs/axios';
+import { FeishuController } from './feishu.controller';
+import { FeishuService } from './feishu.service';
+import { FeishuBot } from './entities/feishu-bot.entity';
+import { ChatModule } from '../chat/chat.module';
+import { UserModule } from '../user/user.module';
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([FeishuBot]),
+    HttpModule,
+    forwardRef(() => ChatModule),
+    forwardRef(() => UserModule),
+  ],
+  controllers: [FeishuController],
+  providers: [FeishuService],
+  exports: [FeishuService, TypeOrmModule],
+})
+export class FeishuModule {}
+```
+
+- [ ] **Step 2: Add FeishuModule to AppModule**
+
+Modify: `server/src/app.module.ts`
+
+Add import:
+```typescript
+import { FeishuModule } from './feishu/feishu.module';
+```
+
+Add to imports array:
+```typescript
+FeishuModule,
+```
+
+---
+
+## Chunk 5: Integration with ChatService
+
+### Task 5.1: Connect Feishu messages to ChatService
+
+**Files:**
+- Modify: `server/src/feishu/feishu.controller.ts`
+- Modify: `server/src/feishu/feishu.service.ts`
+
+- [ ] **Step 1: Extend FeishuService to handle chat integration**
+
+Add to FeishuService:
+```typescript
+  // Import these
+  import { ChatService } from '../chat/chat.service';
+  import { ModelConfigService } from '../model-config/model-config.service';
+  import { TenantService } from '../tenant/tenant.service';
+  import { UserService } from '../user/user.service';
+  import { ModelType } from '../types';
+
+  // Add to constructor
+  constructor(
+    // ... existing
+    private chatService: ChatService,
+    private modelConfigService: ModelConfigService,
+    private tenantService: TenantService,
+    private userService: UserService,
+  ) {}
+
+  /**
+   * Process chat message through RAG
+   */
+  async processChatMessage(
+    bot: FeishuBot,
+    openId: string,
+    messageId: string,
+    userMessage: string,
+  ): Promise<void> {
+    // Get user by Feishu open_id mapping (future: map table)
+    // For now, use userId from bot
+    const userId = bot.userId;
+    
+    // Get user's tenant
+    const user = await this.userService.findById(userId);
+    const tenantId = user?.tenantId || 'default';
+
+    // Get user's LLM config
+    const llmModel = await this.modelConfigService.findDefaultByType(
+      tenantId,
+      ModelType.LLM,
+    );
+
+    if (!llmModel) {
+      await this.sendTextMessage(bot, 'open_id', openId, '请先配置 LLM 模型');
+      return;
+    }
+
+    // Send "thinking" message
+    await this.sendTextMessage(bot, 'open_id', openId, '正在思考...');
+
+    // Stream chat response
+    const stream = this.chatService.streamChat(
+      userMessage,
+      [],  // No history for now (future: persist per openId)
+      userId,
+      llmModel as any,
+      user?.userSetting?.language || 'zh',
+      undefined, // selectedEmbeddingId
+      undefined, // selectedGroups
+      undefined, // selectedFiles
+      undefined, // historyId
+      false, // enableRerank
+      undefined, // selectedRerankId
+      undefined, // temperature
+      undefined, // maxTokens
+      10, // topK
+      0.7, // similarityThreshold
+      undefined, // rerankSimilarityThreshold
+      undefined, // enableQueryExpansion
+      undefined, // enableHyDE
+      tenantId,
+    );
+
+    let fullResponse = '';
+    for await (const chunk of stream) {
+      if (chunk.type === 'content') {
+        fullResponse += chunk.data;
+        // Could send incrementally, but Feishu prefers complete messages
+      }
+    }
+
+    // Send final response
+    // Truncate if too long (Feishu has limits)
+    const maxLength = 5000;
+    const finalMessage = fullResponse.length > maxLength
+      ? fullResponse.substring(0, maxLength) + '...(内容过长)'
+      : fullResponse;
+
+    await this.sendTextMessage(bot, 'open_id', openId, finalMessage);
+  }
+```
+
+- [ ] **Step 2: Update controller to use chat integration**
+
+Modify the `processMessage` method in FeishuController to call `feishuService.processChatMessage()`:
+
+```typescript
+  private async processMessage(
+    bot: any,
+    openId: string,
+    messageId: string,
+    text: string,
+  ) {
+    try {
+      await this.feishuService.processChatMessage(bot, openId, messageId, text);
+    } catch (error) {
+      this.logger.error('Failed to process message', error);
+      try {
+        await this.feishuService.sendTextMessage(
+          bot,
+          'open_id',
+          openId,
+          '抱歉，处理消息时发生错误，请稍后重试。',
+        );
+      } catch (sendError) {
+        this.logger.error('Failed to send error message', sendError);
+      }
+    }
+  }
+```
+
+---
+
+## Chunk 6: Frontend Integration (Optional)
+
+### Task 6.1: Add Feishu sub-view to Plugins
+**Files:**
+- Create: `web/src/pages/Plugins/FeishuPlugin.tsx`
+- Modify: `web/src/components/views/PluginsView.tsx`
+- Modify: `web/src/services/api.ts`
+
+- [ ] **Step 1: Create the Plugin Configuration UI**
+This view should match the design of other plugin cards in the /plugins page but provide a detailed setup guide and form for:
+- App ID / App Secret
+- Webhook URL (Read-only generated URL)
+- Verification Token & Encrypt Key
+
+- [ ] **Step 2: Register the Plugin in PluginsView**
+Modify the main plugins listing to include "Feishu Bot" as an available (or installed) plugin.
+
+Modify: `web/src/services/api.ts`
+```typescript
+// Add Feishu API calls
+export const feishuApi = {
+  listBots: () => api.get('/feishu/bots'),
+  createBot: (data: CreateBotDto) => api.post('/feishu/bots', data),
+  deleteBot: (botId: string) => api.delete(`/feishu/bots/${botId}`),
+};
+```
+
+- [ ] **Step 3: Implementation of PluginsView.tsx**
+If `web/src/components/views/PluginsView.tsx` does not exist, create a generic plugin management layout that can host the Feishu configuration.
+
+**Layout Requirements:**
+- Grid of available plugins.
+- Status toggle (Enabled/Disabled).
+- Detail/Configuration view for active plugins.
+
+
+## Testing Strategy
+
+### Unit Tests
+
+- `feishu.service.spec.ts` - Test token refresh, message sending
+- `feishu.controller.spec.ts` - Test webhook endpoints
+
+### Integration Tests
+
+- Test full flow: Feishu message → Webhook → ChatService → Response
+
+### Manual Testing
+
+1. Create Feishu app in 开放平台
+2. Configure webhook URL (use ngrok for local)
+3. Subscribe to message events
+4. Send message to bot
+5. Verify RAG response
+
+
+---
+
+## Security Considerations
+
+1. **Token Storage**: Encrypt `app_secret` and `encrypt_key` before storing in DB.
+2. **Webhook Verification**:
+   - Verify `verify_token` for simplicity.
+   - **Recommended**: Validate `X-Lark-Signature` using `encrypt_key` to ensure authenticity.
+
+3. **Rate Limiting**: Implement a message queue (e.g., BullMQ) for outbound messages to respect Feishu's global and per-bot rate limits.
+4. **User Privacy**: Implement an opt-in flow for group chats to ensure the bot only processes messages when explicitly allowed or mentioned.
+
+---
+
+## Advanced Optimizations (Recommended)
+
+### 1. Webhook Performance & Reliability
+- **Immediate Response**: Feishu requires a response within 3 seconds. The RAG process can take 10s+. 
+- **Optimization**: The `handleWebhook` should only validate the request and push the event to an internal queue, returning `200 OK` immediately. A background worker then processes the RAG logic and sends the response.
+- **Deduplication**: Use the `event_id` in the webhook payload to ignore duplicate retries from Feishu.
+
+### 2. UX: Managed "Thinking" State
+- **Simulated Streaming**: Since Feishu doesn't support SSE, send an initial "Thinking..." message and use the `PATCH /im/v1/messages/:message_id` API to update the message content every few seconds as chunks arrive.
+- **Interactive Cards**: Use [Message Cards](https://open.feishu.cn/document/common-capabilities/message-card/message-card-overview) instead of plain text for:
+  - Showing search citations with clickable links.
+  - Providing "Regenerate" or "Clear Context" buttons.
+  - Displaying assessment results with formatting (tables/charts).
+
+### 3. Context & History Management
+- **OpenID Mapping**: Maintain a mapping between Feishu `open_id` and AuraK `userId` to persist chat history across different devices/platforms.
+- **Thread Support**: Use Feishu's `root_id` and `parent_id` to allow users to ask follow-up questions within a thread, keeping the UI clean.
+
+### 4. Multi-modal Support
+- **File Ingestion**: Support `im.message.file_received` events. If a user sends a PDF/Docx to the bot, automatically import it into a "Feishu Uploads" group for immediate RAG context.
+- **Image Analysis**: Use the `VisionService` to handle images sent via Feishu.
+
+
+## Future Enhancements
+
+1. **Assessment Integration**: Bind assessment sessions to Feishu conversations using interactive card forms.
+2. **Rich Responses**: Use Feishu interactive cards for better visual presentation.
+3. **Multi-bot Support**: Users can have multiple bots for different specialized tasks.
+4. **Group Chats**: Support bot in group chats with specific @mention logic and moderation.
+5. **Voice Messages**: Handle voice message transcription via Feishu's audio-to-text API for accessibility.
+
+
+---
+
+## Dependencies
+
+- `@nestjs/axios` - For HTTP requests to Feishu API
+- `form-data` - For file/image uploads
+- Optional: `crypto` (built-in) - For signature verification
+
+---
+
+## Reference Links
+
+- [飞书开放平台 - 机器人文档](https://open.feishu.cn/document/faq/bot)
+- [飞书事件订阅](https://open.feishu.cn/document/server-docs/event-subscription-guide/overview)
+- [消息发送 API](https://open.feishu.cn/document/server-docs/im-v1/message-content-description)
+- [获取 tenant_access_token](https://open.feishu.cn/document/server-docs/authentication-management/access-token)
+
+---
+
+> **Plan created:** 2026-03-16
+> **Based on:** Feishu integration analysis