# 技术债务：通用对话服务抽取计划

> **文档类型**: 技术债务  
> **创建日期**: 2025-12-06  
> **优先�?*: P2（中期优化）  
> **预计工时**: 2-3�? 
> **影响模块**: AIA、PKB、Tool C、未来AI知识库模�?

---

## 📋 问题描述

### 当前现状

**后端对话能力分布**�?
```
�?通用能力层（common/�?
├── llm/adapters/              �?LLM适配器（完整�?
�?  ├── LLMFactory.ts          �?统一工厂�?
�?  ├── DeepSeekAdapter.ts
�?  ├── QwenAdapter.ts
�?  ├── GPT5Adapter.ts
�?  └── ClaudeAdapter.ts
├── rag/                       �?RAG检索（完整�?
�?  └── DifyClient.ts
└── storage/, logging/, cache/ �?基础设施（完整）

⚠️ 业务层（legacy/�?
└── services/
    └── conversationService.ts  �?对话管理逻辑�?25行）
        ├── 创建对话
        ├── 发送消�?
        ├── 流式输出
        ├── 上下文组�?
        ├── 历史管理
        └── 知识库检索集�?
```

**前端组件分布**�?
```
�?缺少通用对话组件
各模块重复实现：
├── AIA模块 - 自己实现对话UI
├── PKB模块 - 自己实现对话UI
└── Tool C模块 - 自己实现对话UI（Day 3�?
```

---

## 🎯 问题分析

### 代码重复

| 功能 | 当前状�?| 重复�?|
|------|---------|--------|
| **LLM调用** | �?已抽取（common/llm�?| 0% |
| **对话管理** | ⚠️ 未抽取（legacy中） | 80% |
| **消息存储** | ⚠️ 各模块独立表 | 60% |
| **上下文组�?* | ⚠️ 各模块重复实�?| 70% |
| **流式输出** | ⚠️ 各模块重复实�?| 80% |
| **前端对话UI** | �?完全未抽�?| 90% |

### 影响范围

**现有模块**�?
- AIA（AI智能问答�? 使用legacy/conversationService
- PKB（个人知识库�? 使用legacy/conversationService
- Tool C（数据清洗）- Day 3自己实现（~150行重复代码）

**未来模块**�?
- AI知识库模�?- 需要重复实�?
- 其他AI对话场景 - 需要重复实�?

---

## 💡 优化方案

### 方案：抽取通用对话服务

#### 第一阶段：后端服务抽�?

**创建通用对话服务**�?
```typescript
// backend/src/common/conversation/ConversationService.ts
export class ConversationService {
  /**
   * 通用对话接口
   * 支持多种场景：AIA、PKB、Tool C�?
   */
  async chat(config: ChatConfig): Promise<ChatResponse> {
    // 1. 构建消息上下�?
    const messages = await this.buildContext(config);
    
    // 2. 调用LLM（复用LLMFactory�?
    const llm = LLMFactory.createAdapter(config.modelType);
    const response = await llm.chat(messages, config.options);
    
    // 3. 保存消息（根据配置决定存储位置）
    await this.saveMessage(config.conversationId, config.userMessage, response);
    
    return response;
  }
  
  /**
   * 流式对话
   */
  async streamChat(config: ChatConfig): AsyncGenerator<StreamChunk> {
    const messages = await this.buildContext(config);
    const llm = LLMFactory.createAdapter(config.modelType);
    
    for await (const chunk of llm.chatStream(messages, config.options)) {
      yield chunk;
    }
    
    // 保存完整响应
    await this.saveMessage(...);
  }
  
  /**
   * 获取对话历史
   * 支持多种存储方式（统一接口，不同表�?
   */
  async getHistory(conversationId: string, options?: HistoryOptions) {
    // 根据conversationType路由到不同的�?
    const adapter = this.getStorageAdapter(options.conversationType);
    return await adapter.getHistory(conversationId, options);
  }
  
  /**
   * 保存消息
   * 支持多种存储方式
   */
  async saveMessage(conversationId: string, userMsg: string, aiResponse: any) {
    const adapter = this.getStorageAdapter(this.config.conversationType);
    await adapter.saveMessage(conversationId, userMsg, aiResponse);
  }
  
  /**
   * 构建上下�?
   * 支持：System Prompt + 历史消息 + 当前消息 + RAG检�?
   */
  private async buildContext(config: ChatConfig): Promise<Message[]> {
    const messages: Message[] = [];
    
    // 1. System Prompt
    if (config.systemPrompt) {
      messages.push({ role: 'system', content: config.systemPrompt });
    }
    
    // 2. 历史消息
    if (config.includeHistory) {
      const history = await this.getHistory(config.conversationId, {
        limit: config.historyLimit || 5
      });
      messages.push(...history);
    }
    
    // 3. RAG检索（如果需要）
    if (config.knowledgeBaseIds?.length > 0) {
      const ragContext = await this.retrieveRAGContext(
        config.userMessage,
        config.knowledgeBaseIds
      );
      messages.push({ role: 'system', content: ragContext });
    }
    
    // 4. 当前用户消息
    messages.push({ role: 'user', content: config.userMessage });
    
    return messages;
  }
}

// 配置接口
interface ChatConfig {
  conversationId: string;
  conversationType: 'aia' | 'pkb' | 'tool-c' | 'knowledge-base';  // 路由到不同表
  modelType: ModelType;
  userMessage: string;
  systemPrompt?: string;
  includeHistory?: boolean;
  historyLimit?: number;
  knowledgeBaseIds?: string[];
  options?: {
    temperature?: number;
    maxTokens?: number;
    topP?: number;
  };
}
```

