docs: complete documentation system (250+ files)

- System architecture and design documentation - Business module docs (ASL/AIA/PKB/RVW/DC/SSA/ST) - ASL module complete design (quality assurance, tech selection) - Platform layer and common capabilities docs - Development standards and API specifications - Deployment and operations guides - Project management and milestone tracking - Architecture implementation reports - Documentation templates and guides
2025-11-16 15:43:55 +08:00
parent 0fe6821a89
commit e52020409c
173 changed files with 46227 additions and 11964 deletions
--- a/docs/00-系统总体设计/10-核心业务规则总览.md
+++ b/docs/00-系统总体设计/10-核心业务规则总览.md
@@ -0,0 +1,607 @@
+# 核心业务规则总览
+
+> **版本：** v1.0  
+> **创建日期：** 2025-10-10  
+> **适用范围：** 整个系统
+
+---
+
+## 📋 目录
+
+1. [用户管理规则](#用户管理规则)
+2. [项目管理规则](#项目管理规则)
+3. [智能体管理规则](#智能体管理规则)
+4. [对话管理规则](#对话管理规则)
+5. [知识库管理规则](#知识库管理规则)
+6. [权限控制规则](#权限控制规则)
+7. [配额限制规则](#配额限制规则)
+
+---
+
+## 用户管理规则
+
+### 注册规则
+
+**BR-U001: 邮箱唯一性**
+- 规则：每个邮箱只能注册一个账号
+- 验证时机：注册时
+- 错误提示："该邮箱已被注册"
+
+**BR-U002: 邮箱格式验证**
+- 规则：必须是有效的邮箱格式
+- 正则：`^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}$`
+- 错误提示："邮箱格式不正确"
+
+**BR-U003: 密码强度**
+- 规则：密码至少8位，包含字母和数字
+- 正则：`^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d@$!%*#?&]{8,}$`
+- 错误提示："密码至少8位，需包含字母和数字"
+
+**BR-U004: 默认试用期**
+- 规则：新用户默认获得30天试用期
+- 实现：`trial_ends_at = now() + 30天`
+
+### 登录规则
+
+**BR-U005: 账户状态检查**
+- 规则：只有status=active的用户可以登录
+- 状态：
+  - `active` - 可登录
+  - `inactive` - 未激活，不可登录
+  - `suspended` - 已暂停，不可登录
+
+**BR-U006: 密码错误次数限制**
+- 规则：5分钟内最多5次错误尝试
+- 超过次数：临时锁定账户15分钟
+- 实现：使用Redis记录失败次数
+
+**BR-U007: JWT Token有效期**
+- Access Token：7天
+- Refresh Token：30天
+- 过期后需要重新登录
+
+---
+
+## 项目管理规则
+
+### 创建规则
+
+**BR-P001: 项目数量无限制**
+- 规则：用户可以创建任意数量的项目
+- 理由：项目是核心功能，不应限制
+
+**BR-P002: 项目名称必填**
+- 规则：项目名称不能为空
+- 长度：1-200字符
+- 错误提示："项目名称不能为空"
+
+**BR-P003: 项目描述必填**
+- 规则：项目描述不能为空（用于上下文注入）
+- 最小长度：10字符
+- 错误提示："请输入项目背景信息，至少10个字符"
+
+### 更新规则
+
+**BR-P004: 项目背景动态更新**
+- 规则：用户可以随时编辑项目描述
+- 规则：可以"固定"AI回复到项目描述中
+- 实现：追加到description字段末尾
+
+**BR-P005: 项目所有权验证**
+- 规则：只能修改/删除自己的项目
+- 验证：`project.userId === currentUser.id`
+- 错误提示："无权限操作该项目"
+
+### 删除规则
+
+**BR-P006: 级联删除**
+- 规则：删除项目时，级联删除其所有对话和消息
+- 实现：数据库ON DELETE CASCADE
+- 确认：前端需要二次确认
+
+**BR-P007: 软删除（可选）**
+- 规则：重要项目可以先软删除，保留30天
+- 实现：添加deleted_at字段
+- 备注：当前版本暂不实现
+
+---
+
+## 智能体管理规则
+
+### 智能体配置
+
+**BR-A001: 智能体配置化管理**
+- 规则：智能体配置存储在`config/agents.yaml`
+- 规则：不通过数据库管理
+- 规则：修改配置后需要重启服务
+
+**BR-A002: 智能体状态**
+- `active` - 可用，用户可以选择
+- `inactive` - 不可用，隐藏
+- `testing` - 测试中，仅管理员可见
+
+**BR-A003: 智能体分类**
+- 选题阶段：选题评价、科学问题梳理
+- 研究设计：PICOS构建、观察指标设计、CRF制定、样本量计算、临床研究方案撰写
+- 论文阶段：论文润色、论文翻译、方法学评审、期刊方法学评审、期刊稿约评审
+
+### Prompt管理
+
+**BR-A004: Prompt文件管理**
+- 规则：Prompt存储在`backend/prompts/`目录
+- 命名：`{agent_id}_system.txt` 和 `{agent_id}_user.txt`
+- 版本：通过Git管理版本
+
+**BR-A005: Prompt变量注入**
+- 规则：Prompt中可以使用变量
+- 格式：`{variable_name}`
+- 示例：`{project_description}`, `{user_question}`
+
+### 模型配置
+
+**BR-A006: 模型参数配置**
+- 规则：每个智能体可以配置不同模型的参数
+- 参数：
+  - `temperature`: 0.0-1.0
+  - `max_tokens`: 最大输出token数
+  - `top_p`: 0.0-1.0
+
+**BR-A007: 模型切换**
+- 规则：用户可以在对话中切换模型
+- 可选模型：
+  - `deepseek-v3` (默认)
+  - `qwen3-72b`
+  - `gemini-2.0-flash` (可选)
+
+---
+
+## 对话管理规则
+
+### 创建对话
+
+**BR-C001: 对话归属**
+- 规则：对话可以属于项目，也可以是全局快速问答
+- 项目对话：`projectId` 不为null
+- 全局快速问答：`projectId` 为null
+
+**BR-C002: 对话标题自动生成**
+- 规则：首次创建对话时，标题为"与{智能体名称}的对话"
+- 规则：可以手动修改标题
+
+### 上下文管理
+
+**BR-C003: 项目背景自动注入**
+- 规则：如果对话属于项目，自动将项目description注入上下文
+- 注入位置：System prompt之后
+- 格式：`# 项目背景\n{project.description}`
+
+**BR-C004: 历史对话管理**
+- 规则：保留最近10轮对话作为上下文
+- 规则：超过10轮的对话，进行摘要压缩
+- Token限制：上下文总token数不超过6000
+
+**BR-C005: 知识库引用**
+- 规则：用户可以通过`@知识库名称`引用知识库
+- 规则：最多同时引用3个知识库
+- 检索数量：每个知识库检索Top 5结果
+
+### 消息固定
+
+**BR-C006: 固定消息到项目背景**
+- 规则：只有AI回复可以被固定
+- 规则：只有项目内对话可以固定（全局对话不可）
+- 实现：追加到project.description末尾
+- 格式：
+  ```
+  --- 来自对话的补充 ---
+  {message.content}
+  ```
+
+**BR-C007: 固定消息标记**
+- 规则：被固定的消息，isPinned字段设为true
+- 规则：固定后不可取消（简化实现）
+
+### 流式输出
+
+**BR-C008: Server-Sent Events**
+- 规则：使用SSE实现流式输出
+- 事件类型：
+  - `start`: 开始生成
+  - `token`: 每个token
+  - `done`: 完成
+  - `error`: 错误
+
+**BR-C009: 流式输出超时**
+- 规则：单个请求最长60秒
+- 超时后：返回已生成的内容
+- 错误提示："生成超时，请重试"
+
+---
+
+## 知识库管理规则
+
+### 数量限制
+
+**BR-K001: 知识库数量限制**
+- 规则：每个用户最多创建3个知识库
+- 验证时机：创建知识库时
+- 错误提示："已达到知识库数量上限（3个）"
+
+**BR-K002: 文档数量限制**
+- 规则：每个知识库最多上传50个文档
+- 验证时机：上传文档时
+- 错误提示："该知识库文档数量已达上限（50个）"
+
+### 文档上传
+
+**BR-K003: 文件格式限制**
+- 规则：只支持PDF和DOCX格式
+- MIME类型：
+  - `application/pdf`
+  - `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
+- 错误提示："仅支持PDF和DOCX格式"
+
+**BR-K004: 文件大小限制**
+- 规则：单个文件最大50MB
+- 验证时机：上传前（前端）和上传后（后端）
+- 错误提示："文件大小超过限制（最大50MB）"
+
+**BR-K005: 文件名唯一性**
+- 规则：同一知识库内，文件名不能重复
+- 验证：检查是否已存在同名文件
+- 处理：自动重命名（添加时间戳）
+
+### 文档处理
+
+**BR-K006: 文档处理状态**
+- 状态流转：
+  1. `uploading` - 上传中
+  2. `processing` - Dify处理中
+  3. `completed` - 处理完成
+  4. `failed` - 处理失败
+
+**BR-K007: 处理失败重试**
+- 规则：处理失败的文档不自动重试
+- 规则：用户可以删除后重新上传
+- 错误信息：记录在error_message字段
+
+**BR-K008: 异步处理**
+- 规则：文档上传后立即返回
+- 规则：后台异步提交到Dify处理
+- 规则：前端轮询获取处理状态
+
+### 知识库检索
+
+**BR-K009: 混合检索**
+- 规则：使用关键词检索 + 语义检索
+- 规则：启用Reranking重排序
+- Top K：5个结果
+- 相似度阈值：0.5
+
+**BR-K010: 检索结果引用**
+- 规则：AI回答必须注明引用来源
+- 格式：`[文档名] 内容...`
+- 规则：前端显示可点击的引用标记
+
+---
+
+## 权限控制规则
+
+### 用户权限
+
+**BR-P001: 角色定义**
+- `user` - 普通用户
+  - 可以使用所有功能
+  - 受配额限制
+- `admin` - 管理员
+  - 所有user权限
+  - 可以访问运营后台
+  - 可以查看所有用户数据
+
+### 数据隔离
+
+**BR-P002: 用户数据隔离**
+- 规则：用户只能访问自己创建的数据
+- 验证：所有查询必须包含userId过滤
+- 实现：
+  ```sql
+  WHERE user_id = currentUser.id
+  ```
+
+**BR-P003: 项目权限验证**
+- 规则：修改/删除项目前，验证所有权
+- 实现：
+  ```typescript
+  const project = await prisma.project.findFirst({
+    where: { id: projectId, userId: currentUser.id }
+  })
+  if (!project) throw new UnauthorizedError()
+  ```
+
+### 管理员权限
+
+**BR-P004: 用户管理权限**
+- 规则：只有admin可以查看用户列表
+- 规则：只有admin可以修改用户状态
+- 规则：admin不能删除用户（只能暂停）
+
+**BR-P005: 对话查看权限**
+- 规则：只有admin可以查看用户对话
+- 规则：必须记录审计日志
+- 规则：敏感信息需要脱敏（如邮箱、手机号）
+
+---
+
+## 配额限制规则
+
+### 知识库配额
+
+**BR-Q001: 知识库数量配额**
+- 默认配额：3个知识库
+- 记录字段：`users.kb_quota`, `users.kb_used`
+- 更新时机：创建/删除知识库时
+
+**BR-Q002: 文档数量配额**
+- 默认配额：50个文档/知识库
+- 检查时机：上传文档前
+- 实现：
+  ```sql
+  SELECT COUNT(*) FROM documents 
+  WHERE kb_id = ? AND status != 'failed'
+  ```
+
+### 存储配额（预留）
+
+**BR-Q003: 存储空间配额**
+- 默认配额：1GB/用户
+- 当前版本：不强制限制
+- 未来：可以根据实际需求启用
+
+### API限流
+
+**BR-Q004: API请求频率限制**
+- 普通用户：100次/分钟
+- 管理员：500次/分钟
+- 实现：使用Redis + 滑动窗口算法
+
+**BR-Q005: 登录接口限流**
+- 规则：5次/分钟
+- 规则：IP和账户双重限制
+- 超过后：临时封禁15分钟
+
+---
+
+## 业务流程
+
+### 完整的对话流程
+
+```
+1. 用户选择智能体
+   ↓
+2. 创建对话（可选关联项目）
+   ↓
+3. 用户发送消息（可选引用知识库）
+   ↓
+4. 后端组装上下文：
+   - 项目背景（如有）
+   - 智能体System Prompt
+   - 历史对话（最近10轮）
+   - 知识库检索结果（如有）
+   - 当前用户问题
+   ↓
+5. 调用LLM（流式输出）
+   ↓
+6. 保存消息到数据库
+   ↓
+7. 用户可选：固定消息到项目背景
+```
+
+### 知识库文档处理流程
+
+```
+1. 用户上传文档
+   ↓
+2. 验证：
+   - 文件格式
+   - 文件大小
+   - 数量限制
+   ↓
+3. 上传到对象存储（OSS）
+   ↓
+4. 创建document记录（status: uploading）
+   ↓
+5. 异步提交到Dify：
+   - 调用Dify上传API
+   - 获取dify_document_id
+   ↓
+6. 轮询处理状态（每2秒）：
+   - processing → 更新progress
+   - completed → 更新status, segments_count, tokens_count
+   - failed → 更新status, error_message
+   ↓
+7. 更新知识库统计：
+   - file_count
+   - total_size_bytes
+```
+
+---
+
+## 数据一致性规则
+
+### 统计字段更新
+
+**BR-D001: 项目对话数统计**
+- 字段：`projects.conversation_count`
+- 更新时机：创建/删除对话时
+- 实现：使用事务保证一致性
+
+**BR-D002: 知识库文档数统计**
+- 字段：`knowledge_bases.file_count`
+- 更新时机：文档状态变为completed或删除时
+- 计算：只统计status='completed'的文档
+
+**BR-D003: 用户知识库数统计**
+- 字段：`users.kb_used`
+- 更新时机：创建/删除知识库时
+- 验证：创建前检查是否超过quota
+
+### 级联删除
+
+**BR-D004: 用户删除级联**
+- 规则：删除用户时，级联删除所有关联数据
+- 包括：projects, conversations, messages, knowledge_bases, documents
+- 实现：数据库ON DELETE CASCADE
+
+**BR-D005: 项目删除级联**
+- 规则：删除项目时，级联删除所有对话和消息
+- 实现：数据库ON DELETE CASCADE
+
+**BR-D006: 知识库删除级联**
+- 规则：删除知识库时：
+  1. 级联删除数据库中的documents
+  2. 调用Dify API删除dataset
+  3. 删除对象存储中的文件
+
+---
+
+## 异常处理规则
+
+### 错误类型
+
+**BR-E001: 业务错误**
+- 验证失败：HTTP 422
+- 资源不存在：HTTP 404
+- 权限不足：HTTP 403
+- 配额超限：HTTP 403
+
+**BR-E002: 系统错误**
+- 数据库错误：HTTP 500
+- 网络错误：HTTP 503
+- Dify服务错误：HTTP 503
+
+### 错误响应
+
+**BR-E003: 统一错误格式**
+```json
+{
+  "success": false,
+  "error": {
+    "code": "QUOTA_EXCEEDED",
+    "message": "知识库数量已达上限",
+    "details": {
+      "resource": "knowledge_base",
+      "quota": 3,
+      "used": 3
+    }
+  },
+  "timestamp": "2025-10-10T10:00:00.000Z"
+}
+```
+
+---
+
+## 安全规则
+
+### 密码安全
+
+**BR-S001: 密码加密**
+- 算法：bcrypt
+- 成本因子：12
+- 规则：永不存储明文密码
+
+**BR-S002: Token安全**
+- 规则：Token包含用户ID和角色
+- 规则：Token签名使用JWT_SECRET
+- 规则：过期Token自动失效
+
+### SQL注入防护
+
+**BR-S003: 使用ORM**
+- 规则：所有数据库操作使用Prisma ORM
+- 规则：禁止拼接SQL语句
+- 规则：使用参数化查询
+
+### XSS防护
+
+**BR-S004: 输入转义**
+- 规则：所有用户输入在显示前转义
+- 规则：使用React默认转义
+- 规则：禁止使用dangerouslySetInnerHTML（除非必要）
+
+---
+
+## 性能优化规则
+
+### 缓存规则
+
+**BR-O001: 智能体列表缓存**
+- 规则：智能体列表缓存1小时
+- 实现：Redis缓存
+- 失效：修改agents.yaml后需清除缓存
+
+**BR-O002: 用户信息缓存**
+- 规则：用户信息缓存5分钟
+- Key：`user:{userId}`
+- 失效：用户信息更新时
+
+### 查询优化
+
+**BR-O003: 分页查询**
+- 规则：列表查询必须分页
+- 默认：20条/页
+- 最大：100条/页
+
+**BR-O004: 索引使用**
+- 规则：频繁查询的字段必须建立索引
+- 包括：email, userId, projectId, conversationId
+- 定期：检查慢查询日志
+
+---
+
+## 数据保留规则
+
+### 数据归档
+
+**BR-R001: 对话归档（未来）**
+- 规则：超过6个月的对话自动归档
+- 归档表：conversations_archive
+- 查询：默认不查询归档数据
+
+**BR-R002: 日志清理**
+- 规则：admin_logs保留3个月
+- 执行：定时任务每月清理
+
+---
+
+## 业务规则变更流程
+
+1. **提出变更**：填写变更申请
+2. **影响评估**：评估对系统的影响
+3. **Review**：技术团队Review
+4. **更新文档**：同步更新本文档
+5. **实施变更**：修改代码
+6. **测试验证**：测试新规则
+7. **上线发布**：发布到生产
+
+---
+
+**文档维护：** 业务规则变更需同步更新  
+**Review频率：** 每个里程碑Review一次  
+**最后更新：** 2025-10-10  
+**维护者：** 产品经理 + 技术负责人
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+