aurak/README.md

# AuraK — Enterprise AI Knowledge Base & Talent Assessment Platform

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

### 🔐 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)

---

## 🚀 Quick Start

### Prerequisites
- 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

# 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
```

### 2. 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

```
路径: 系统设置 → 用户管理
```
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/
│   │   ├── 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
```

---

## 🔧 Configuration Reference

### 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 |

---

## 📄 License

See [LICENSE](LICENSE) file.