**存储适配�?*（支持不同模块的不同表）�?
```typescript
// backend/src/common/conversation/adapters/StorageAdapter.ts
interface ConversationStorageAdapter {
  getHistory(conversationId: string, options?: HistoryOptions): Promise<Message[]>;
  saveMessage(conversationId: string, userMsg: string, aiResponse: any): Promise<void>;
}

// AIA/PKB使用通用�?
class GeneralStorageAdapter implements ConversationStorageAdapter {
  async getHistory(conversationId: string) {
    return await prisma.generalMessage.findMany({
      where: { conversationId },
      orderBy: { createdAt: 'desc' },
      take: options.limit
    });
  }
}

// Tool C使用独立�?
class ToolCStorageAdapter implements ConversationStorageAdapter {
  async getHistory(conversationId: string) {
    return await prisma.dcToolCAiHistory.findMany({
      where: { sessionId: conversationId },
      orderBy: { createdAt: 'desc' },
      take: options.limit
    });
  }
}
```

---

#### 第二阶段：前端组件抽�?

**创建通用对话组件�?*�?
```tsx
// frontend-v2/src/shared/components/Chat/
├── ChatContainer.tsx          // 对话容器（布局�?
├── MessageList.tsx            // 消息列表（虚拟滚动）
├── MessageItem.tsx            // 单条消息（用�?AI�?
├── MessageInput.tsx           // 输入框（支持多行、快捷键�?
├── StreamingMessage.tsx       // 流式渲染（打字机效果�?
├── CitationBadge.tsx          // 引用标记
├── LoadingIndicator.tsx       // 加载动画
└── index.ts

// 使用示例
import { ChatContainer } from '@/shared/components/Chat';

<ChatContainer
  conversationId={sessionId}
  conversationType="tool-c"
  systemPrompt={buildSystemPrompt()}
  onSendMessage={handleSendMessage}
  enableHistory={true}
  enableRAG={false}
/>
```

**组件特�?*�?
- �?支持流式/非流式渲�?
- �?支持引用跳转
- �?支持历史消息加载
- �?支持Markdown渲染
- �?支持代码高亮
- �?响应式布局

---

## 📊 改造前后对�?

### 代码量对�?

| 模块 | 改造前 | 改造后 | 减少 |
|------|--------|--------|------|
| **后端** |
| AIA对话逻辑 | 200�?| 50行（调用通用服务�?| -75% |
| PKB对话逻辑 | 180�?| 50�?| -72% |
| Tool C对话逻辑 | 150�?| 50�?| -67% |
| 通用服务 | 0�?| 300行（新建�?| +300�?|
| **总计** | 530�?| 450�?| **-15%** |
| **前端** |
| 各模块对话UI | 600行�? | 200行�?（调用通用组件�?| -67% |
| 通用组件 | 0�?| 500行（新建�?| +500�?|
| **总计** | 1800�?| 1100�?| **-39%** |
| **全部合计** | 2330�?| 1550�?| **-33%** |

### 质量提升

| 指标 | 改造前 | 改造后 | 提升 |
|------|--------|--------|------|
| 代码复用�?| 20% | 80% | +300% |
| 统一交互体验 | �?| �?| 100% |
| 未来扩展成本 | 高（每次重复�?| 低（直接复用�?| -80% |
| 维护成本 | 高（多处修改�?| 低（单点修改�?| -70% |

