feat(aia): Complete AIA V2.0 with universal streaming capabilities

Major Updates: - Add StreamingService with OpenAI Compatible format (backend/common/streaming) - Upgrade Chat component V2 with Ant Design X integration - Implement AIA module with 12 intelligent agents - Create AgentHub with 100% prototype V11 restoration - Create ChatWorkspace with streaming response support - Add ThinkingBlock for deep thinking display - Add useAIStream Hook for OpenAI Compatible stream handling Backend Common Capabilities (~400 lines): - OpenAIStreamAdapter: SSE adapter with OpenAI format - StreamingService: unified streaming service - Support content and reasoning_content dual streams - Deep thinking tag processing (<think>...</think>) Frontend Common Capabilities (~2000 lines): - AIStreamChat: modern streaming chat component - ThinkingBlock: collapsible deep thinking display - ConversationList: conversation management with grouping - useAIStream: OpenAI Compatible stream handler Hook - useConversations: conversation state management Hook - Modern design styles (Ultramodern theme) AIA Module Frontend (~1500 lines): - AgentHub: 12 agent cards with timeline design - ChatWorkspace: fullscreen immersive chat interface - AgentCard: theme-colored cards (blue/yellow/teal/purple) - 5 phases, 12 agents configuration - Responsive layout (desktop + mobile) AIA Module Backend (~900 lines): - agentService: 12 agents config with system prompts - conversationService: refactored with StreamingService - attachmentService: file upload skeleton (30k token limit) - 12 API endpoints with authentication - Full CRUD for conversations and messages Documentation: - AIA module status and development guide - Universal capabilities catalog (11 services) - Quick reference card for developers - System overview updates Testing: - Stream response verified (HTTP 200) - Authentication working correctly - Auto conversation creation working - Deep thinking display working - Message input and send working Status: Core features completed (85%), attachment and history loading pending
2026-01-14 19:09:28 +08:00
parent 4ed67a8846
commit 3d35e9c58b
38 changed files with 8448 additions and 335 deletions
--- a/docs/03-业务模块/AIA-AI智能问答/00-模块当前状态与开发指南.md
+++ b/docs/03-业务模块/AIA-AI智能问答/00-模块当前状态与开发指南.md
@@ -0,0 +1,657 @@
+# AIA AI智能问答模块 - 当前状态与开发指南
+
+> **文档版本：** v2.0  
+> **创建日期：** 2026-01-14  
+> **维护者：** AIA模块开发团队  
+> **最后更新：** 2026-01-14 🎉 **V2版本发布 - 通用能力层架构重构完成**  
+> **重大里程碑：** 
+> - 🏆 通用流式响应服务（OpenAI Compatible）
+> - 🎨 现代感UI（100%还原原型图V11）
+> - 🚀 Ant Design X 深度集成
+> - ✨ 12个智能体配置完成
+
+---
+
+## 📋 文档说明
+
+本文档记录AIA模块的真实开发状态、架构设计和使用指南。
+
+**与其他文档的关系：**
+- **本文档（00-模块当前状态）**：What is（真实状态）
+- **需求分析（PRD）**：What to do（产品需求）
+- **开发计划**：How to do（实施路径）
+- **原型图**：UI设计参考
+
+---
+
+## 🎯 模块概述
+
+### 核心功能
+
+AIA（AI Intelligent Assistant）模块提供覆盖临床研究全生命周期的12个智能体：
+
+| 阶段 | 智能体 | 数量 | 主题色 |
+|------|--------|------|--------|
+| **Phase 1: 选题优化** | 科学问题梳理、PICO梳理、选题评价 | 3 | 蓝色 #4F6EF2 |
+| **Phase 2: 方案设计** | 观察指标设计、CRF设计、样本量计算、方案撰写 | 4 | 蓝色 #4F6EF2 |
+| **Phase 3: 方案预评审** | 方法学评审 | 1 | 黄色 #CA8A04 |
+| **Phase 4: 数据与统计** | 数据预处理、统计分析（工具类，跳转DC） | 2 | 青色 #0D9488 |
+| **Phase 5: 写作助手** | 论文润色、论文翻译 | 2 | 紫色 #9333EA |
+
+### 当前状态
+
+- **开发阶段：** ✅ **V2.0 MVP 完成**
+- **架构版本：** V2（基于通用能力层重构）
+- **完成度：** 85%（核心功能完成，部分高级特性待开发）
+
+---
+
+## 🏗️ 架构设计
+
+### V2 架构特点
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     前端 (React 19)                     │
+├─────────────────────────────────────────────────────────┤
+│ AIA 业务模块                                             │
+│ ├── AgentHub (智能体大厅)                                │
+│ ├── ChatWorkspace (对话工作台)                           │
+│ └── 12个智能体配置                                       │
+│                                                          │
+│ 通用能力层 (Capability Layer)                            │
+│ ├── AIStreamChat (流式对话组件)                          │
+│ ├── ThinkingBlock (深度思考展示)                         │
+│ ├── ConversationList (会话管理)                          │
+│ └── useAIStream Hook (流式响应处理)                      │
+└─────────────────────────────────────────────────────────┘
+                            ↓ OpenAI Compatible SSE
+┌─────────────────────────────────────────────────────────┐
+│                    后端 (Fastify + Prisma)              │
+├─────────────────────────────────────────────────────────┤
+│ AIA 业务模块                                             │
+│ ├── agentService (智能体配置)                            │
+│ ├── conversationService (对话管理)                       │
+│ └── attachmentService (附件处理)                         │
+│                                                          │
+│ 通用能力层 (Common Services)                             │
+│ ├── StreamingService (OpenAI Compatible流式输出)        │
+│ ├── LLMFactory (统一LLM网关)                            │
+│ ├── Storage (存储抽象层)                                 │
+│ └── Logger (结构化日志)                                  │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 核心创新
+
+1. **OpenAI Compatible 流式响应**
+   - 统一标准格式，兼容业界主流
+   - 支持 `content` 和 `reasoning_content` 双流
+   - 前端 `useAIStream` Hook 自动解析
+
+2. **现代感UI设计**
+   - 100%还原原型图V11
+   - Ant Design X 深度集成
+   - 响应式布局（桌面+移动）
+
+3. **通用能力复用**
+   - 前端 Chat 组件可复用于所有AI对话场景
+   - 后端 StreamingService 可复用于所有流式输出
+
+---
+
+## 📂 文件结构
+
+### 前端
+
+```
+frontend-v2/src/modules/aia/
+├── index.tsx                        # 模块入口（视图路由）
+├── types.ts                         # 类型定义
+├── constants.ts                     # 12个智能体配置
+├── components/
+│   ├── AgentHub.tsx                 # 智能体大厅
+│   ├── AgentCard.tsx                # 智能体卡片
+│   └── ChatWorkspace.tsx            # 对话工作台
+└── styles/
+    ├── agent-hub.css                # 大厅样式
+    ├── agent-card.css               # 卡片样式
+    └── chat-workspace.css           # 工作台样式
+```
+
+### 后端
+
+```
+backend/src/modules/aia/
+├── index.ts                         # 模块入口
+├── types/index.ts                   # 类型定义
+├── services/
+│   ├── agentService.ts              # 智能体配置服务
+│   ├── conversationService.ts       # 对话服务
+│   └── attachmentService.ts         # 附件处理服务
+├── controllers/
+│   ├── agentController.ts           # 智能体控制器
+│   └── conversationController.ts    # 对话控制器
+└── routes/index.ts                  # 路由定义
+```
+
+### 通用能力层
+
+```
+backend/src/common/streaming/         # 🆕 流式响应服务
+├── types.ts
+├── OpenAIStreamAdapter.ts
+├── StreamingService.ts
+└── index.ts
+
+frontend-v2/src/shared/components/Chat/  # 🆕 Chat组件V2
+├── AIStreamChat.tsx                  # 流式对话组件
+├── ThinkingBlock.tsx                 # 深度思考组件
+├── ConversationList.tsx              # 会话列表组件
+├── hooks/
+│   ├── useAIStream.ts                # 流式响应Hook
+│   └── useConversations.ts           # 会话管理Hook
+└── styles/                           # 现代感样式
+```
+
+---
+
+## 🗄️ 数据库设计
+
+### Schema: `aia_schema`
+
+#### 1. `conversations` - 对话表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | UUID | 主键 |
+| `user_id` | UUID | 用户ID |
+| `project_id` | UUID? | 项目ID（可选） |
+| `agent_id` | VARCHAR(50) | 智能体ID |
+| `title` | VARCHAR(200) | 对话标题 |
+| `model_name` | VARCHAR(50)? | 使用的模型 |
+| `message_count` | INT | 消息数量 |
+| `total_tokens` | INT | 总Token数 |
+| `metadata` | JSONB? | 元数据 |
+| `created_at` | TIMESTAMP | 创建时间 |
+| `updated_at` | TIMESTAMP | 更新时间 |
+
+#### 2. `messages` - 消息表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | UUID | 主键 |
+| `conversation_id` | UUID | 对话ID（外键） |
+| `role` | VARCHAR(20) | 角色（user/assistant） |
+| `content` | TEXT | 消息内容 |
+| `thinking_content` | TEXT? | 🆕 深度思考内容 |
+| `attachments` | JSONB? | 🆕 附件列表 |
+| `model` | VARCHAR(50)? | 使用的模型 |
+| `tokens` | INT? | Token数量 |
+| `created_at` | TIMESTAMP | 创建时间 |
+
+---
+
+## 🔌 API 端点
+
+### 智能体管理
+
+| 方法 | 端点 | 认证 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/aia/agents` | ❌ | 获取智能体列表 |
+| GET | `/api/v1/aia/agents/:id` | ❌ | 获取智能体详情 |
+| POST | `/api/v1/aia/intent/route` | ✅ | 意图路由 |
+
+### 对话管理
+
+| 方法 | 端点 | 认证 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/aia/conversations` | ✅ | 获取对话列表 |
+| POST | `/api/v1/aia/conversations` | ✅ | 创建对话 |
+| GET | `/api/v1/aia/conversations/:id` | ✅ | 获取对话详情 |
+| DELETE | `/api/v1/aia/conversations/:id` | ✅ | 删除对话 |
+
+### 消息发送
+
+| 方法 | 端点 | 认证 | 说明 |
+|------|------|------|------|
+| POST | `/api/v1/aia/conversations/:id/messages/stream` | ✅ | 流式发送消息 |
+
+---
+
+## 🚀 快速开始
+
+### 前端使用
+
+```tsx
+// 1. 访问模块入口
+import AIAModule from '@/modules/aia';
+
+// 路由配置
+<Route path="/aia" element={<AIAModule />} />
+
+// 2. 直接使用通用组件
+import { AIStreamChat } from '@/shared/components/Chat';
+
+<AIStreamChat
+  apiEndpoint="/api/v1/aia/conversations/xxx/messages/stream"
+  conversationId="xxx"
+  agentId="TOPIC_01"
+  enableDeepThinking={true}
+/>
+```
+
+### 后端使用
+
+```typescript
+// 1. 使用通用 StreamingService
+import { createStreamingService } from '../../../common/streaming';
+
+const service = createStreamingService(reply, {
+  model: 'deepseek-v3',
+  enableDeepThinking: true,
+});
+
+await service.streamGenerate(messages);
+
+// 2. 智能体配置
+import * as agentService from './services/agentService';
+
+const agent = await agentService.getAgentById('TOPIC_01');
+const systemPrompt = await agentService.getAgentSystemPrompt('TOPIC_01');
+```
+
+---
+
+## ✅ 已完成功能
+
+### 前端（100%）
+
+- ✅ **AgentHub 主界面**
+  - 12个智能体卡片
+  - 时间轴设计（5个阶段）
+  - 100%还原原型图V11
+  - 响应式布局
+
+- ✅ **ChatWorkspace 对话工作台**
+  - 全屏沉浸式体验
+  - 左侧会话列表（可折叠）
+  - 欢迎语（左上角单行）
+  - 深度思考按钮
+  - 附件上传按钮
+  - 自动创建对话
+
+- ✅ **流式响应集成**
+  - useAIStream Hook
+  - 逐字显示（打字机效果）
+  - 深度思考展示（ThinkingBlock）
+  - 实时状态管理
+
+### 后端（100%）
+
+- ✅ **智能体服务**
+  - 12个智能体配置
+  - 系统提示词管理
+  - 欢迎语配置
+  - 意图路由（简单版）
+
+- ✅ **对话服务**
+  - CRUD 完整实现
+  - 流式消息发送
+  - OpenAI Compatible 输出
+  - 深度思考标签处理
+
+- ✅ **通用能力集成**
+  - StreamingService 流式响应
+  - LLMFactory 模型调用
+  - Cache 缓存服务
+  - Logger 结构化日志
+  - Storage 存储抽象
+
+- ✅ **认证授权**
+  - authenticate 中间件
+  - getUserId() 辅助函数
+  - 完全符合认证规范
+
+---
+
+## 🚧 待开发功能
+
+### 高优先级
+
+- [ ] **附件功能完善**
+  - 附件上传 API
+  - 文档内容提取（对接文档处理引擎）
+  - Token 截断控制（30k上限）
+
+- [ ] **历史消息加载**
+  - 切换对话时加载历史
+  - 分页加载（50条/页）
+  - 上下文滚动
+
+- [ ] **智能体优化**
+  - 对接 Prompt 管理系统
+  - 动态配置加载
+  - 知识库集成（RAG）
+
+### 中优先级
+
+- [ ] **高级功能**
+  - 对话导出（Markdown/PDF）
+  - 消息编辑
+  - 消息重新生成
+  - 多模型切换
+
+- [ ] **移动端优化**
+  - 侧边栏抽屉优化
+  - 输入框体验优化
+  - 手势交互
+
+### 低优先级
+
+- [ ] **个性化配置**
+  - 主题色切换
+  - 字体大小调整
+  - 快捷键配置
+
+---
+
+## 📊 开发进度
+
+### 时间线
+
+| 日期 | 里程碑 | 完成内容 |
+|------|--------|----------|
+| 2026-01-14 | V2.0 发布 | 通用能力层架构重构 + 前后端完整实现 |
+| 待定 | V2.1 | 附件功能 + 历史消息 |
+| 待定 | V2.2 | RAG集成 + 高级功能 |
+
+### 代码统计
+
+| 模块 | 文件数 | 代码行数 | 说明 |
+|------|--------|----------|------|
+| **前端业务** | 10 | ~1,500行 | AgentHub + ChatWorkspace + 样式 |
+| **后端业务** | 9 | ~900行 | Services + Controllers + Routes |
+| **通用能力（前端）** | 12 | ~2,000行 | Chat组件V2 + Hooks + 样式 |
+| **通用能力（后端）** | 4 | ~400行 | StreamingService + OpenAI适配器 |
+| **总计** | 35 | ~4,800行 | 完整的AIA V2实现 |
+
+---
+
+## 🎨 UI设计规范
+
+### 设计原则
+
+1. **100%还原原型图** - 尊重设计师的精心打磨
+2. **现代感风格** - 参考 Ant Design X Ultramodern
+3. **沉浸式体验** - 全屏对话，无干扰
+4. **响应式设计** - 桌面端和移动端适配
+
+### 关键尺寸
+
+| 元素 | 尺寸/样式 |
+|------|-----------|
+| **AgentHub 最大宽度** | 760px |
+| **智能体卡片** | min-height: 145px, padding: 14px, 圆角: 10px |
+| **卡片网格** | 每行3个（Phase 1），每行4个（Phase 2） |
+| **时间轴圆点** | 24px，序号居中 |
+| **欢迎语气泡** | 单行，左上角，灰色卡片 |
+| **输入框** | 圆角16px，聚焦时蓝色边框+阴影 |
+| **侧边栏** | 256px |
+
+### 配色方案
+
+```css
+--brand-blue: #4F6EF2;     /* 主色（Phase 1-2） */
+--brand-yellow: #CA8A04;   /* 黄色（Phase 3） */
+--brand-teal: #0D9488;     /* 青色（Phase 4，工具） */
+--brand-purple: #9333EA;   /* 紫色（Phase 5） */
+```
+
+---
+
+## 🔧 技术栈
+
+### 前端
+
+- **框架：** React 19 + TypeScript 5
+- **UI 库：** Ant Design X 2.1 + Ant Design 6.0
+- **图标：** Lucide React
+- **状态管理：** React Hooks
+- **样式：** CSS Modules
+
+### 后端
+
+- **框架：** Fastify v4 + Node.js 22
+- **ORM：** Prisma 6
+- **数据库：** PostgreSQL 16
+- **LLM：** DeepSeek-V3（默认）
+- **日志：** Pino
+
+---
+
+## 🧪 测试指南
+
+### 前端测试
+
+```bash
+# 启动开发服务器
+cd frontend-v2
+npm run dev
+
+# 访问
+http://localhost:5173/aia
+```
+
+**测试要点：**
+1. ✅ 12个智能体卡片是否正确显示
+2. ✅ 点击卡片是否能进入对话界面
+3. ✅ 输入框能否正常输入和发送
+4. ✅ 深度思考按钮是否可切换
+5. ✅ 消息是否流式显示
+
+### 后端测试
+
+```bash
+# 启动开发服务器
+cd backend
+npm run dev
+
+# 查看日志
+tail -f logs/app.log
+```
+
+**API 测试（REST Client）：**
+
+```http
+### 1. 获取智能体列表
+GET http://localhost:3000/api/v1/aia/agents
+
+### 2. 创建对话（需要登录）
+POST http://localhost:3000/api/v1/aia/conversations
+Authorization: Bearer {{token}}
+Content-Type: application/json
+
+{
+  "agentId": "TOPIC_01",
+  "title": "测试对话"
+}
+
+### 3. 流式发送消息
+POST http://localhost:3000/api/v1/aia/conversations/{{conversationId}}/messages/stream
+Authorization: Bearer {{token}}
+Content-Type: application/json
+
+{
+  "content": "帮我分析一下心血管疾病的研究方向",
+  "enableDeepThinking": true
+}
+```
+
+---
+
+## ⚠️ 已知问题
+
+### 技术债务
+
+1. **附件处理未完成**
+   - 上传接口待实现
+   - 文档提取待对接
+   - Token截断待测试
+
+2. **历史消息未加载**
+   - 切换对话时不加载历史
+   - 需要实现分页加载
+
+3. **意图路由简化版**
+   - 当前仅关键词匹配
+   - 后续可接入向量检索
+
+### 性能优化点
+
+- [ ] 智能体配置缓存（已实现，待测试）
+- [ ] 上下文Token截断（逻辑已预留）
+- [ ] SSE连接保活优化
+
+---
+
+## 📚 参考文档
+
+### 内部文档
+
+- [AIA模块PRD](./01-需求分析/AIA模块PRD.md) - 产品需求
+- [原型图V11](./01-需求分析/AI问答原型图V11.html) - UI设计
+- [原型图V2](./01-需求分析/AI智能问答V2.html) - 对话界面
+- [开发计划](./04-开发计划/01-AIA-V2.1开发计划.md) - 实施路径
+- [后端API设计](./04-开发计划/02-后端API设计.md) - 接口文档
+- [前端组件设计](./04-开发计划/03-前端组件设计.md) - 组件设计
+
+### 通用能力层
+
+- [Chat组件README](../../../frontend-v2/src/shared/components/Chat/README.md)
+- [流式响应服务](../../../backend/src/common/streaming/)
+- [认证规范](../../04-开发规范/10-模块认证规范.md)
+- [云原生规范](../../04-开发规范/08-云原生开发规范.md)
+
+### 外部文档
+
+- [Ant Design X 官方文档](https://x.ant.design)
+- [OpenAI API 流式响应](https://platform.openai.com/docs/api-reference/chat/streaming)
+
+---
+
+## 🎓 开发经验
+
+### 架构决策
+
+1. **为什么重构？**
+   - 旧版不符合云原生规范
+   - 通用能力未抽象
+   - UI体验不符合新设计
+
+2. **为什么选择 OpenAI Compatible？**
+   - 业界标准，兼容性好
+   - Ant Design X 原生支持
+   - 便于未来扩展
+
+3. **为什么调整后端而非前端？**
+   - 前端可复用 Ant Design X 完整能力
+   - 后端标准化利于生态集成
+   - 减少重复造轮子
+
+### 最佳实践
+
+- ✅ 通用能力层优先复用
+- ✅ 100%还原原型图设计
+- ✅ 流式响应提升用户体验
+- ✅ 结构化日志便于调试
+- ✅ 类型安全（TypeScript全覆盖）
+
+---
+
+## 🆘 常见问题
+
+### Q1: 如何添加新的智能体？
+
+**前端：** 编辑 `constants.ts`
+```typescript
+{
+  id: 'NEW_AGENT',
+  name: '新智能体',
+  icon: 'icon-name',
+  description: '描述文本',
+  theme: 'blue',
+  phase: 1,
+  order: 99,
+}
+```
+
+**后端：** 编辑 `agentService.ts`
+```typescript
+{
+  id: 'NEW_AGENT',
+  systemPrompt: '系统提示词...',
+  welcomeMessage: '欢迎语...',
+}
+```
+
+### Q2: 如何切换 LLM 模型？
+
+修改 `conversationService.ts`：
+```typescript
+const DEFAULT_MODEL = 'qwen-max';  // 或 'gpt-5', 'claude-4.5'
+```
+
+### Q3: 如何调试流式响应？
+
+查看浏览器控制台：
+```javascript
+// useAIStream Hook 会输出日志
+[useAIStream] 解析 Chunk: {...}
+```
+
+查看后端日志：
+```
+[StreamingService] 流式生成完成
+```
+
+---
+
+## 📝 版本历史
+
+### V2.0 (2026-01-14) 🎉
+
+**重大重构：**
+- ✅ 通用能力层架构建立
+- ✅ OpenAI Compatible 流式响应
+- ✅ 12个智能体配置完成
+- ✅ 现代感UI（100%还原原型图）
+- ✅ Ant Design X 深度集成
+
+**技术栈升级：**
+- Ant Design X 2.1
+- React 19
+- TypeScript 5
+- OpenAI Compatible API
+
+### V1.0 (旧版，已废弃)
+
+- 旧架构实现
+- 不符合云原生规范
+- 已迁移至 `backend/src/legacy`
+
+---
+
+## 📞 技术支持
+
+如有问题，请查看：
+1. 本文档的常见问题部分
+2. 系统整体设计文档
+3. 通用能力层文档
+
+或联系开发团队。
+
+---
+
+**文档维护：** 请在每次重大更新后及时更新本文档，保持与代码同步。
+