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,225 +1,398 @@
-# CLAUDE.md
+# AuraK — AI 工作指南

-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+> 本文件指导 AI 助手（Claude Code 等）如何理解和使用此仓库。
+> 项目：AuraK — 企业级多租户 AI 知识库与人才评价平台

-## Project Overview
+---

-Simple Knowledge Base is a full-stack RAG (Retrieval-Augmented Generation) Q&A system built with React 19 + NestJS. It's a monorepo with Japanese/Chinese documentation but English code.
+## 一、项目全景

-**Key Features:**
- Multi-model support (OpenAI-compatible APIs + Google Gemini native SDK)
- Dual processing modes: Fast (Tika text-only) and High-precision (Vision pipeline)
- User isolation with JWT authentication and per-user knowledge bases
- Hybrid search (vector + keyword) with Elasticsearch
- Multi-language interface (Japanese, Chinese, English)
- Streaming responses via Server-Sent Events (SSE)
+```
+AuraK/
+├── web/                    # React 19 + Vite 前端 (端口 13001)
+│   ├── components/         # UI 组件（含 views/ 目录下的主要页面）
+│   ├── contexts/           # AuthContext / LanguageContext / ConfirmContext
+│   ├── services/           # API 客户端（apiClient.ts + 各服务）
+│   ├── hooks/              # usePermissions 等自定义 Hook
+│   └── src/pages/          # 路由页面（薄壳，委托给 components/views）
+├── server/                 # NestJS 后端 (端口 3001)
+│   ├── src/auth/           # 认证（JWT/API Key）+ 权限（RBAC）
+│   │   └── permission/     # Permission/Role 实体 + Service + Guard
+│   ├── src/assessment/     # 考核评估子系统（最复杂）
+│   ├── src/tenant/         # 多租户 + 租户成员管理
+│   └── src/user/           # 用户 CRUD
+├── docs/plans/             # 设计文档和计划
+├── test-*.mjs              # Playwright 测试脚本（项目根目录）
+└── docker-compose.yml      # 基础设施（Elasticsearch, Tika, LibreOffice）
+```

-## Development Setup
+### 核心技术栈

