AIclinicalresearch/docs/00-系统总体设计/10-核心业务规则总览.md

核心业务规则总览

版本： 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过滤
• 实现：

  WHERE user_id = currentUser.id
  

BR-P003: 项目权限验证

• 规则：修改/删除项目前，验证所有权
• 实现：

  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个文档/知识库
• 检查时机：上传文档前
• 实现：

  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: 统一错误格式

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