🎯 派洞察——科研文献智能 RAG 知识库系统

🛡️ 管理员模块

模块定位：管理员模块是系统的核心管理模块，负责处理系统管理、用户管理、知识库管理和系统监控等高级功能。

🎯 核心目标

  • ✅ 系统管理：提供系统级别的配置和管理功能
  • ✅ 用户管控：管理所有用户账户，包括创建、修改、权限分配等
  • ✅ 知识库维护：管理知识库文档，包括添加、删除、分类等
  • ✅ 系统监控：实时监控系统状态和用户活动
  • ✅ 安全保障：确保系统运行的安全性和稳定性

📊 一、功能需求

👥 用户管理

📝 功能描述：管理员可以查看、创建、修改和删除用户账户，分配组织标签和管理权限。

🔧 管理功能：

  • 查看所有用户列表和详细信息
  • 创建新的管理员用户
  • 为用户分配组织标签
  • 管理用户权限和状态

📚 知识库管理

📖 功能描述：管理员可以管理知识库文档，包括添加新文档、删除旧文档等维护操作。

🔧 管理功能：

  • 添加新的知识库文档
  • 删除不需要的文档
  • 管理文档描述和分类

📊 系统监控

📈 功能描述：实时监控系统的运行状态，包括资源使用情况和用户活动。

🔧 监控内容：

  • CPU、内存、磁盘使用率
  • 活跃用户数
  • 文档总数和对话总数
  • 用户活动日志

🏷️ 组织标签管理

🆔 功能描述：管理员可以创建、修改、删除组织标签，构建组织标签树结构。

🔧 管理功能：

  • 创建新的组织标签
  • 更新现有标签信息
  • 删除不需要的标签
  • 获取标签树结构

💬 对话历史管理

📝 功能描述：管理员可以查看和查询所有用户的对话历史，支持按用户和时间范围筛选。

🔧 查询功能：

  • 查看所有用户的对话历史
  • 按指定用户筛选对话
  • 按时间范围筛选对话
  • 导出对话记录

🛠️ 二、技术方案

🔐 身份认证与授权

🛡️ 管理员验证：所有管理员接口都需要验证用户的管理员身份，确保只有管理员才能访问。

🔑 JWT认证：使用JWT token进行身份认证，从请求头中提取并验证token。

🎯 权限控制：基于角色的访问控制（RBAC），只有ADMIN角色的用户才能访问管理员接口。

💾 数据持久化

🗄️ MySQL：存储用户信息、组织标签、知识库文档信息等结构化数据。

⚡ Redis：缓存用户会话信息、对话历史、系统状态等实时数据。

🚀 Spring Data JPA：提供数据库操作的ORM支持，简化数据访问层开发。

🧰 辅助工具

🔤 Apache Commons Lang3：提供字符串处理、集合操作等工具方法。

📝 Jackson：JSON序列化和反序列化，处理API请求响应数据。

📊 LogUtils：统一的日志记录工具，记录业务操作和性能监控。

🔍 系统监控

📈 性能监控：使用LogUtils.PerformanceMonitor监控系统接口性能。

📝 业务日志：记录所有管理员操作的详细日志，便于审计和问题追踪。

⚠️ 错误处理：统一的异常处理机制，确保系统稳定性。

📝 三、关键流程

📋 1. 获取所有用户列表

🔄 流程步骤

  1. 🔍 提取Token：从Authorization头中提取Bearer token
  2. ✅ 验证管理员：验证当前用户是否为管理员
  3. 📊 查询用户：调用userRepository.findAll()获取所有用户
  4. 🛡️ 数据脱敏：移除用户密码等敏感信息
  5. 📤 返回结果：返回用户列表数据

接口设计

请求URL

1
GET /api/v1/admin/users

请求头

1
Authorization: Bearer JWT_TOKEN

成功响应

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "code": 200,
  "message": "Get all users successful",
  "data": [
    {
      "id": 1,
      "username": "user1",
      "role": "USER",
      "orgTags": ["PRIVATE_user1"],
      "primaryOrg": "PRIVATE_user1"
    }
  ]
}

