wwz110/aurak
1
0
Fork 0
forked from hangshuo652/aurak
Code Pull Requests Activity

docs: 全面更新文档体系 — AI指南 + 人可读说明书

Browse Source 
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>
This commit is contained in:
Developer
2026-06-09 13:19:45 +08:00
parent 1aee7e0baf
commit 65ede9fcff
3 changed files with 845 additions and 431 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+243 -161
View File
@@ -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.