Developer
65ede9fcff
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>
279 lines
9.0 KiB
Markdown
279 lines
9.0 KiB
Markdown
# AuraK — 企业级 AI 知识库与人才评价平台
|
||
|
||
AuraK 是基于 **React 19 + NestJS** 构建的多租户智能平台，集 RAG 知识库管理、AI 交互式考核评估、企业级 RBAC 权限管理于一体。
|
||
|
||
---
|
||
|
||
## ✨ 功能特性
|
||
|
||
### 🔐 多租户与权限管理
|
||
- **租户隔离** — 严格的数据隔离，每个租户独立成员管理和配置
|
||
- **RBAC 权限系统** — 三层角色（SUPER_ADMIN / TENANT_ADMIN / USER），26 项细粒度权限，7 大分类
|
||
- **自定义角色** — 创建自定义角色并精准分配权限集
|
||
- **权限矩阵 UI** — 设置页内可视化权限编辑，勾选即生效
|
||
- **自动种子数据** — 首次启动自动创建角色和默认权限
|
||
|
||
### 📊 AI 交互式考核评估
|
||
- **AI 智能出题** — 基于知识库自动生成选择题和简答题，支持多轮追问
|
||
- **题库系统** — 预置题目 + AI 实时生成双来源，支持审核发布流程
|
||
- **多维度加权评分** — 按自定义维度权重（Prompt / LLM / IDE / 开发范式 / 工作能力）计算综合得分
|
||
- **证书系统** — 自动生成等级证书（Novice / Proficient / Advanced / Expert）
|
||
- **灵活模板** — 可配置题数、维度权重、及格分、时间限制
|
||
- **非技术人员模式** — 独立模板排除 IDE 和开发范式，只考核 Prompt 和 LLM 理解
|
||
|
||
**考试流程：** 管理员创建考生账号 → 考生登录 → 参加考核 → AI 自动评分 + 发证 → 查看历史记录
|
||
|
||
### 📚 智能知识库
|
||
- **双处理模式** — 快速模式（Tika 文本提取）+ 高精度模式（Vision Pipeline 图文混合识别）
|
||
- **混合检索** — Elasticsearch BM25 关键词 + 向量检索
|
||
- **多格式支持** — PDF、Word、PPT、Excel、图片等
|
||
- **层级化分组** — 文件夹式知识库分组管理
|
||
|
||
### 🤖 多模型 AI 引擎
|
||
- OpenAI 兼容接口（DeepSeek、Claude 等）
|
||
- Google Gemini 原生 SDK
|
||
- 可配置 LLM / Embedding / Rerank / Vision 模型
|
||
|
||
### 🌐 其他功能
|
||
- SSE 流式响应
|
||
- 多语言界面（中文 / 英文 / 日文）
|
||
- 飞书机器人集成
|
||
- 文档转播客
|
||
- 笔记/共享笔记本
|
||
- 用户配额管理
|
||
|
||
---
|
||
|
||
## 🏗️ 技术架构
|
||
|
||
### 前端
|
||
- **框架：** React 19 + TypeScript + Vite 6
|
||
- **样式：** Tailwind CSS v4 + 统一设计语言（indigo 主题色）
|
||
- **图标：** Lucide React
|
||
- **状态管理：** React Context
|
||
- **动画：** Framer Motion
|
||
|
||
### 后端
|
||
- **框架：** NestJS 11 + TypeScript
|
||
- **AI 引擎：** LangChain + LangGraph（考核工作流）
|
||
- **数据库：** SQLite（元数据） + Elasticsearch 9（向量+全文检索）
|
||
- **认证：** JWT + API Key 双机制
|
||
- **文档处理：** Apache Tika + Vision Pipeline + LibreOffice
|
||
|
||
### 基础设施
|
||
- Docker Compose（Elasticsearch / Tika / LibreOffice）
|
||
- Nginx 反向代理（生产环境）
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 前提条件
|
||
- Node.js 18+, Yarn
|
||
- Docker & Docker Compose
|
||
|
||
### 1. 安装与启动
|
||
|
||
```bash
|
||
# 克隆并安装
|
||
git clone <repo-url>
|
||
cd AuraK
|
||
yarn install
|
||
|
||
# 配置环境变量
|
||
cp server/.env.sample server/.env
|
||
# 编辑 server/.env — 设置 JWT_SECRET、API Key 等
|
||
|
||
# 启动基础设施（可选 — AI 功能需要 Elasticsearch）
|
||
docker-compose up -d elasticsearch tika libreoffice
|
||
|
||
# 启动开发服务器
|
||
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 &
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 使用指南
|
||
|
||
### 系统设置与用户管理
|
||
|
||
```
|
||
路径: 系统设置 → 用户管理
|
||
```
|
||
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/
|
||
│ │ ├── 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 测试脚本
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 配置参考
|
||
|
||
### 环境变量（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) 文件。
|