失败响应

1
2
3
4
{
  "code": 500,
  "message": "Failed to get users: error message"
}

📚 2. 添加知识库文档

🔄 流程步骤

  1. 📤 接收请求：接收文件和描述信息
  2. ✅ 验证管理员：验证当前用户的管理员身份
  3. 📁 文件处理：处理上传的文档文件
  4. 💾 存储文档：将文档信息保存到知识库
  5. 📝 记录日志：记录添加文档的操作日志
  6. 📤 返回结果：返回操作成功信息

接口设计

请求URL

1
POST /api/v1/admin/knowledge/add

请求参数

1
2
file: MultipartFile        // 文档文件
description: String        // 文档描述

成功响应

1
2
3
{
  "message": "文档已成功添加到知识库"
}

失败响应

1
2
3
{
  "error": "添加文档失败: error message"
}

🗑️ 3. 删除知识库文档

🔄 流程步骤

  1. 📋 接收参数：接收文档ID参数
  2. ✅ 验证管理员：验证当前用户的管理员身份
  3. 🔍 查找文档：验证文档是否存在
  4. 🗑️ 删除文档：从知识库中删除指定文档
  5. 📝 记录日志：记录删除文档的操作日志
  6. 📤 返回结果：返回删除成功信息

接口设计

请求URL

1
DELETE /api/v1/admin/knowledge/{documentId}

路径参数

1
documentId: String    // 文档唯一标识

成功响应

1
2
3
{
  "message": "文档已成功从知识库中删除"
}

失败响应

1
2
3
{
  "error": "删除文档失败: error message"
}

📊 4. 获取系统状态

🔄 流程步骤

  1. ✅ 验证管理员：验证当前用户的管理员身份
  2. 📈 收集数据：收集系统各项状态指标
  3. 📊 计算指标：计算CPU、内存、磁盘使用率等
  4. 📤 返回结果：返回系统状态信息

接口设计

请求URL

1
GET /api/v1/admin/system/status

成功响应

1
2
3
4
5
6
7
8
9
10
{
  "data": {
    "cpu_usage": "30%",
    "memory_usage": "45%",
    "disk_usage": "60%",
    "active_users": 15,
    "total_documents": 250,
    "total_conversations": 1200
  }
}

失败响应

1
2
3
{
  "error": "获取系统状态失败: error message"
}

📋 5. 获取用户活动日志

🔄 流程步骤

  1. ✅ 验证管理员：验证当前用户的管理员身份
  2. 🔍 参数解析：解析查询参数（用户名、时间范围等）
  3. 📊 查询日志：从数据库或缓存中获取用户活动数据
  4. ⏰ 时间过滤：根据时间范围筛选活动记录
  5. 📤 返回结果：返回用户活动日志列表

接口设计

请求URL

1
GET /api/v1/admin/user-activities

请求参数

1
2
3
username: String (可选)    // 指定用户名
start_date: String (可选)  // 开始时间
end_date: String (可选)    // 结束时间

成功响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "data": [
    {
      "username": "user1",
      "action": "LOGIN",
      "timestamp": "2023-03-01T10:15:30",
      "ip_address": "192.168.1.100"
    },
    {
      "username": "user2",
      "action": "UPLOAD_FILE",
      "timestamp": "2023-03-01T11:20:45",
      "ip_address": "192.168.1.101"
    }
  ]
}

👤 6. 创建管理员用户

🔄 流程步骤

  1. ✅ 验证管理员：验证当前用户的管理员身份
  2. 📋 参数验证：验证新管理员用户名和密码
  3. 🔍 重复检查：检查用户名是否已存在
  4. 🔐 密码加密：使用BCrypt加密新用户密码
  5. 🎭 角色分配：为新用户分配ADMIN角色
  6. 🏷️ 创建标签：创建私有组织标签
  7. 💾 保存用户：将新管理员信息保存到数据库
  8. 📤 返回结果：返回创建成功信息

