zant-admin 1.0.4 → 2.0.1

package/README.en.md

@@ -1,36 +1,425 @@
-# zc-ant-vue
+<div align="center">
+  <h1>ZAntAdmin</h1>
+  <img src="./public/logo.png" alt="ZAntAdmin Logo" width="120">
+</div>
 
-#### Description
-{**When you're done, you can delete the content in this README and update the file with details for others getting started with your repository**}
+<div align="center">
 
-#### Software Architecture
-Software architecture description
+![ZAntAdmin](https://img.shields.io/badge/ZAntAdmin-Admin%20Platform-blue.svg)
+![Vue](https://img.shields.io/badge/Vue-3.5-green.svg)
+![Ant Design Vue](https://img.shields.io/badge/Ant%20Design%20Vue-4.2.6-red.svg)
+![License](https://img.shields.io/badge/License-MIT-yellow.svg)
 
-#### Installation
+[Live Demo](http://106.13.37.129:8123) | [Backend Project](https://gitee.com/zchty/zant-core)
 
-1.  xxxx
-2.  xxxx
-3.  xxxx
+</div>
 
-#### Instructions
+## 📋 Table of Contents
 
-1.  xxxx
-2.  xxxx
-3.  xxxx
+- [Introduction](#introduction)
+- [Technical Architecture](#technical-architecture)
+- [Project Structure](#project-structure)
+- [Quick Start](#quick-start)
+- [Core Features](#core-features)
+- [Project Features](#project-features)
+- [Contribution](#contribution)
+- [License](#license)
 
-#### Contribution
+## Introduction
 
-1.  Fork the repository
-2.  Create Feat_xxx branch
-3.  Commit your code
-4.  Create Pull Request
+ZAntAdmin is a modern frontend management system built with Vue 3.5 + Vite + Ant Design Vue 4.2.6. It adopts the latest frontend technology stack and provides complete user authentication, permission management, dynamic routing, data visualization, and other functions, suitable for the development of enterprise-level management systems.
 
+### Preview
 
-#### Gitee Feature
+<div>
+  <img src="./src/assets/imgs/md/login.png" alt="Login Page" width="300" style="margin-right: 10px; margin-bottom: 10px; border: 1px solid #d9d9d9; border-radius: 4px;">
+  <img src="./src/assets/imgs/md/console.png" alt="Dashboard" width="300" style="margin-right: 10px; margin-bottom: 10px; border: 1px solid #d9d9d9; border-radius: 4px;">
+  <img src="./src/assets/imgs/md/serviceMonitoring.png" alt="Service Monitoring" width="300" style="margin-bottom: 10px; border: 1px solid #d9d9d9; border-radius: 4px;">
+   <img src="./src/assets/imgs/md/statistics.png" alt="Statistics" width="300" style="margin-right: 10px; margin-bottom: 10px; border: 1px solid #d9d9d9; border-radius: 4px;">
+   <img src="./src/assets/imgs/md/menu.png" alt="Menu Management" width="300" style="margin-right: 10px; margin-bottom: 10px; border: 1px solid #d9d9d9; border-radius: 4px;">
+</div>
 
-1.  You can use Readme\_XXX.md to support different languages, such as Readme\_en.md, Readme\_zh.md
-2.  Gitee blog [blog.gitee.com](https://blog.gitee.com)
-3.  Explore open source project [https://gitee.com/explore](https://gitee.com/explore)
-4.  The most valuable open source project [GVP](https://gitee.com/gvp)
-5.  The manual of Gitee [https://gitee.com/help](https://gitee.com/help)
-6.  The most popular members  [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)
+## Technical Architecture
+
+### Core Framework
+- **Vue 3**: Adopting Composition API and `<script setup>` syntax sugar
+- **Vite**: Modern frontend build tool, providing fast development experience
+- **Vue Router 4**: Routing management, supporting dynamic routing and navigation guards
+- **Pinia**: State management, replacing Vuex, providing a simpler API
+
+### UI Framework
+- **Ant Design Vue 4**: Enterprise-level UI component library
+- **@ant-design/icons-vue**: Ant Design icon library
+
+### Utility Libraries
+- **alova**: Request library, providing powerful request management capabilities
+- **dayjs**: Lightweight date processing library
+- **echarts**: Data visualization chart library
+- **file-saver**: File saving tool
+- **pinia-plugin-persist**: Pinia persistence plugin
+
+### Development Tools
+- **ESLint**: Code quality checking
+- **Prettier**: Code formatting
+- **vite-plugin-clean**: Clean old files during build
+
+## Project Structure
+
+```
+ZAntAdmin/
+├── public/                  # Static resources
+├── src/
+│   ├── api/                 # API interfaces
+│   │   ├── methods/         # Module API methods
+│   │   └── request.js       # Request encapsulation
+│   ├── assets/              # Static resources
+│   │   ├── css/             # Style files
+│   │   └── imgs/            # Image resources
+│   ├── components/          # Common components
+│   │   ├── details/         # Detail components
+│   │   ├── edit/            # Edit components
+│   │   └── pages/           # Page components
+│   ├── config/              # Configuration files
+│   ├── directives/          # Custom directives
+│   ├── router/              # Router configuration
+│   ├── stores/              # State management
+│   ├── utils/               # Utility functions
+│   ├── views/               # Page views
+│   ├── App.vue              # Root component
+│   └── main.js              # Entry file
+├── .env.development         # Development environment variables
+├── .env.production          # Production environment variables
+├── .env.test                # Test environment variables
+├── eslint.config.js         # ESLint configuration
+├── .prettierrc.json         # Prettier configuration
+├── index.html               # HTML template
+├── package.json             # Project dependencies
+└── vite.config.js           # Vite configuration
+```
+
+## Core Features
+
+### 1. User Authentication & Permission Management
+- Token-based user authentication
+- Dynamic permission control
+- Role management
+- Permission directives (`v-permission`)
+
+### 2. Dynamic Routing System
+- Dynamic route loading based on backend menu configuration
+- Route guards for access control
+- Multi-level menu support
+- Route cache control
+
+### 3. Data Management
+- Common CRUD operation encapsulation
+- Form validation
+- Data import/export
+- File upload/download
+
+### 4. System Management
+- User management
+- Role management
+- Menu management
+- Dictionary management
+- System monitoring
+- Log management
+
+### 5. Data Visualization
+- Chart display based on ECharts
+- Statistical analysis pages
+- Data dashboard
+
+## Quick Start
+
+### Requirements
+- Node.js >= 16.0.0 (LTS recommended)
+- npm >= 7.0.0
+
+### Method 1: Using Scaffold (Recommended)
+
+ZAnt Admin Scaffold is a quick generation tool for frontend management systems based on Vue 3.5 + Vite + Ant Design Vue. With simple command-line operations, you can quickly create a fully functional management system project.
+
+#### Install Scaffold
+
+```bash
+# Install scaffold globally
+npm install -g zant-admin
+
+# Or run directly with npx
+npx zant-admin create my-project
+```
+
+#### Create New Project
+
+##### Interactive Creation (Recommended)
+```bash
+zant-admin create my-project --interactive
+```
+
+The system will guide you through the following configurations:
+- Project description
+- Author name
+- Project template selection
+- Feature selection
+- Skip dependency installation
+
+##### Command Line Arguments
+```bash
+# Basic creation
+zant-admin create my-project
+
+# Specify template and description
+zant-admin create my-project --template basic --description "Basic Management System"
+
+# Skip dependency installation
+zant-admin create my-project --skip-install
+
+# Disable interactive mode
+zant-admin create my-project --no-interactive
+```
+
+#### Scaffold Commands
+
+##### create Command
+Create a new ZAnt Admin project.
+
+**Arguments:**
+- `<project-name>`: Project name (required)
+
+**Options:**
+- `-t, --template <template>`: Project template (default: "default")
+- `-d, --description <description>`: Project description
+- `-a, --author <author>`: Author name
+- `--skip-install`: Skip dependency installation
+- `--no-interactive`: Disable interactive mode
+
+##### list-templates Command
+Show available project templates.
+
+```bash
+zant-admin list-templates
+```
+
+##### View Help
+```bash
+zant-admin --help
+```
+
+### Method 2: Manual Installation
+
+#### Project Templates
+
+##### Default Template (default)
+- Contains complete management system functions
+- Presets common pages and components
+- Recommended for most projects
+
+##### Basic Template (basic)
+- Contains only core functions
+- Suitable for projects requiring high customization
+- Includes basic pages like login, dashboard, console
+
+##### Full Template (full)
+- Contains all example pages and advanced functions
+- Suitable for learning and reference
+- Includes complete examples like user management, permission management
+
+#### Features
+
+In interactive mode, you can select the following features:
+
+##### User Management Module
+- User list page
+- User CRUD functions
+- User status management
+
+##### Permission Management Module
+- Role management
+- Permission configuration
+- Access control
+
+##### Data Visualization Charts
+- ECharts integration
+- Data statistics charts
+- Dashboard display
+
+##### File Upload Function
+- Image upload
+- File management
+- Upload progress display
+
+##### Internationalization Support
+- Multi-language switching
+- Chinese/English support
+- Language package management
+
+#### Project Structure
+
+The generated project has the following structure:
+
+```
+my-project/
+├── public/                 # Static resources
+├── src/
+│   ├── api/               # API requests
+│   ├── assets/            # Static resources
+│   ├── components/        # Common components
+│   ├── config/            # Configuration files
+│   ├── locales/           # Internationalization files (if selected)
+│   ├── router/            # Router configuration
+│   ├── stores/            # State management
+│   ├── utils/             # Utility functions
+│   ├── views/             # Page views
+│   ├── App.vue            # Root component
+│   └── main.js            # Entry file
+├── package.json           # Project configuration
+├── vite.config.js         # Vite configuration
+└── README.md              # Project documentation
+```
+
+#### Install Dependencies
+```bash
+npm install
+```
+
+#### Start Development Server
+```bash
+npm run dev
+```
+
+#### Build for Production
+```bash
+npm run build
+```
+
+#### Preview Production Build
+```bash
+npm run preview
+```
+
+# Code Linting & Fixing
+npm run lint
+
+# Code Formatting
+npm run format
+
+### Development Standards
+
+#### Development Guide
+
+##### Start Development Server
+
+```bash
+cd my-project
+npm install  # If dependency installation was skipped
+npm run dev
+```
+
+##### Build for Production
+
+```bash
+npm run build
+```
+
+##### Code Linting
+
+```bash
+npm run lint
+```
+
+##### Code Formatting
+
+```bash
+npm run format
+```
+
+#### Tech Stack
+
+- **Vue 3**: Progressive JavaScript Framework
+- **Vite**: Next Generation Frontend Tooling
+- **Ant Design Vue**: Enterprise-class UI Design Language
+- **Pinia**: Vue State Management
+- **Vue Router**: Official Vue Router
+- **ESLint + Prettier**: Code Linting and Formatting
+
+#### FAQ
+
+##### Q: Permission error when creating project?
+A: Please ensure you have sufficient permissions to create files in the target directory.
+
+##### Q: Dependency installation failed?
+A: Try using `--skip-install` to skip installation, then manually run `npm install`.
+
+##### Q: How to customize templates?
+A: You can modify template files in the `templates/` directory to customize generated content.
+
+##### Q: Support TypeScript?
+A: Current version mainly supports JavaScript, TypeScript support will be added in future versions.
+
+#### Vue Component Standards
+1. Use Composition API (`<script setup>`) syntax sugar
+2. Use PascalCase for component naming
+3. Use `.vue` extension for component files
+4. Use `scoped` styles to avoid global pollution
+
+#### JavaScript Standards
+1. Use ES6+ syntax
+2. Use `import/export` for modularization
+3. Prefer `const`, then `let`, avoid `var`
+4. Use arrow functions to simplify code
+
+#### CSS Standards
+1. Use kebab-case for CSS class names
+2. Use `scoped` for component styles to avoid global pollution
+
+#### Code Commit Standards
+1. Follow conventional commit specification
+2. Ensure ESLint check passes before commit
+
+## Project Features
+
+### 1. Modular Design
+The project adopts a highly modular design, with functional modules independent of each other, facilitating maintenance and expansion.
+
+### 2. Common Component Encapsulation
+Provides rich common components, such as form tables, icon selectors, etc., improving development efficiency.
+
+### 3. Utility Function Library
+Encapsulates common utility functions, such as region tools, form CRUD operations, etc., simplifying business logic development.
+
+### 4. Responsive Design
+Responsive design based on Ant Design Vue, adapting to devices of different screen sizes.
+
+### 5. Internationalization Support
+Reserved internationalization interfaces for future multi-language expansion.
+
+## Deployment
+
+### Environment Configuration
+The project supports multi-environment configuration, managing variables for different environments via `.env` files:
+- `.env.development`: Development environment
+- `.env.test`: Test environment
+- `.env.production`: Production environment
+
+### Build & Deploy
+1. Run build command: `npm run build`
+2. Deploy files in `dist` directory to Web server
+3. Configure server to support SPA routing mode
+
+## Contribution
+
+1. Raise Issues or Suggestions
+   - Submit Issue describing the problem or suggestion
+   - Provide relevant code snippets or screenshots
+
+2. Participate in Development
+   - Fork this project
+   - Create feature branch (`git checkout -b feature/AmazingFeature`)
+   - Commit changes (`git commit -m 'Add some AmazingFeature'`)
+   - Push to branch (`git push origin feature/AmazingFeature`)
+   - Submit Pull Request
+
+## License
+
+This project is licensed under the MIT License, see the LICENSE file for details.