# 核心业务规则总览

> **版本：** 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  
**维护者：** 产品经理 + 技术负责人