接口设计

请求URL

1
POST /api/v1/admin/users/create-admin

请求体

1
2
3
4
{
  "username": "new_admin",
  "password": "secure_password"
}

成功响应

1
2
3
4
{
  "code": 200,
  "message": "管理员用户创建成功"
}

失败响应

1
2
3
4
{
  "code": 400,
  "message": "用户名已存在"
}

🏷️ 7. 创建组织标签

🔄 流程步骤

  1. ✅ 验证管理员：验证当前用户的管理员身份
  2. 📋 参数验证：验证标签ID、名称等必填参数
  3. 🔍 重复检查：检查标签ID是否已存在
  4. 👪 父标签验证：验证父标签是否存在（如果有）
  5. 💾 保存标签：将新标签信息保存到数据库
  6. 📤 返回结果：返回创建成功的标签信息

接口设计

请求URL

1
POST /api/v1/admin/org-tags

请求体

1
2
3
4
5
6
{
  "tagId": "dept_research",
  "name": "研究部",
  "description": "研究部门组织标签",
  "parentTag": "company"  // 可选
}

成功响应

1
2
3
4
5
6
7
8
9
10
{
  "code": 200,
  "message": "组织标签创建成功",
  "data": {
    "tagId": "dept_research",
    "name": "研究部",
    "description": "研究部门组织标签",
    "parentTag": "company"
  }
}

📋 8. 获取所有组织标签

🔄 流程步骤

  1. ✅ 验证管理员：验证当前用户的管理员身份
  2. 📊 查询标签：从数据库获取所有组织标签
  3. 📤 返回结果：返回标签列表

接口设计

请求URL

1
GET /api/v1/admin/org-tags

成功响应

1
2
3
4
5
6
7
8
9
10
11
{
  "code": 200,
  "message": "获取组织标签成功",
  "data": [
    {
      "tagId": "dept_research",
      "name": "研究部",
      "description": "研究部门组织标签"
    }
  ]
}

🔗 9. 为用户分配组织标签

🔄 流程步骤

  1. ✅ 验证管理员：验证当前用户的管理员身份
  2. 📋 参数验证：验证用户ID和标签列表
  3. 🔍 用户验证：验证目标用户是否存在
  4. 🏷️ 标签验证：验证所有标签是否存在
  5. 🔗 分配标签：将标签分配给用户
  6. 📝 记录日志：记录标签分配操作
  7. 📤 返回结果：返回分配成功信息

接口设计

请求URL

1
PUT /api/v1/admin/users/{userId}/org-tags

路径参数

1
userId: Long    // 用户ID

请求体

1
2
3
{
  "orgTags": ["dept_research", "team_ai"]
}

成功响应

1
2
3
4
{
  "code": 200,
  "message": "组织标签分配成功"
}

🌳 10. 获取组织标签树结构

🔄 流程步骤

  1. ✅ 验证管理员：验证当前用户的管理员身份
  2. 📊 构建树形：从数据库获取标签并构建树形结构
  3. 🔄 层级处理：处理父子标签关系
  4. 📤 返回结果：返回树形结构的标签数据

接口设计

请求URL

1
GET /api/v1/admin/org-tags/tree

成功响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "code": 200,
  "message": "获取组织标签树成功",
  "data": [
    {
      "tagId": "company",
      "name": "公司",
      "children": [
        {
          "tagId": "dept_research",
          "name": "研究部"
        }
      ]
    }
  ]
}

✏️ 11. 更新组织标签

🔄 流程步骤

  1. ✅ 验证管理员：验证当前用户的管理员身份
  2. 📋 参数验证：验证更新参数
  3. 🔍 标签验证：验证目标标签是否存在
  4. 👪 父标签验证：验证新的父标签（如果有）
  5. ✏️ 更新信息：更新标签的名称、描述等信息
  6. 📝 记录日志：记录标签更新操作
  7. 📤 返回结果：返回更新后的标签信息

