docs: 全面更新文档体系 — AI指南 + 人可读说明书

CLAUDE.md — AI 工作指南: - 项目全景：目录结构/技术栈/端口 - 系统架构：前端路由/后端模块/认证流程 - 权限系统：三层角色/26项权限/守卫流水线/解析链路 - 考核系统：数据模型/出题算法/模板配置 - 测试脚本：7个Playwright测试说明 - 开发指南：启动/测试/重启/数据库管理 - 代码规范：TypeScript模式/权限装饰器/React约定 - Playwright测试技巧：React受控输入框/等待策略 README.md — 人可读英文说明书: - 系统介绍 + 功能特性 - 完整使用指南（用户管理/权限管理/考核模板/组织考试） - 核心流程说明（认证/出题/权限解析） - 测试命令参考 - 项目结构 + 配置参考 README_ZH.md — 人可读中文说明书: - 全面中文版本，包含所有新功能 - 步骤式操作指南，便于管理员使用 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-09 13:19:45 +08:00
parent 1aee7e0baf
commit 65ede9fcff
3 changed files with 845 additions and 431 deletions
@@ -1,119 +1,278 @@
-# AuraK：企业级全栈智能 AI 知识平台
+# AuraK — 企业级 AI 知识库与人才评价平台

-AuraK 是一个基于 **React 19** 与 **NestJS** 构建的现代化企业级 AI 知识库与人才评价系统。它不仅提供了高度可扩展的 RAG（检索增强生成）能力，还深度集成了多租户管理、交互式评价工作流及飞书办公生态。
+AuraK 是基于 **React 19 + NestJS** 构建的多租户智能平台，集 RAG 知识库管理、AI 交互式考核评估、企业级 RBAC 权限管理于一体。

 ---

-## ✨ 核心特性
+## ✨ 功能特性

-### 🔐 企业级多租户与权限
- **租户隔离**：严格的数据与资源租户级物理隔离，支持独立域名/子域名挂载。
- **RBAC 权限管理**：预置超级管理员、租户管理员、普通用户等多种角色。
- **成员管理**：支持租户内成员邀请、权限分配与配额限制。
+### 🔐 多租户与权限管理
+- **租户隔离** — 严格的数据隔离，每个租户独立成员管理和配置
+- **RBAC 权限系统** — 三层角色（SUPER_ADMIN / TENANT_ADMIN / USER），26 项细粒度权限，7 大分类
+- **自定义角色** — 创建自定义角色并精准分配权限集
+- **权限矩阵 UI** — 设置页内可视化权限编辑，勾选即生效
+- **自动种子数据** — 首次启动自动创建角色和默认权限

-### 📚 智能知识路由与管理
- **层级化分组**：支持知识库文件的文件夹式层级管理（Knowledge Groups），轻松应对海量文档。
- **双模式处理流水线**：
-    - **快速模式 (Fast)**：基于 Apache Tika，极速提取海量纯文本。
-    - **高精度模式 (High-Precision)**：集成了 **Vision Pipeline**，利用多模态模型识别复杂 PDF/图片中的图文混合内容。
- **格式全支持**：原生支持 PDF, Word, PPT, Excel, TXT, Markdown 以及各类图片格式。
+### 📊 AI 交互式考核评估
+- **AI 智能出题** — 基于知识库自动生成选择题和简答题，支持多轮追问
+- **题库系统** — 预置题目 + AI 实时生成双来源，支持审核发布流程
+- **多维度加权评分** — 按自定义维度权重（Prompt / LLM / IDE / 开发范式 / 工作能力）计算综合得分
+- **证书系统** — 自动生成等级证书（Novice / Proficient / Advanced / Expert）
+- **灵活模板** — 可配置题数、维度权重、及格分、时间限制
+- **非技术人员模式** — 独立模板排除 IDE 和开发范式，只考核 Prompt 和 LLM 理解

-### 📊 交互式人才评价 (Assessment)
- **LangGraph 工作流**：基于图结构的 AI 对话逻辑，实现逻辑严密的自动化面试与素质评价。
- **落地式出题 (Grounded Q&A)**：基于 RAG 技术，从自有知识库中根据关键词精准提取素材生成专业题目。
- **加权智能评分**：支持 Standard (1.0), Advanced (1.5), Specialist (2.0) 三级难度权重的自动化综合评分。
- **多语言评价**：支持中、英、日三语同步测评。
+**考试流程：** 管理员创建考生账号 → 考生登录 → 参加考核 → AI 自动评分 + 发证 → 查看历史记录

