HaHafeng
66255368b7
Features - User Management (Phase 4.1): - Database: Add user_modules table for fine-grained module permissions - Database: Add 4 user permissions (view/create/edit/delete) to role_permissions - Backend: UserService (780 lines) - CRUD with tenant isolation - Backend: UserController + UserRoutes (648 lines) - 13 API endpoints - Backend: Batch import users from Excel - Frontend: UserListPage (412 lines) - list/filter/search/pagination - Frontend: UserFormPage (341 lines) - create/edit with module config - Frontend: UserDetailPage (393 lines) - details/tenant/module management - Frontend: 3 modal components (592 lines) - import/assign/configure - API: GET/POST/PUT/DELETE /api/admin/users/* endpoints Architecture Upgrade - Module Permission System: - Backend: Add getUserModules() method in auth.service - Backend: Login API returns modules array in user object - Frontend: AuthContext adds hasModule() method - Frontend: Navigation filters modules based on user.modules - Frontend: RouteGuard checks requiredModule instead of requiredVersion - Frontend: Remove deprecated version-based permission system - UX: Only show accessible modules in navigation (clean UI) - UX: Smart redirect after login (avoid 403 for regular users) Fixes: - Fix UTF-8 encoding corruption in ~100 docs files - Fix pageSize type conversion in userService (String to Number) - Fix authUser undefined error in TopNavigation - Fix login redirect logic with role-based access check - Update Git commit guidelines v1.2 with UTF-8 safety rules Database Changes: - CREATE TABLE user_modules (user_id, tenant_id, module_code, is_enabled) - ADD UNIQUE CONSTRAINT (user_id, tenant_id, module_code) - INSERT 4 permissions + role assignments - UPDATE PUBLIC tenant with 8 module subscriptions Technical: - Backend: 5 new files (~2400 lines) - Frontend: 10 new files (~2500 lines) - Docs: 1 development record + 2 status updates + 1 guideline update - Total: ~4900 lines of code Status: User management 100% complete, module permission system operational
543 lines
14 KiB
Markdown
543 lines
14 KiB
Markdown
# AIA 模块 V2.1 开发计划
|
||
|
||
> **版本**：V2.1
|
||
> **创建日期**：2026-01-11
|
||
> **计划周期**：约 8-11 天
|
||
> **策略**：重写后端 + 复用数据库 + 新开发前端
|
||
> **关联PRD**：`01-需求分析/AIA模块PRD.md`
|
||
> **关联原型**：`01-需求分析/AI智能问答V2.html`
|
||
|
||
---
|
||
|
||
## 📋 开发策略概述
|
||
|
||
### 核心决策
|
||
|
||
| 组件 | 策略 | 理由 |
|
||
|------|------|------|
|
||
| **后端** | 🔴 **重写** | 旧版不符合云原生规范（console.log、未使用平台能力） |
|
||
| **数据库** | ✅ **复用** | aia_schema 已完善，字段满足需求 |
|
||
| **前端** | 🔴 **新开发** | 复用 shared/components/Chat 通用组件，全新UI |
|
||
|
||
### 技术规范
|
||
|
||
| 规范 | 要求 |
|
||
|------|------|
|
||
| **日志** | 使用 `logger` from `@/common/logging`（禁止 console.log） |
|
||
| **存储** | 使用 `storage` from `@/common/storage` |
|
||
| **缓存** | 使用 `cache` from `@/common/cache` |
|
||
| **队列** | 使用 `jobQueue` from `@/common/jobs` |
|
||
| **Prompt** | 使用 `promptService.get()` from `@/common/prompts` |
|
||
| **代码位置** | `backend/src/modules/aia/` |
|
||
| **API路由** | `/api/v2/aia/*` |
|
||
|
||
---
|
||
|
||
## 📊 数据库状态（✅ 已完成）
|
||
|
||
### 表结构（3个表）
|
||
|
||
```
|
||
aia_schema.projects ✅ 保留
|
||
aia_schema.conversations ✅ 保留
|
||
aia_schema.messages ✅ 保留 + 新增字段
|
||
```
|
||
|
||
### 新增字段（2026-01-11 已迁移）
|
||
|
||
| 表 | 字段 | 类型 | 说明 |
|
||
|----|------|------|------|
|
||
| messages | `thinking_content` | TEXT | 深度思考内容 `<think>...</think>` |
|
||
| messages | `attachments` | JSONB | 附件数组（上限5个，单个≤20MB，文本≤30K tokens） |
|
||
|
||
### 已删除表
|
||
|
||
| 表 | 原因 |
|
||
|----|------|
|
||
| `general_conversations` | 功能重叠，使用 conversations.project_id = NULL |
|
||
| `general_messages` | 功能重叠 |
|
||
|
||
---
|
||
|
||
## 🗓️ 开发阶段
|
||
|
||
### Phase 1: 后端重写（3-4天）
|
||
|
||
#### Day 1: 模块骨架 + 核心服务
|
||
|
||
**目标**：搭建模块结构，迁移核心对话服务
|
||
|
||
**任务清单**：
|
||
|
||
- [ ] **1.1 创建模块目录结构**
|
||
```
|
||
backend/src/modules/aia/
|
||
├── controllers/
|
||
│ ├── conversationController.ts
|
||
│ ├── agentController.ts
|
||
│ └── projectController.ts
|
||
├── services/
|
||
│ ├── conversationService.ts
|
||
│ ├── agentService.ts
|
||
│ └── projectService.ts
|
||
├── routes/
|
||
│ └── index.ts
|
||
├── types/
|
||
│ └── index.ts
|
||
└── index.ts
|
||
```
|
||
|
||
- [ ] **1.2 重写 conversationService**
|
||
- 从 legacy 复制核心逻辑
|
||
- 替换 `console.log` → `logger`
|
||
- 使用 `prisma.message`（已在 aia_schema）
|
||
- 添加 `thinkingContent` 处理逻辑
|
||
- 保持流式输出能力
|
||
|
||
- [ ] **1.3 重写 agentService**
|
||
- 改用 `promptService.get()` 获取 Prompt
|
||
- 缓存智能体配置（使用 `cache`）
|
||
|
||
- [ ] **1.4 注册 v2 路由**
|
||
- 注册到 `/api/v2/aia/*`
|
||
- 保持 legacy 路由兼容（逐步迁移）
|
||
|
||
**验收标准**：
|
||
- [ ] 基础对话功能可用
|
||
- [ ] 流式输出正常
|
||
- [ ] 日志输出到 logger
|
||
|
||
---
|
||
|
||
#### Day 2: 深度思考 + 附件上传
|
||
|
||
**目标**：实现 V2.1 新增功能
|
||
|
||
**任务清单**：
|
||
|
||
- [ ] **2.1 深度思考模式**
|
||
- 检测 LLM 输出中的 `<think>...</think>` 标签
|
||
- 提取并存储到 `messages.thinking_content`
|
||
- 从 `content` 中移除 think 标签
|
||
- 流式输出时分离 thinking 和 content
|
||
|
||
- [ ] **2.2 附件上传服务**
|
||
- 使用 `storage.upload()` 上传到 OSS
|
||
- 调用 Python 微服务提取文本
|
||
- Token 计数（使用 tiktoken）
|
||
- 截断处理（超过 30K tokens）
|
||
- 存储附件信息到 `messages.attachments`
|
||
|
||
- [ ] **2.3 附件注入 LLM 上下文**
|
||
- 组装附件文本到 User Prompt
|
||
- 控制总 Token 长度
|
||
|
||
**技术规格**：
|
||
|
||
```typescript
|
||
// 附件处理配置
|
||
const ATTACHMENT_CONFIG = {
|
||
maxCount: 5, // 每条消息最多5个附件
|
||
maxSizePerFile: 20 * 1024 * 1024, // 单个文件20MB
|
||
maxTokens: 30000, // 提取文本最多30K tokens
|
||
supportedTypes: ['pdf', 'docx', 'txt', 'xlsx'],
|
||
};
|
||
```
|
||
|
||
**验收标准**：
|
||
- [ ] 深度思考内容正确分离存储
|
||
- [ ] 附件上传成功
|
||
- [ ] 附件文本正确注入 LLM
|
||
|
||
---
|
||
|
||
#### Day 3: 意图路由 + 知识库集成
|
||
|
||
**目标**：实现全局意图路由，完善知识库引用
|
||
|
||
**任务清单**：
|
||
|
||
- [ ] **3.1 意图路由服务**
|
||
- 新建 `intentRouterService.ts`
|
||
- 调用 Router Agent 识别意图
|
||
- 返回目标 Agent ID + 预填 Prompt
|
||
- 添加 500ms 防抖（前端实现）
|
||
|
||
- [ ] **3.2 完善知识库集成**
|
||
- 复用 PKB 模块的 RAG 检索
|
||
- 智能引用系统（[来源N]）
|
||
- 引用清单格式化
|
||
|
||
- [ ] **3.3 API 端点完善**
|
||
```
|
||
POST /api/v2/aia/intent/route # 意图路由
|
||
POST /api/v2/aia/conversations # 创建对话
|
||
GET /api/v2/aia/conversations # 对话列表
|
||
GET /api/v2/aia/conversations/:id # 对话详情
|
||
POST /api/v2/aia/conversations/:id/messages/stream # 发送消息（流式）
|
||
POST /api/v2/aia/conversations/:id/attachments # 上传附件
|
||
GET /api/v2/aia/agents # 智能体列表
|
||
GET /api/v2/aia/agents/:id # 智能体详情
|
||
```
|
||
|
||
**验收标准**：
|
||
- [ ] 意图路由正确识别并跳转
|
||
- [ ] 知识库引用正确显示
|
||
- [ ] 所有 API 端点可用
|
||
|
||
---
|
||
|
||
#### Day 4: 测试 + 文档
|
||
|
||
**目标**：完成后端测试和文档
|
||
|
||
**任务清单**：
|
||
|
||
- [ ] **4.1 单元测试**
|
||
- conversationService 测试
|
||
- 深度思考解析测试
|
||
- 附件处理测试
|
||
|
||
- [ ] **4.2 集成测试**
|
||
- 完整对话流程
|
||
- 附件上传流程
|
||
- 知识库检索流程
|
||
|
||
- [ ] **4.3 API 文档**
|
||
- 更新 REST Client 测试文件
|
||
- 编写 API 使用示例
|
||
|
||
**验收标准**：
|
||
- [ ] 测试覆盖核心功能
|
||
- [ ] API 文档完整
|
||
|
||
---
|
||
|
||
### Phase 2: 前端开发（5-7天）
|
||
|
||
#### Day 5-6: 智能体大厅（Dashboard）
|
||
|
||
**目标**：实现首页智能体大厅
|
||
|
||
**任务清单**：
|
||
|
||
- [ ] **5.1 创建模块目录结构**
|
||
```
|
||
frontend-v2/src/modules/aia/
|
||
├── pages/
|
||
│ ├── Dashboard.tsx # 智能体大厅
|
||
│ └── Workspace.tsx # 对话工作台
|
||
├── components/
|
||
│ ├── AgentPipeline.tsx # 5阶段流水线
|
||
│ ├── AgentCard.tsx # 智能体卡片
|
||
│ ├── IntentSearch.tsx # 意图搜索框
|
||
│ ├── ConversationList.tsx # 历史会话列表
|
||
│ ├── ThinkingBlock.tsx # 深度思考折叠块
|
||
│ ├── AttachmentUpload.tsx # 附件上传
|
||
│ ├── AttachmentCard.tsx # 附件卡片
|
||
│ └── SlashCommands.tsx # 快捷指令
|
||
├── hooks/
|
||
│ ├── useConversation.ts
|
||
│ ├── useAgents.ts
|
||
│ └── useIntentRouter.ts
|
||
├── api/
|
||
│ └── index.ts
|
||
├── types/
|
||
│ └── index.ts
|
||
└── index.tsx
|
||
```
|
||
|
||
- [ ] **5.2 智能体流水线（AgentPipeline）**
|
||
- 5阶段布局（严格还原 V11 原型）
|
||
- 3色视觉体系
|
||
- 卡片点击跳转 Workspace
|
||
- 工具卡片跳转外部模块（DC/ST）
|
||
|
||
- [ ] **5.3 意图搜索框（IntentSearch）**
|
||
- 顶部大搜索框
|
||
- 500ms 防抖
|
||
- 调用意图路由 API
|
||
- 自动跳转目标 Agent
|
||
|
||
**验收标准**：
|
||
- [ ] 5阶段流水线正确展示
|
||
- [ ] 意图搜索功能可用
|
||
- [ ] 与原型图一致
|
||
|
||
---
|
||
|
||
#### Day 7-8: 对话工作台（Workspace）
|
||
|
||
**目标**：实现沉浸式对话界面
|
||
|
||
**任务清单**：
|
||
|
||
- [ ] **7.1 工作台布局**
|
||
- Gemini 风格（大留白、少分割线）
|
||
- 左侧侧边栏（历史会话，可折叠）
|
||
- 主对话区（Header + 消息列表 + 输入框）
|
||
|
||
- [ ] **7.2 复用 Chat 通用组件**
|
||
```tsx
|
||
import { ChatContainer } from '@/shared/components/Chat';
|
||
|
||
<ChatContainer
|
||
providerConfig={{
|
||
apiEndpoint: '/api/v2/aia/conversations/:id/messages/stream',
|
||
requestFn: sendMessageWithStream,
|
||
}}
|
||
customMessageRenderer={renderAIAMessage}
|
||
/>
|
||
```
|
||
|
||
- [ ] **7.3 深度思考折叠块（ThinkingBlock）**
|
||
- 可折叠灰色引用块
|
||
- 生成中展开，完成后自动收起
|
||
- 显示"已深度思考 (耗时 Xs)"
|
||
|
||
- [ ] **7.4 附件上传组件**
|
||
- 支持拖拽上传
|
||
- 文件类型/大小校验
|
||
- 上传进度显示
|
||
- 消息气泡下方附件卡片
|
||
|
||
- [ ] **7.5 历史会话列表**
|
||
- 按时间分组（今天、昨天、7天前）
|
||
- 桌面端固定显示
|
||
- 移动端抽屉滑出
|
||
|
||
**验收标准**：
|
||
- [ ] Gemini 风格 UI
|
||
- [ ] 深度思考正确展示
|
||
- [ ] 附件上传完整流程
|
||
- [ ] 历史会话切换
|
||
|
||
---
|
||
|
||
#### Day 9: Markdown 增强 + 快捷指令
|
||
|
||
**目标**：增强对话体验
|
||
|
||
**任务清单**：
|
||
|
||
- [ ] **9.1 Markdown 渲染增强**
|
||
- KaTeX 公式渲染（医学公式）
|
||
- 表格横向滚动
|
||
- 代码块语法高亮 + 一键复制
|
||
|
||
- [ ] **9.2 快捷指令（SlashCommands）**
|
||
- 输入 `/` 弹出菜单
|
||
- 支持：/润色, /扩写, /翻译, /导出Word
|
||
- 键盘导航
|
||
|
||
- [ ] **9.3 结果操作栏**
|
||
- Hover 显示工具栏
|
||
- 复制（Markdown 源码）
|
||
- 重新生成
|
||
- 导出 Word（调用 RVW 导出服务）
|
||
|
||
**验收标准**：
|
||
- [ ] 公式正确渲染
|
||
- [ ] 快捷指令可用
|
||
- [ ] 操作栏功能完整
|
||
|
||
---
|
||
|
||
#### Day 10: 移动端适配
|
||
|
||
**目标**：响应式布局适配
|
||
|
||
**任务清单**：
|
||
|
||
- [ ] **10.1 Dashboard 移动端**
|
||
- 隐藏复杂导航
|
||
- 卡片单列流式布局
|
||
- 时间轴样式调整
|
||
|
||
- [ ] **10.2 Workspace 移动端**
|
||
- 侧边栏改为抽屉
|
||
- 输入框键盘适配（scrollIntoView）
|
||
- 发送按钮始终可见
|
||
|
||
- [ ] **10.3 触控优化**
|
||
- 按钮 active 态
|
||
- 触控区域优化
|
||
|
||
**验收标准**：
|
||
- [ ] md (768px) 断点响应正确
|
||
- [ ] 移动端交互流畅
|
||
|
||
---
|
||
|
||
#### Day 11: 集成测试 + 优化
|
||
|
||
**目标**：完成整体测试和优化
|
||
|
||
**任务清单**：
|
||
|
||
- [ ] **11.1 端到端测试**
|
||
- 完整对话流程
|
||
- 附件上传流程
|
||
- 深度思考流程
|
||
- 知识库引用流程
|
||
|
||
- [ ] **11.2 性能优化**
|
||
- TTFB < 1.5s
|
||
- 移动端 LCP < 1s
|
||
- 意图搜索防抖
|
||
|
||
- [ ] **11.3 Bug 修复**
|
||
|
||
- [ ] **11.4 文档更新**
|
||
- 更新模块状态文档
|
||
- 更新系统当前状态
|
||
|
||
**验收标准**：
|
||
- [ ] 所有功能正常
|
||
- [ ] 性能达标
|
||
- [ ] 文档完整
|
||
|
||
---
|
||
|
||
## 📁 文件清单
|
||
|
||
### 后端新增文件
|
||
|
||
```
|
||
backend/src/modules/aia/
|
||
├── controllers/
|
||
│ ├── conversationController.ts # ~300行
|
||
│ ├── agentController.ts # ~150行
|
||
│ └── projectController.ts # ~200行
|
||
├── services/
|
||
│ ├── conversationService.ts # ~500行（核心）
|
||
│ ├── agentService.ts # ~200行
|
||
│ ├── projectService.ts # ~150行
|
||
│ ├── intentRouterService.ts # ~100行（新）
|
||
│ └── attachmentService.ts # ~200行（新）
|
||
├── routes/
|
||
│ └── index.ts # ~100行
|
||
├── types/
|
||
│ └── index.ts # ~100行
|
||
└── index.ts # ~20行
|
||
|
||
预计总计：~2000行
|
||
```
|
||
|
||
### 前端新增文件
|
||
|
||
```
|
||
frontend-v2/src/modules/aia/
|
||
├── pages/
|
||
│ ├── Dashboard.tsx # ~400行
|
||
│ └── Workspace.tsx # ~500行
|
||
├── components/
|
||
│ ├── AgentPipeline.tsx # ~300行
|
||
│ ├── AgentCard.tsx # ~100行
|
||
│ ├── IntentSearch.tsx # ~150行
|
||
│ ├── ConversationList.tsx # ~200行
|
||
│ ├── ThinkingBlock.tsx # ~100行
|
||
│ ├── AttachmentUpload.tsx # ~200行
|
||
│ ├── AttachmentCard.tsx # ~80行
|
||
│ └── SlashCommands.tsx # ~150行
|
||
├── hooks/
|
||
│ ├── useConversation.ts # ~150行
|
||
│ ├── useAgents.ts # ~100行
|
||
│ └── useIntentRouter.ts # ~80行
|
||
├── api/
|
||
│ └── index.ts # ~200行
|
||
├── types/
|
||
│ └── index.ts # ~100行
|
||
└── index.tsx # ~50行
|
||
|
||
预计总计：~2900行
|
||
```
|
||
|
||
---
|
||
|
||
## 🔗 依赖关系
|
||
|
||
### 后端依赖
|
||
|
||
| 依赖 | 来源 | 说明 |
|
||
|------|------|------|
|
||
| `logger` | `@/common/logging` | 日志服务 |
|
||
| `storage` | `@/common/storage` | OSS存储 |
|
||
| `cache` | `@/common/cache` | Redis/PG缓存 |
|
||
| `jobQueue` | `@/common/jobs` | 异步任务 |
|
||
| `promptService` | `@/common/prompts` | Prompt管理 |
|
||
| `LLMFactory` | `@/common/llm` | LLM适配器 |
|
||
| `prisma` | `@/config/database` | 数据库 |
|
||
| `ExtractionClient` | `@/clients` | 文档提取 |
|
||
| `TokenService` | `@/services` | Token计数 |
|
||
|
||
### 前端依赖
|
||
|
||
| 依赖 | 来源 | 说明 |
|
||
|------|------|------|
|
||
| `ChatContainer` | `@/shared/components/Chat` | 通用对话组件 |
|
||
| `Ant Design` | `antd` | UI组件库 |
|
||
| `Ant Design X` | `@ant-design/x` | AI对话组件 |
|
||
| `KaTeX` | `katex` | 公式渲染 |
|
||
| `react-markdown` | `react-markdown` | Markdown渲染 |
|
||
|
||
---
|
||
|
||
## 📈 风险评估
|
||
|
||
| 风险 | 概率 | 影响 | 缓解措施 |
|
||
|------|------|------|---------|
|
||
| 流式输出兼容性 | 中 | 高 | 复用已验证的 SSE 代码 |
|
||
| 附件提取超时 | 中 | 中 | 使用 jobQueue 异步处理 |
|
||
| 移动端适配问题 | 低 | 中 | 提前规划断点和布局 |
|
||
| Prompt管理服务未就绪 | 低 | 中 | 可临时回退到文件读取 |
|
||
|
||
---
|
||
|
||
## ✅ 验收标准
|
||
|
||
### 功能验收
|
||
|
||
- [ ] 智能体大厅完整展示
|
||
- [ ] 意图搜索正确路由
|
||
- [ ] 多轮对话正常
|
||
- [ ] 流式输出流畅
|
||
- [ ] 深度思考正确折叠
|
||
- [ ] 附件上传完整
|
||
- [ ] 知识库引用正确
|
||
- [ ] 快捷指令可用
|
||
- [ ] 移动端适配正常
|
||
|
||
### 性能验收
|
||
|
||
- [ ] TTFB < 1.5s
|
||
- [ ] 移动端 LCP < 1s
|
||
- [ ] 意图搜索响应 < 500ms
|
||
|
||
### 质量验收
|
||
|
||
- [ ] 无 console.log（使用 logger）
|
||
- [ ] 代码符合云原生规范
|
||
- [ ] API 文档完整
|
||
- [ ] 单元测试覆盖核心功能
|
||
|
||
---
|
||
|
||
## 📝 更新日志
|
||
|
||
| 日期 | 版本 | 内容 |
|
||
|------|------|------|
|
||
| 2026-01-11 | V1.0 | 创建开发计划 |
|
||
|
||
---
|
||
|
||
**计划制定人**：AI Assistant
|
||
**审核人**：待定
|
||
**批准人**：待定
|
||
|
||
|
||
|
||
|
||
|
||
|