接口设计

请求URL

1
PUT /api/v1/admin/org-tags/{tagId}

路径参数

1
tagId: String    // 标签ID

请求体

1
2
3
4
5
{
  "name": "更新后的名称",
  "description": "更新后的描述",
  "parentTag": "new_parent"  // 可选
}

成功响应

1
2
3
4
5
6
7
8
9
{
  "code": 200,
  "message": "组织标签更新成功",
  "data": {
    "tagId": "dept_research",
    "name": "更新后的名称",
    "description": "更新后的描述"
  }
}

🗑️ 12. 删除组织标签

🔄 流程步骤

  1. ✅ 验证管理员：验证当前用户的管理员身份
  2. 🔍 标签验证：验证目标标签是否存在
  3. ⚠️ 依赖检查：检查是否有子标签或用户关联
  4. 🗑️ 删除标签：从数据库中删除标签
  5. 📝 记录日志：记录标签删除操作
  6. 📤 返回结果：返回删除成功信息

接口设计

请求URL

1
DELETE /api/v1/admin/org-tags/{tagId}

路径参数

1
tagId: String    // 要删除的标签ID

成功响应

1
2
3
4
{
  "code": 200,
  "message": "组织标签删除成功"
}

失败响应

1
2
3
4
{
  "code": 400,
  "message": "该标签正在被使用，无法删除"
}

📋 13. 获取用户列表（分页）

🔄 流程步骤

  1. ✅ 验证管理员：验证当前用户的管理员身份
  2. 📋 参数解析：解析分页参数和筛选条件
  3. 🔍 条件查询：根据关键词、组织标签、状态等条件查询用户
  4. 📊 分页处理：执行分页查询
  5. 📤 返回结果：返回分页的用户数据

接口设计

请求URL

1
GET /api/v1/admin/users/list

请求参数

1
2
3
4
5
keyword: String (可选)     // 搜索关键词
orgTag: String (可选)      // 组织标签筛选
status: Integer (可选)     // 用户状态筛选
page: int (默认1)         // 页码
size: int (默认20)        // 每页数量

成功响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "code": 200,
  "message": "获取用户列表成功",
  "data": {
    "content": [
      {
        "id": 1,
        "username": "user1",
        "role": "USER",
        "orgTags": ["PRIVATE_user1"],
        "primaryOrg": "PRIVATE_user1"
      }
    ],
    "totalElements": 100,
    "totalPages": 5,
    "currentPage": 1,
    "pageSize": 20
  }
}

💬 14. 管理员查询所有对话历史

🔄 流程步骤

  1. ✅ 验证管理员：验证当前用户的管理员身份
  2. 📋 参数解析：解析查询参数（用户ID、时间范围等）
  3. 🔍 用户验证：如果指定用户ID，验证用户是否存在
  4. 📊 查询对话：从Redis中查询所有对话历史
  5. ⏰ 时间过滤：根据时间范围筛选对话记录
  6. 📤 返回结果：返回格式化的对话历史数据

接口设计

请求URL

1
GET /api/v1/admin/conversation

请求参数

1
2
3
userid: String (可选)      // 指定用户ID
start_date: String (可选)  // 开始时间 (格式: 2023-01-01T12:00:00)
end_date: String (可选)    // 结束时间 (格式: 2023-01-01T12:00:00)

成功响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "code": 200,
  "message": "获取对话历史成功",
  "data": [
    {
      "role": "user",
      "content": "用户消息内容",
      "timestamp": "2023-03-01T10:15:30",
      "username": "user1"
    },
    {
      "role": "assistant",
      "content": "助手回复内容",
      "timestamp": "2023-03-01T10:15:32",
      "username": "user1"
    }
  ]
}

失败响应

1
2
3
4
{
  "code": 404,
  "message": "目标用户不存在"
}

🗃️ 四、库表设计

👤 1. 用户表

与用户管理模块共用，详见用户管理模块文档

🏷️ 2. 组织标签表