-### 🤖 深度飞书办公集成
- **免公网 WebSocket 机器人**：支持通过飞书长连接（WebSocket）直接接入企业内网，无需公网 IP 或域名映射。
- **互动消息卡片**：在飞书中实时展示 AI 思考过程、检索来源及测评进度。
- **移动端评价**：用户可直接在飞书聊天窗口完成完整的人才评价流程。
+### 📚 智能知识库
+- **双处理模式** — 快速模式（Tika 文本提取）+ 高精度模式（Vision Pipeline 图文混合识别）
+- **混合检索** — Elasticsearch BM25 关键词 + 向量检索
+- **多格式支持** — PDF、Word、PPT、Excel、图片等
+- **层级化分组** — 文件夹式知识库分组管理

-### 🚀 高级 RAG 性能优化
- **混合检索 (Hybrid Search)**：结合 Elasticsearch 的 BM25 关键词检索与高维度向量检索，大幅提升首选片段准确率。
- **智能重排序 (Rerank)**：内置 Rerank 模型二次校验，确保生成内容的真实性与相关性。
- **SSE 流式响应**：秒级首屏响应，实时展示知识检索状态与生成进度。
+### 🤖 多模型 AI 引擎
+- OpenAI 兼容接口（DeepSeek、Claude 等）
+- Google Gemini 原生 SDK
+- 可配置 LLM / Embedding / Rerank / Vision 模型

-### 🛠️ 生产力增强工具
- **播客生成 (Podcasts)**：一键将长文档转化为播客形式的音频摘要。
- **智能笔记 (Notes)**：支持对知识库内容记录分类笔记。
- **搜索历史溯源**：完整的聊天历史记录与引用文档回溯。
+### 🌐 其他功能
+- SSE 流式响应
+- 多语言界面（中文 / 英文 / 日文）
+- 飞书机器人集成
+- 文档转播客
+- 笔记/共享笔记本
+- 用户配额管理

 ---

 ## 🏗️ 技术架构

-### 前端 (Web)
- **核心**：React 19 + TypeScript + Vite
- **UI/样式**：Tailwind CSS + Lucide React
- **交互**：React Context + SSE Streaming + Framer Motion (微动画)
+### 前端
+- **框架：** React 19 + TypeScript + Vite 6
+- **样式：** Tailwind CSS v4 + 统一设计语言（indigo 主题色）
+- **图标：** Lucide React
+- **状态管理：** React Context
+- **动画：** Framer Motion

-### 后端 (Server)
- **框架**：NestJS (Node.js) + TypeScript
- **AI 引擎**：LangChain + **LangGraph** (评价工作流)
- **存储**：SQLite (元数据) + **Elasticsearch** (向量与全文检索)
- **处理层**：Apache Tika + Vision Pipeline + LibreOffice (文档转换)
- **通信**：Feishu WebSocket Manager + SSE
+### 后端
+- **框架：** NestJS 11 + TypeScript
+- **AI 引擎：** LangChain + LangGraph（考核工作流）
+- **数据库：** SQLite（元数据） + Elasticsearch 9（向量+全文检索）
+- **认证：** JWT + API Key 双机制
+- **文档处理：** Apache Tika + Vision Pipeline + LibreOffice

---
-
-## 🏢 内网部署支持
-
-AuraK 专为私有化部署设计：
- **资源本地化**：KaTeX、字体等静态资源完全本地化，无需访问 CDN。
- **私有模型接入**：支持接入各类 OpenAI 兼容格式的内网私有化模型服务。
- **容器化部署**：提供完整的 Docker Compose 一键启动方案，支持私有镜像仓库。
-
-详细指南请参考 [内网部署手册](INTERNAL_DEPLOYMENT_GUIDE.md)。
+### 基础设施
+- Docker Compose（Elasticsearch / Tika / LibreOffice）
+- Nginx 反向代理（生产环境）

 ---

 ## 🚀 快速开始

-### 1. 准备工作
- Node.js 18+
- Yarn
+### 前提条件
+- Node.js 18+, Yarn
 - Docker & Docker Compose

