Developer
ebb8fbd298
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>
214 lines
6.9 KiB
Markdown
214 lines
6.9 KiB
Markdown
# AuraK
|
|
|
|
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
|
|
|
|
| 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
|
|
|
|
### 1. Install & Start
|
|
|
|
```bash
|
|
git clone <repo-url>
|
|
cd AuraK
|
|
yarn install
|
|
cp server/.env.sample server/.env
|
|
# Edit server/.env — set JWT_SECRET
|
|
|
|
# Start infrastructure (optional for basic features)
|
|
docker-compose up -d elasticsearch tika libreoffice
|
|
|
|
# Start development servers
|
|
yarn dev
|
|
# Frontend: http://localhost:13001
|
|
# Backend: http://localhost:3001
|
|
```
|
|
|
|
### 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
|
|
```
|
|
|
|
---
|
|
|
|
## 📖 User Guide
|
|
|
|
### User Management
|
|
|
|
```
|
|
Settings → User Management
|
|
```
|
|
|
|
| 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. **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
|
|
```
|
|
|
|
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
|
|
|
|
**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
|
|
|
|
**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 members: add/remove users, assign roles
|
|
- Per-tenant settings (models, knowledge bases, features)
|
|
- Data isolation: Tenant A users cannot access Tenant B data
|
|
|
|
---
|
|
|
|
## 🧪 Testing
|
|
|
|
```bash
|
|
# Full system test (142 items)
|
|
cd /d/AuraK && node test-systematic.mjs
|
|
|
|
# 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
|
|
|
|
```
|
|
AuraK/
|
|
├── 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
|
|
```
|
|
|
|
---
|
|
|
|
## 🏗️ Tech Stack
|
|
|
|
| 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 |
|
|
|
|
---
|
|
|
|
## 🔧 Configuration
|
|
|
|
| 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 |
|