与用户管理模块共用，详见用户管理模块文档

📊 3. 系统日志表

字段设计

1
2
3
4
5
6
7
8
9
10
11
12
| 🔑 **字段** | 📋 **类型** | 📝 **描述** |
| --- | --- | --- |
| `id` | `BIGINT` | 🆔 主键，日志ID |
| `operation_type` | `VARCHAR(50)` | 📋 操作类型 |
| `operator` | `VARCHAR(255)` | 👤 操作者用户名 |
| `target_user` | `VARCHAR(255)` | 🎯 目标用户（可选） |
| `details` | `TEXT` | 📝 操作详情 |
| `ip_address` | `VARCHAR(45)` | 🌐 IP地址 |
| `user_agent` | `TEXT` | 🧭 用户代理 |
| `status` | `ENUM('SUCCESS', 'FAILURE')` | ✅ 操作状态 |
| `error_message` | `TEXT` | ❌ 错误信息（失败时） |
| `created_at` | `TIMESTAMP` | 📅 创建时间 |

建表语句

1
2
3
4
5
6
7
8
9
10
11
12
13
14
CREATE TABLE system_logs (
    id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '日志唯一标识',
    operation_type VARCHAR(50) NOT NULL COMMENT '操作类型',
    operator VARCHAR(255) NOT NULL COMMENT '操作者用户名',
    target_user VARCHAR(255) DEFAULT NULL COMMENT '目标用户',
    details TEXT COMMENT '操作详情',
    ip_address VARCHAR(45) DEFAULT NULL COMMENT 'IP地址',
    user_agent TEXT COMMENT '用户代理',
    status ENUM('SUCCESS', 'FAILURE') NOT NULL COMMENT '操作状态',
    error_message TEXT COMMENT '错误信息',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    INDEX idx_operator (operator) COMMENT '操作者索引',
    INDEX idx_created_at (created_at) COMMENT '时间索引'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统日志表';

📚 4. 知识库文档表

字段设计

1
2
3
4
5
6
7
8
9
10
11
12
13
| 🔑 **字段** | 📋 **类型** | 📝 **描述** |
| --- | --- | --- |
| `id` | `BIGINT` | 🆔 主键，文档ID |
| `document_id` | `VARCHAR(100)` | 📄 文档唯一标识 |
| `file_name` | `VARCHAR(255)` | 📎 文件名 |
| `file_path` | `TEXT` | 📍 文件路径 |
| `description` | `TEXT` | 📝 文档描述 |
| `file_size` | `BIGINT` | 📏 文件大小 |
| `mime_type` | `VARCHAR(100)` | 🎯 文件类型 |
| `uploaded_by` | `BIGINT` | 👤 上传者ID |
| `status` | `ENUM('ACTIVE', 'DELETED')` | 📊 文档状态 |
| `created_at` | `TIMESTAMP` | 📅 创建时间 |
| `updated_at` | `TIMESTAMP` | 🔄 更新时间 |

建表语句

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
CREATE TABLE knowledge_documents (
    id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '文档唯一标识',
    document_id VARCHAR(100) NOT NULL UNIQUE COMMENT '文档唯一标识',
    file_name VARCHAR(255) NOT NULL COMMENT '文件名',
    file_path TEXT NOT NULL COMMENT '文件存储路径',
    description TEXT COMMENT '文档描述',
    file_size BIGINT NOT NULL COMMENT '文件大小',
    mime_type VARCHAR(100) NOT NULL COMMENT '文件MIME类型',
    uploaded_by BIGINT NOT NULL COMMENT '上传者ID',
    status ENUM('ACTIVE', 'DELETED') DEFAULT 'ACTIVE' COMMENT '文档状态',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    FOREIGN KEY (uploaded_by) REFERENCES users(id),
    INDEX idx_document_id (document_id) COMMENT '文档ID索引',
    INDEX idx_status (status) COMMENT '状态索引',
    INDEX idx_created_at (created_at) COMMENT '时间索引'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='知识库文档表';