-### 2. 克隆与安装
+### 1. 安装与启动
+
 ```bash
-git clone <repository-url>
-cd auraAuraK
+# 克隆并安装
+git clone <repo-url>
+cd AuraK
 yarn install
-```

-### 3. 启动周边服务
-```bash
+# 配置环境变量
+cp server/.env.sample server/.env
+# 编辑 server/.env — 设置 JWT_SECRET、API Key 等
+
+# 启动基础设施（可选 — AI 功能需要 Elasticsearch）
 docker-compose up -d elasticsearch tika libreoffice
-```

-### 4. 环境配置
-分别修改 `server/.env` 和 `web/.env`。
-
-### 5. 启动项目
-```bash
+# 启动开发服务器
 yarn dev
+# 前端：http://localhost:13001
+# 后端：http://localhost:3001
+```
+
+### 2. 默认登录
+```
+用户名: admin
+密码:   admin123
+```
+
+### 3. 免 Docker 快速启动
+
+```bash
+# 启动后端
+cd server && node dist/main.js &
+
+# 启动前端
+cd web && npx vite --port 13001 &
 ```
-访问 `http://localhost:5173` 开始体验！

 ---

-## 📁 项目目录
+## 📖 使用指南
+
+### 系统设置与用户管理
+
 ```
-auraAuraK/
-├── web/                    # 前端 React 应用
-├── server/                 # 后端 NestJS 应用
+路径: 系统设置 → 用户管理
+```
+1. **创建用户** — 填写用户名、密码、显示名
+2. **分配角色** — 点击用户编辑 → 选择 USER / TENANT_ADMIN / SUPER_ADMIN
+3. **权限预览** — 选择角色时同步显示该角色的权限数
+4. **批量操作** — 支持 XLSX 导入导出用户
+
+### 权限管理
+
+```
+路径: 系统设置 → 权限管理
+```
+1. **角色列表** — 左侧显示所有角色（SUPER_ADMIN、TENANT_ADMIN、USER + 自定义角色）
+2. **权限矩阵** — 点击角色 → 右侧展开权限分类 → 逐项勾选
+3. **创建自定义角色** — 点击「+」→ 填名称 → 设权限 → 保存
+4. **系统角色保护** — 系统内置角色不可修改不可删除
+
+### 考核模板配置
+
+```
+路径: 系统设置 → 测评模板
+```
+1. **创建模板** — 设置名称、题数、及格分、时间限制
+2. **配置维度** — 添加/删除考核维度，设置权重
+   - 技术人员模板：PROMPT 30% / LLM 30% / IDE 20% / DEV_PATTERN 20%
+   - 非技术人员模板：PROMPT 50% / LLM 30% / WORK_CAPABILITY 20%
+3. **关联题库** — 创建并发布题库，模板自动从题库抽题
+4. **AI 出题** — 未关联题库时由 AI 实时生成
+
+### 组织考试
+
+```
+路径: 考核评估 → 选择模板 → 开始专业评估
+```
+
+**管理员操作：**
+1. 系统设置 → 用户管理 → 创建考生账号
+2. 告知考生用户名和密码
+
+**考生操作：**
+1. 使用账号密码登录
+2. 进入考核评估页面 → 选择模板 → 开始
+3. 完成选择题和简答题
+4. AI 可能追问（多轮对话）
+5. 作答完成后查看分数和等级
+
+**查看结果：**
+- **历史记录** — 考核页面右侧栏列出所有历史成绩
+- **详情** — 点击记录查看每题得分和 AI 评语
+- **证书** — 点击「查看证书」查看等级、总分、各维度得分
+- **导出** — 支持下载 PDF 报告和导出 Excel
+
+### 租户管理（仅 SUPER_ADMIN）
+
+```
+路径: 系统设置 → 租户管理
+```
+- 创建/编辑/删除租户，支持父子层级结构
+- 管理租户成员：添加用户、分配角色
+- 每个租户独立的知识库和配置
+- 数据隔离：A 租户用户不可见 B 租户数据
+
+---
+
+## 🔄 核心流程
+
+### 认证流程
+```
+密码登录 → 签发 JWT → 获取 API Key（存 localStorage）
+  → 后续所有请求通过 x-api-key 头
+  → x-tenant-id 头指定租户上下文
+```
+
+### 出题算法
+```
+模板维度权重（如 PROMPT:30, LLM:30, IDE:20, DEV_PATTERN:20）
+  → floor + remainder 分配（保证合计 = 题数）
+  → 权重高的维度优先分配余数
+  → 各维度独立乱序抽题
+  → 最终 shuffle 后返回
+```
+
+### 权限解析链路
+```
+用户 → TenantMember.role (SUPER_ADMIN/TENANT_ADMIN/USER)
+  → 通过 baseRole 映射到 Role 实体
+  → RolePermission 表给出权限集合
+  → 遗留: user.isAdmin = true → 全部权限
+```
+
+---
+
+## 🧪 测试
+
+项目根目录下包含 Playwright 测试脚本：
+
+| 命令 | 覆盖范围 |
+|---|---|
+| `node test-systematic.mjs` | **142 项** — 认证/CRUD/RBAC/边界/UI/用户故事 |
+| `node test-e2e-full.mjs` | 94 项 — 全角色 E2E 测试 |
+| `node test-user-lifecycle.mjs` | 42 项 — 用户生命周期+异常边界 |
+| `node exam-organizer.mjs` | 考试场景：创建考生→考核→查看结果 |
+| `node test-permission-flow.mjs` | 三层角色权限边界验证 |
+| `node test-multiround.mjs` | 考核多轮对话测试 |
+
+---
+
+## 📁 项目结构
+
+```
+AuraK/
+├── web/                          # React 前端
+│   ├── components/
+│   │   ├── views/
+│   │   │   ├── SettingsView.tsx          # 系统设置（用户/模型/租户）
+│   │   │   ├── PermissionSettingsView.tsx # RBAC 权限矩阵编辑
+│   │   │   ├── AssessmentView.tsx        # 考核流程 UI
+│   │   │   └── AssessmentTemplateManager.tsx  # 模板编辑器
+│   │   ├── PermissionGate.tsx    # 组件级权限门控
+│   │   └── LoginPage.tsx         # 登录页
 │   ├── src/
-│   │   ├── tenant/         # 多租户管理
-│   │   ├── assessment/     # 合才评价 (LangGraph)
-│   │   ├── feishu/         # 飞书集成
-│   │   ├── knowledge-group/# 知识库分组
-│   │   └── chat/           # RAG 核心逻辑
-├── docs/                   # 技术方案与 API 文档
-└── docker-compose.yml      # 全栈部署配置
+│   │   ├── contexts/AuthContext.tsx     # 认证状态管理
+│   │   ├── hooks/usePermissions.ts     # 权限 Hook
+│   │   ├── pages/workspace/            # 路由页面
+│   │   └── services/                   # API 客户端
+│   └── index.tsx                       # 路由入口
+├── server/                       # NestJS 后端
+│   ├── src/
+│   │   ├── auth/permission/      # RBAC 权限模块
+│   │   ├── assessment/           # 考核评估子系统
+│   │   ├── user/                 # 用户 CRUD
+│   │   ├── tenant/               # 多租户
+│   │   ├── admin/                # 管理端 API
+│   │   └── super-admin/          # 超级管理员 API
+│   └── dist/                     # 编译输出
+├── docker-compose.yml
+├── CLAUDE.md                     # AI 工作指南
+└── test-*.mjs                    # Playwright 测试脚本
 ```

 ---

-## 📄 开源协议
-本项目采用 MIT 协议。详见 [LICENSE](LICENSE) 文件。
+## 🔧 配置参考
+
+### 环境变量（server/.env）
+
+| 变量 | 默认值 | 说明 |
+|---|---|---|
+| PORT | 3001 | API 端口 |
+| DATABASE_PATH | ./data/metadata.db | SQLite 路径 |
+| ELASTICSEARCH_HOST | http://127.0.0.1:9200 | Elasticsearch |
+| JWT_SECRET | （必填） | JWT 签名密钥 |
+| UPLOAD_FILE_PATH | ./uploads | 文件存储路径 |
+| MAX_FILE_SIZE | 104857600 | 上传大小限制（100MB） |
+
+---
+
+## 📄 许可
+
+详见 [LICENSE](LICENSE) 文件。