# aurak 文档
> 生成于: 2026年08月05日 11:04
> 模板: detailed (36 页)
> 引擎: RAG + LLM
---
## 目录
- [1.1 编写目的](#11-编写目的)
- [1.2 背景](#12-背景)
- [1.3 定义](#13-定义)
- [1.4 参考资料](#14-参考资料)
- [2.1 需求概述](#21-需求概述)
- [2.2 技术选型](#22-技术选型)
- [2.3 软件结构](#23-软件结构)
- [3.1 功能清单](#31-功能清单)
- [3.2 流程逻辑](#32-流程逻辑)
- [3.3 核心业务](#33-核心业务)
- [4.1 表详细设计](#41-表详细设计)
- [4.2 主键与外键策略](#42-主键与外键策略)
- [4.3 索引设计](#43-索引设计)
- [4.4 存储分配](#44-存储分配)
- [5.1 外部接口](#51-外部接口)
- [5.2 内部接口](#52-内部接口)
- [5.3 数据格式](#53-数据格式)
- [6.1 布局与导航](#61-布局与导航)
- [6.2 组件](#62-组件)
- [6.3 状态管理](#63-状态管理)
- [7.1 认证与授权](#71-认证与授权)
- [7.2 传输安全](#72-传输安全)
- [7.3 输入验证](#73-输入验证)
- [7.4 数据库安全](#74-数据库安全)
- [7.5 审计与日志](#75-审计与日志)
- [8.1 环境配置](#81-环境配置)
- [8.2 容器化](#82-容器化)
- [8.3 监控与日志](#83-监控与日志)
- [8.4 故障排查](#84-故障排查)
- [9.1 单元测试](#91-单元测试)
- [9.2 集成测试](#92-集成测试)
- [9.3 E2E 测试](#93-e2e-测试)
- [10.1 代码风格](#101-代码风格)
- [10.2 分支与提交规范](#102-分支与提交规范)
- [10.3 环境变量清单](#103-环境变量清单)
- [10.4 变更记录](#104-变更记录)
---
## 1. 引言
### 1.1 编写目的
#### 文档目的
本文档为 **AuraK 企业级 AI 知识库与人才评估平台** 的完整技术参考手册，旨在为不同角色的读者提供准确、可执行的系统说明。
##### 编写背景
AuraK 是一个集多租户管理、基于角色的访问控制（RBAC）、AI 智能评估、知识库管理、多模型 AI 引擎及飞书机器人集成于一体的企业级平台。系统采用前后端分离架构，后端基于 NestJS 构建，前端使用 React 与 Vite，并依赖 Elasticsearch、Tika、LibreOffice 等基础服务组件。
随着系统功能模块持续扩展（当前已涵盖 20 余个业务模块、26 项细粒度权限、多套评估模板及完整的租户隔离机制），亟需一份系统性的技术文档，以统一开发、测试、运维及二次开发人员对系统架构与实现细节的理解。
##### 编写目的
本文档主要实现以下目标：
1. **架构说明**：阐述系统的整体架构设计，包括多租户数据隔离机制、RBAC 三级权限体系（SUPER_ADMIN / TENANT_ADMIN / USER）、AI 评估工作流（自动出题、自适应追问、多维加权评分）以及知识库双通道处理（Tika 快速解析与 Vision Pipeline 高精度解析）。
2. **开发指导**：为后端（NestJS + TypeORM + SQLite/Elasticsearch）与前端（React + Vite + TailwindCSS）开发人员提供模块划分、实体关系、服务接口及代码约定的详细说明，降低新成员上手成本。
3. **部署与运维参考**：提供基于 Docker Compose 的基础设施编排（Elasticsearch、Tika、LibreOffice）、Nginx 反向代理与 SSL 配置、环境变量说明及常见运维操作指引。
4. **测试规范**：汇总现有测试体系（Playwright E2E、Jest 单元测试、API 冒烟测试脚本），明确测试覆盖范围与执行方式。
##### 预期读者
本文档面向以下读者群体：
| 读者角色 | 关注重点 | 建议章节 |
|---|---|---|
| 后端开发工程师 | 模块划分、实体关系、API 设计、权限守卫流程、AI 评估图编排 | 架构设计、数据模型、API 参考、AI 评估引擎 |
| 前端开发工程师 | 页面路由、组件结构、服务调用方式、状态管理 | 前端架构、页面功能说明 |
| 测试工程师 | 测试计划、E2E 用例、接口测试脚本、性能验证方法 | 测试指南 |
| 运维工程师 | 部署拓扑、Docker 编排、环境配置、日志与监控 | 部署与运维 |
| 技术管理者 | 系统能力边界、安全模型、扩展性设计 | 系统概述、安全模型 |
##### 文档范围
本文档覆盖 AuraK 系统的全部核心子系统，包括但不限于：
- **认证与权限**：JWT 认证、API Key 机制、多级权限守卫、角色与权限实体
- **多租户**：租户中间件、数据隔离订阅器、租户成员与设置管理
- **AI 评估**：评估模板、题库管理、图编排（分析→生成→追问→评分）、证书系统
- **知识库**：文档解析（Tika/OCR/Vision Pipeline）、文本分块、向量化与混合检索（BM25 + 向量）
- **AI 引擎**：多模型接入（OpenAI 兼容 + Gemini）、Embedding/Rerank/Vision 模型配置、SSE 流式输出
- **飞书集成**：WebSocket 网关、交互式消息卡片、移动端评估会话
- **基础功能**：笔记管理、搜索历史、导入任务、模型配置、系统设置
> 注：各模块的详细 API 端点、数据库表结构及错误码说明，请分别参阅本文档对应章节。
### 1.2 背景
#### 项目定位
AuraK 是一款面向企业的 AI 知识库与人才评估平台，定位为将知识管理与人才能力评估相结合的一体化解决方案。项目名称中的 "Aura" 寓意平台能够洞察用户的能力特质，"K" 代表 Knowledge（知识），整体体现了"以知识为基础、以评估为手段"的产品理念。
#### 核心业务能力
平台围绕六大核心能力构建，覆盖企业知识管理与人才评估的完整链路：
| 能力领域 | 核心功能 |
|---------|---------|
| 多租户架构 | 严格的数据隔离、层级化组织树、租户级独立配置 |
| 权限体系（RBAC） | 三级角色（超级管理员/租户管理员/普通用户）、26 项细粒度权限、自定义角色与可视化权限矩阵 |
| AI 智能评估 | 自动出题（选择题+简答题）、自适应追问对话、加权多维度评分、证书颁发系统 |
| 知识库管理 | 双通道文档处理（Tika 快速解析 / Vision Pipeline 高精度解析）、混合检索（BM25 + 向量）、多格式文件支持 |
| AI 引擎 | 多模型接入（兼容 OpenAI 协议及 Gemini）、可配置的 LLM/Embedding/Rerank/Vision 模型、SSE 流式输出 |
| 飞书机器人 | WebSocket 集成、交互式消息卡片、移动端评估能力 |
#### 技术架构概览
平台采用前后端分离架构，后端基于 NestJS 框架构建，前端使用 React 技术栈。系统集成 Elasticsearch 实现全文检索与向量检索，通过 Tika 与 LibreOffice 服务完成文档解析与格式转换，并引入 LangChain 图编排引擎驱动 AI 评估流程。
##### 后端核心模块
- **评估引擎**：基于 LangChain 图结构编排，包含题目生成器、面试官节点、评分节点与分析器节点，支持多轮对话式评估
- **知识库服务**：提供文档导入、文本分块、向量化、混合检索及重排序能力
- **租户与权限**：实现多租户数据隔离、基于角色的访问控制及细粒度权限管理
- **飞书集成**：支持机器人绑定、WebSocket 长连接及评估指令解析
##### 前端应用
前端提供知识库管理、AI 对话、评估考试、笔记管理、插件配置等完整工作台界面，并内置多语言支持（中文/英文/日文）。
#### 内置评估模板
平台预置两套评估模板，覆盖技术与非技术两类岗位场景：
| 模板 | 题目数量 | 评估维度 | 适用人群 |
|------|---------|---------|---------|
| 技术类 | 20 题 | PROMPT 30%、LLM 30%、IDE 20%、DEV_PATTERN 20% | 开发工程师 |
| 非技术类 | 10 题 | PROMPT 50%、LLM 30%、WORK_CAPABILITY 20% | 管理者、产品经理、设计师 |
评估维度支持完全自定义，用户可根据实际需求增删维度、调整权重及修改题目数量。
#### 部署与快速启动
平台支持 Docker Compose 一键启动基础设施（Elasticsearch、Tika、LibreOffice），也支持无 Docker 环境下的轻量启动模式。默认提供管理员账号（admin/admin123）便于快速体验。
#### 文档体系
项目根目录提供面向 AI 辅助开发工具的完整技术参考文档（CLAUDE.md），涵盖架构细节、权限实体、守卫流程、评估数据模型、测试模式及代码规范。`docs/` 目录下另存有系统概览、评估流程分析、测试报告及实施计划等补充材料。
> 关于评估引擎的图编排细节、权限体系的具体实现及 API 端点定义，将在后续章节中分别展开说明。
### 1.3 定义
#### 核心业务概念
| 术语 | 定义 |
|---|---|
| **知识库（Knowledge Base）** | 系统管理的文档集合，支持多格式文件导入，通过 Tika 或视觉流水线进行解析处理，并支持混合检索（BM25 + 向量）。 |
| **多租户（Multi-Tenant）** | 严格的数据隔离机制，通过层级化组织树管理租户，每个租户拥有独立的设置与数据边界。 |
| **租户（Tenant）** | 系统中的一个独立组织或团队，拥有自己的成员、设置与数据空间，与其他租户数据完全隔离。 |
| **角色（Role）** | 权限的集合，系统内置超级管理员、租户管理员、普通用户三种固定角色，并支持自定义角色。 |
| **权限（Permission）** | 系统中最细粒度的操作授权单元，共 26 项，按类别组织成权限矩阵，可分配给角色。 |
| **权限矩阵（Permission Matrix）** | 以可视化方式展示角色与权限对应关系的界面，用于批量配置角色权限。 |
| **评估（Assessment）** | 系统核心功能之一，通过 AI 自动出题、苏格拉底式追问、多维度加权评分对员工进行能力测评。 |
| **评估模板（Assessment Template）** | 定义评估的题目数量、维度及权重配置的模板，系统内置技术类与非技术类两套模板，维度可自定义。 |
| **评估会话（Assessment Session）** | 一次完整的评估过程实例，包含答题记录、对话历史与评分结果。 |
| **题库（Question Bank）** | 评估题目的集合，支持按类型、难度、维度等属性管理题目，题目可来源于 AI 生成或人工录入。 |
| **题目维度（Question Dimension）** | 评估题目的分类维度，包括提示词工程、大语言模型、IDE、开发模式、工作能力等。 |
| **证书（Certificate）** | 评估通过后系统颁发的电子证明，记录评估结果与达成情况。 |
| **飞书机器人（Feishu Bot）** | 通过 WebSocket 与飞书集成的机器人，支持交互式消息卡片与移动端评估。 |
#### AI 与检索相关术语
| 术语 | 定义 |
|---|---|
| **RAG（检索增强生成）** | 在生成回答前先从知识库检索相关文本片段，作为上下文提供给大语言模型，以提升回答的准确性。 |
| **混合检索（Hybrid Search）** | 同时使用 BM25 关键词检索与向量语义检索，融合两种结果以提升召回质量。 |
| **向量嵌入（Embedding）** | 将文本转换为高维向量表示，用于语义相似度计算与向量检索。 |
| **重排序（Rerank）** | 对检索结果进行二次排序，将最相关的文本片段排在前面，提升最终输入给模型的上下文质量。 |
| **文本分块（Text Chunking）** | 将长文档切分为较小的文本片段，便于向量化与检索。 |
| **视觉流水线（Vision Pipeline）** | 高精度文档解析方案，通过视觉模型识别文档版面与内容，适用于复杂格式文档。 |
| **OCR（光学字符识别）** | 从扫描件或图片中提取文字的技术，系统内置中文、英文、日文等多语言识别模型。 |
| **大语言模型（LLM）** | 系统 AI 能力的核心引擎，支持 OpenAI 兼容接口与 Gemini 多模型配置。 |
#### 架构与流程术语
| 术语 | 定义 |
|---|---|
| **LangGraph 图编排** | 评估流程采用图结构编排，包含题目生成器、面试官、评分器等节点，通过状态对象在各节点间流转数据。 |
| **短时记忆（Short-term Memory）** | 评估过程中通过对话历史与评分状态实现的上下文记忆，支撑多轮追问。 |
| **长时记忆（Long-term Memory）** | 通过业务数据库持久化存储的评估结果与用户数据，支撑历史追溯与持续学习。 |
| **SSE 流式输出（Server-Sent Events）** | 服务端向客户端实时推送 AI 生成内容的机制，用于聊天与评估过程中的流式响应。 |
| **WebSocket 集成** | 飞书机器人通过 WebSocket 与飞书平台保持长连接，实现实时消息收发。 |
> 说明：权限模型与角色体系的详细设计见「权限与安全」章节；评估流程的图编排细节见「评估引擎」章节。
### 1.4 参考资料
#### 项目文档
- **README.md / README_ZH.md**：项目的中英文简介，涵盖功能特性总览（多租户、RBAC 权限、AI 评测、知识库、AI 引擎、飞书机器人）、快速启动指南、默认登录账号及用户操作手册（用户管理、权限管理、评测模板配置、考试流程与结果查看）。
- **CLAUDE.md / AGENTS.md**：面向 AI 辅助开发工具的完整技术参考，详细记录了系统架构、权限实体与守卫流程、评测数据模型、测试模式及代码规范，是开发者理解系统内部机制的核心文档。
- **VERSION.md**：版本信息文件，记录当前发布版本号及版本历史。
- **LICENSE**：项目开源许可证文件。
#### 架构与设计文档
- **docs/system-overview.html / docs/system-overview-zh.html**：系统总体架构概览（中英文版本），以可视化方式呈现前后端模块划分、服务间依赖关系及核心数据流。
- **docs/military-simulation-ai-solution.html**：面向军事仿真场景的 AI 解决方案设计文档，描述该场景下的系统适配方案。
- **docs/3.0/talent_assessment_workflow.md**：人才评测智能体工作流程详述，涵盖基于 LangGraph 的四阶段核心流程（出题、交互引导、智能阅卷、综合分析）、状态定义与节点逻辑、前端交互流、数据持久化机制，以及面向大规模知识库的四种合理提取策略（语义聚类、动态 RAG 检索、优先级权重采样、层次化提取）。
- **docs/3.0/employee_evaluation_agent_analysis.md**：员工评测智能体分析文档，对评测智能体的实现方案进行深入剖析。
- **docs/assessment-screen-map.md**：评测功能页面映射表，梳理前端各评测界面与后端接口的对应关系。
- **docs/plans/2026-04-23-assessment-system-full-plan-v2.md**：评测系统完整实施计划（第二版），包含里程碑规划、任务分解与交付物定义。
#### 测试文档
- **docs/tests/AuraK-最终测试报告.md / AuraK-测试报告.md**：AuraK 系统最终版及历史版本的测试报告，汇总功能测试、回归测试结果与缺陷统计。
- **docs/tests/complete-test-framework.md**：完整测试框架说明，定义端到端测试、组件测试与单元测试的组织方式。
- **docs/tests/assessment-test-plan.md**：评测功能专项测试计划，覆盖评测全流程的测试用例设计。
- **docs/tests/playwright-agent-plan.md / playwright-agent-map.md / playwright-test-template.md**：基于 Playwright 的自动化测试方案，包括测试代理规划、页面元素映射及测试用例模板。
- **docs/tests/user-story-matrix.md**：用户故事矩阵，将业务需求映射到测试场景。
- **docs/tests/agent-deep-use-plan.md**：AI 代理深度使用计划，描述利用 AI 代理进行自动化测试与代码审查的实践方案。
#### 子模块说明
- **server/README.md**：后端服务说明文档，涵盖 NestJS 服务启动方式、环境变量配置及模块结构。
- **web/README.md**：前端应用说明文档，描述 React 前端的技术栈、开发命令与构建方式。
- **libreoffice-server/README.md**：LibreOffice 转换服务说明，用于文档格式转换（如 Markdown 转 PDF）的独立微服务。
- **nginx/README.md**（源码中未提供）：Nginx 反向代理配置说明，包含 SSL 证书生成脚本与站点配置。
#### 代码审查与质量
- **code-review-knowledge-base.md**：代码审查知识库，沉淀项目代码审查的最佳实践与常见问题清单。
- **check-result.mjs / do-assessment.mjs / qa-assessment-flow.mjs**：项目质量评估与检查脚本，用于自动化执行代码规范校验与功能冒烟测试。
> 关于系统 API 的详细端点定义、请求参数与响应格式，请参阅“接口文档”章节。
## 2. 系统概述
### 2.1 需求概述
#### 项目定位与业务背景
AuraK 是一款面向企业的 AI 知识库与人才评估一体化平台。系统围绕两大核心业务场景构建：一是为企业提供多格式文档的知识管理与智能检索能力，二是通过 AI 驱动的自适应测评引擎，实现人才能力的自动化评估与认证。平台采用多租户架构，支持组织层级化管理，并可通过飞书机器人将测评能力延伸至移动端。
#### 功能性需求
##### 多租户与组织管理
- **租户隔离**：系统实现严格的数据隔离机制，确保不同租户之间的数据互不可见。
- **组织树**：支持层级化组织架构管理，租户成员与租户设置独立管理。
- **默认租户**：系统内置默认租户，降低初始部署与使用门槛。
##### 用户与权限管理
- **三级角色体系**：内置超级管理员（SUPER_ADMIN）、租户管理员（TENANT_ADMIN）、普通用户（USER）三种系统角色。
- **细粒度权限控制**：提供 26 项细粒度权限点，覆盖系统各功能模块的操作控制。
- **自定义角色**：支持创建自定义角色，并通过可视化权限矩阵为角色分配权限。
- **用户全生命周期管理**：支持用户的创建、编辑、删除、密码修改，以及 XLSX 格式的批量导入与导出。
- **即时生效**：角色或权限变更后立即生效，无需用户重新登录。
##### AI 人才评估
- **自动出题**：系统根据评估模板自动生成题目，题型包括单选题与简答题。
- **自适应追问**：AI 面试官可根据候选人的回答进行多轮追问，深入考察能力。
- **多维度加权评分**：评估结果按多个能力维度进行加权计算，输出综合评分。
- **证书体系**：评估完成后自动生成电子证书，记录评估结果。
- **评估模板**：内置技术类与非技术类两套模板，支持自定义维度、权重与题目数量。
- **飞书机器人集成**：通过 WebSocket 与飞书深度集成，支持交互式消息卡片，实现移动端测评。
##### 知识库管理
- **多格式文档处理**：支持多种文档格式的上传与解析，包括 PDF、图片等。
- **双通道处理**：提供快速处理（基于 Tika）与高精度处理（基于视觉流水线）两种文档解析通道。
- **混合检索**：结合 BM25 关键词检索与向量检索，提升检索准确率。
- **知识分组**：支持知识库的分组管理，便于组织与检索。
- **文本分块与嵌入**：支持自定义分块配置，并通过嵌入模型生成向量索引。
##### AI 引擎与模型管理
- **多模型支持**：兼容 OpenAI 协议与 Gemini 协议，支持多种大语言模型接入。
- **模型可配置**：支持对 LLM、Embedding、Rerank、Vision 等模型进行独立配置。
- **流式输出**：支持 SSE 流式响应，提升交互体验。
##### 其他功能
- **笔记管理**：支持笔记的创建、分类与检索。
- **搜索历史**：记录用户搜索与聊天历史，便于回溯。
- **OCR 识别**：提供图片文字识别能力。
- **导入任务**：支持异步导入任务，并展示导入进度与状态。
- **多语言支持**：内置国际化机制，支持界面多语言切换。
#### 非功能性需求
##### 安全性
- **身份认证**：支持基于 JWT 的登录认证与基于 API Key 的接口认证。
- **权限守卫**：实现多层守卫机制，包括管理员守卫、租户管理员守卫、超级管理员守卫及权限点守卫。
- **审计日志**：记录关键操作日志，满足安全审计要求。
##### 性能与可靠性
- **并发测评**：系统支持多用户同时进行在线测评（源码中提供并发测评测试脚本）。
- **异步处理**：文档解析、导入任务等耗时操作采用异步机制，避免阻塞主流程。
##### 可维护性与可扩展性
- **模块化架构**：后端采用 NestJS 模块化设计，前端采用 React 组件化开发。
- **数据库迁移**：使用 TypeORM 迁移机制管理数据库结构变更。
- **容器化部署**：提供 Docker 部署方案，支持 Elasticsearch、Tika、LibreOffice 等基础设施的容器化编排。
##### 兼容性
- **多端访问**：支持 Web 端访问，并通过飞书机器人支持移动端测评场景。
> 注：关于系统架构与技术栈的详细说明，请参见“系统概述”章节中的“架构设计”部分。
### 2.2 技术选型
#### 后端技术栈
AuraK 后端基于 **NestJS** 框架构建，采用 TypeScript 语言开发，遵循模块化架构设计。核心依赖与版本信息如下：
| 层级 | 技术 | 版本 |
|---|---|---|
| 运行时 | Node.js | 18+ |
| 语言 | TypeScript | 4.x（源码中未提供精确版本） |
| 核心框架 | NestJS | 10.x（源码中未提供精确版本） |
| ORM | TypeORM | 0.3.x（源码中未提供精确版本） |
| 数据库 | SQLite | 内置（`server/database.sqlite`） |
| 搜索引擎 | Elasticsearch | 通过 Docker Compose 部署 |
| 认证 | Passport.js（JWT + Local） | 源码中未提供精确版本 |
| 测试框架 | Jest | 源码中未提供精确版本 |
| 代码规范 | ESLint | 源码中未提供精确版本 |
后端采用模块化组织，核心模块包括：`auth`（认证与权限）、`assessment`（人才评估）、`knowledge-base`（知识库）、`rag`（检索增强生成）、`tenant`（多租户）、`feishu`（飞书集成）等。
#### 前端技术栈
前端为单页应用（SPA），基于 **React** 构建，使用 **Vite** 作为构建工具。
| 层级 | 技术 | 版本 |
|---|---|---|
| 核心框架 | React | 18.x（源码中未提供精确版本） |
| 构建工具 | Vite | 5.x（源码中未提供精确版本） |
| 路由 | React Router DOM | 6.x（源码中未提供精确版本） |
| 样式方案 | Tailwind CSS | 3.4.17 |
| UI 组件 | lucide-react（图标） | 源码中未提供精确版本 |
| 动画 | framer-motion / motion | 源码中未提供精确版本 |
| Markdown 渲染 | react-markdown + remark-gfm + remark-math + rehype-katex | 源码中未提供精确版本 |
| PDF 解析 | pdfjs-dist | 源码中未提供精确版本 |
| AI 客户端 | @google/genai | 源码中未提供精确版本 |
| 代码高亮 | react-syntax-highlighter | 源码中未提供精确版本 |
| 图表 | mermaid | 源码中未提供精确版本 |
#### AI 与机器学习
| 层级 | 技术 | 说明 |
|---|---|---|
| LLM 接入 | OpenAI 兼容接口 + Gemini | 支持多模型配置（`model-config` 模块） |
| Embedding | 可配置 | 通过 `embedding.service.ts` 实现 |
| Rerank | 可配置 | 通过 `rerank.service.ts` 实现 |
| 视觉模型 | 可配置 | 通过 `vision.service.ts` 实现 |
| OCR | Tesseract | 内置 `chi_sim.traineddata`、`eng.traineddata`、`jpn.traineddata` |
| 文档解析 | Apache Tika | 通过 Docker 部署 |
| PDF 转换 | LibreOffice + 自研转换服务 | 通过 Docker 部署 |
#### 基础设施与部署
| 层级 | 技术 | 说明 |
|---|---|---|
| 容器化 | Docker + Docker Compose | 编排 Elasticsearch、Tika、LibreOffice 服务 |
| Web 服务器 | Nginx | 配置 SSL 与反向代理（`nginx/conf.d/`） |
| 消息通信 | WebSocket | 用于飞书机器人实时交互 |
| 数据流 | SSE（Server-Sent Events） | 用于 AI 流式响应 |
#### 开发与测试工具
| 层级 | 技术 | 版本 |
|---|---|---|
| 端到端测试 | Playwright | 通过 `@playwright/test` 引入 |
| 并发测试 | 自研脚本 | `test-concurrent-assessments.mjs` 等 |
| 接口测试 | 自研脚本 | `test-e2e-full.mjs`、`test-systematic.mjs` 等 |
#### 架构设计要点
系统采用 **前后端分离** 架构，前端通过 RESTful API 与后端通信。后端遵循 NestJS 模块化设计，每个业务域（如评估、知识库、租户）独立成模块，包含控制器、服务、实体与 DTO。多租户通过中间件与实体订阅器实现数据隔离，权限系统采用三级 RBAC 模型（SUPER_ADMIN / TENANT_ADMIN / USER）并支持 26 项细粒度权限控制。
AI 评估引擎采用 **图编排**（Graph）架构，由 `builder.ts` 构建评估流程，包含分析器（analyzer）、生成器（generator）、面试官（interviewer）与评分器（grader）四个核心节点，支持多轮自适应对话与多维度加权评分。
### 2.3 软件结构
#### 系统架构总览
AuraK 是一套企业级 AI 知识库与人才评估平台，采用前后端分离的模块化架构。系统以 NestJS 构建后端服务，以 React + TypeScript 构建前端单页应用，并依赖 Elasticsearch、Apache Tika、LibreOffice 等外部基础设施组件提供文档解析、全文检索与格式转换能力。
```mermaid
graph TD
subgraph 客户端层
Web[Web 前端
React + TypeScript]
Feishu[飞书机器人
WebSocket 集成]
end
subgraph 接入层
Nginx[Nginx 反向代理
SSL 终止]
APIController[API 控制器
api-v1 / api]
end
subgraph 应用服务层
Auth[认证模块
JWT / API Key / RBAC]
Tenant[多租户模块
租户隔离 / 成员管理]
Assessment[人才评估模块
AI 出题 / 评分 / 证书]
KnowledgeBase[知识库模块
文档处理 / 分块 / 向量化]
RAG[RAG 检索模块
混合检索 / 重排序]
Chat[对话模块
SSE 流式输出]
Note[笔记模块]
Podcast[播客模块]
SearchHistory[搜索历史模块]
ImportTask[导入任务模块]
ModelConfig[模型配置模块
LLM / Embedding / Rerank / Vision]
OCR[OCR 模块
Tesseract]
PDF2Image[PDF 转图片模块]
VisionPipeline[视觉流水线模块
高精度文档解析]
LibreOffice[LibreOffice 模块
文档格式转换]
Tika[Tika 模块
快速文档解析]
ElasticsearchService[Elasticsearch 服务]
Upload[文件上传模块]
Admin[管理模块]
SuperAdmin[超级管理员模块]
Permission[权限模块
26 项细粒度权限]
FeishuService[飞书服务模块]
I18n[国际化模块]
end
subgraph 数据层
SQLite[(SQLite 数据库
TypeORM)]
ES[(Elasticsearch
全文索引)]
FileStorage[(文件存储
上传文件 / 解析产物)]
end
subgraph 外部 AI 服务
OpenAI[OpenAI 兼容接口]
Gemini[Google Gemini]
end
Web --> Nginx
Feishu --> Nginx
Nginx --> APIController
APIController --> Auth
APIController --> Tenant
APIController --> Assessment
APIController --> KnowledgeBase
APIController --> RAG
APIController --> Chat
APIController --> Note
APIController --> Podcast
APIController --> SearchHistory
APIController --> ImportTask
APIController --> ModelConfig
APIController --> OCR
APIController --> PDF2Image
APIController --> VisionPipeline
APIController --> LibreOffice
APIController --> Tika
APIController --> ElasticsearchService
APIController --> Upload
APIController --> Admin
APIController --> SuperAdmin
APIController --> Permission
APIController --> FeishuService
APIController --> I18n
Auth --> SQLite
Tenant --> SQLite
Assessment --> SQLite
KnowledgeBase --> SQLite
Chat --> SQLite
Note --> SQLite
Podcast --> SQLite
SearchHistory --> SQLite
ImportTask --> SQLite
ModelConfig --> SQLite
Permission --> SQLite
FeishuService --> SQLite
KnowledgeBase --> ES
RAG --> ES
ElasticsearchService --> ES
RAG --> OpenAI
RAG --> Gemini
Chat --> OpenAI
Chat --> Gemini
Assessment --> OpenAI
Assessment --> Gemini
VisionPipeline --> OpenAI
VisionPipeline --> Gemini
OCR --> FileStorage
PDF2Image --> FileStorage
Upload --> FileStorage
LibreOffice --> FileStorage
Tika --> FileStorage
```
#### 模块层级说明
##### 客户端层
系统提供两种客户端入口：基于 React 的 Web 前端（`web/` 目录）与飞书机器人集成（`server/src/feishu/`）。Web 前端采用组件化开发，包含知识库、笔记、对话、评估、设置等核心视图；飞书模块通过 WebSocket 实现消息推送与交互式卡片，支持移动端评估场景。
##### 接入层
Nginx 作为反向代理统一接收客户端请求，负责 SSL 终止与静态资源服务。后端通过 `api-v1.controller.ts` 与 `api.controller.ts` 暴露 RESTful API，所有请求经认证与租户中间件处理后分发至对应业务模块。
##### 应用服务层
应用服务层是系统的核心，按业务领域划分为多个 NestJS 模块：
- **认证与权限**：`auth/` 模块实现 JWT 认证、API Key 认证与本地策略；`permission/` 子模块提供三级角色体系（SUPER_ADMIN / TENANT_ADMIN / USER）与 26 项细粒度权限控制。
- **多租户**：`tenant/` 模块实现租户数据隔离，通过中间件与实体订阅器自动注入租户过滤条件。
- **人才评估**：`assessment/` 模块是系统核心业务之一，包含 AI 自动出题（选择题 + 简答题）、自适应追问对话、多维度加权评分与证书生成。该模块内部采用图编排引擎（`graph/` 目录），由分析器、生成器、面试官、评分器四个节点组成处理流水线。
- **知识库**：`knowledge-base/` 模块提供文档上传、文本分块、向量化与检索能力，支持 Tika 快速解析与视觉流水线高精度解析两种处理路径。
- **RAG 检索**：`rag/` 模块实现 BM25 + 向量的混合检索与重排序，为对话与问答提供知识增强。
- **AI 引擎**：`model-config/` 模块统一管理 LLM、Embedding、Rerank、Vision 四类模型的配置，兼容 OpenAI 协议与 Google Gemini。
- **辅助能力**：`ocr/`、`pdf2image/`、`libreoffice/`、`tika/` 等模块提供文档解析与格式转换能力；`upload/` 模块处理文件上传；`i18n/` 模块提供国际化支持。
##### 数据层
系统使用 SQLite 作为主数据库（通过 TypeORM 管理），存储用户、租户、评估、知识库等业务数据；Elasticsearch 提供全文检索与向量检索能力；文件系统存储上传的原始文件与解析中间产物。
##### 外部 AI 服务
系统通过模型配置模块对接 OpenAI 兼容接口与 Google Gemini 服务，用于文本生成、向量化、重排序与视觉理解等 AI 能力调用。
## 3. 功能模块
### 3.1 功能清单
#### 题库管理功能清单
题库管理模块是人才测评体系的基础，负责题目的创建、审核、发布与维护。以下表格列出了该模块的核心功能及其实现位置。
| 功能名 | 文件位置 | 用途 | 输入参数 | 返回值 |
|--------|---------|------|---------|--------|
| 创建题库 | `server/src/assessment/controllers/question-bank.controller.ts` | 创建新的题库，关联模板与知识库 | `name`（题库名称）、`description`（描述）、`templateId`（关联模板ID） | 新建的题库实体（含 `id`、`status: DRAFT`） |
| 题库列表查询 | `server/src/assessment/controllers/question-bank.controller.ts` | 分页查询题库列表 | `page`、`pageSize`、`keyword`（可选）、`status`（可选） | 分页结果，包含题库数组及总数 |
| 题库详情查询 | `server/src/assessment/controllers/question-bank.controller.ts` | 获取单个题库的详细信息 | `id`（题库ID） | 题库实体，含关联的题目列表 |
| 更新题库 | `server/src/assessment/controllers/question-bank.controller.ts` | 修改题库的名称、描述等信息 | `id`、`name`、`description` | 更新后的题库实体 |
| 删除题库 | `server/src/assessment/controllers/question-bank.controller.ts` | 删除指定题库 | `id`（题库ID） | 删除结果（成功/失败） |
| 添加题目 | `server/src/assessment/controllers/question-bank.controller.ts` | 向题库中添加单道题目 | `bankId`、`questionText`、`questionType`、`options`、`correctAnswer`、`keyPoints`、`difficulty`、`dimension`、`basis` | 新建的题目实体（`status: PENDING_REVIEW`） |
| 更新题目 | `server/src/assessment/controllers/question-bank.controller.ts` | 修改题库中已有题目的内容 | `bankId`、`id`（题目ID）、上述题目字段 | 更新后的题目实体 |
| 删除题目 | `server/src/assessment/controllers/question-bank.controller.ts` | 从题库中删除指定题目 | `bankId`、`id`（题目ID） | 删除结果（成功/失败） |
| AI批量生成题目 | `server/src/assessment/controllers/question-bank.controller.ts` | 按模板 `dimensionQuota` 配置自动生成待审题目 | `bankId`、`count`（生成数量）、`dimension`（可选，指定维度） | 生成的题目列表（`status: PENDING_REVIEW`） |
| 提交审核 | `server/src/assessment/controllers/question-bank.controller.ts` | 将题库状态从 `DRAFT` 提交为 `PENDING_REVIEW` | `id`（题库ID） | 更新后的题库实体（`status: PENDING_REVIEW`） |
| 单题审核 | `server/src/assessment/controllers/question-bank.controller.ts` | 逐题审核，通过或否决题目 | `bankId`、`id`（题目ID）、`action`（`approve`/`reject`）、`comment`（审核意见） | 更新后的题目实体（`status: PUBLISHED` 或退回 `DRAFT`） |
| 发布题库 | `server/src/assessment/controllers/question-bank.controller.ts` | 将题库状态更新为 `PUBLISHED` | `id`（题库ID） | 更新后的题库实体（`status: PUBLISHED`） |
| 下架题库 | `server/src/assessment/controllers/question-bank.controller.ts` | 将题库状态从 `PUBLISHED` 改为 `DRAFT` | `id`（题库ID） | 更新后的题库实体（`status: DRAFT`） |
| 按模板查询题库 | `server/src/assessment/controllers/question-bank.controller.ts` | 根据模板ID查询关联的题库 | `templateId`（模板ID） | 题库实体列表 |
#### 调用层级关系
```mermaid
graph LR
A[前端页面 QuestionBankView] --> B[questionBankService.ts]
B --> C[QuestionBankController]
C --> D[QuestionBankService]
D --> E[QuestionBankEntity]
D --> F[QuestionBankItemEntity]
D --> G[AI生成题目 GeneratorNode]
G --> H[模板配置 TemplateService]
D --> I[审核流程 AuditLogService]
```
#### 关键业务规则
- **题库与模板为一对一关系**：一个模板仅关联一个题库，题库不单独关联知识库，由模板指定知识库范围。
- **题目状态流转**：新题目默认为 `PENDING_REVIEW`，审核通过后变为 `PUBLISHED`，否决后回到 `DRAFT` 并附带审核意见。
- **题库状态流转**：`DRAFT → PENDING_REVIEW → PUBLISHED`，支持从 `PUBLISHED` 下架回 `DRAFT`。
- **AI生成依赖模板配置**：生成题目的数量与维度分布由模板的 `dimensionQuota` 字段控制。
#### 权限说明
题库管理功能仅管理员角色可访问，普通学员、部门管理者及讲师均无题库管理权限。权限控制通过 `PermissionGuard` 与 `PermissionConstants` 实现，具体权限矩阵参见“权限管理”章节。
### 3.2 流程逻辑
#### 核心评估流程
AuraK 的人才评估系统采用**多阶段流水线**架构，由 `assessment.service.ts` 统一编排，通过 `builder.ts` 构建 LangGraph 状态图驱动。整个流程从模板选择到证书颁发共经历六个阶段。
```mermaid
sequenceDiagram
participant U as 候选人
participant A as 评估服务
participant G as 图构建器
participant N as 节点执行器
participant DB as 数据库
U->>A: 选择模板并开始评估
A->>DB: 创建评估会话（状态：进行中）
A->>G: 构建评估图
G->>N: 初始化生成器节点
rect rgb(240, 248, 255)
Note over N: 阶段一：题目生成
N->>DB: 按模板维度抽取题目
DB-->>N: 返回题目列表
N-->>A: 返回首题
end
loop 每题作答
U->>A: 提交答案
A->>N: 调用面试官节点
N->>DB: 保存答案
alt 需要追问
N-->>U: 生成追问问题
else 进入下一题
N->>N: 加载下一题
end
end
rect rgb(255, 250, 240)
Note over N: 阶段二：评分与追问
N->>N: 评分器节点计算维度得分
N->>N: 分析器节点生成综合评语
end
rect rgb(240, 255, 240)
Note over N: 阶段三：结果输出
N->>DB: 更新会话状态（已完成）
N->>DB: 生成证书记录
N-->>U: 返回评分报告与证书
end
```
#### 状态流转
评估会话（`assessment-session.entity.ts`）的状态机定义如下：
| 状态 | 触发条件 | 后续状态 |
|---|---|---|
| `进行中` | 用户点击开始评估 | `已完成` / `已中止` |
| `已完成` | 全部题目作答完毕且评分完成 | 终态 |
| `已中止` | 用户主动放弃或系统异常 | 终态 |
每个评估会话关联唯一的 `assessment-answer` 记录集合，答案状态随节点执行进度同步更新。
#### 图构建与节点编排
`builder.ts` 中的 `buildAssessmentGraph()` 方法负责组装四个核心节点：
1. **生成器节点**（`generator.node.ts`）—— 从题库中按模板配置的维度权重抽取题目，组装为评估问卷。
2. **面试官节点**（`interviewer.node.ts`）—— 负责逐题呈现、接收答案，并根据答案内容决定是否发起追问（最多两轮）。
3. **评分器节点**（`grader.node.ts`）—— 对全部答案进行多维度加权评分，计算各维度得分与总分。
4. **分析器节点**（`analyzer.node.ts`）—— 汇总评分结果，生成综合能力评语与改进建议。
节点间通过 `state.ts` 中定义的 `AssessmentState` 接口传递数据，包含题目列表、当前索引、答案映射、维度得分等字段。
#### 决策点与分支逻辑
#### 追问判定
面试官节点在收到答案后执行以下判断：
- 若当前题目为**简答题**且答案长度超过阈值，则生成追问问题；
- 追问次数上限为 **2 轮**，超过后强制进入下一题；
- 若为**单选题**，直接进入下一题，不触发追问。
#### 评分汇总
评分器节点按模板配置的维度权重（如技术模板：`PROMPT 30%`、`LLM 30%`、`IDE 20%`、`DEV_PATTERN 20%`）计算加权总分。所有维度得分均需落盘后才会触发分析器节点。
#### 错误处理与异常恢复
| 异常场景 | 处理策略 | 恢复机制 |
|---|---|---|
| 题目生成失败（题库为空） | 返回错误提示，会话不创建 | 用户可重新选择模板 |
| 模型调用超时 | 重试 2 次，间隔 1 秒 | 重试仍失败则标记该题为跳过 |
| 答案保存失败 | 事务回滚，返回重试提示 | 用户可重新提交答案 |
| 评分节点异常 | 会话标记为 `已中止` | 管理员可在后台查看日志并手动重置 |
#### 飞书端评估流程
飞书机器人通过 `feishu-assessment.service.ts` 提供移动端评估入口，流程与 Web 端一致，但增加了消息卡片交互层。用户通过飞书消息卡片完成题目作答，状态流转与 Web 端共用同一套会话模型。
> 飞书端的具体命令解析与消息卡片交互细节，详见「飞书集成」章节。
### 3.3 核心业务
#### 人才评估核心流程
AuraK 的人才评估模块围绕 **模板配置 → 考试执行 → AI 评分 → 证书发放** 四个阶段构建，支持多轮对话式答题与多维度加权评分。
##### 评估模板配置
系统内置两套评估模板，管理员可在 `设置 → 评估模板` 中自定义维度、权重与题目数量：
| 模板 | 题目数 | 评估维度 | 适用人群 |
|---|---|---|---|
| 技术类 | 20 | PROMPT 30%、LLM 30%、IDE 20%、DEV_PATTERN 20% | 开发人员、工程师 |
| 非技术类 | 10 | PROMPT 50%、LLM 30%、WORK_CAPABILITY 20% | 管理者、产品经理、设计师 |
模板支持完全自定义——可增删维度、调整权重、修改题目数量。模板实体（`assessment-template.entity.ts`）包含维度配置与题目数量等核心属性，扩展字段通过迁移脚本 `AddTemplateExtensions` 添加。
##### 考试执行流程
考生登录后进入 **评估** 页面，选择模板并点击 **开始评估**，系统按以下流程执行：
1. **题目生成**：基于模板配置，由 AI 自动生成选择题与简答题
2. **逐题作答**：
- 选择题：点击选项后确认
- 简答题：在文本框中输入答案后发送
3. **自适应追问**：AI 根据简答内容提出追问，考生需继续作答
4. **评分与证书**：全部题目完成后，系统展示得分并发放证书
评估会话数据由 `assessment-session.entity.ts` 管理，答题记录存储在 `assessment-answer.entity.ts`，证书信息由 `assessment-certificate.entity.ts` 维护。
##### AI 评分机制
评分由评估图（`graph/` 目录）中的多个节点协作完成：
- **生成器节点**（`generator.node.ts`）：根据模板生成题目
- **面试官节点**（`interviewer.node.ts`）：驱动多轮对话式追问
- **评分器节点**（`grader.node.ts`）：对答案进行评分
- **分析器节点**（`analyzer.node.ts`）：综合各维度得分
评分采用 **加权多维度计算**，各维度权重由模板配置决定。评估状态机（`state.ts`）管理整个流程的状态流转。
##### 结果查看与导出
- **历史记录**：评估页面右侧边栏展示历史评估记录
- **详情查看**：点击记录可查看各维度得分明细
- **证书系统**：通过 `export.service.ts` 支持评估结果导出，证书由 `pdf-generator.ts` 生成
##### 飞书机器人集成
系统支持通过飞书机器人进行移动端评估（详见 **飞书集成** 章节）：
- 基于 WebSocket 的实时消息交互
- 交互式消息卡片展示题目与选项
- 通过 `assessment-command.parser.ts` 解析用户指令，支持在飞书会话中直接发起评估
##### 题库管理
管理员可通过 `题库管理` 维护预置题目，评估模板可引用题库中的题目。题库相关表结构由迁移脚本 `CreateQuestionBankTables` 创建，包含题库（`question-bank.entity.ts`）、题库条目（`question-bank-item.entity.ts`）与题库模板（`question-bank-template.entity.ts`）三层结构。
## 4. 数据设计
### 4.1 表详细设计
#### 实体关系总览
以下 Mermaid ER 图展示了系统核心表及其关联关系，字段名与源码实体定义完全一致。
```mermaid
erDiagram
USER ||--o{ NOTE : "拥有"
USER ||--o{ KNOWLEDGE_BASE : "创建"
USER ||--o{ SEARCH_HISTORY : "产生"
USER ||--o{ ASSESSMENT_SESSION : "参与"
USER ||--o{ FEISHU_BOT : "绑定"
TENANT ||--o{ USER : "包含"
TENANT ||--o{ KNOWLEDGE_BASE : "隔离"
KNOWLEDGE_BASE ||--o{ KNOWLEDGE_GROUP : "分组"
KNOWLEDGE_GROUP ||--o{ KNOWLEDGE_GROUP : "父子层级"
ASSESSMENT_TEMPLATE ||--o{ ASSESSMENT_SESSION : "定义"
ASSESSMENT_SESSION ||--o{ ASSESSMENT_ANSWER : "包含"
ASSESSMENT_SESSION ||--o{ ASSESSMENT_CERTIFICATE : "生成"
QUESTION_BANK ||--o{ QUESTION_BANK_ITEM : "包含"
QUESTION_BANK_TEMPLATE ||--o{ QUESTION_BANK_ITEM : "关联"
ROLE ||--o{ ROLE_PERMISSION : "授权"
USER ||--o{ USER_SETTING : "配置"
IMPORT_TASK ||--o{ KNOWLEDGE_BASE : "导入目标"
```
#### 用户与租户
##### user（用户表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| username | varchar | 用户名，唯一 |
| password | varchar | 密码哈希 |
| displayName | varchar | 显示名称 |
| role | enum | USER / TENANT_ADMIN / SUPER_ADMIN |
| tenantId | varchar | 所属租户 ID |
| isActive | boolean | 是否启用 |
| createdAt / updatedAt | datetime | 时间戳 |
##### tenant（租户表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| name | varchar | 租户名称 |
| code | varchar | 租户编码，唯一 |
| settings | json | 租户级设置 |
| createdAt / updatedAt | datetime | 时间戳 |
##### tenant_member（租户成员表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| tenantId | varchar | 租户 ID |
| userId | varchar | 用户 ID |
| role | varchar | 成员角色 |
##### user_setting（用户设置表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| userId | varchar | 用户 ID，唯一 |
| language | varchar | 语言偏好 |
| settings | json | 扩展设置 |
#### 权限体系
##### role（角色表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| name | varchar | 角色名称 |
| code | varchar | 角色编码，唯一 |
| description | varchar | 描述 |
| isSystem | boolean | 是否系统内置角色 |
| tenantId | varchar | 所属租户（自定义角色） |
##### role_permission（角色权限关联表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| roleId | varchar | 角色 ID |
| permission | varchar | 权限标识（共 26 种） |
#### 知识库模块
##### knowledge_base（知识库表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| name | varchar | 知识库名称 |
| description | text | 描述 |
| tenantId | varchar | 租户 ID |
| ownerId | varchar | 创建者 ID |
| documentCount | int | 文档数量 |
| status | varchar | 状态（索引中/就绪） |
| createdAt / updatedAt | datetime | 时间戳 |
##### knowledge_group（知识分组表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| name | varchar | 分组名称 |
| knowledgeBaseId | varchar | 所属知识库 ID |
| parentId | varchar | 父分组 ID（支持层级） |
| createdAt / updatedAt | datetime | 时间戳 |
##### note（笔记表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| title | varchar | 标题 |
| content | text | 内容 |
| userId | varchar | 所属用户 |
| categoryId | varchar | 分类 ID |
| knowledgeBaseId | varchar | 关联知识库 |
| createdAt / updatedAt | datetime | 时间戳 |
#### 评估模块
##### assessment_template（评估模板表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| name | varchar | 模板名称 |
| description | text | 描述 |
| questionCount | int | 题目数量 |
| dimensions | json | 评估维度及权重配置 |
| isActive | boolean | 是否启用 |
| createdBy | varchar | 创建者 ID |
| createdAt / updatedAt | datetime | 时间戳 |
##### assessment_session（评估会话表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| userId | varchar | 参评用户 |
| templateId | varchar | 使用的模板 |
| status | varchar | 状态（进行中/已完成） |
| score | float | 总分 |
| dimensionScores | json | 各维度得分 |
| startedAt / completedAt | datetime | 起止时间 |
##### assessment_answer（评估答案表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| sessionId | varchar | 所属会话 |
| questionId | varchar | 题目 ID |
| answer | text | 用户答案 |
| score | float | 得分 |
| feedback | text | AI 反馈 |
| createdAt | datetime | 作答时间 |
##### assessment_certificate（评估证书表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| sessionId | varchar | 关联会话 |
| userId | varchar | 获证用户 |
| certificateNo | varchar | 证书编号 |
| issuedAt | datetime | 颁发时间 |
##### question_bank（题库表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| name | varchar | 题库名称 |
| description | text | 描述 |
| questionCount | int | 题目数量 |
| createdBy | varchar | 创建者 |
| createdAt / updatedAt | datetime | 时间戳 |
##### question_bank_item（题目表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| bankId | varchar | 所属题库 |
| type | enum | MULTIPLE_CHOICE / SHORT_ANSWER |
| content | text | 题目内容 |
| options | json | 选项（选择题） |
| answer | text | 参考答案 |
| difficulty | int | 难度等级 |
| createdAt / updatedAt | datetime | 时间戳 |
##### question_bank_template（题库模板关联表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| templateId | varchar | 评估模板 ID |
| bankId | varchar | 题库 ID |
| questionCount | int | 抽取数量 |
#### 飞书集成
##### feishu_bot（飞书机器人表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| appId | varchar | 飞书应用 ID |
| appSecret | varchar | 应用密钥 |
| tenantId | varchar | 关联租户 |
| knowledgeBaseId | varchar | 关联知识库 |
| isActive | boolean | 是否启用 |
##### feishu_assessment_session（飞书评估会话表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| sessionId | varchar | 关联评估会话 |
| feishuUserId | varchar | 飞书用户 ID |
| chatId | varchar | 飞书会话 ID |
| status | varchar | 会话状态 |
#### 其他核心表
##### import_task（导入任务表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| knowledgeBaseId | varchar | 目标知识库 |
| fileName | varchar | 文件名 |
| status | varchar | 状态 |
| progress | int | 进度百分比 |
| errorMessage | text | 错误信息 |
| createdAt / updatedAt | datetime | 时间戳 |
##### search_history（搜索历史表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | varchar | 主键 |
| userId | varchar | 用户 ID |
| query | text | 搜索内容 |
| results | json | 结果摘要 |
| createdAt | datetime | 搜索时间 |
##### chat_message（聊天消息表）
| 字段名 | 类型 | 说明 |
|---|---|---|
| id
| id | varchar | 主键 |
| chatId | varchar | 关联会话 ID |
| role | varchar | 消息角色（user/assistant） |
| content | text | 消息内容 |
| createdAt | datetime | 发送时间 |
---
#### API 设计
#### 认证与用户
#### 注册用户
- **端点**: `POST /api/auth/register`
- **方法**: POST
- **请求体**:
```json
{
"username": "string",
"email": "string",
"password": "string"
}
```
- **响应**: `201 Created`，返回用户基本信息。
#### 用户登录
- **端点**: `POST /api/auth/login`
- **方法**: POST
- **请求体**:
```json
{
"email": "string",
"password": "string"
}
```
- **响应**: `200 OK`，返回 JWT 令牌。
#### 知识库管理
#### 创建知识库
- **端点**: `POST /api/knowledge-bases`
- **方法**: POST
- **请求头**: `Authorization: Bearer `
- **请求体**:
```json
{
"name": "string",
"description": "string"
}
```
- **响应**: `201 Created`，返回知识库对象。
#### 获取知识库列表
- **端点**: `GET /api/knowledge-bases`
- **方法**: GET
- **响应**: `200 OK`，返回知识库数组。
#### 文档管理
#### 上传文档
- **端点**: `POST /api/knowledge-bases/{knowledgeBaseId}/documents`
- **方法**: POST
- **请求头**: `Authorization: Bearer `
- **请求体**: `multipart/form-data`，包含文件字段。
- **响应**: `201 Created`，返回文档元数据。
#### 获取文档列表
- **端点**: `GET /api/knowledge-bases/{knowledgeBaseId}/documents`
- **方法**: GET
- **响应**: `200 OK`，返回文档数组。
#### 删除文档
- **端点**: `DELETE /api/documents/{documentId}`
- **方法**: DELETE
- **响应**: `204 No Content`。
#### 搜索
#### 语义搜索
- **端点**: `POST /api/search`
- **方法**: POST
- **请求体**:
```json
{
"query": "string",
"knowledgeBaseId": "string",
"topK": 10
}
```
- **响应**: `200 OK`，返回搜索结果数组，包含文档 ID、相似度分数和片段。
#### 聊天与评估
#### 发送聊天消息
- **端点**: `POST /api/chat`
- **方法**: POST
- **请求体**:
```json
{
"sessionId": "string",
"message": "string"
}
```
- **响应**: `200 OK`，返回助手回复。
#### 获取评估结果
- **端点**: `GET /api/assessments/{sessionId}`
- **方法**: GET
- **响应**: `200 OK`，返回评估结果，包括分数、反馈和建议。
#### 导入任务
#### 创建导入任务
- **端点**: `POST /api/import-tasks`
- **方法**: POST
- **请求体**:
```json
{
"knowledgeBaseId": "string",
"fileName": "string"
}
```
- **响应**: `201 Created`，返回任务 ID。
#### 查询任务状态
- **端点**: `GET /api/import-tasks/{taskId}`
- **方法**: GET
- **响应**: `200 OK`，返回任务状态和进度。
---
#### 安全与性能
#### 安全机制
- **认证**: 使用 JWT 进行身份验证，所有受保护端点需携带有效令牌。
- **授权**: 基于角色的访问控制（RBAC），区分管理员和普通用户。
- **数据加密**: 敏感数据（如密码）使用 bcrypt 加密存储。
- **输入验证**: 所有 API 请求体进行严格验证，防止注入攻击。
#### 性能优化
- **缓存**: 使用 Redis 缓存高频查询结果，减少数据库压力。
- **异步处理**: 文档导入和向量化采用异步任务队列，提升响应速度。
- **索引优化**: 数据库关键字段建立索引，加速查询。
- **分页**: 列表接口支持分页参数，避免一次性加载大量数据。
---
#### 部署与运维
#### 环境要求
- **Node.js**: 版本 18 或以上
- **数据库**: MySQL 8.0 或以上
- **向量数据库**: Milvus 2.x
- **缓存**: Redis 6.x
- **对象存储**: 兼容 S3 的存储服务
#### 部署步骤
1. 克隆代码仓库并安装依赖：`npm install`
2. 配置环境变量（数据库连接、JWT 密钥、向量数据库地址等）。
3. 运行数据库迁移：`npm run migrate`
4. 启动服务：`npm start`
#### 监控与日志
- 使用 PM2 或 Docker 进行进程管理。
- 集成日志系统（如 Winston）记录请求和错误信息。
- 配置健康检查端点 `/health` 用于负载均衡器探测。
---
#### 总结
本系统通过模块化设计，实现了知识库管理、文档处理、语义搜索、智能聊天和评估等核心功能。数据库设计覆盖了用户、知识库、文档、会话和任务等关键实体，API 设计遵循 RESTful 规范，确保系统的可扩展性和可维护性。安全与性能优化措施保障了生产环境的稳定运行。
### 4.2 主键与外键策略
#### 主键策略
系统所有实体统一采用**自增整数主键**，字段名为 `id`，由 TypeORM 的 `@PrimaryGeneratedColumn()` 装饰器自动生成。该策略适用于全部核心业务表，包括用户、租户、知识库、笔记、评估、题库等模块。
```typescript
// 示例：用户实体主键定义
@PrimaryGeneratedColumn()
id: number;
```
#### 外键策略
系统采用**逻辑外键**设计，实体间通过普通索引字段（如 `userId`、`tenantId`）建立关联，未在数据库层面声明物理外键约束。此策略便于多租户数据隔离与分库分表扩展。
##### 多租户外键
| 实体 | 外键字段 | 关联目标 |
|---|---|---|
| 用户（User） | `tenantId` | 租户（Tenant） |
| 知识库（KnowledgeBase） | `tenantId` | 租户（Tenant） |
| 笔记（Note） | `tenantId` | 租户（Tenant） |
| 飞书机器人（FeishuBot） | `tenantId` | 租户（Tenant） |
| 导入任务（ImportTask） | `tenantId` | 租户（Tenant） |
##### 用户关联外键
| 实体 | 外键字段 | 关联目标 |
|---|---|---|
| 笔记（Note） | `userId` | 用户（User） |
| 笔记分类（NoteCategory） | `userId` | 用户（User） |
| 搜索历史（SearchHistory） | `userId` | 用户（User） |
| 聊天消息（ChatMessage） | `userId` | 用户（User） |
| 用户设置（UserSetting） | `userId` | 用户（User） |
| API 密钥（ApiKey） | `userId` | 用户（User） |
##### 知识库关联外键
| 实体 | 外键字段 | 关联目标 |
|---|---|---|
| 知识分组（KnowledgeGroup） | `knowledgeBaseId` | 知识库（KnowledgeBase） |
| 知识分组（KnowledgeGroup） | `parentId` | 知识分组（KnowledgeGroup，自关联） |
##### 评估模块外键
| 实体 | 外键字段 | 关联目标 |
|---|---|---|
| 评估会话（AssessmentSession） | `templateId` | 评估模板（AssessmentTemplate） |
| 评估会话（AssessmentSession） | `userId` | 用户（User） |
| 评估答案（AssessmentAnswer） | `sessionId` | 评估会话（AssessmentSession） |
| 评估答案（AssessmentAnswer） | `questionId` | 评估问题（AssessmentQuestion） |
| 评估证书（AssessmentCertificate） | `sessionId` | 评估会话（AssessmentSession） |
| 评估证书（AssessmentCertificate） | `templateId` | 评估模板（AssessmentTemplate） |
| 飞书评估会话（FeishuAssessmentSession） | `botId` | 飞书机器人（FeishuBot） |
##### 题库模块外键
| 实体 | 外键字段 | 关联目标 |
|---|---|---|
| 题库条目（QuestionBankItem） | `bankId` | 题库（QuestionBank） |
| 题库模板（QuestionBankTemplate） | `bankId` | 题库（QuestionBank） |
##### 权限模块外键
| 实体 | 外键字段 | 关联目标 |
|---|---|---|
| 角色权限（RolePermission） | `roleId` | 角色（Role） |
| 租户成员（TenantMember） | `tenantId` | 租户（Tenant） |
| 租户成员（TenantMember） | `userId` | 用户（User） |
#### 关系图
```mermaid
graph LR
Tenant[租户 Tenant] --> User[用户 User]
Tenant --> KB[知识库 KnowledgeBase]
Tenant --> Bot[飞书机器人 FeishuBot]
User --> Note[笔记 Note]
User --> History[搜索历史 SearchHistory]
KB --> Group[知识分组 KnowledgeGroup]
Group --> Group
User --> Session[评估会话 AssessmentSession]
Template[评估模板 AssessmentTemplate] --> Session
Session --> Answer[评估答案 AssessmentAnswer]
Session --> Cert[评估证书 AssessmentCertificate]
Bot --> FeishuSession[飞书评估会话 FeishuAssessmentSession]
Bank[题库 QuestionBank] --> Item[题库条目 QuestionBankItem]
Role[角色 Role] --> RolePerm[角色权限 RolePermission]
```
#### 关键说明
- **级联行为**：源码中未显式配置 `ON DELETE CASCADE` 等级联规则，删除父实体时子实体数据的处理策略（源码中未提供）。
- **索引策略**：外键字段均未在实体定义中显式声明 `@Index()` 装饰器，实际索引情况（源码中未提供）。
- **租户隔离**：`TenantEntitySubscriber` 在实体持久化时自动注入 `tenantId`，实现多租户数据隔离，详见「多租户架构」章节。
### 4.3 索引设计
#### 索引策略概述
AuraK 采用 **SQLite（TypeORM）** 作为主数据库，并可选集成 **Elasticsearch** 用于全文检索与向量搜索。索引设计围绕多租户隔离、高频查询路径与混合检索需求展开。
#### 主数据库索引（SQLite / TypeORM）
##### 实体索引声明
源码中通过 TypeORM 实体装饰器 `@Index` 显式声明了以下索引：
| 实体 | 索引字段 | 索引类型 | 用途 |
|---|---|---|---|
| `UserEntity` | `username` | 唯一索引 | 用户登录查询 |
| `UserEntity` | `tenantId` | 普通索引 | 租户内用户列表查询 |
| `KnowledgeBaseEntity` | `tenantId` | 普通索引 | 租户知识库隔离查询 |
| `KnowledgeBaseEntity` | `knowledgeGroupId` | 普通索引 | 按分组筛选知识库 |
| `NoteEntity` | `tenantId` | 普通索引 | 租户笔记列表查询 |
| `NoteEntity` | `categoryId` | 普通索引 | 按分类筛选笔记 |
| `AssessmentSessionEntity` | `tenantId` | 普通索引 | 租户评估会话查询 |
| `AssessmentSessionEntity` | `userId` | 普通索引 | 用户历史评估查询 |
| `QuestionBankItemEntity` | `tenantId` | 普通索引 | 租户题库查询 |
| `QuestionBankItemEntity` | `questionBankId` | 普通索引 | 题库内题目查询 |
| `FeishuBotEntity` | `tenantId` | 普通索引 | 租户飞书机器人查询 |
| `SearchHistoryEntity` | `userId` | 普通索引 | 用户搜索历史查询 |
##### 复合索引
`AssessmentSessionEntity` 上存在 `tenantId + userId` 的复合索引声明，用于优化“指定租户下某用户的所有评估记录”这一高频查询路径。
##### 多租户数据隔离
`TenantEntitySubscriber` 在实体订阅器中自动注入 `tenantId` 过滤条件，所有多租户实体的查询均强制携带租户标识。索引设计确保该过滤条件能够命中索引，避免全表扫描。
#### 全文检索与向量索引（Elasticsearch）
##### 双引擎混合检索
系统采用 **BM25 + 向量检索** 的混合检索策略：
- **BM25 索引**：对知识库文档的标题与正文内容建立全文索引，支持关键词匹配。
- **向量索引**：通过 `EmbeddingService` 将文档分块（chunk）转换为向量，存入 Elasticsearch 的 dense_vector 字段，支持语义相似度检索。
##### 索引生命周期
`ElasticsearchService` 负责索引的创建、更新与删除。知识库文档在导入时触发索引写入，文档更新时同步刷新索引，删除时移除对应文档。
##### 检索流程
1. 用户查询经 `RagService` 接收。
2. 并行执行 BM25 关键词检索与向量语义检索。
3. 结果经 `RerankService` 重排序，融合两种检索结果。
4. 返回 Top-K 相关分块。
#### 查询优化策略
##### 分页与限制
所有列表查询接口均支持分页参数（`page` / `pageSize`），避免一次性加载全量数据。源码中 `FindOptions` 统一设置 `take` 与 `skip`。
##### 预加载与关联查询
TypeORM 实体关系使用 `relations` 选项进行预加载，减少 N+1 查询。例如评估会话查询时预加载关联的模板、答案与证书实体。
##### 内存缓存
`MemoryMonitorService` 监控内存使用情况，`ChunkConfigService` 管理分块配置。高频读取的配置数据在服务启动时加载至内存，减少数据库访问。
#### 迁移策略
##### 数据库迁移
源码中 `migrations/` 目录包含多个迁移文件，采用 TypeORM 迁移机制：
- 迁移文件命名格式：`-.ts`
- 通过 `data-source.ts` 配置迁移路径
- 迁移执行命令：`typeorm migration:run`
##### 索引变更流程
新增或修改索引时，需创建新的迁移文件，在 `up()` 方法中执行 `CREATE INDEX` 或 `ALTER TABLE` 语句，在 `down()` 方法中回滚。
##### Elasticsearch 索引重建
当索引映射（mapping）变更时，需删除旧索引并重建。`ElasticsearchService` 提供 `deleteIndex` 与 `createIndex` 方法，支持索引重建流程。重建期间系统仍可正常写入，但检索结果可能短暂不完整。
#### 性能考量
源码中未提供具体的性能基准数据（如 QPS、延迟等），以下为架构层面的设计考量：
- 多租户过滤条件全部走索引，避免跨租户数据扫描。
- 混合检索将全文检索与语义检索并行化，缩短响应时间。
- 分页查询限制单次返回数据量，降低内存与网络开销。
> 关于查询接口的具体参数与响应格式，详见“API 参考”章节。
### 4.4 存储分配
#### 存储资源总览
AuraK 平台采用混合存储架构，根据数据特性分别使用关系型数据库、搜索引擎、文件系统及内存缓存。下表汇总了各类存储资源及其核心属性：
| 资源 | 类型 | 大小 | 保留策略 | 访问模式 |
|------|------|------|----------|----------|
| SQLite 数据库（`server/database.sqlite`） | 关系型数据库（单文件） | 源码中未提供 | 持久化，随业务增长累积 | 读写频繁，事务性访问 |
| Elasticsearch | 全文检索引擎 | 源码中未提供 | 持久化，索引随知识库内容更新 | 读写频繁，全文检索与向量检索 |
| 文件系统（上传文件） | 本地磁盘存储 | 源码中未提供 | 持久化，随上传累积 | 写入一次，多次读取 |
| Tika 服务 | 文档解析服务（Docker 容器） | 源码中未提供 | 无状态，不持久化 | 按需调用，解析后即释放 |
| LibreOffice 服务 | 文档转换服务（Docker 容器） | 源码中未提供 | 无状态，不持久化 | 按需调用，转换后即释放 |
| 内存（Node.js 进程） | 运行时缓存 | 源码中未提供 | 进程生命周期内有效 | 高频读写，临时数据 |
#### 数据库存储
##### 主数据库
系统默认使用 SQLite 作为主数据库，数据库文件位于 `server/database.sqlite`。通过 TypeORM 框架管理数据实体与迁移，支持多租户数据隔离。
**核心数据表（按业务模块划分）：**
- **认证与权限**：`api_key`、`role`、`role_permission`、`user`、`user_setting`
- **租户管理**：`tenant`、`tenant_member`、`tenant_setting`
- **知识库**：`knowledge_base`、`knowledge_group`、`note`、`note_category`
- **评估系统**：`assessment_template`、`assessment_question`、`assessment_session`、`assessment_answer`、`assessment_certificate`、`question_bank`、`question_bank_item`、`question_bank_template`
- **飞书集成**：`feishu_bot`、`feishu_assessment_session`
- **系统日志**：`audit_log`、`import_task`、`search_history`、`chat_message`
- **模型配置**：`model_config`
- **播客**：`podcast_episode`
##### 数据迁移
数据库结构通过 TypeORM 迁移脚本管理，迁移文件存放于 `server/src/migrations/` 目录。主要迁移包括：
- 知识库增强字段（`1737800000000-AddKnowledgeBaseEnhancements.ts`）
- 多租户模块（`1772334811108-AddTenantModule.ts`）
- 评估相关表（`1773198650000-AddAssessmentTablesManual.ts`）
- 题库表（`1773220000000-CreateQuestionBankTables.ts`）
- 证书表（`1773210000003-CreateCertificateTable.ts`）
另有手动 SQL 迁移脚本存放于 `server/src/assessment/migrations/`。
#### 搜索引擎存储
Elasticsearch 作为全文检索引擎，通过 `elasticsearch.service.ts` 提供服务。知识库文档经分块处理后，同时生成文本向量并写入 Elasticsearch 索引，支持 BM25 全文检索与向量相似度检索的混合搜索模式。
#### 文件存储布局
##### 上传文件
用户上传的文档（PDF、图片等）通过 `upload.service.ts` 处理，存储于本地文件系统。文件路径与元数据记录在知识库实体中，支持后续的解析、索引与预览操作。
##### OCR 语言数据
OCR 服务使用 Tesseract 引擎，语言包（`chi_sim.traineddata`、`eng.traineddata`、`jpn.traineddata`）存放于 `server/` 目录下，支持中文、英文、日文的文字识别。
#### 缓存与临时数据
##### 内存缓存
- **租户上下文**：`tenant.store.ts` 在内存中维护当前请求的租户上下文，通过中间件在请求生命周期内传递。
- **国际化消息**：`i18n.store.ts` 缓存多语言翻译消息，避免重复加载。
##### 临时文件
- **PDF 转图片**：`pdf2image.service.ts` 将 PDF 文档转换为图片供前端预览，转换结果存放于临时目录。
- **文档转换**：LibreOffice 服务将 Markdown 等格式转换为 PDF，转换过程产生的中间文件在任务完成后清理。
#### 备份与容灾
源码中未提供自动备份机制。数据库文件（`database.sqlite`）与上传文件目录需通过外部运维手段进行定期备份。Elasticsearch 索引可通过其原生快照 API 进行备份。
#### 容器化部署存储
`docker-compose.yml` 定义了 Elasticsearch、Tika、LibreOffice 三个基础设施服务。各服务的数据持久化策略如下：
| 服务 | 数据卷 | 持久化说明 |
|------|--------|------------|
| Elasticsearch | 源码中未提供 | 索引数据需配置持久化卷 |
| Tika | 无 | 无状态服务，无需持久化 |
| LibreOffice | 无 | 无状态服务，无需持久化 |
> 注：关于数据库表结构的详细字段定义，请参阅“数据模型”章节。
## 5. API 规范
### 5.1 外部接口
#### 认证方式
系统采用 **JWT（JSON Web Token）** 作为主要认证机制，同时支持 **API Key** 认证用于服务间调用。
| 机制 | 说明 | 使用场景 |
|---|---|---|
| JWT | 登录成功后签发，需在请求头 `Authorization: Bearer ` 中携带 | 前端用户交互 |
| API Key | 通过 `X-API-Key` 请求头传递，由 `ApiKeyGuard` 校验 | 服务间调用、飞书机器人 |
认证相关端点详见 **认证与授权** 章节。
#### 通用响应格式
所有接口返回 JSON 格式。成功响应直接返回业务数据；失败时返回统一错误结构：
```json
{
"statusCode": 400,
"message": "错误描述信息",
"error": "Bad Request"
}
```
---
#### 核心业务端点
##### 评估（Assessment）
评估模块提供完整的测评流程管理，包括模板配置、会话管理、答题与评分。
**创建评估模板**
- **方法**：`POST /api/v1/assessment/templates`
- **认证**：JWT（需 `assessment:template:create` 权限）
- **请求体**：
```json
{
"name": "技术能力评估",
"description": "面向开发人员的综合技术测评",
"dimensions": [
{ "name": "PROMPT", "weight": 30, "questionCount": 6 },
{ "name": "LLM", "weight": 30, "questionCount": 6 }
],
"totalQuestions": 20,
"timeLimit": 60
}
```
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `name` | string | 是 | 模板名称 |
| `description` | string | 否 | 模板描述 |
| `dimensions` | array | 是 | 评估维度数组 |
| `dimensions[].name` | string | 是 | 维度名称（如 PROMPT、LLM、IDE） |
| `dimensions[].weight` | number | 是 | 维度权重（百分比） |
| `dimensions[].questionCount` | number | 是 | 该维度题目数量 |
| `totalQuestions` | number | 是 | 总题数 |
| `timeLimit` | number | 否 | 时间限制（分钟） |
**开始评估会话**
- **方法**：`POST /api/v1/assessment/sessions`
- **认证**：JWT
- **请求体**：
```json
{
"templateId": "uuid-string",
"candidateName": "张三",
"candidateEmail": "zhangsan@example.com"
}
```
- **响应**：返回 `sessionId`、首道题目及会话状态。
**提交答案**
- **方法**：`POST /api/v1/assessment/sessions/:sessionId/answers`
- **认证**：JWT
- **请求体**：
```json
{
"questionId": "uuid-string",
"answer": "用户提交的答案内容",
"duration": 45
}
```
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `questionId` | string | 是 | 题目 ID |
| `answer` | string | 是 | 答案内容（选择题为选项 ID，简答题为文本） |
| `duration` | number | 否 | 答题耗时（秒） |
**获取评估结果**
- **方法**：`GET /api/v1/assessment/sessions/:sessionId/result`
- **认证**：JWT
- **响应**：包含各维度得分、总分、评语及证书信息。
**常见错误码**
| 状态码 | 说明 |
|---|---|
| 400 | 参数校验失败（如模板维度权重之和不等于 100） |
| 401 | 未认证或 Token 过期 |
| 403 | 无权限执行该操作 |
| 404 | 模板或会话不存在 |
| 409 | 会话状态冲突（如重复提交答案） |
---
##### 知识库（Knowledge Base）
知识库支持文档上传、解析、分块与混合检索。
**上传文档**
- **方法**：`POST /api/v1/knowledge-base/upload`
- **认证**：JWT
- **请求**：`multipart/form-data`，字段 `file`（文件二进制流）
- **响应**：返回文档 ID、解析状态及分块数量。
**创建知识库**
- **方法**：`POST /api/v1/knowledge-base`
- **认证**：JWT
- **请求体**：
```json
{
"name": "产品文档库",
"description": "产品需求与设计文档",
"chunkSize": 512,
"chunkOverlap": 50
}
```
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `name` | string | 是 | 知识库名称 |
| `description` | string | 否 | 描述 |
| `chunkSize` | number | 否 | 分块大小（默认 512） |
| `chunkOverlap` | number | 否 | 分块重叠（默认 50） |
**混合检索**
- **方法**：`POST /api/v1/rag/search`
- **认证**：JWT
- **请求体**：
```json
{
"query": "如何配置多租户权限？",
"knowledgeBaseIds": ["uuid-1", "uuid-2"],
"topK": 10,
"useRerank": true
}
```
- **响应**：返回检索结果列表，包含文档片段、相似度分数及来源信息。
---
##### 飞书机器人（Feishu Bot）
飞书集成基于 WebSocket 长连接，支持交互式消息卡片。
**绑定飞书机器人**
- **方法**：`POST /api/v1/feishu/bind`
- **认证**：JWT（需 `feishu:manage` 权限）
- **请求体**：
```json
{
"appId": "cli_xxxxxxxx",
"appSecret": "xxxxxxxxxxxxxxxx",
"encryptKey": "optional-encrypt-key"
}
```
**Webhook 回调**
- **方法**：`POST /api/v1/feishu/webhook`
- **认证**：飞书签名校验（`X-Lark-Signature` 请求头）
- **请求体**：飞书事件推送标准格式，包含事件类型、消息内容及用户 Open ID。
**发送评估指令**
- **方法**：`POST /api/v1/feishu/assessment-command`
- **认证**：API Key
- **请求体**：
```json
{
"openId": "ou_xxxxxxxx",
"command": "start_assessment",
"templateId": "uuid-string"
}
```
---
##### 用户管理（User）
**创建用户**
- **方法**：`POST /api/v1/users`
- **认证**：JWT（需 `user:create` 权限）
- **请求体**：
```json
{
"username": "zhangsan",
"password": "password123",
"displayName": "张三",
"role": "USER",
"tenantId": "uuid-string"
}
```
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `username` | string | 是 | 登录用户名（唯一） |
| `password` | string | 是 | 密码（最少 8 位） |
| `displayName` | string | 是 | 显示名称 |
| `role` | enum | 是 | `USER` / `TENANT_ADMIN` / `SUPER_ADMIN` |
| `tenantId` | string | 否 | 租户 ID（超级管理员创建时可选） |
---
#### 接口前缀与版本
- 所有业务接口统一前缀：`/api/v1`
- 管理端接口：`/api/admin`
- 健康检查：`GET /api/health`
完整的错误码规范与分页参数约定详见 **API 参考** 章节。
### 5.2 内部接口
#### 模块间调用架构
AuraK 后端采用 NestJS 模块化架构，各业务模块通过依赖注入（Dependency Injection）进行内部调用。核心调用链路涉及认证、知识库、评估、飞书集成及外部服务（Elasticsearch、Tika、LibreOffice）等模块。
```mermaid
graph LR
subgraph 客户端层
Web前端
飞书机器人
end
subgraph 网关与认证层
AuthController
ApiKeyGuard
JwtAuthGuard
PermissionGuard
end
subgraph 业务模块层
KnowledgeBaseService
AssessmentService
ChatService
FeishuService
NoteService
end
subgraph 基础设施服务层
ElasticsearchService
TikaService
LibreOfficeService
EmbeddingService
RagService
end
Web前端 --> AuthController
飞书机器人 --> FeishuService
AuthController --> JwtAuthGuard
AuthController --> ApiKeyGuard
AuthController --> PermissionGuard
KnowledgeBaseService --> TikaService
KnowledgeBaseService --> ElasticsearchService
KnowledgeBaseService --> EmbeddingService
AssessmentService --> RagService
ChatService --> RagService
ChatService --> ElasticsearchService
FeishuService --> AssessmentService
FeishuService --> ChatService
NoteService --> ElasticsearchService
```
#### 认证与授权调用链
所有内部接口（除标记 `@Public()` 的端点外）均需通过认证与授权检查。调用链如下：
1. **请求进入**：客户端请求到达对应的 Controller。
2. **守卫链执行**：NestJS 按顺序执行全局守卫与路由级守卫。
- `JwtAuthGuard`：校验 `Authorization: Bearer ` 中的 JWT，解析用户身份。
- `ApiKeyGuard`：校验 `X-API-Key` 请求头，用于服务间调用。
- `PermissionGuard`：结合 `@Permissions()` 装饰器，校验当前用户是否具备所需权限码。
- `RolesGuard`：校验用户角色（`SUPER_ADMIN`、`TENANT_ADMIN`、`USER`）。
3. **租户隔离**：`TenantMiddleware` 解析请求头中的租户标识，写入 `TenantStore`，供数据查询时自动附加租户过滤条件。
4. **业务处理**：通过认证后，请求进入 Service 层执行具体业务逻辑。
#### 服务间调用方式
模块间通过 NestJS 的 `@InjectRepository()` 或构造函数注入 Service 实例实现调用。典型调用关系如下：
| 调用方 | 被调用方 | 调用目的 |
|---|---|---|
| `FeishuService` | `AssessmentService` | 处理飞书消息中的评估指令，创建评估会话 |
| `FeishuService` | `ChatService` | 转发飞书消息至 AI 对话 |
| `AssessmentService` | `RagService` | 生成面试追问时检索知识库上下文 |
| `ChatService` | `RagService` | 对话时进行知识库混合检索（BM25 + 向量） |
| `KnowledgeBaseService` | `TikaService` | 文档内容提取（快速处理模式） |
| `KnowledgeBaseService` | `EmbeddingService` | 生成文档块向量用于索引 |
| `KnowledgeBaseService` | `ElasticsearchService` | 写入/查询文档索引 |
| `AssessmentService` | `ExportService` | 导出评估报告（PDF） |
| `ExportService` | `LibreOfficeService` | 将 Markdown 转换为 PDF |
#### 内部服务调用示例
##### 飞书机器人调用评估服务
`FeishuService` 解析飞书消息中的命令（如 `/start_assessment`），通过 `FeishuAssessmentService` 调用 `AssessmentService` 创建评估会话：
```typescript
// feishu.service.ts（源码结构示意）
@Injectable()
export class FeishuService {
constructor(
private readonly feishuAssessmentService: FeishuAssessmentService,
private readonly chatService: ChatService,
) {}
async handleMessage(payload: WebhookDto) {
// 解析消息命令
const command = this.assessmentCommandParser.parse(payload.text);
if (command.type === 'assessment') {
return this.feishuAssessmentService.handleCommand(command, payload);
}
// 默认转发至 AI 对话
return this.chatService.sendMessage(payload);
}
}
```
##### 知识库处理管道
`KnowledgeBaseService` 根据文档类型选择处理路径，调用内部服务完成文档解析、分块、向量化与索引：
```typescript
// knowledge-base.service.ts（源码结构示意）
async processDocument(file: Express.Multer.File, kbId: string) {
// 1. 调用 Tika 提取文本
const text = await this.tikaService.extractText(file);
// 2. 调用 TextChunkerService 分块
const chunks = this.textChunkerService.chunk(text, chunkConfig);
// 3. 调用 EmbeddingService 生成向量
const embeddings = await this.embeddingService.generate(chunks);
// 4. 调用 ElasticsearchService 写入索引
await this.elasticsearchService.indexDocuments(kbId, chunks, embeddings);
}
```
#### 内部接口鉴权机制
内部服务间调用通过以下机制保障安全：
| 机制 | 实现方式 | 适用场景 |
|---|---|---|
| **API Key** | `ApiKeyGuard` 校验 `X-API-Key` 请求头，密钥存于 `api_key` 表 | 外部系统或可信服务调用 |
| **JWT** | `JwtAuthGuard` 校验 Bearer Token | 用户登录后的前端请求 |
| **租户隔离** | `TenantMiddleware` + `TenantEntitySubscriber` 自动附加租户条件 | 所有多租户数据访问 |
| **权限码** | `PermissionGuard` + `@Permissions()` 装饰器，共 26 个细粒度权限 | 管理类操作 |
#### 内部调用流程说明
1. **同步调用**：大部分模块间调用为同步 HTTP 或进程内方法调用，如 `ChatService` 调用 `RagService` 进行检索。
2. **异步任务**：耗时操作（如文档导入、PDF 生成）通过 `ImportTaskService` 创建任务记录，由后台异步执行，前端通过轮询任务状态获取结果。
3. **WebSocket**：飞书机器人通过 `FeishuWsManager` 维护 WebSocket 连接，实现消息的实时推送与接收。
> 关于各模块对外暴露的 REST 端点及请求/响应格式，详见“API 参考”章节。
### 5.3 数据格式
#### 全局约定
#### 请求与响应格式
系统采用标准的 **RESTful JSON** 格式进行数据交换。所有 API 请求与响应均使用 `Content-Type: application/json`（文件上传接口除外）。响应体统一封装为以下结构：
```json
{
"code": 0,
"data": {},
"message": "success"
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `code` | number | 业务状态码，`0` 表示成功，非零表示失败 |
| `data` | object/array | 业务数据负载，可为空对象 |
| `message` | string | 状态描述信息 |
#### 日期时间格式
所有时间字段统一采用 **ISO 8601** 标准格式的 UTC 字符串，精确到毫秒：
```json
{
"createdAt": "2026-04-23T08:30:00.000Z",
"updatedAt": "2026-04-23T08:30:00.000Z"
}
```
前端展示时由客户端根据本地时区进行转换。数据库中以 SQLite 的 `datetime` 类型存储，通过 TypeORM 实体映射为 JavaScript `Date` 对象。
#### 枚举与状态码
系统内部使用字符串枚举表示固定状态集合，主要枚举值如下：
| 枚举名称 | 取值 | 说明 |
|---|---|---|
| `UserRole` | `SUPER_ADMIN` / `TENANT_ADMIN` / `USER` | 用户角色三级体系 |
| `AssessmentStatus` | `IN_PROGRESS` / `COMPLETED` / `EXPIRED` | 评估会话状态 |
| `QuestionType` | `MULTIPLE_CHOICE` / `SHORT_ANSWER` | 题目类型 |
| `ImportTaskStatus` | `PENDING` / `PROCESSING` / `COMPLETED` / `FAILED` | 导入任务状态 |
#### 分页格式
列表类接口统一采用分页参数 `page`（页码，从 1 开始）与 `pageSize`（每页条数）。分页响应结构如下：
```json
{
"code": 0,
"data": {
"items": [],
"total": 100,
"page": 1,
"pageSize": 20
},
"message": "success"
}
```
| 字段 | 类型 | 说明 |
|---|---|---|
| `items` | array | 当前页数据列表 |
| `total` | number | 符合条件的总记录数 |
| `page` | number | 当前页码 |
| `pageSize` | number | 每页条数 |
#### 文件上传格式
文件上传接口使用 `multipart/form-data` 格式，支持的文件类型由 `file-support.constants.ts` 定义，涵盖文档、图片、音视频等常见格式。上传响应返回文件元数据：
```json
{
"code": 0,
"data": {
"id": "uuid-string",
"filename": "原始文件名.pdf",
"mimeType": "application/pdf",
"size": 1024000,
"url": "/uploads/xxx.pdf"
},
"message": "success"
}
```
#### 流式响应格式
AI 对话与评估相关接口支持 **SSE（Server-Sent Events）** 流式输出。响应以 `text/event-stream` 格式返回，每个事件包含 `data:` 前缀的 JSON 片段，以空行分隔。事件流结束以 `data: [DONE]` 标记。
#### 多租户数据约定
系统为多租户架构，租户标识通过请求头 `X-Tenant-Id` 传递。所有业务数据表均包含 `tenantId` 字段用于数据隔离，由 `tenant-entity.subscriber.ts` 中的实体订阅器自动注入，业务代码无需手动处理。
#### 错误码约定
业务错误码采用非零整数表示，具体错误码与 HTTP 状态码的映射关系详见 **API 规范** 章节中的「错误处理」子章节。错误响应体中的 `message` 字段支持多语言，由 `i18n` 模块根据请求头 `Accept-Language` 动态返回对应语言文本。
## 6. 用户界面
### 6.1 布局与导航
#### 整体布局结构
AuraK 前端采用 **React + React Router** 构建，整体布局分为两大区域：
- **认证区域**：登录页面（`web/src/pages/auth/Login.tsx`），独立于主布局。
- **工作区区域**：登录后进入，由 `WorkspaceLayout` 组件承载，包含侧栏导航与内容区。
工作区布局文件位于 `web/components/layouts/WorkspaceLayout.tsx`（另有 `web/src/components/layouts/WorkspaceLayout.tsx` 副本），采用侧栏（`SidebarRail`）+ 主内容区的经典结构。侧栏提供功能导航入口，主内容区根据路由动态渲染对应视图。
#### 路由配置
路由定义在 `web/App.tsx` 中，采用嵌套路由结构。工作区路由以 `workspace` 为父路径，子路由对应各功能页面：
| 路由路径 | 页面组件 | 功能 |
|:---------|:---------|:-----|
| `/login` | `Login.tsx` | 用户登录 |
| `/workspace` | `WorkspaceLayout` | 工作区父布局 |
| `/workspace/chat` | `ChatPage.tsx` | AI 对话 |
| `/workspace/knowledge` | `KnowledgePage.tsx` | 知识库管理 |
| `/workspace/notebooks` | `NotebooksPage.tsx` | 笔记本列表 |
| `/workspace/memos` | `MemosPage.tsx` | 备忘录 |
| `/workspace/assessment` | `AssessmentPage.tsx` | 考核评估 |
| `/workspace/assessment-stats` | `AssessmentStatsView.tsx` | 评估统计 |
| `/workspace/question-banks` | `QuestionBankView.tsx` | 题库列表 |
| `/workspace/question-banks/:id` | `QuestionBankDetailView.tsx` | 题库详情 |
| `/workspace/agents` | `AgentsPage.tsx` | AI 智能体 |
| `/workspace/plugins` | `PluginsPage.tsx` | 插件管理 |
| `/workspace/settings` | `SettingsPage.tsx` | 系统设置 |
> 注：`assessment-stats`、`question-banks` 等路由在 `App.tsx` 中可能以相对路径形式嵌套于 `workspace` 下，具体匹配规则以源码为准。
#### 侧栏导航
侧栏（`SidebarRail.tsx`）提供以下导航入口：
- **对话**（Chat）
- **知识库**（Knowledge）
- **笔记本**（Notebooks）
- **备忘录**（Memos）
- **考核评估**（Assessment）
- **评估统计**（Assessment Stats）
- **题库管理**（Question Banks）
- **智能体**（Agents）
- **插件**（Plugins）
- **设置**（Settings）
导航项通过图标 + 文本形式展示，点击后通过 React Router 的 `Link` 或 `useNavigate` 跳转到对应路由。
#### 关键视图与导航流程
##### 考核评估流程
考核评估是系统的核心功能，导航流程如下：
1. 用户从侧栏点击 **考核评估**，进入 `/workspace/assessment`。
2. `AssessmentPage.tsx` 渲染 `AssessmentView.tsx`，展示模板选择列表。
3. 用户选择模板后点击 **开始评估**，进入答题交互界面。
4. 答题完成后提交，展示结果与证书。
`AssessmentView.tsx` 内部包含多个子视图状态：
- **答题交互**：选择题（选项按钮 + 确认）、简答题（textarea + 发送）、AI 追问流程。
- **进度导航**：题序圆点（当前题蓝色、标记题黄色、其他灰色）+ 标记回头按钮。
- **提交确认**：未答完时弹出确认弹窗。
- **结果展示**：等级、分数、每题详情、报告。
- **证书弹窗**：等级、总分、维度得分、题目列表。
- **历史侧栏**：右侧展示考评历史列表。
##### 题库管理流程
1. 从侧栏点击 **题库管理**，进入 `/workspace/question-banks`。
2. `QuestionBankView.tsx` 展示题库卡片列表，支持搜索与筛选（全部/已发布/草稿/待审核）。
3. 点击题库卡片进入 `/workspace/question-banks/:id`，由 `QuestionBankDetailView.tsx` 渲染题库详情。
4. 详情页支持题目 CRUD、AI 生成、批量审核、提交审核（DRAFT→PENDING_REVIEW）、发布（PENDING_REVIEW→PUBLISHED）等操作。
##### 设置页面
`/workspace/settings` 由 `SettingsPage.tsx` 渲染，内部通过 Tab 切换不同设置模块，其中 **测评模板**（Tab: `assessment_templates`）由 `AssessmentTemplateManager.tsx` 实现，支持模板 CRUD、维度配置（添加/删除/权重）及 P2 配置（attemptLimit/reviewMode/shuffleQuestions/预约时段）。
#### 布局组件与权限控制
工作区布局中，部分导航项受权限控制。`PermissionGate.tsx` 组件用于根据用户权限决定是否渲染特定导航入口或页面内容。权限逻辑基于 `usePermissions` Hook（`web/src/hooks/usePermissions.ts`），权限定义见 `server/src/auth/permission/permission.constants.ts`。
#### 相关章节
- 各视图的具体交互细节与数据流，参见 **功能模块** 章节。
- 权限控制机制详见 **权限模型** 章节。
### 6.2 组件
#### 通用交互组件
前端 UI 层基于 React 19 + TypeScript + Vite 构建，`web/components/` 目录下集中存放可复用组件。按功能可划分为以下几组：
**对话框与弹窗类**
| 组件文件 | 功能说明 |
|---------|---------|
| `ConfirmDialog.tsx` | 通用确认对话框，配合 `contexts/ConfirmContext.tsx` 全局调用 |
| `CreateNoteFromPDFDialog.tsx` | 从 PDF 创建笔记的对话框 |
| `CreateNotebookDialog.tsx` / `EditNotebookDialog.tsx` | 笔记本的创建与编辑对话框 |
| `SettingsModal.tsx` / `IndexingModal.tsx` | 设置与索引进度弹窗 |
| `AICommandModal.tsx` | AI 指令输入弹窗 |
**抽屉类（Drawer）**
| 组件文件 | 功能说明 |
|---------|---------|
| `AICommandDrawer.tsx` | AI 指令侧边抽屉 |
| `ChunkInfoDrawer.tsx` | 知识库分块信息展示抽屉 |
| `CreateNotebookDrawer.tsx` / `EditNotebookDrawer.tsx` | 笔记本创建/编辑抽屉 |
| `GroupSelectionDrawer.tsx` | 知识分组选择抽屉 |
| `HistoryDrawer.tsx` | 对话历史记录抽屉 |
| `ImportFolderDrawer.tsx` | 文件夹导入抽屉 |
| `InputDrawer.tsx` | 通用输入抽屉 |
| `SettingsDrawer.tsx` | 设置抽屉 |
| `SourcePreviewDrawer.tsx` | 来源预览抽屉 |
| `drawers/ImportTasksDrawer.tsx` | 导入任务列表抽屉 |
**上传与拖拽类**
- `DragDropUpload.tsx` — 通用拖拽上传组件
- `NotebookDragDropUpload.tsx` — 笔记本场景专用拖拽上传
- `GlobalDragDropOverlay.tsx` / `NotebookGlobalDragDropOverlay.tsx` — 全局拖拽覆盖层
**选择器与展示类**
- `GroupSelector.tsx` / `GroupManager.tsx` — 知识分组选择与管理
- `ModeSelector.tsx` — 模式切换器
- `VisionModelSelector.tsx` — 视觉模型选择器
- `FileGroupTags.tsx` — 文件分组标签
- `SearchResultsPanel.tsx` / `SearchHistoryList.tsx` — 搜索结果与历史列表
- `PDFPreview.tsx` / `PDFSelectionTool.tsx` — PDF 预览与选区工具
- `UserInfoDisplay.tsx` — 用户信息展示
- `Logo.tsx` — 品牌 Logo
#### 聊天与 AI 相关组件
- `ChatInterface.tsx` — 聊天主界面，承载消息渲染与输入交互
- `ChatMessage.tsx` — 单条聊天消息组件，支持 Markdown 与流式渲染
- `ConfigPanel.tsx` — AI 配置面板
#### 权限控制组件
- `PermissionGate.tsx` — 基于权限的渲染门控组件，配合 `contexts/AuthContext.tsx` 与 `hooks/usePermissions.ts` 使用，控制按钮或区块的可见性。
#### 布局组件
`web/components/layouts/` 下提供：
- `WorkspaceLayout.tsx` — 工作区整体布局（同时存在于 `web/src/components/layouts/`）
- `SidebarRail.tsx` — 侧边栏轨道
- `AdminLayout.tsx` — 管理后台布局
#### 基础 UI 组件
`web/src/components/ui/` 提供原子级基础组件：
- `button.tsx` — 按钮
- `card.tsx` — 卡片容器
- `select.tsx` — 下拉选择器
#### 视图组件
`web/components/views/` 下为业务视图级组件，代表完整功能页面：
| 组件文件 | 对应功能 |
|---------|---------|
| `AssessmentView.tsx` | 考核评估主界面（含历史记录侧栏） |
| `AssessmentStatsView.tsx` | 评估统计面板（雷达图/趋势图） |
| `AssessmentTemplateManager.tsx` | 测评模板管理 |
| `QuestionBankView.tsx` / `QuestionBankDetailView.tsx` | 题库列表与详情 |
| `KnowledgeBaseView.tsx` | 知识库管理 |
| `ChatView.tsx` | 对话视图 |
| `NotebooksView.tsx` / `NotebookDetailView.tsx` | 笔记本列表与详情 |
| `MemosView.tsx` | 备忘录视图 |
| `PermissionSettingsView.tsx` | 权限设置矩阵 |
| `SettingsView.tsx` | 系统设置 |
| `PluginsView.tsx` | 插件管理 |
#### 上下文与工具
`web/contexts/` 提供全局状态：
- `AuthContext.tsx` — 认证状态
- `ConfirmContext.tsx` — 确认对话框上下文
- `LanguageContext.tsx` — 国际化语言上下文
- `ToastContext.tsx` — 轻提示上下文
`web/utils/` 提供工具函数：`clipboard.ts`（剪贴板）、`fileUtils.ts`（文件处理）、`translations.ts`（翻译映射）、`uuid.ts`（ID 生成）。
#### 组件间关系说明
考核评估模块是组件交互最复杂的场景：`AssessmentView.tsx` 作为主容器，内部协调 `ChatInterface` 渲染对话流、`HistoryDrawer` 展示历史记录、`ConfirmDialog` 处理操作确认，并通过 `services/assessmentService.ts` 与后端 LangGraph 状态机通信。题库管理则由 `QuestionBankView` 与 `QuestionBankDetailView` 两级视图构成，详情视图内嵌题目审核与批量操作面板。
> 关于视图组件对应的后端 API 与数据模型，详见「API 参考」与「数据模型」章节。
### 6.3 状态管理
#### 状态管理架构概览
AuraK 前端采用 **React Context** 作为全局状态管理方案，未引入 Redux、Zustand 等第三方状态库。所有全局状态均通过 Context Provider 在组件树顶层注入，配合自定义 Hooks 实现状态访问与更新。
#### 认证状态（AuthContext）
认证状态由 `web/src/contexts/AuthContext.tsx` 管理，负责用户登录态、令牌存储与权限信息的全局维护。
**核心职责：**
- 维护当前登录用户信息（用户名、显示名、角色等）
- 管理 JWT 令牌与 API Key 的存储（localStorage）
- 提供登录、登出、令牌刷新等操作
- 在应用初始化时恢复会话状态
**使用方式：**
```tsx
// 在组件中访问认证状态
const { user, isAuthenticated, login, logout } = useAuth();
```
认证流程为：密码登录 → 签发 JWT → 获取 API Key（存 localStorage）→ 后续请求通过 `x-api-key` 头携带，`x-tenant-id` 头指定租户上下文。
#### 语言状态（LanguageContext）
语言状态由 `web/contexts/LanguageContext.tsx` 管理，负责多语言界面的切换与翻译文本的提供。
**核心职责：**
- 维护当前语言（中文 / 英文 / 日文）
- 提供翻译函数，根据 key 返回对应语言的文本
- 语言切换时触发组件重新渲染
翻译文本定义在 `web/utils/translations.ts` 中，包含导航、按钮、提示等 UI 文案。例如：
```ts
// translations.ts 中的部分翻译 key
navAgent: "智能体",
navAssessment: "评测",
navPlugin: "插件",
switchLanguage: "切换语言",
```
#### 提示与确认状态（ToastContext / ConfirmContext）
这两个 Context 提供全局 UI 反馈能力：
- **ToastContext**（`web/contexts/ToastContext.tsx`）：全局消息提示，用于操作成功、失败等轻量反馈。
- **ConfirmContext**（`web/contexts/ConfirmContext.tsx`）：全局确认对话框，用于需要用户确认的破坏性操作（如删除）。
**使用示例：**
```tsx
const { showToast } = useToast();
const { confirm } = useConfirm();
// 触发提示
showToast('保存成功', 'success');
// 弹出确认框
await confirm('确定要删除该用户吗？');
```
#### 权限状态（usePermissions Hook）
权限判断逻辑封装在 `web/src/hooks/usePermissions.ts` 中，基于当前用户的角色与权限集合提供细粒度的访问控制。
**核心能力：**
- 检查当前用户是否拥有指定权限 key（如 `user:view`、`kb:edit`）
- 支持组件级别的权限门控渲染
权限门控组件 `PermissionGate`（`web/components/PermissionGate.tsx`）基于该 Hook 实现，用于条件渲染受权限保护的 UI 元素。
#### 服务层状态（Services）
各业务模块的状态通过 `web/services/` 目录下的服务模块管理，这些模块封装了 API 调用逻辑，并在组件内部通过 `useState` / `useEffect` 维护局部状态。主要服务包括：
| 服务模块 | 职责 |
|---|---|
| `authService.ts` | 登录、登出、令牌管理 |
| `userService.ts` | 用户 CRUD 操作 |
| `knowledgeBaseService.ts` | 知识库管理 |
| `assessmentService.ts` | 考核流程管理 |
| `questionBankService.ts` | 题库管理 |
| `chatService.ts` | 对话与流式响应 |
#### 租户上下文（服务端）
服务端通过 `server/src/tenant/tenant.store.ts` 维护租户上下文，前端请求通过 `x-tenant-id` 头传递租户标识，服务端中间件（`tenant.middleware.ts`）解析并注入当前租户上下文，实现多租户数据隔离。该机制在“多租户架构”章节中有详细说明。
#### 状态管理选型说明
项目选择 React Context 而非 Redux 等外部状态库，主要基于以下考量：
- 应用状态规模适中，Context 足以覆盖全局共享状态需求
- 减少依赖体积，保持轻量化
- 与 React 19 的并发特性天然兼容
对于组件内部的复杂状态（如表单、列表筛选），使用 React 内置的 `useState` / `useReducer` 管理，不提升至全局 Context，以降低不必要的重渲染开销。
## 7. 安全设计
### 7.1 认证与授权
#### 认证机制总览
AuraK 采用 **JWT + API Key 双机制** 进行身份认证。系统默认使用 JWT（JSON Web Token）作为主要认证方式，同时为服务间通信提供 API Key 认证通道。认证模块位于 `server/src/auth/` 目录下，基于 NestJS Passport 策略实现。
#### JWT 认证流程
JWT 认证基于 Passport 的 `local` 与 `jwt` 策略组合实现：
1. **登录**：用户通过 `POST /auth/login` 提交用户名与密码，`local.strategy.ts` 验证凭据。
2. **签发令牌**：认证成功后，`auth.service.ts` 签发 JWT 令牌并返回给客户端。
3. **请求携带**：客户端在后续请求的 `Authorization: Bearer ` 头中携带令牌。
4. **令牌验证**：`jwt.strategy.ts` 解析并验证令牌签名与有效期，将用户信息挂载到请求对象。
相关守卫（Guard）包括：
| 守卫 | 职责 |
|---|---|
| `local-auth.guard.ts` | 登录接口的本地认证守卫 |
| `jwt-auth.guard.ts` | 验证 JWT 令牌有效性 |
| `combined-auth.guard.ts` | 全局认证守卫，同时支持 JWT 与 API Key |
| `public.decorator.ts` | 标记公开接口，跳过认证 |
#### API Key 认证
除 JWT 外，系统通过 `api-key.guard.ts` 支持 API Key 认证。API Key 实体定义于 `server/src/auth/entities/api-key.entity.ts`，适用于服务间调用或自动化脚本场景。`combined-auth.guard.ts` 会优先尝试 JWT，若不存在则回退到 API Key 校验。
#### 角色体系
系统内置三级角色，定义于 `server/src/user/user-role.enum.ts`：
| 角色 | 权限数 | 核心能力 |
|---|---|---|
| **SUPER_ADMIN** | 26 项 | 全部权限：用户/租户/知识库/考核/模型/设置 |
| **TENANT_ADMIN** | 21 项 | 本租户管理：用户/知识库/考核/模型；不能跨租户、删用户、改系统设置 |
| **USER** | 5 项 | 使用知识库、参与考核、查看插件 |
角色实体（`role.entity.ts`）包含 `isSystem` 标记，系统角色受保护不可删改；`baseRole` 字段映射到 `UserRole` 枚举；`tenantId` 为 `null` 表示全局角色，非 `null` 则为租户自定义角色。
#### 权限模型（RBAC）
权限定义位于 `server/src/auth/permission/permission.constants.ts`，共 26 项细粒度权限，按分类组织：
| 分类 | 权限 |
|---|---|
| 用户管理 | `user:view` / `user:create` / `user:edit` / `user:delete` / `user:role` / `user:password` |
| 租户管理 | `tenant:view` / `tenant:create` / `tenant:edit` / `tenant:delete` / `tenant:members` |
| 知识库 | `kb:view` / `kb:create` / `kb:edit` / `kb:delete` / `kb:publish` |
| 考核 | `assess:view` / `assess:manage` / `assess:template` / `assess:bank` |
| 模型 | `model:view` / `model:config` |
| 插件 | `plugin:view` / `plugin:manage` |
| 设置 | `settings:view` / `settings:system` |
角色与权限通过 `role-permission.entity.ts` 关联表建立多对多关系。
#### 权限检查机制
权限检查通过装饰器与守卫组合实现：
```typescript
// 控制器示例
@UseGuards(PermissionGuard)
@Permission('kb:create')
@Post()
create() { /* ... */ }
```
核心组件：
- `permission.decorator.ts` — `@Permission()` 装饰器，声明所需权限
- `permission.guard.ts` — 校验当前用户是否具备所需权限
- `roles.decorator.ts` — `@Roles()` 装饰器，声明所需角色
- `roles.guard.ts` — 校验当前用户角色
- `super-admin.guard.ts` / `tenant-admin.guard.ts` — 针对特定角色的专用守卫
前端通过 `PermissionGate.tsx` 组件与 `usePermissions.ts` Hook 实现组件级权限门控，与后端权限定义保持一致。
#### 多租户数据隔离
系统通过 `tenant.middleware.ts` 与 `tenant-entity.subscriber.ts` 实现租户级数据隔离。请求经过中间件时解析当前租户上下文，实体订阅器在数据库操作时自动附加租户过滤条件，确保租户间数据不可互访。租户成员关系定义于 `tenant-member.entity.ts`。
#### 安全说明
- JWT 密钥通过环境变量 `JWT_SECRET` 配置（见 README 快速开始章节）。
- 代码审查记录指出 `knowledge-base.service.ts` 中存在动态引入 `jsonwebtoken` 的用法（第 1676-1685 行），建议统一通过 NestJS `JwtService` 管理令牌操作。
- 系统角色（SUPER_ADMIN、TENANT_ADMIN、USER）的权限不可修改，自定义角色可灵活配置权限矩阵。
> 相关 API 端点与请求/响应格式详见「API 参考」章节；用户 CRUD 与角色分配操作详见「用户管理」章节。
### 7.2 传输安全
#### 传输层加密（TLS/HTTPS）
AuraK 的传输安全由 Nginx 反向代理层统一承载。源码中 `nginx/nginx.conf` 与 `nginx/conf.d/` 目录下的配置文件定义了 HTTPS 的启用方式与证书管理策略。
##### 证书配置
Nginx 配置引用了位于 `nginx/conf.d/ssl/` 目录下的证书文件：
- **证书文件**：`cert.pem`
- **私钥文件**：`key.pem`
证书的生成由 `nginx/generate-ssl.sh` 脚本完成。该脚本用于生成自签名 SSL 证书，适用于开发环境或内网部署场景。生产环境部署时，应将自签名证书替换为由受信任的证书颁发机构（CA）签发的正式证书。
##### HTTPS 强制与重定向
Nginx 配置中实现了 HTTP 到 HTTPS 的强制跳转，确保所有客户端请求均通过加密通道传输。该机制有效防御以下攻击：
- **中间人攻击（MITM）**：通过 TLS 加密，防止攻击者在客户端与服务器之间窃听或篡改传输中的数据。
- **降级攻击**：强制使用 HTTPS，阻止攻击者将通信协议从 HTTPS 降级为明文 HTTP，从而规避加密保护。
##### 安全响应头
Nginx 配置中设置了多项安全响应头，以增强浏览器端的安全防护。具体配置项在源码中未完整列出，但根据 Nginx 配置文件的常规实践，通常包含以下内容（源码中未提供完整清单，以下为基于配置文件的推断）：
| 响应头 | 作用 | 防御的攻击类型 |
|---|---|---|
| `X-Content-Type-Options: nosniff` | 禁止浏览器对响应内容进行 MIME 类型嗅探 | 内容嗅探攻击、MIME 混淆攻击 |
| `X-Frame-Options` | 控制页面是否允许被嵌入到 `