-### Prerequisites
- Node.js 18+
- Yarn
- Docker & Docker Compose
+| 层 | 技术 |
+|---|---|
+| 前端 | React 19, TypeScript, Vite 6, Tailwind CSS v4, Framer Motion, Lucide icons |
+| 后端 | NestJS 11, TypeORM, SQLite (better-sqlite3), LangChain/LangGraph |
+| 搜索 | Elasticsearch 9（向量+全文混合检索）|
+| 认证 | JWT + API Key 双机制 |
+| 部署 | Docker Compose（Nginx 反向代理）|
+
+---
+
+## 二、系统架构
+
+### 2.1 前端路由
+
+| 路径 | 组件 | 说明 |
+|---|---|---|
+| `/login` | LoginPage | 公开 |
+| `/` | OverviewPage | 工作台首页 |
+| `/chat` | ChatPage | AI 对话 |
+| `/assessment` | AssessmentPage | 考核评估 |
+| `/assessment-stats` | AssessmentStatsView | 评估统计 |
+| `/question-banks` | QuestionBankView | 题库管理 |
+| `/settings` | SettingsPage | 系统设置 |
+
+### 2.2 后端模块
+
+app.module.ts 注册了 27 个模块，核心模块：
+
+- **AuthModule** — 认证（JWT/API Key 双策略）
+- **PermissionModule** — RBAC 权限（Role/RolePermission 实体 + PermissionService + PermissionsGuard）
+- **UserModule** — 用户 CRUD
+- **TenantModule** — 多租户（全局模块）
+- **AssessmentModule** — 考核评估（最复杂，含会话/出题/评分/证书）
+- **AdminModule / SuperAdminModule** — 管理端 API
+- **KnowledgeBaseModule** — 知识库索引和检索
+- **ModelConfigModule** — AI 模型配置
+
+### 2.3 认证流程
+
+```
+密码登录:
+  POST /api/auth/login (username, password)
+  → LocalAuthGuard → JwtService.sign(payload) → { access_token, user }
+
+获取 API Key:
+  GET /api/users/api-key (Authorization: Bearer <JWT>)
+  → 返回 kb_xxxxxxxx...（存前端 localStorage）
+
+后续所有请求:
+  Headers: { x-api-key: <apiKey>, x-tenant-id: <tenantId> }
+
+全局守卫: CombinedAuthGuard（APP_GUARD 注册）
+  → 先尝试 API Key 认证，失败则回退 JWT
+  → @Public() 装饰器跳过认证
+```
+
+---
+
+## 三、权限系统（RBAC）核心
+
+### 3.1 三层角色
+
+| 角色 | 权限数 | 能做什么 |
+|---|---|---|
+| **SUPER_ADMIN** | 26 项 | 全部权限：用户/租户/知识库/考核/模型/插件/设置 |
+| **TENANT_ADMIN** | 21 项 | 管理本租户用户和资源；不能跨租户/删用户/改系统设置 |
+| **USER** | 5 项 | kb:view/create/edit, assess:view, plugin:view |
+
+### 3.2 权限常量定义
+
+位于 `server/src/auth/permission/permission.constants.ts`
+
+```typescript
+// 用户管理: 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
+```
+
+### 3.3 权限守卫流水线
+
+```
+CombinedAuthGuard (认证) → 已有，全局注册
+  → RolesGuard (角色门控) → @Roles(SUPER_ADMIN, TENANT_ADMIN)
+     → PermissionsGuard (权限门控) → @Permission('user:view')
+```
+
+**系统角色保护**: 系统角色（isSystem=true）的权限不可通过 API 修改。
+
+### 3.4 权限解析链路
+
+```
+PermissionService.getUserPermissions(userId, tenantId)
+  → 1. 如果 user.isAdmin === true，返回全部 SUPER_ADMIN 权限
+  → 2. 查找 TenantMember(userId, tenantId)
+  → 3. TenantMember.role → Role.baseRole → RolePermission.permissionKey
+```
+
+---
+
+## 四、考核评估系统
+
+### 4.1 数据模型
+
+```
+AssessmentTemplate (模板)
+  └── question_count, dimensions[{name, label, weight}], passingScore
+      └── QuestionBank (题库，一对一关联模板)
+          └── QuestionBankItem (题目)
+              ├── questionType: SHORT_ANSWER / MULTIPLE_CHOICE / TRUE_FALSE
+              └── dimension: PROMPT / LLM / IDE / DEV_PATTERN / WORK_CAPABILITY
+
+AssessmentSession (会话)
+  ├── questions_json (缓存的题目列表)
+  ├── messages (对话历史)
+  ├── scores / dimensionScores
+  └── finalReport (AI 生成的报告)
+
+AssessmentCertificate (证书)
+  └── level: Novice / Proficient / Advanced / Expert
+```
+
+### 4.2 出题算法
+
+`selectQuestions()` 在 `question-bank.service.ts`:
+
+```typescript
+// 按维度权重公平分配（floor + remainder，保证总和 = count）
+// 20题模板: PROMPT(30%)→6题, LLM(30%)→6题, IDE(20%)→4题, DEV_PATTERN(20%)→4题
+```
+
+### 4.3 模板配置（数据库 `assessment_templates` 表）
+
+```typescript
+// dimensions 字段是 JSON 数组，前端「测评模板」页面可编辑
+dimensions = [
+  { name: "PROMPT",  label: "Prompt Engineering",  weight: 30 },
+  { name: "LLM",     label: "LLM Knowledge",       weight: 30 },
+  { name: "IDE",     label: "IDE Proficiency",     weight: 20 },
+  { name: "DEV_PATTERN", label: "Dev Patterns",    weight: 20 },
+]
+```
+
+---
+
+## 五、测试脚本
+
+所有 Playwright 测试位于项目根目录：
+
+| 脚本 | 用途 | 运行命令 |
+|---|---|---|
+| `test-systematic.mjs` | **142 项系统性测试**（身份/CRUD/权限/边界/UI） | `node test-systematic.mjs` |
+| `test-e2e-full.mjs` | 94 项全角色 E2E 测试 | `node test-e2e-full.mjs` |
+| `test-user-lifecycle.mjs` | 42 项用户生命周期测试 | `node test-user-lifecycle.mjs` |
+| `test-multiround.mjs` | 考核多轮对话测试 | `node test-multiround.mjs` |
+| `test-permission-flow.mjs` | 三层角色权限验证 | `node test-permission-flow.mjs` |
+| `test-question-distribution.mjs` | 出题分布验证 | `node test-question-distribution.mjs` |
+| `exam-organizer.mjs` | 考试组织者场景（创建考生+考核+查看结果） | `node exam-organizer.mjs` |
+
+---
+
+## 六、开发指南
+
+### 6.1 启动项目

-### Initial Setup
 ```bash
-# Install dependencies
-yarn install
+# 后端
+cd server && node dist/main.js          # 生产模式（需要先 nest build）
+cd server && yarn start:dev             # 开发模式（热加载）

-# Start infrastructure services
+# 前端
+cd web && npx vite --port 13001         # 开发模式
+cd web && npx vite build                # 编译
+
+# 基础设施（需要 Docker）
 docker-compose up -d elasticsearch tika libreoffice
-
-# Configure environment
-cp server/.env.sample server/.env
-# Edit server/.env with API keys and configuration
 ```

-### Development Commands
+### 6.2 运行测试
+
 ```bash
-# Start both frontend and backend in development mode
-yarn dev
-
-# Frontend only (port 13001)
-cd web && yarn dev
-
-# Backend only (port 3001)
-cd server && yarn start:dev
-
-# Run tests
-cd server && yarn test
-cd server && yarn test:e2e
-
-# Lint and format
-cd server && yarn lint
-cd server && yarn format
+cd /d/AuraK && node test-systematic.mjs    # 142 项全面测试
 ```

