hangshuo652/aurak
1
0
Fork 1
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: 统一 CLAUDE.md 和 README.md 文档体系

Browse Source 
CLAUDE.md（AI 参考）:
- 4 个 👉 AI 实现参考 标记，AI 可快速定位
- 完整的实体定义（TypeScript 代码块）
- 权限守卫流水线 + 解析链路
- 考核数据模型 + 出题算法伪代码
- API 认证流程 + 关键端点表
- 测试注意事项（React 受控输入/等待策略）
- 人可读用户指南（与 README 一致）

README.md（人可读）:
- 顶部引用 CLAUDE.md — AI 阅读指引
- 功能亮点表格式呈现
- 步骤式操作指南（用户/权限/模板/考试/租户）
- 轻量内容，详细技术参考指向 CLAUDE.md

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Developer
2026-06-09 13:29:28 +08:00
parent 65ede9fcff
commit ebb8fbd298
2 changed files with 520 additions and 508 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+131 -207
View File
@@ -1,90 +1,39 @@
# AuraK — Enterprise AI Knowledge Base & Talent Assessment Platform
# AuraK
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.
Enterprise AI Knowledge Base & Talent Assessment Platform.
> **For AI assistants (Claude Code / OpenCode / Codex / Gemini CLI):** See [CLAUDE.md](CLAUDE.md) for the complete technical reference — all architecture details, permission entities, guard flow, assessment data model, test patterns, and code conventions are documented there.
---
## ✨ Features
### 🔐 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 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
### Infrastructure
- Docker Compose (Elasticsearch, Tika, LibreOffice)
- Nginx reverse proxy (production)
| Area | Highlights |
|---|---|
| **Multi-Tenant** | Strict data isolation, hierarchical org tree, per-tenant settings |
| **RBAC** | 3 tiers (SUPER_ADMIN / TENANT_ADMIN / USER), 26 granular permissions, custom roles, visual permission matrix |
| **AI Assessment** | Auto question generation (MC + short answer), adaptive follow-up dialogue, weighted multi-dimension scoring, certificate system |
| **Knowledge Base** | Dual processing (Fast via Tika / High-Precision via Vision Pipeline), hybrid search (BM25 + vector), multi-format support |
| **AI Engine** | Multi-model (OpenAI-compatible + Gemini), configurable LLM/Embedding/Rerank/Vision, SSE streaming |
| **Feishu Bot** | WebSocket integration, interactive message cards, mobile assessment |
---
## 🚀 Quick Start
### Prerequisites
- Node.js 18+, Yarn
- Docker & Docker Compose
- Node.js 18+, Yarn, Docker & Docker Compose
### 1. Install & Start
```bash
# Clone and install
git clone <repo-url>
cd AuraK
yarn install
# Configuration
cp server/.env.sample server/.env
# Edit server/.env — set JWT_SECRET, API keys
# Edit server/.env — set JWT_SECRET
# Start infrastructure (optional — AI features need Elasticsearch)
# Start infrastructure (optional for basic features)
docker-compose up -d elasticsearch tika libreoffice
# Start development servers
@@ -93,197 +42,172 @@ yarn dev
# Backend: http://localhost:3001
```
### 2. Default Login
### 2. Quick Start (no Docker)
```bash
cd /d/AuraK/server && node dist/main.js &
cd /d/AuraK/web && npx vite --port 13001 &
```
### 3. Default Login
```
Username: admin
Password: admin123
```
### 3. Quick Start (without Docker)
```bash
# Start backend (production mode)
cd server && node dist/main.js &
# Start frontend
cd web && npx vite --port 13001 &
```
---
## 📖 User Guide
### System Setup & User Management
### User Management
```
路径: 系统设置 → 用户管理
Settings → User Management
```
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
| Action | Steps |
|---|---|
| Create user | Fill username, password, display name → Create |
| Edit user | Click Edit icon → Modify info → Select role (USER / TENANT_ADMIN / SUPER_ADMIN) → Save |
| Change password | Click key icon → Enter new password → Confirm |
| Delete user | Click trash icon → Confirm |
| Export/Import | Click Export/Import buttons → XLSX format |
> Role changes take effect immediately — the user does not need to log out and back in.
### Permission Management
```
路径: 系统设置 → 权限管理
Settings → 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. **Left panel** — lists all roles: SUPER_ADMIN, TENANT_ADMIN, USER, and any custom roles
2. **Click a role** — right panel shows the permission matrix organized by category
3. **Toggle permissions** — check/uncheck individual items
4. **Save** — changes take effect immediately
5. **Custom roles** — click "+" to create, set permissions, then assign to users via User Management
> System roles (SUPER_ADMIN, TENANT_ADMIN, USER) are protected — their permissions cannot be modified.
### Assessment Templates
```
路径: 系统设置 → 测评模板
Settings → Assessment Templates
```
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
Two built-in templates:
| Template | Questions | Dimensions | Audience |
|---|---|---|---|
| **Technical** | 20 | PROMPT 30%, LLM 30%, IDE 20%, DEV_PATTERN 20% | Developers, Engineers |
| **Non-Technical** | 10 | PROMPT 50%, LLM 30%, WORK_CAPABILITY 20% | Managers, PMs, Designers |
Dimensions are fully customizable — add/remove, adjust weights, change question count.
### Running an Exam
```
路径: 考核评估 → 选择模板 → 开始专业评估
```
**As an organizer (admin):**
1. Go to `Settings → User Management` → create student accounts
2. Give students their credentials
**For Organizers (Admin):**
1. Go to Settings → User Management → Create student accounts
2. Tell students their credentials
**As a candidate:**
1. Login → go to **Assessment**
2. Select a template → click **Start Assessment**
3. **Multiple choice:** click an option → click Confirm
4. **Short answer:** type your answer in the textarea → click Send
5. The AI may ask follow-up questions — keep answering
6. After all questions, view your score and certificate
**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
**Viewing results:**
- **History** — right sidebar on the Assessment page
- **Details** — click any history entry to see per-question scores
- **Certificate** — click "View Certificate" for level, total score, dimension scores
- **Export** — PDF report and Excel download
### Tenant Management (SUPER_ADMIN only)
```
路径: 系统设置 → 租户管理
Settings → Tenant Management
```
- 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
```
- Manage members: add/remove users, assign roles
- Per-tenant settings (models, knowledge bases, features)
- Data isolation: Tenant A users cannot access Tenant B data
---
## 🧪 Testing
Playwright test scripts in project root:
```bash
# Full system test (142 items)
cd /d/AuraK && node test-systematic.mjs
| 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 |
# Exam organizer scenario (create students → take exam → view results)
cd /d/AuraK && node exam-organizer.mjs
```
All test scripts are in the project root, prefixed with `test-*.mjs`.
---
## 🏗️ Project Structure
## 📁 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/
│ │ ├── 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
├── web/ # React frontend (:13001)
│ ├── components/views/ # Main page views
│ ├── src/contexts/ # Auth / Language contexts
│ ├── src/hooks/ # usePermissions
│ └── src/services/ # API clients
├── server/ # NestJS backend (:3001)
│ ├── src/auth/ # Auth + RBAC permission module
│ │ └── permission/ # Role/Permission entities, service, guard
│ ├── src/assessment/ # Assessment subsystem
│ ├── src/user/ # User CRUD
│ ├── src/tenant/ # Multi-tenant
│ └── src/admin/ # Admin API
├── CLAUDE.md # AI assistant reference
├── README.md # This file
├── README_ZH.md # 中文说明
├── test-*.mjs # Playwright test scripts
└── docker-compose.yml # Infrastructure
```
---
## 🔧 Configuration Reference
## 🏗️ Tech Stack
### Server Environment (server/.env)
| 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 |
| Layer | Technology |
|---|---|
| Frontend | React 19, TypeScript, Vite 6, Tailwind CSS v4, Framer Motion |
| Backend | NestJS 11, TypeORM, LangChain, LangGraph |
| Database | better-sqlite3 (metadata) + Elasticsearch 9 (vector/text search) |
| Auth | JWT + API Key |
| AI | OpenAI-compatible (DeepSeek, Claude) + Google Gemini |
| Infra | Docker Compose (ES, Tika, LibreOffice) + Nginx |
---
## 📄 License
## 🔧 Configuration
See [LICENSE](LICENSE) file.
| Variable | Default | Purpose |
|---|---|---|
| PORT | 3001 | Backend port |
| DATABASE_PATH | ./data/metadata.db | SQLite path |
| ELASTICSEARCH_HOST | http://127.0.0.1:9200 | Search engine |
| JWT_SECRET | (required) | JWT signing secret |
| UPLOAD_FILE_PATH | ./uploads | File storage |
| MAX_FILE_SIZE | 104857600 | Upload limit (100MB) |
---
## 🔗 Related Documents
| Document | Audience | Content |
|---|---|---|
| [CLAUDE.md](CLAUDE.md) | AI assistants + Developers | Full technical reference: architecture, entities, API, permission system, assessment model, testing patterns |
| [README_ZH.md](README_ZH.md) | Chinese-speaking users | Complete Chinese user guide |
| [STARTUP.md](STARTUP.md) | Operators | Startup scripts and environment setup |
| [VERSION.md](VERSION.md) | All | Version history and changelog |