---

## 🚀 实施计划

### 阶段1：后端服务抽取（1.5天）

**Day 1上午：设�?*
- [ ] 设计ConversationService接口
- [ ] 设计StorageAdapter接口
- [ ] 设计ChatConfig配置结构

**Day 1下午：实现核心服�?*
- [ ] 实现ConversationService核心逻辑
- [ ] 实现GeneralStorageAdapter
- [ ] 实现ToolCStorageAdapter

**Day 2上午：迁移现有模�?*
- [ ] AIA模块改造（使用通用服务�?
- [ ] PKB模块改造（使用通用服务�?
- [ ] Tool C模块改造（使用通用服务�?

**Day 2下午：测�?*
- [ ] 单元测试
- [ ] 集成测试
- [ ] 回归测试（确保原功能正常�?

---

### 阶段2：前端组件抽取（1天）

**Day 3上午：设计与实现**
- [ ] 设计ChatContainer API
- [ ] 实现核心组件�?个）
- [ ] 样式统一

**Day 3下午：迁移与测试**
- [ ] AIA模块前端改�?
- [ ] PKB模块前端改�?
- [ ] Tool C模块前端改�?
- [ ] UI测试

---

### 阶段3：文档与培训�?.5天）

- [ ] 编写使用文档
- [ ] 编写最佳实�?
- [ ] 团队培训

---

## 📝 验收标准

### 功能验收
- [ ] AIA模块对话功能正常
- [ ] PKB模块对话功能正常
- [ ] Tool C模块对话功能正常
- [ ] 流式输出正常
- [ ] 历史消息加载正常
- [ ] RAG检索集成正�?

### 代码质量
- [ ] 代码复用率≥80%
- [ ] 单元测试覆盖率≥80%
- [ ] 无TypeScript错误
- [ ] 无ESLint警告

### 用户体验
- [ ] 对话交互流畅（响�?2秒）
- [ ] 流式输出流畅（无卡顿�?
- [ ] UI统一美观
- [ ] 移动端适配良好

---

## 💰 收益分析

### 短期收益�?个月内）

1. **代码质量提升**
   - 减少重复代码33%
   - 提升代码复用率至80%
   - 降低维护成本70%

2. **开发效率提�?*
   - 新模块对话功能开发时间：�?天→0.5天（-75%�?
   - Bug修复效率：单点修改，影响全局�?200%�?

3. **用户体验统一**
   - 统一交互模式
   - 统一视觉风格
   - 统一性能标准

### 长期收益�?-6个月�?

1. **支持未来模块**
   - AI知识库模块：直接复用�?额外开�?
   - 其他AI对话场景：快速实�?

2. **技术架构优�?*
   - 真正实现分层架构（业务层→通用层）
   - 为微服务拆分做准�?

3. **商业价�?*
   - 模块独立部署更容�?
   - 模块独立售卖更灵�?
   - 客户定制成本降低

---

## ⚠️ 风险与应�?

### 风险1：回归测试工作量�?
**应对**�?
- 优先实现自动化测�?
- 分模块逐步迁移
- 保留原代码作为备�?

### 风险2：历史数据迁�?
**应对**�?
- 不需要迁移数�?
- 只迁移代码逻辑
- 各模块保留独立表

### 风险3：前端组件复杂度
**应对**�?
- 采用渐进式重�?
- 先抽取核心组�?
- 后续迭代优化

---

## 📅 建议执行时间

**推荐时间窗口**�?
- **选项1**：Tool C MVP完成后（Day 10-13�?
- **选项2**：所有DC模块完成后（Week 8-9�?
- **选项3**：AI知识库模块启动前（Quarter 2�?

**当前决策**：延后至Tool C MVP完成�?

---

## 🔗 相关文档

- [系统架构分层设计](../../00-系统总体设计/01-系统架构分层设计.md)
- [云原生开发规范](../../04-开发规�?08-云原生开发规�?md)
- [Tool C Day 3开发计划](../../03-业务模块/DC-数据清洗整理/04-开发计�?工具C_Day3开发计�?md)

---

## 📝 更新记录

| 日期 | 版本 | 更新内容 | 更新�?|
|------|------|---------|--------|
| 2025-12-06 | V1.0 | 初始创建 | AI Assistant |

---

**文档状�?*: �?已创�? 
**优先�?*: P2（中期优化）  
**下一�?*: 完成Tool C Day 3 MVP后重新评�?