-### Docker Services
- **Elasticsearch**: 9200 (vector storage)
- **Apache Tika**: 9998 (document text extraction)
- **LibreOffice Server**: 8100 (document conversion)
- **Backend API**: 3001
- **Frontend**: 13001 (dev), 80/443 (production via nginx)
+### 6.3 重启服务

-## Architecture
-
-### Project Structure
-```
-simple-kb/
-├── web/                    # React frontend (Vite)
-│   ├── components/         # UI components (ChatInterface, ConfigPanel, etc.)
-│   ├── contexts/          # React Context providers
-│   ├── services/          # API client services
-│   └── utils/             # Utility functions
-├── server/                # NestJS backend
-│   ├── src/
-│   │   ├── ai/            # AI services (embedding, etc.)
-│   │   ├── api/           # API module
-│   │   ├── auth/          # JWT authentication
-│   │   ├── chat/          # Chat/RAG module
-│   │   ├── elasticsearch/ # Elasticsearch integration
-│   │   ├── import-task/   # Import task management
-│   │   ├── knowledge-base/# Knowledge base management
-│   │   ├── libreoffice/   # LibreOffice integration
-│   │   ├── model-config/  # Model configuration management
-│   │   ├── vision/        # Vision model integration
-│   │   └── vision-pipeline/# Vision pipeline orchestration
-│   ├── data/              # SQLite database storage
-│   ├── uploads/           # Uploaded files storage
-│   └── temp/              # Temporary files
-├── docs/                  # Comprehensive documentation (Japanese/Chinese)
-├── nginx/                 # Nginx configuration
-├── libreoffice-server/    # LibreOffice conversion service (Python/FastAPI)
-└── docker-compose.yml     # Docker orchestration
-```
-
-### Key Architectural Concepts
-
-**Dual Processing Modes:**
-1. **Fast Mode**: Apache Tika for text-only extraction (quick, no API cost)
-2. **High-Precision Mode**: Vision Pipeline (LibreOffice → PDF → Images → Vision Model) for mixed image/text documents (slower, incurs API costs)
-
-**Multi-Model Support:**
- OpenAI-compatible APIs (OpenAI, DeepSeek, Claude, etc.)
- Google Gemini native SDK
- Configurable LLM, Embedding, and Rerank models
-
-**RAG System:**
- Hybrid search (vector + keyword) with Elasticsearch
- Streaming responses via Server-Sent Events (SSE)
- Source citation and similarity scoring
- Chunk configuration (size, overlap)
-
-## Code Standards
-
-### Language Requirements
- **Code comments must be in English**
- **Log messages must be in English**
- **Error messages must support internationalization** to enable multi-language frontend interface
- **API response messages must support internationalization** to enable multi-language frontend interface
- Interface supports Japanese, Chinese, and English
-
-### Testing
- Backend uses Jest for unit and e2e tests
- Frontend currently has no test framework configured
- Run tests: `cd server && yarn test` or `yarn test:e2e`
-
-### Code Quality
- ESLint and Prettier configured for backend
- Format code: `cd server && yarn format`
- Lint code: `cd server && yarn lint`
-
-## Common Development Tasks
-
-### Adding a New API Endpoint
-1. Create controller in appropriate module under `server/src/`
-2. Add service methods with English comments
-3. Update DTOs and validation
-4. Add tests in `*.spec.ts` files
-
-### Adding a New Frontend Component
-1. Create component in `web/components/`
-2. Add TypeScript interfaces in `web/types.ts`
-3. Use Tailwind CSS for styling
-4. Connect to backend services in `web/services/`
-
-### Debugging
- Backend logs are in Chinese
- Check Elasticsearch: `curl http://localhost:9200/_cat/indices`
- Check Tika: `curl http://localhost:9998/tika`
- Check LibreOffice: `curl http://localhost:8100/health`
-
-## Environment Configuration
-
-Key environment variables (`server/.env`):
- `OPENAI_API_KEY`: OpenAI-compatible API key
- `GEMINI_API_KEY`: Google Gemini API key
- `ELASTICSEARCH_HOST`: Elasticsearch URL (default: http://localhost:9200)
- `TIKA_HOST`: Apache Tika URL (default: http://localhost:9998)
- `LIBREOFFICE_URL`: LibreOffice server URL (default: http://localhost:8100)
- `JWT_SECRET`: JWT signing secret
-
-## Deployment
-
-### Development
 ```bash
-docker-compose up -d elasticsearch tika libreoffice
-yarn dev
+taskkill //F //IM node.exe 2>/dev/null     # 杀所有 Node 进程
+cd /d/AuraK/server && node dist/main.js &  # 启动后端
+cd /d/AuraK/web && npx vite --port 13001 & # 启动前端
 ```

-### Production
+### 6.4 数据库管理
+
 ```bash
-docker-compose up -d  # Builds and starts all services
+# SQLite 文件路径
+server/data/metadata.db
+
+# 直接查询
+cd /d/AuraK && node -e "
+const sqlite3 = require('better-sqlite3');
+const db = new sqlite3('server/data/metadata.db');
+db.prepare('SELECT * FROM users').all();
+db.close();
+"
 ```

-### Ports in Production
- Frontend: 80/443 (via nginx)
- Backend API: 3001 (proxied through nginx)
- Elasticsearch: 9200
- Tika: 9998
- LibreOffice: 8100
+### 6.5 常见问题

-## AI 工作流指令
+- **端口占用**: `netstat -ano | grep 3001` → `taskkill //F //PID <pid>`
+- **后端启动失败**: 确保从 `server/` 目录启动以加载 .env
+- **Windows 杀进程**: 用 `taskkill //F //PID`，`kill` 不可靠
+- **Dist 目录修改**: `server/dist/` 下的 .js 直接修改即可生效（无需 nest build）

-本项目已安装 **gstack**（54 个技能）和 **Superpowers**（14 个技能）。请按以下规则协调使用：
+---

-### 自动触发规则
-当用户的意图匹配以下场景时，**自动调用对应的 gstack skill**（使用 Skill 工具），并在调用前向用户说明启动了哪个技能：
+## 七、代码规范

- 用户讨论需求、想法、产品方向 → 调用 `office-hours` skill，说"正在启动 **office-hours**（产品策略顾问）..."
- 用户讨论功能范围、优先级 → 调用 `plan-ceo-review` skill，说"正在启动 **plan-ceo-review**（战略评审）..."
- 用户讨论技术方案、架构设计 → 调用 `plan-eng-review` skill，说"正在启动 **plan-eng-review**（架构评审）..."
- 用户要求审查代码 → 调用 `review` skill，说"正在启动 **review**（代码审查）..."
- 用户要求测试/QA → 调用 `qa` skill，说"正在启动 **qa**（自动化测试）..."
- 用户要求安全审查 → 调用 `cso` skill，说"正在启动 **cso**（安全审计）..."
- 用户要求发布/发版 → 调用 `ship` skill，说"正在启动 **ship**（发布流程）..."
- 用户报告 bug 需要调试 → 调用 `investigate` skill，说"正在启动 **investigate**（系统化调试）..."
+### 7.1 TypeScript 模式

-### Superpowers 保留自动触发
-Superpowers 的技能（brainstorming、test-driven-development、systematic-debugging 等）继续保持原有自动触发机制，不做干预。
+- **实体定义**: TypeORM `@Entity` + `@Column` + 枚举类型
+- **控制器**: `@Controller` + `@UseGuards(CombinedAuthGuard)` + `@Permission()`
+- **服务**: `@Injectable` 类，方法名用动词开头
+- **前端组件**: React FC + TypeScript interface props

-### 通知机制
-每次自动调用 gstack skill 时，必须明确告知用户正在启动哪个技能及其作用。
+### 7.2 权限装饰器使用

-## Troubleshooting
+```typescript
+// 后端 API — 在控制器方法上标注所需权限
+@Post()
+@UseGuards(PermissionsGuard)
+@Permission('user:create')
+async createUser(@Request() req, @Body() body: CreateUserDto) { ... }

-### Common Issues
-1. **Elasticsearch not starting**: Check memory limits in docker-compose.yml
-2. **File upload failures**: Ensure `uploads/` and `temp/` directories exist with proper permissions
-3. **Vision pipeline errors**: Verify LibreOffice server is running and accessible
-4. **API key errors**: Check environment variables in `server/.env`
+// 前端 — 用 PermissionGate 组件或 usePermissions hook
+<PermissionGate permission="user:create">
+  <Button>创建用户</Button>
+</PermissionGate>

-### Database Management
- SQLite database: `server/data/metadata.db`
- Elasticsearch indices: Managed automatically by the application
- To reset: Delete `server/data/metadata.db` and Elasticsearch data volume
+const { hasPermission } = usePermissions();
+{hasPermission('user:view') && <UserList />}
+```

-## Documentation
+### 7.3 通用 React 约定

- **README.md**: Project overview in Japanese
- **docs/**: Comprehensive documentation (mostly Japanese/Chinese)
- **DESIGN.md**: System architecture and design
- **API.md**: API reference
- **DEVELOPMENT_STANDARDS.md**: Mandates English comments/logs and internationalized messages
+- 使用 `cn()` 工具函数（tailwind-merge）合并 className
+- 图标用 `lucide-react`
+- 动画用 `framer-motion`
+- API 调用用 `apiClient` 或原生 `fetch`
+- 模态框用 `createPortal` + `AnimatePresence`

-When modifying code, always add English comments and logs as required by development standards. Error and UI messages must be properly internationalized. The project has extensive existing documentation in Japanese/Chinese - refer to `docs/` directory for detailed technical information.
+---
+
+## 八、Playwright 测试指南
+
+### 8.1 测试模式
+
+```javascript
+import { chromium } from 'playwright';
+const browser = await chromium.launch({ headless: true });
+const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
+
+// 模拟 API 调用
+const r = await fetch(`${API}/api/auth/login`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ username, password }),
+});
+```
+
+### 8.2 React 受控输入框操作（关键）⚠️
+
+React 的受控 input/textarea 依赖 native setter 触发 `onChange`。**不要用 `type()` 或 `fill()`**，应使用：
+
+```javascript
+await page.evaluate((text) => {
+  const ta = document.querySelector('textarea');
+  if (!ta) return;
+  const setter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')?.set;
+  setter?.call(ta, text);
+  ta.dispatchEvent(new Event('input', { bubbles: true }));
+}, '要输入的文字');
+```
+
+### 8.3 等待按钮可用
+
+```javascript
+await page.waitForFunction(() => {
+  const btn = document.querySelector('button:has(svg.lucide-send)');
+  return btn && !btn.disabled;
+}, { timeout: 10000 });
+```
+
+### 8.4 等待 spinner 消失
+
+```javascript
+await page.waitForFunction(() => !document.querySelector('.animate-spin'), { timeout: 60000 });
+```
+
+### 8.5 检测考核题型
+
+```javascript
+const state = await page.evaluate(() => {
+  // 选择题选项按钮
+  const optionBtns = Array.from(document.querySelectorAll('button.w-full.text-left.px-5.py-4'))
+    .filter(b => !b.textContent?.includes('确认答案'));
+  // 简答题 textarea
+  const ta = document.querySelector('textarea');
+  return { choiceCount: optionBtns.length, hasTextarea: ta?.offsetParent !== null };
+});
+```
+
+---
+
+## 九、部署配置
+
+### 端口
+
+| 服务 | 端口 |
+|---|---|
+| 前端（开发） | 13001 |
+| 前端（生产/Nginx） | 80/443 |
+| 后端 API | 3001 |
+| Elasticsearch | 9200 |
+| Apache Tika | 9998 |
+| LibreOffice | 8100 |
+
+### 环境变量
+
+`server/.env` 关键配置：
+
+```
+PORT=3001
+DATABASE_PATH=./data/metadata.db
+ELASTICSEARCH_HOST=http://127.0.0.1:9200
+JWT_SECRET=your-secret
+```
+
+---
+
+## 十、快速参考命令
+
+```bash
+# 启动
+cd /d/AuraK/server && node dist/main.js &
+cd /d/AuraK/web && npx vite --port 13001 &
+
+# 后端编译
+cd /d/AuraK/server && npx nest build
+
+# 运行测试
+cd /d/AuraK && node test-systematic.mjs
+
+# 数据库查询
+cd /d/AuraK && node -e "
+const s=require('better-sqlite3');
+const d=new s('server/data/metadata.db');
+const r=d.prepare('...').all(); console.log(r); d.close();"
+
+# 清理端口
+taskkill //F //IM node.exe 2>/dev/null
+
+# 前端编译
+cd /d/AuraK/web && npx vite build
+```
@@ -1,207 +1,289 @@
-# AuraK
+# AuraK — Enterprise AI Knowledge Base & Talent Assessment Platform

-AuraK is a multi-tenant intelligent AI knowledge base platform. Built with React + NestJS, it's a full-stack RAG (Retrieval-Augmented Generation) system with external API support, RBAC, and tenant isolation.
+AuraK is a multi-tenant intelligent platform built with **React 19 + NestJS**, combining RAG-powered knowledge management, interactive AI assessment, and enterprise-grade RBAC permission system.
+
+---

 ## ✨ Features

- 🔐 **User System**: Complete user registration, login, and permission management
- 🤖 **Multi-Model Support**: OpenAI-compatible interfaces + Google Gemini native support
- 📚 **Intelligent Knowledge Base**: Document upload, chunking, vectorization, hybrid search
- 💬 **Streaming Chat**: Real-time display of processing status and generated content
- 🔍 **Citation Tracking**: Clear display of source documents and related segments for answers
- 🌍 **Multi-Language Support**: Japanese, Chinese, and English for interface and AI responses
- 👁️ **Vision Capabilities**: Supports multimodal models for image processing
- ⚙️ **Flexible Configuration**: User-specific API keys and inference parameter customization
- 🎯 **Dual-Mode Processing**: Fast mode (Tika) + High-precision mode (Vision Pipeline)
- 💰 **Cost Management**: User quota management and cost estimation
+### 🔐 Enterprise Multi-Tenant & RBAC
+- **Tenant Isolation** — Strict data isolation between tenants with independent member management
+- **RBAC Permissions** — 3-tier roles (SUPER_ADMIN / TENANT_ADMIN / USER) with 26 granular permissions across 7 categories
+- **Custom Roles** — Create and assign custom roles with specific permission sets
+- **Permission Matrix UI** — Visual permission matrix editor in Settings panel
+- **Role Auto-Seed** — Default roles with permission sets created on startup
+
+### 📊 Interactive AI Assessment
+- **AI-Powered Exams** — Automated question generation, grading, and follow-up questioning via LangGraph workflow
+- **Dual Question Sources** — Pre-built question banks + AI generation on-the-fly
+- **Multi-Dimension Scoring** — Weighted scoring across customizable dimensions (Prompt, LLM, IDE, Dev Patterns, Work Capability)
+- **Certificate System** — Auto-generated certificates with score breakdown by dimension
+- **Adaptable Templates** — Configure question count, dimensions, time limits, passing scores per template
+- **Non-Technical Mode** — Separate templates for non-technical staff (exclude IDE/Dev Patterns)
+
+**Exam Flow:** Admin creates accounts → Candidates login → Take assessment → AI grades + issues certificate → View history
+
+### 📚 Intelligent Knowledge Base
+- **Dual Processing Modes** — Fast mode (Tika text extraction) + High-precision mode (Vision Pipeline for image/PDF)
+- **Hybrid Search** — BM25 keyword + vector embedding with Elasticsearch
+- **Multi-Format Support** — PDF, Word, PPT, Excel, images
+- **Hierarchical Groups** — Folder-style knowledge group management
+
+### 🤖 Multi-Model AI Engine
+- OpenAI-compatible APIs (OpenAI, DeepSeek, Claude, etc.)
+- Google Gemini native SDK
+- Configurable LLM / Embedding / Rerank / Vision models
+
+### 🌐 Additional Features
+- Streaming SSE responses
+- Multi-language (Chinese, English, Japanese)
+- Feishu (Lark) bot integration
+- Podcast generation from documents
+- Notebook/shared notes system
+- User quota management
+
+---

 ## 🏗️ Tech Stack

 ### Frontend
-
- **Framework**: React 19 + TypeScript + Vite
- **Styling**: Tailwind CSS
- **Icons**: Lucide React
- **State Management**: React Context
+- **Framework:** React 19 + TypeScript + Vite 6
+- **Styling:** Tailwind CSS v4 + custom design system
+- **Icons:** Lucide React
+- **State:** React Context
+- **UI Components:** Framer Motion, react-router-dom v7

 ### Backend
+- **Framework:** NestJS 11 + TypeScript
+- **AI Engine:** LangChain + LangGraph (assessment workflow)
+- **Database:** SQLite (better-sqlite3, metadata) + Elasticsearch 9 (vector + full-text)
+- **Auth:** JWT + API Key dual mechanism
+- **Document Processing:** Apache Tika + Vision Pipeline + LibreOffice

- **Framework**: NestJS + TypeScript
- **AI Framework**: LangChain
- **Database**: SQLite (metadata) + Elasticsearch (vector storage)
- **File Processing**: Apache Tika + Vision Pipeline
- **Authentication**: JWT
- **Document Conversion**: LibreOffice + ImageMagick
+### Infrastructure
+- Docker Compose (Elasticsearch, Tika, LibreOffice)
+- Nginx reverse proxy (production)

-## 🏢 Internal Network Deployment
-
-This system supports deployment in internal networks. Main modifications include:
-
- **External Resources**: KaTeX CSS moved from external CDN to local resources
- **AI Models**: Supports configuring internal AI model services without external API access
- **Build Configuration**: Dockerfiles can be configured to use internal image registries
-
-See [Internal Deployment Guide](INTERNAL_DEPLOYMENT_GUIDE.md) for detailed configuration instructions.
+---

 ## 🚀 Quick Start

 ### Prerequisites
-
- Node.js 18+
- Yarn
+- Node.js 18+, Yarn
 - Docker & Docker Compose

-### 1. Clone the Project
-
-```bash
-git clone <repository-url>
-cd simple-kb
-```
-
-### 2. Install Dependencies
+### 1. Install & Start

 ```bash
+# Clone and install
+git clone <repo-url>
+cd AuraK
 yarn install
-```

-### 3. Start Basic Services
-
-```bash
-docker-compose up -d elasticsearch tika libreoffice
-```
-
-### 4. Configure Environment Variables
-
-```bash
-# Backend environment setup
+# Configuration
 cp server/.env.sample server/.env
-# Edit server/.env file (set API keys, etc.)
+# Edit server/.env — set JWT_SECRET, API keys

-# Frontend environment setup
-cp web/.env.example web/.env
-# Edit web/.env file (modify frontend settings as needed)
+# Start infrastructure (optional — AI features need Elasticsearch)
+docker-compose up -d elasticsearch tika libreoffice
+
+# Start development servers
+yarn dev
+# Frontend: http://localhost:13001
+# Backend:  http://localhost:3001
 ```

-See the comments in `server/.env.sample` and `web/.env.example` for detailed configuration.
+### 2. Default Login
+```
+Username: admin
+Password: admin123
+```

-### 5. Start Development Server
+### 3. Quick Start (without Docker)

 ```bash
-yarn dev
+# Start backend (production mode)
+cd server && node dist/main.js &
+
+# Start frontend
+cd web && npx vite --port 13001 &
 ```

-Access http://localhost:5173 to get started!
+---

 ## 📖 User Guide

-### 1. User Registration/Login
-
- Account registration is required for first-time use.
- Each user has their own independent knowledge base and model settings.
-
-### 2. AI Model Configuration
-
- Add AI models from "Model Management".
- Supports OpenAI, DeepSeek, Claude and other compatible interfaces.
- Supports Google Gemini native interface.
- Configure LLM, Embedding, and Rerank models.
-
-### 3. Document Upload
-
- Supports various formats: PDF, Word, PPT, Excel, etc.
- Choose between Fast mode (text-only) or High-precision mode (image + text mixed).
- Adjustable chunk size and overlap for documents.
- Select embedding model for vectorization.
-
-### 4. Start Intelligent Q&A
-
- Ask questions based on uploaded documents.
- View search and generation process in real-time.
- Check answer sources and related document fragments.
-
-## 🔧 Configuration Guide
-
-### Model Settings
-
- **LLM Model**: Used for dialogue generation (e.g., GPT-4, Gemini-1.5-Pro)
- **Embedding Model**: Used for document vectorization (e.g., text-embedding-3-small)
- **Rerank Model**: Used for re-ranking search results (optional)
-
-### Inference Parameters
-
- **Temperature**: Controls answer randomness (0-1)
- **Max Tokens**: Maximum output length
- **Top K**: Number of document segments to search
- **Similarity Threshold**: Filters low-relevance content
-
-## 📁 Project Structure
+### System Setup & User Management

 ```
-simple-kb/
-├── web/                 # Frontend application
-│   ├── components/      # React components
-│   ├── services/        # API services
-│   ├── contexts/        # React Context
-│   └── utils/          # Utility functions
-├── server/             # Backend application
+路径: 系统设置 → 用户管理
+```
+1. **Create Users** — Add users with username, password, display name
+2. **Assign Roles** — Click edit on any user → select USER / TENANT_ADMIN / SUPER_ADMIN
+3. **Role Preview** — Each role shows its permission count
+4. **Bulk Import/Export** — XLSX import and export
+
+### Permission Management
+
+```
+路径: 系统设置 → 权限管理
+```
+1. **Role List** — Left panel shows all roles (SUPER_ADMIN, TENANT_ADMIN, USER + custom)
+2. **Permission Matrix** — Click a role → toggle individual permissions
+3. **Custom Roles** — Create role → set permissions → assign to users
+4. **System Role Protection** — Built-in roles cannot be modified
+
+### Assessment Setup
+
+```
+路径: 系统设置 → 测评模板
+```
+1. **Create Template** — Set name, question count, passing score, time limits
+2. **Configure Dimensions** — Add/remove dimensions, set weights (e.g., PROMPT:30%, LLM:30%, IDE:20%, DEV_PATTERN:20%)
+3. **Link Question Bank** — Create/attach a question bank with published items
+4. **AI Generation** — If no bank linked, AI generates questions from knowledge base
+
+### Running an Exam
+
+```
+路径: 考核评估 → 选择模板 → 开始专业评估
+```
+
+**For Organizers (Admin):**
+1. Go to Settings → User Management → Create student accounts
+2. Tell students their credentials
+
+**For Candidates:**
+1. Login with credentials
+2. Go to Assessment → Select template → Start
+3. Answer multiple-choice and short-answer questions
+4. AI may ask follow-up questions (multi-round dialogue)
+5. View results after completion
+
+**Viewing Results:**
+- **History** — Right sidebar on Assessment page shows past attempts
+- **Details** — Click any history entry to see per-question scores
+- **Certificate** — Click "查看证书" to view grade and dimension breakdown
+- **Export** — PDF report and Excel download available
+
+### Tenant Management (SUPER_ADMIN only)
+
+```
+路径: 系统设置 → 租户管理
+```
+- Create/edit/delete tenants with hierarchical parent-child structure
+- Manage tenant members: add users, assign roles (USER / TENANT_ADMIN)
+- Separate knowledge bases and settings per tenant
+- Data isolation: users in Tenant A cannot see Tenant B's data
+
+---
+
+## 🔄 Key System Flows
+
+### Authentication Flow
+```
+Password Login → JWT issued → API Key generated (stored in localStorage)
+  → All subsequent requests via x-api-key header
+  → x-tenant-id header for tenant context
+```
+
+### Question Selection Algorithm
+```
+Template dimensions (e.g., PROMPT:30, LLM:30, IDE:20, DEV_PATTERN:20)
+  → floor + remainder allocation (guarantees sum = question count)
+  → Higher weight dimensions get remainder priority
+  → Each dimension's pool shuffled independently
+  → Final result shuffled before return
+```
+
+### Role → Permission Resolution
+```
+User → TenantMember.role (SUPER_ADMIN/TENANT_ADMIN/USER)
+  → Maps to Role entity via baseRole
+  → RolePermission table gives permission keys
+  → Legacy: user.isAdmin = true → ALL permissions
+```
+
+---
+
+## 🧪 Testing
+
+Playwright test scripts in project root:
+
+| Command | Coverage |
+|---|---|
+| `node test-systematic.mjs` | **142 tests** — auth, CRUD, RBAC, boundary, UI, user stories |
+| `node test-e2e-full.mjs` | 94 tests — full E2E with 3 roles |
+| `node test-user-lifecycle.mjs` | 42 tests — user lifecycle, edge cases |
+| `node exam-organizer.mjs` | Exam scenario: create students → take exam → view results |
+| `node test-permission-flow.mjs` | 3-role permission boundary verification |
+| `node test-multiround.mjs` | Multi-round dialogue in assessments |
+
+---
+
+## 🏗️ Project Structure
+
+```
+AuraK/
+├── web/                          # React frontend
+│   ├── components/
+│   │   ├── views/                # Main page components
+│   │   │   ├── SettingsView.tsx       # System settings (users, models, tenants)
+│   │   │   ├── PermissionSettingsView.tsx  # RBAC permission matrix UI
+│   │   │   ├── AssessmentView.tsx    # Assessment flow UI
+│   │   │   └── AssessmentTemplateManager.tsx  # Template editor
+│   │   ├── PermissionGate.tsx    # Component-level permission gate
+│   │   └── LoginPage.tsx         # Login page
 │   ├── src/
-│   │   ├── auth/       # Authentication module
-│   │   ├── chat/       # Chat module
-│   │   ├── knowledge-base/ # Knowledge base module
-│   │   ├── model-config/   # Model configuration module
-│   │   └── user/       # User module
-│   └── data/           # Data storage
-├── docs/               # Project documentation
-└── docker-compose.yml  # Docker configuration
+│   │   ├── contexts/AuthContext.tsx    # Auth state + tenant switching
+│   │   ├── hooks/usePermissions.ts    # Permissions hook
+│   │   ├── pages/workspace/          # Route pages
+│   │   └── services/                 # API clients
+│   └── index.tsx                 # Entry + routing
+├── server/                       # NestJS backend
+│   ├── src/
+│   │   ├── auth/
+│   │   │   ├── permission/       # RBAC module
+│   │   │   │   ├── permission.constants.ts  # 26 permission definitions
+│   │   │   │   ├── permission.service.ts     # Resolution + seed
+│   │   │   │   ├── permission.guard.ts       # @Permission() guard
+│   │   │   │   ├── role.entity.ts            # Role entity
+│   │   │   │   ├── role-permission.entity.ts # Role ↔ Permission join
+│   │   │   │   ├── role.controller.ts        # Role CRUD API
+│   │   │   │   └── permission.controller.ts  # Permission API
+│   │   │   ├── roles.guard.ts    # @Roles() guard
+│   │   │   └── combined-auth.guard.ts  # Global auth guard
+│   │   ├── assessment/
+│   │   │   ├── services/question-bank.service.ts  # Question selection algorithm
+│   │   │   └── assessment.service.ts     # Session management + grading
+│   │   ├── user/                 # User CRUD + controller
+│   │   ├── tenant/               # Multi-tenant model
+│   │   ├── admin/                # Admin API
+│   │   └── super-admin/          # Super admin API
+│   └── dist/                     # Compiled output
+├── docker-compose.yml
+└── test-*.mjs                    # Playwright test scripts
 ```

-## 📚 Documentation
+---

- [System Design Document](docs/DESIGN.md)
- [Current Implementation Status](docs/CURRENT_IMPLEMENTATION.md)
- [API Documentation](docs/API.md)
- [Deployment Guide](docs/DEPLOYMENT.md)
- [RAG Feature Implementation](docs/rag_complete_implementation.md)
+## 🔧 Configuration Reference

-## 🐳 Docker Deployment
+### Server Environment (server/.env)

-### Development Environment
+| Variable | Default | Purpose |
+|---|---|---|
+| PORT | 3001 | API server port |
+| DATABASE_PATH | ./data/metadata.db | SQLite file location |
+| ELASTICSEARCH_HOST | http://127.0.0.1:9200 | Elasticsearch endpoint |
+| TIKA_HOST | http://127.0.0.1:9998 | Tika text extraction |
+| LIBREOFFICE_URL | http://127.0.0.1:8100 | Document conversion |
+| JWT_SECRET | (required) | JWT signing key |
+| UPLOAD_FILE_PATH | ./uploads | File storage |
+| MAX_FILE_SIZE | 104857600 | Upload limit |

-```bash
-# Start basic services
-docker-compose up -d elasticsearch tika
-
-# Local development
-yarn dev
-```
-
-### Production Environment
-
-```bash
-# Build and start all services
-docker-compose up -d
-```
-
-## 🤝 Contributing
-
-1. Fork the project
-2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
-3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
-4. Push to the branch (`git push origin feature/AmazingFeature`)
-5. Open a Pull Request
+---

 ## 📄 License

-This project is provided under the MIT license. See the [LICENSE](LICENSE) file for details.
-
-## 🙏 Acknowledgments
-
- [LangChain](https://langchain.com/) - AI application development framework
- [NestJS](https://nestjs.com/) - Node.js backend framework
- [React](https://react.dev/) - Frontend UI framework
- [Elasticsearch](https://www.elastic.co/) - Search and analytics engine
- [Apache Tika](https://tika.apache.org/) - Document parsing tool
-
-## 📞 Support
-
-For questions or suggestions, please submit an [Issue](../../issues) or contact the maintainers.
+See [LICENSE](LICENSE) file.
@@ -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) 文件。