aurak/README_ZH.md

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. 安装与启动

# 克隆并安装
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 快速启动

# 启动后端
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 文件。