# 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) 文件。