461 lines
14 KiB
Markdown
461 lines
14 KiB
Markdown
<div align="center">
|
|
<img src="https://gaoziman.oss-cn-hangzhou.aliyuncs.com/uPic/2025-07-09-%E7%94%B0%E5%9B%AD%E7%8A%AC.svg" style="width:150px"/>
|
|
<h1>🚀 Coi Admin</h1>
|
|
<p>A Modern Admin Dashboard Template Based on Vue3 + Vite + TypeScript + Naive UI</p>
|
|
</div>
|
|
|
|
<div align="center">
|
|
|
|
[](LICENSE)
|
|
[](https://vuejs.org/)
|
|
[](https://vitejs.dev/)
|
|
[](https://www.typescriptlang.org/)
|
|
[](https://www.naiveui.com/)
|
|
[](https://unocss.dev/)
|
|
|
|
</div>
|
|
|
|
<div align="center">
|
|
|
|
**English | [简体中文](./README.zh-CN.md)**
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
## ✨ Introduction
|
|
|
|
**Coi Admin** is a modern admin dashboard template built with the latest frontend technologies. The project adopts a clean design philosophy and provides complete permission management, user management, system management, and other features, aiming to provide developers with an out-of-the-box admin solution.
|
|
|
|
### 🎯 Design Philosophy
|
|
|
|
- **🎨 Clean & Beautiful** - Adopts Naive UI design language with a clean and modern interface
|
|
- **⚡ Developer Friendly** - Complete TypeScript support and excellent development experience
|
|
- **📱 Responsive Design** - Perfect adaptation for desktop and mobile devices
|
|
- **🔧 Easy Customization** - Flexible configuration system for easy theme and layout customization
|
|
- **📚 Complete Standards** - Detailed development specifications and code comments
|
|
|
|
---
|
|
|
|
## 🚀 Core Features
|
|
|
|
### 💎 Technology Architecture
|
|
- **🔥 Vue 3.5.16** - Latest Vue3 Composition API
|
|
- **⚡ Vite 6.3.5** - Ultra-fast frontend build tool
|
|
- **📘 TypeScript 5.8.3** - Complete type safety support
|
|
- **🎨 Naive UI 2.41.1** - Enterprise-grade component library
|
|
- **🎪 UnoCSS 66.2.0** - High-performance atomic CSS engine
|
|
- **🌐 Vue Router 4** - Official routing manager
|
|
- **📦 Pinia** - Next-generation state management
|
|
- **🔗 Alova** - Lightweight request library
|
|
|
|
### 🛠️ Functional Features
|
|
- **🔐 Complete Permission System** - RBAC-based permission management with route-level, component-level, and button-level permission control
|
|
- **👤 User Management** - Complete user CRUD operations with role assignment and permission management
|
|
- **🏷️ Role Management** - Flexible role permission configuration with dynamic permission assignment
|
|
- **📋 Menu Management** - Dynamic menu configuration supporting icons, routes, and various properties
|
|
- **🔄 Route Management** - Support for static and dynamic routes with automatic breadcrumb generation
|
|
- **🌙 Theme Switching** - Support for light/dark theme switching with visual consistency
|
|
- **🌍 Internationalization** - Complete multi-language support
|
|
- **📊 Data Visualization** - Integrated chart components supporting various data display needs
|
|
|
|
### 🎨 Interface Features
|
|
- **📱 Responsive Layout** - Perfect adaptation to various screen sizes
|
|
- **🎯 Modern Design** - Adopts latest UI design trends
|
|
- **🎪 Animation Effects** - Rich transition animations enhancing user experience
|
|
- **📐 Flexible Layout** - Support for sidebar menu, top menu, mixed menu, and other layouts
|
|
- **🔖 Tab Management** - Support for multi-tab operations improving work efficiency
|
|
|
|
---
|
|
|
|
## 📦 Tech Stack
|
|
|
|
| Technology | Version | Description |
|
|
|------------|---------|-------------|
|
|
| **Vue** | `3.5.16` | Progressive JavaScript framework |
|
|
| **Vite** | `6.3.5` | Next-generation frontend build tool |
|
|
| **TypeScript** | `5.8.3` | JavaScript superset providing type safety |
|
|
| **Naive UI** | `2.41.1` | Vue 3 enterprise component library |
|
|
| **UnoCSS** | `66.2.0` | High-performance atomic CSS engine |
|
|
| **Vue Router** | `4.5.1` | Vue.js official routing manager |
|
|
| **Pinia** | `3.0.3` | Vue state management library |
|
|
| **Alova** | `3.3.2` | Lightweight request strategy library |
|
|
| **Vue I18n** | `11.1.5` | Internationalization plugin |
|
|
| **VueUse** | `13.3.0` | Vue Composition utilities |
|
|
|
|
---
|
|
|
|
## 📂 Project Structure
|
|
|
|
```
|
|
coder-common-thin-frontend/
|
|
├── 📁 src/
|
|
│ ├── 📁 components/ # Common components
|
|
│ │ ├── 📁 common/ # Generic components (Coi series)
|
|
│ │ └── 📁 custom/ # Custom components
|
|
│ ├── 📁 views/ # Page components
|
|
│ │ ├── 📁 dashboard/ # Dashboard
|
|
│ │ ├── 📁 system/ # System management
|
|
│ │ ├── 📁 personal-center/ # Personal center
|
|
│ │ └── 📁 login/ # Login page
|
|
│ ├── 📁 store/ # State management
|
|
│ │ ├── 📁 auth.ts # Authentication state
|
|
│ │ ├── 📁 router/ # Router state
|
|
│ │ └── 📁 app/ # Application state
|
|
│ ├── 📁 router/ # Router configuration
|
|
│ ├── 📁 service/ # API services
|
|
│ │ ├── 📁 api/ # Interface definitions
|
|
│ │ └── 📁 http/ # HTTP configuration
|
|
│ ├── 📁 utils/ # Utility functions
|
|
│ ├── 📁 hooks/ # Composable functions
|
|
│ ├── 📁 constants/ # Constants
|
|
│ ├── 📁 typings/ # Type definitions
|
|
│ └── 📁 styles/ # Style files
|
|
├── 📁 doc/ # Project documentation
|
|
├── 📁 locales/ # Internationalization packages
|
|
└── 📄 CLAUDE.md # Development standards documentation
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### 📋 Environment Requirements
|
|
|
|
Ensure your development environment meets the following requirements:
|
|
|
|
- **Node.js** `>= 21.x`
|
|
- **pnpm** `>= 10.x` (recommended)
|
|
|
|
### 📥 Installation
|
|
|
|
```bash
|
|
# Clone project
|
|
git clone <your-project-url>
|
|
|
|
# Enter project directory
|
|
cd coder-common-thin-frontend
|
|
|
|
# Install dependencies
|
|
pnpm install
|
|
```
|
|
|
|
### 🛠️ Development Environment
|
|
|
|
```bash
|
|
# Start development server (default port: 9980)
|
|
pnpm dev
|
|
|
|
# Start test environment
|
|
pnpm dev:test
|
|
|
|
# Start production environment
|
|
pnpm dev:prod
|
|
```
|
|
|
|
### 🏗️ Build & Deploy
|
|
|
|
```bash
|
|
# Build production version
|
|
pnpm build
|
|
|
|
# Build development version
|
|
pnpm build:dev
|
|
|
|
# Build test version
|
|
pnpm build:test
|
|
|
|
# Preview build result
|
|
pnpm preview
|
|
```
|
|
|
|
### 🔍 Code Linting
|
|
|
|
```bash
|
|
# Run ESLint and type checking
|
|
pnpm lint
|
|
|
|
# Auto-fix code issues
|
|
pnpm lint:fix
|
|
|
|
# Check ESLint configuration
|
|
pnpm lint:check
|
|
|
|
# View bundle size analysis
|
|
pnpm sizecheck
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 Core Functionality
|
|
|
|
### 🔐 Permission Management System
|
|
|
|
- **Multi-level Permission Verification** - Route-level, component-level, and API-level permission control
|
|
- **RBAC Permission Model** - Role-based access control
|
|
- **Permission Directives** - `v-permission` directive and `usePermission` composable
|
|
- **Super Permission** - Support for super admin bypassing permission checks
|
|
|
|
### 👥 User Management
|
|
|
|
- **User CRUD** - Complete user create, read, update, delete functionality
|
|
- **Role Assignment** - Flexible user role management
|
|
- **Status Management** - User enable/disable status control
|
|
- **Password Management** - Secure password reset functionality
|
|
|
|
### 🏷️ Role Management
|
|
|
|
- **Role Configuration** - Flexible role permission configuration
|
|
- **Permission Assignment** - Visual permission assignment interface
|
|
- **Role Inheritance** - Support for role permission inheritance mechanism
|
|
|
|
### 🌐 Routing System
|
|
|
|
- **Dynamic Routes** - Support for backend-returned dynamic route configuration
|
|
- **Static Routes** - Local static route configuration
|
|
- **Route Guards** - Complete route permission verification
|
|
- **Breadcrumbs** - Automatic navigation breadcrumb generation
|
|
|
|
---
|
|
|
|
## 🎨 Component System
|
|
|
|
### 🧩 Coi Component Library
|
|
|
|
The project includes a built-in **Coi** series component library providing unified design language:
|
|
|
|
- **CoiDialog** - Unified dialog component supporting ESC close, mask close, and other features
|
|
- **CoiEmpty** - Beautiful empty state component supporting multiple types and custom actions
|
|
- **CoiIcon** - Icon component supporting Iconify icon library
|
|
|
|
### 📝 Usage Examples
|
|
|
|
```vue
|
|
<template>
|
|
<!-- Dialog usage -->
|
|
<CoiDialog
|
|
ref="dialogRef"
|
|
title="Confirm Action"
|
|
@coi-confirm="handleConfirm"
|
|
@coi-cancel="handleCancel"
|
|
>
|
|
<template #content>
|
|
<p>Are you sure you want to perform this action?</p>
|
|
</template>
|
|
</CoiDialog>
|
|
|
|
<!-- Empty state usage -->
|
|
<CoiEmpty
|
|
type="search"
|
|
:show-action="true"
|
|
action-text="Search Again"
|
|
@action="handleRefresh"
|
|
/>
|
|
</template>
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 API Management
|
|
|
|
### 🔗 API Interfaces
|
|
|
|
The project uses **ApiFox** for interface management and Mock:
|
|
|
|
- **Online Documentation**: [https://nova-admin.apifox.cn](https://nova-admin.apifox.cn)
|
|
- **Interface Categories**: Authentication, user management, role management, system management, etc.
|
|
- **Mock Data**: Complete interface Mock data support
|
|
|
|
### 📡 HTTP Client
|
|
|
|
HTTP client based on **Alova** encapsulation:
|
|
|
|
```typescript
|
|
// API call example
|
|
import { addUser, getUserList } from '@/service/api/system/user'
|
|
|
|
// Get user list
|
|
const { data } = await getUserList({ pageNo: 1, pageSize: 10 })
|
|
|
|
// Add user
|
|
await addUser({ userName: 'test', loginName: 'test' })
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 Development Standards
|
|
|
|
The project includes complete development standards documentation `CLAUDE.md`, covering:
|
|
|
|
### 🎯 Core Principles
|
|
- **Readability First** - Code is written for humans to read
|
|
- **DRY Principle** - Don't Repeat Yourself
|
|
- **High Cohesion, Low Coupling** - Modular design
|
|
|
|
### 📋 Coding Standards
|
|
- **Naming Conventions** - Unified naming agreements
|
|
- **File Organization** - Clear directory structure
|
|
- **Component Development** - Component development best practices
|
|
- **API Design** - RESTful API design standards
|
|
|
|
### 🎨 Icon Usage Standards
|
|
- **Unified Icon Library** - Use `icon-park-outline` icon library
|
|
- **Semantic Icons** - Icon meaning matches functionality
|
|
- **Button Requirements** - All buttons must include icons
|
|
|
|
---
|
|
|
|
## 🌍 Internationalization Support
|
|
|
|
The project includes complete internationalization support:
|
|
|
|
```typescript
|
|
// Language configuration
|
|
const { t } = useI18n()
|
|
|
|
// Use translation
|
|
const title = t('common.confirm')
|
|
```
|
|
|
|
Supported languages:
|
|
- 🇨🇳 Simplified Chinese
|
|
- 🇺🇸 English
|
|
|
|
---
|
|
|
|
## 🎨 Theme Customization
|
|
|
|
### 🌙 Theme Switching
|
|
|
|
Support seamless light/dark theme switching:
|
|
|
|
```typescript
|
|
// Theme switching
|
|
const { theme, toggleTheme } = useTheme()
|
|
```
|
|
|
|
### 🎨 Style Customization
|
|
|
|
- **CSS Variables** - Support CSS variable customization
|
|
- **UnoCSS** - Atomic CSS for flexible customization
|
|
- **Theme Colors** - Configurable theme color schemes
|
|
|
|
---
|
|
|
|
## 📖 Development Guide
|
|
|
|
### 🔧 Adding New Pages
|
|
|
|
1. Create page component in `src/views/`
|
|
2. Add route configuration in `src/router/routes.static.ts`
|
|
3. Configure permission requirements (roles field)
|
|
|
|
### 🔌 Adding New APIs
|
|
|
|
1. Define interfaces in `src/service/api/`
|
|
2. Use project-encapsulated alova instance
|
|
3. Follow unified response handling format
|
|
|
|
### 🧩 Adding New Components
|
|
|
|
1. Create component in `src/components/`
|
|
2. Use TypeScript to define Props and Emits
|
|
3. Follow Coi component naming conventions
|
|
|
|
---
|
|
|
|
## 🚀 Deployment Guide
|
|
|
|
### 📦 Build Optimization
|
|
|
|
```bash
|
|
# Production build
|
|
pnpm build
|
|
|
|
# Analyze bundle size
|
|
pnpm sizecheck
|
|
```
|
|
|
|
### 🐳 Docker Deployment
|
|
|
|
```bash
|
|
# Deploy using Docker Compose
|
|
docker compose -f docker-compose.product.yml up --build -d
|
|
```
|
|
|
|
### 🌐 Nginx Configuration
|
|
|
|
Refer to the `nginx.conf` configuration file in the project.
|
|
|
|
---
|
|
|
|
## 🤝 Contributing
|
|
|
|
We welcome all forms of contributions!
|
|
|
|
### 🐛 Bug Reports
|
|
|
|
If you find bugs or have feature suggestions:
|
|
|
|
1. Check [Issues](../../issues) for existing related issues
|
|
2. Create a new Issue with detailed problem description or suggestions
|
|
3. If possible, provide reproduction steps or expected behavior
|
|
|
|
### 💡 Feature Suggestions
|
|
|
|
We welcome new feature suggestions:
|
|
|
|
1. Ensure suggestions align with project goals
|
|
2. Provide detailed feature requirements and use cases
|
|
3. If possible, provide design solutions or prototypes
|
|
|
|
### 🔧 Code Contributions
|
|
|
|
1. Fork this repository
|
|
2. Create a new feature branch: `git checkout -b feature/amazing-feature`
|
|
3. Commit your changes: `git commit -m 'feat: add amazing feature'`
|
|
4. Push to the branch: `git push origin feature/amazing-feature`
|
|
5. Submit a Pull Request
|
|
|
|
### 📝 Commit Standards
|
|
|
|
Please follow [Conventional Commits](https://conventionalcommits.org/) specification:
|
|
|
|
```
|
|
feat: new features
|
|
fix: bug fixes
|
|
docs: documentation updates
|
|
style: code formatting adjustments
|
|
refactor: code refactoring
|
|
test: test-related
|
|
chore: build process or auxiliary tool changes
|
|
```
|
|
|
|
---
|
|
|
|
## 📄 License
|
|
|
|
This project is open source under the [MIT](LICENSE) license.
|
|
|
|
---
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
Thanks to the following excellent open source projects:
|
|
|
|
- [Vue.js](https://vuejs.org/) - Progressive JavaScript framework
|
|
- [Vite](https://vitejs.dev/) - Next-generation frontend build tool
|
|
- [Naive UI](https://www.naiveui.com/) - Vue 3 component library
|
|
- [UnoCSS](https://unocss.dev/) - Atomic CSS engine
|
|
- [Alova](https://alova.js.org/) - Lightweight request strategy library
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
|
|
**If this project helps you, please give it a ⭐**
|
|
|
|
**Let's build better admin systems together!**
|
|
|
|
</div>
|