### Install Dependencies and Run Project

Source: https://en.doc.mineadmin.com/front/base/start

Installs project dependencies using pnpm and starts the development server. Assumes Node.js and pnpm are already installed.

```bash
# Install dependencies
pnpm i or pnpm install

# Run
pnpm dev
```

--------------------------------

### Basic MineAdmin Configuration Setup

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Copies the example environment file to `.env` for local configuration. This is a crucial first step after downloading the source code.

```bash
# Enter project directory
cd MineAdmin  # or your-project-name

# Copy environment configuration file
cp .env.example .env
```

--------------------------------

### Frontend Installation: Install Dependencies and Start Server

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Installs frontend dependencies using pnpm and starts the development server. Assumes the user is in the 'web' directory.

```bash
# Enter frontend directory
cd web

# Install dependencies
pnpm install

# Start development server
pnpm dev
```

--------------------------------

### Backend Installation: Start Service

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Starts the MineAdmin backend service using the Hyperf framework.

```bash
# Start Hyperf service
php bin/hyperf.php start
```

--------------------------------

### List Locally Installed MineAdmin Plugins

Source: https://en.doc.mineadmin.com/plugin/guide

Displays a list of all plugins currently installed on the local MineAdmin system.

```bash
php bin/hyperf.php mine-extension:local-list
```

--------------------------------

### Install MineAdmin Plugin

Source: https://en.doc.mineadmin.com/plugin/guide

Installs a specified plugin into the MineAdmin system. The --yes flag bypasses confirmation prompts.

```bash
php bin/hyperf.php mine-extension:install mycompany/hello-world --yes
```

--------------------------------

### Install Local MineAdmin Plugin

Source: https://en.doc.mineadmin.com/plugin/guide

Installs a plugin from a local file path. The --yes flag bypasses confirmation prompts.

```bash
php bin/hyperf.php mine-extension:install plugin/path --yes
```

--------------------------------

### Docker Compose Installation and Initialization

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Commands for starting MineAdmin services using Docker Compose, checking service status, viewing logs, and initializing the application within the container, including dependency installation and database migrations.

```bash
# Start all services in the background
docker-compose up -d

# Check service status
docker-compose ps

# View logs for all services
docker-compose logs -f

# View logs for a specific service
docker-compose logs -f mineadmin

# Enter application container
docker-compose exec mineadmin bash

# Install backend dependencies
composer install --no-dev --optimize-autoloader

# Database migration
php bin/hyperf.php migrate

# Data seeding
php bin/hyperf.php db:seed
```

--------------------------------

### Start MineAdmin Development Server

Source: https://en.doc.mineadmin.com/plugin/guide

Starts the Hyperf development server for the MineAdmin application.

```bash
php bin/hyperf.php start
```

--------------------------------

### Backend Installation: Database Initialization

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Initializes the MineAdmin database by creating the database (optional) and running migrations to set up the schema, followed by seeding initial data.

```bash
# Create database (optional, can be done manually)
mysql -u root -p -e "CREATE DATABASE mineadmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# Execute database migration
php bin/hyperf.php migrate

# Seed initial data
php bin/hyperf.php db:seed
```

--------------------------------

### Hello World Controller

Source: https://en.doc.mineadmin.com/plugin/guide

A sample controller for a MineAdmin plugin that provides a greeting endpoint. It uses Hyperf annotations to define the controller prefix and the GET mapping for the greeting method.

```php
<?php

namespace Plugin\MyCompany\HelloWorld\Controller;

use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\GetMapping;

#[Controller(prefix: '/hello-world')]
class HelloController
{
    #[GetMapping('/greeting')]
    public function greeting(): array
    {
        return [
            'code' => 200,
            'message' => 'Hello from MineAdmin Plugin!',
            'data' => [
                'plugin' => 'hello-world',
                'timestamp' => time()
            ]
        ];
    }
}
```

--------------------------------

### Frontend Installation: Environment Preparation

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Prepares the frontend development environment by installing and using a specific Node.js version (18) via nvm and installing pnpm globally.

```bash
# Install and use recommended Node.js version
nvm install 18
nvm use 18

# Install pnpm globally (if not already installed)
npm install -g pnpm
```

--------------------------------

### Docker Custom Build and Run

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Builds a custom Docker image for MineAdmin and starts a container, mapping ports and volumes, and setting environment variables for database and Redis connections.

```bash
docker build -t mineadmin:latest .

docker run -d \
  --name mineadmin \
  -p 9501:9501 \
  -v $(pwd):/opt/www \
  -e DB_HOST=your_db_host \
  -e DB_DATABASE=mineadmin \
  -e DB_USERNAME=your_username \
  -e DB_PASSWORD=your_password \
  -e REDIS_HOST=your_redis_host \
  mineadmin:latest
```

--------------------------------

### Backend Installation: Composer Dependencies

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Installs backend dependencies using Composer. Includes commands for both development environments (verbose) and production environments (optimized, no dev dependencies).

```bash
# Install dependency packages (development environment)
composer install -vvv

# Production environment installation (optional)
composer install --no-dev --optimize-autoloader
```

--------------------------------

### Performance Optimization: Production Environment

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Optimizes the production environment by installing dependencies without development files, clearing configuration cache, and building the frontend production version.

```bash
# Use production configuration
composer install --no-dev --optimize-autoloader

# Clear configuration cache
php bin/hyperf.php config:clear

# Build frontend production version
cd web && pnpm build
```

--------------------------------

### Troubleshooting: Slow Frontend Dependency Installation

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Suggests solutions for slow frontend dependency installations by configuring pnpm or npm to use faster mirrors, such as the Taobao mirror.

```bash
# Use Taobao mirror
pnpm config set registry https://registry.npmmirror.com

# Or use cnpm
npm install -g cnpm --registry=https://registry.npmmirror.com
cnpm install
```

--------------------------------

### Download MineAdmin Plugin

Source: https://en.doc.mineadmin.com/plugin/guide

Downloads a specified plugin from the remote repository. Replace 'plugin-name' with the actual plugin name.

```bash
php bin/hyperf.php mine-extension:download --name plugin-name
```

--------------------------------

### List Remote MineAdmin Plugins

Source: https://en.doc.mineadmin.com/plugin/guide

Fetches and displays a list of available plugins from the remote repository.

```bash
php bin/hyperf.php mine-extension:list
```

--------------------------------

### ConfigProvider.php Example

Source: https://en.doc.mineadmin.com/plugin/configProvider

An example of a ConfigProvider class in PHP. This class returns an array containing configuration for annotations, dependencies, commands, listeners, and publishable configuration files. The 'publish' section specifies how to copy configuration files during application installation.

```php
<?php

declare(strict_types=1);
/**
 * This file is part of MineAdmin.
 *
 * @link     https://www.mineadmin.com
 * @document https://doc.mineadmin.com
 * @contact  root@imoi.cn
 * @license  https://github.com/mineadmin/MineAdmin/blob/master/LICENSE
 */

namespace Plugin\MineAdmin\AppStore;

class ConfigProvider
{
    public function __invoke()
    {
        return [
            // Merge into config/autoload/annotations.php
            'annotations' => [
                'scan' => [
                    'paths' => [
                        __DIR__,
                    ],
                ],
            ],
            // Merge into config/autoload/dependencies.php
            'dependencies' => [],
            // Default Command definitions, analogous to config/autoload/commands.php
            'commands' => [],
            // Similar to commands
            'listeners' => [],
              
            // Default component configuration files.
            // When executing the command, the file specified in 'source' will be copied to the 'destination' path.
            'publish' => [
                [
                    'id' => 'config',
                    'description' => 'description of this config file.', // Description
                    // Recommended to place default configurations in the publish folder, with filenames matching the component name.
                    'source' => __DIR__ . '/../publish/appstore.php',  // Path to the configuration file
                    'destination' => BASE_PATH . '/config/autoload/appstore.php', // Copy to this path
                ],
            ],
        ];
    }
}

```

--------------------------------

### Starting the MineAdmin Service

Source: https://en.doc.mineadmin.com/backend

Command to start the HTTP service for the MineAdmin backend. Requires PHP and Swoole/Swow to be installed.

```Bash
php bin/hyperf.php start
```

--------------------------------

### Troubleshooting: Redis Connection Failure

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Provides steps to resolve Redis connection issues, including checking the service status with `redis-cli ping` and starting the Redis service using system commands.

```bash
# Check Redis service status
redis-cli ping

# Start Redis service (varies by system)
# Ubuntu/Debian
sudo systemctl start redis-server

# CentOS/RHEL
sudo systemctl start redis

# macOS
brew services start redis
```

--------------------------------

### Local Environment Prerequisite Checks

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Verifies the presence and versions of essential tools and extensions required for local MineAdmin installation, including PHP, Composer, Swoole, Redis, PDO_MySQL, Node.js, and pnpm.

```bash
php --version

composer --version

php -m | grep -E "(swoole|redis|pdo_mysql)"

node --version

pnpm --version
```

--------------------------------

### Development Environment Configuration (.env)

Source: https://en.doc.mineadmin.com/guide/start/deployment

Example `.env` file configuration for a development environment, specifying database, Redis, and application settings.

```bash
APP_NAME=MineAdmin
APP_ENV=dev
APP_DEBUG=true
APP_URL=http://127.0.0.1:9501

# Database Configuration
DB_DRIVER=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=mineadmin
DB_USERNAME=root
DB_PASSWORD=your_password
DB_CHARSET=utf8mb4
DB_COLLATION=utf8mb4_unicode_ci
DB_PREFIX=

# Redis Configuration
REDIS_HOST=127.0.0.1
REDIS_AUTH=
REDIS_PORT=6379
REDIS_DB=0

# JWT Secret Key (generate a new key)
JWT_SECRET=your_jwt_secret_key_here
```

--------------------------------

### Troubleshooting: Composer Dependency Failure

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Provides solutions for Composer dependency installation failures, including clearing the cache, updating Composer, and ignoring platform requirements during reinstallation.

```bash
# Clear Composer cache
composer clear-cache

# Update Composer to latest version
composer self-update

# Reinstall
composer install --ignore-platform-reqs
```

--------------------------------

### MineAdmin Frontend Hot Updates

Source: https://en.doc.mineadmin.com/plugin/guide

Initiates hot updates for the MineAdmin frontend development environment. This command should be run from the frontend project directory.

```bash
npm run dev
```

--------------------------------

### Initialize Plugin System

Source: https://en.doc.mineadmin.com/plugin/guide

Initializes the plugin extension system for MineAdmin. This command is essential for managing plugins within the MineAdmin framework. Note that MineAdmin 3.0+ versions initialize this by default.

```bash
php bin/hyperf.php mine-extension:initial
```

--------------------------------

### Copy Environment File

Source: https://en.doc.mineadmin.com/guide/start/deployment

Shell command to copy the example environment file to a new file for customization.

```shell
cp .env.example .env
```

--------------------------------

### Production Environment Configuration (.env)

Source: https://en.doc.mineadmin.com/guide/start/deployment

Example `.env` file configuration for a production environment, including secure settings for database, Redis, and JWT.

```bash
APP_NAME=MineAdmin
APP_ENV=prod
APP_DEBUG=false
APP_URL=https://your-domain.com

# Database Configuration (use internal IP)
DB_DRIVER=mysql
DB_HOST=10.0.0.10
DB_PORT=3306
DB_DATABASE=mineadmin
DB_USERNAME=mineadmin
DB_PASSWORD=strong_password_here
DB_CHARSET=utf8mb4
DB_COLLATION=utf8mb4_unicode_ci
DB_PREFIX=

# Redis Configuration (use internal IP, enable password)
REDIS_HOST=10.0.0.11
REDIS_AUTH=redis_password_here
REDIS_PORT=6379
REDIS_DB=0

# JWT Secret Key (64-character strong key)
JWT_SECRET=generated_64_character_jwt_secret_key_here
```

--------------------------------

### Troubleshooting: Database Connection Failure

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Offers solutions for database connection errors, such as checking service status, verifying configuration, and testing the connection manually.

```bash
# Test database connection
mysql -h 127.0.0.1 -P 3306 -u root -p
```

--------------------------------

### Performance Optimization: Development Environment

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Optimizes the development environment by enabling OPcache for PHP and increasing the PHP memory limit.

```bash
# Enable OPcache (PHP configuration)
echo "opcache.enable=1" >> /etc/php/8.1/cli/conf.d/99-opcache.ini

# Increase PHP memory limit
echo "memory_limit=512M" >> /etc/php/8.1/cli/conf.d/99-memory.ini
```

--------------------------------

### UserService Methods

Source: https://en.doc.mineadmin.com/plugin/examples

Provides core user management functionalities including getting lists, creating, updating, importing from files, and exporting to files.

```php
<?php

namespace Plugin\Example\UserManager\Service;

use Mine\Abstracts\AbstractService;
use Plugin\Example\UserManager\Repository\UserRepository;
use Plugin\Example\UserManager\Contract\UserServiceInterface;

class UserService extends AbstractService implements UserServiceInterface
{
    public function __construct(
        private UserRepository $repository
    ) {}

    /**
     * Get user list
     */
    public function getList(array $params = []): array
    {
        return $this->repository->getList($params);
    }

    /**
     * Create user
     */
    public function create(array $data): array
    {
        // Password encryption
        if (isset($data['password'])) {
            $data['password'] = password_hash($data['password'], PASSWORD_DEFAULT);
        }

        // Generate user avatar
        if (!isset($data['avatar'])) {
            $data['avatar'] = $this->generateAvatar($data['username']);
        }

        $user = $this->repository->create($data);

        // Trigger user creation event
        event(new UserCreatedEvent($user));

        return $user->toArray();
    }

    /**
     * Update user
     */
    public function update(int $id, array $data): array
    {
        // Password update handling
        if (isset($data['password']) && !empty($data['password'])) {
            $data['password'] = password_hash($data['password'], PASSWORD_DEFAULT);
        } else {
            unset($data['password']);
        }

        $user = $this->repository->update($id, $data);

        // Trigger user update event
        event(new UserUpdatedEvent($user));

        return $user->toArray();
    }

    /**
     * Import users from file
     */
    public function importFromFile($file): array
    {
        $filePath = $file->getPath() . '/' . $file->getFilename();
        
        // Read Excel file
        $data = $this->parseExcelFile($filePath);
        
        $successCount = 0;
        $errorCount = 0;
        $errors = [];

        foreach ($data as $index => $row) {
            try {
                $this->create([
                    'username' => $row['username'],
                    'email' => $row['email'],
                    'phone' => $row['phone'] ?? null,
                    'password' => $row['password'] ?? '123456',
                ]);
                $successCount++;
            } catch (\Exception $e) {
                $errorCount++;
                $errors[] = "Row {$index}: " . $e->getMessage();
            }
        }

        return [
            'success_count' => $successCount,
            'error_count' => $errorCount,
            'errors' => $errors
        ];
    }

    /**
     * Export users to file
     */
    public function exportToFile(array $params = []): string
    {
        $users = $this->repository->getAllForExport($params);
        
        // Generate Excel file
        $filePath = $this->generateExcelFile($users);
        
        return $filePath;
    }

    /**
     * Generate user avatar
     */
    private function generateAvatar(string $username): string
    {
        // Use third-party library to generate avatar
        $avatar = new \Intervention\Image\ImageManager();
        // ... Avatar generation logic
        
        return '/uploads/avatars/' . $username . '.png';
    }

    /**
     * Parse Excel file
     */
    private function parseExcelFile(string $filePath): array
    {
        // Excel parsing logic
        return [];
    }

    /**
     * Generate Excel file
     */
    private function generateExcelFile(array $users): string
    {
        // Excel generation logic
        return '/tmp/users_export_' . date('YmdHis') . '.xlsx';
    }

    protected function getRepository(): string
    {
        return UserRepository::class;
    }
}

```

--------------------------------

### Preview Project

Source: https://en.doc.mineadmin.com/front/base/build-preview

Starts a local server to preview the built and packaged project, allowing for local testing.

```bash
pnpm run serve
```

--------------------------------

### Test MineAdmin API Endpoint

Source: https://en.doc.mineadmin.com/plugin/guide

Tests a specific API endpoint (e.g., /hello-world/greeting) by sending an HTTP GET request to the running development server.

```bash
curl http://localhost:9501/hello-world/greeting
```

--------------------------------

### Frontend Component Example

Source: https://en.doc.mineadmin.com/plugin/guide

A Vue.js component for a MineAdmin plugin that displays a greeting message and allows users to fetch it from the backend. It includes a button to trigger the API call and updates the message based on the response.

```vue
<!-- web/components/HelloWorld.vue -->
<template>
  <div class="hello-world">
    <h2>Hello World Plugin</h2>
    <p>{{ message }}</p>
    <el-button @click="fetchGreeting" type="primary">
      Get Greeting
    </el-button>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const message = ref('Welcome to the Hello World plugin!')

const fetchGreeting = async () => {
  // Call backend API
  try {
    const response = await fetch('/hello-world/greeting')
    const data = await response.json()
    message.value = data.message
  } catch (error) {
    console.error('Failed to get greeting:', error)
  }
}
</script>
```

--------------------------------

### Plugin Installation Event Listener

Source: https://en.doc.mineadmin.com/plugin/lifecycle

An example of a PHP event listener for the `AFTER_INSTALL` plugin event. This listener logs the installation details, clears the plugin's cache, and sends a notification upon successful installation.

```php
use Hyperf\Event\Annotation\Listener;
use Hyperf\Event\Contract\ListenerInterface;

#[Listener]
class PluginInstallListener implements ListenerInterface
{
    public function listen(): array
    {
        return [
            PluginEvents::AFTER_INSTALL,
        ];
    }

    public function process(object $event): void
    {
        // Post-installation logic
        logger()->info('Plugin installed', [
            'plugin' => $event->getPluginName(),
            'version' => $event->getVersion()
        ]);
        
        // Clear cache
        $this->clearCache($event->getPluginName());
        
        // Send notification
        $this->sendNotification($event);
    }
}
```

--------------------------------

### mine.json Configuration Example

Source: https://en.doc.mineadmin.com/plugin/mineJson

A comprehensive example of a mine.json file, illustrating the structure for defining application metadata, dependencies, and backend configurations.

```json
{
  "name": "mine-admin/apps-store",
  "description": "MineAdmin App Marketplace Visual Plugin",
  "version": "1.0.0",
  "type": "mixed",
  "author": [
    {
      "name": "zds",
      "role": "developer"
    }
  ],
  "package": {
    "dependencies": {

    }
  },
  "composer": {
    "require": {
    },
    "psr-4": {
      "Plugin\\MineAdmin\\AppStore\\": "src"
    },
    "script": {
      "publishAsyncQueue": "php bin/hyperf.php vendor:publish hyperf/async-queue"
    },
    "config": "Plugin\\MineAdmin\\AppStore\\ConfigProvider"
  }
}
```

--------------------------------

### Build Project

Source: https://en.doc.mineadmin.com/front/base/build-preview

Executes the build process for the frontend project, generating a 'dist' folder with static files.

```bash
pnpm run build
```

--------------------------------

### useMessage Hook Usage Example (TypeScript)

Source: https://en.doc.mineadmin.com/front/high/hooks

An example demonstrating how to use the `useMessage` hook in a Vue component's setup function to trigger various message and confirmation dialogs.

```typescript
import { useMessage } from '@/hooks/useMessage'

export default defineComponent({
  setup() {
    const message = useMessage()

    const handleSuccess = () => {
      message.success('Operation successful!')
    }

    const handleError = () => {
      message.error('Operation failed, please retry')
    }

    const handleConfirm = async () => {
      try {
        await message.confirm('Confirm this operation?')
        console.log('User confirmed operation')
      } catch {
        console.log('User canceled operation')
      }
    }

    const handleDelete = async () => {
      try {
        await message.delConfirm()
        console.log('Perform deletion')
      } catch {
        console.log('Cancel deletion')
      }
    }

    return {
      handleSuccess,
      handleError,
      handleConfirm,
      handleDelete
    }
  }
})
```

--------------------------------

### Download MineAdmin Source Code with Git

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Clones the MineAdmin repository from GitHub to download the source code. Supports cloning the main branch or a specified directory. Also shows how to switch to the 'master-department' branch for enhanced features.

```bash
git clone https://github.com/mineadmin/MineAdmin.git

# Or clone to a specified directory
git clone https://github.com/mineadmin/MineAdmin.git your-project-name

# Switch to enhanced version branch
git checkout master-department
```

--------------------------------

### Get Installed Plugins (PHP)

Source: https://en.doc.mineadmin.com/plugin/api

Retrieves a list of all installed plugins. Each plugin entry includes its name, version, path, configuration (from mine.json), and status (enabled/disabled).

```php
<?php

use Mine\AppStore\Plugin;

// Get all installed plugins
$plugins = Plugin::getInstalled();

// Return format
[
    'vendor/plugin-name' => [
        'name' => 'vendor/plugin-name',
        'version' => '1.0.0',
        'path' => '/path/to/plugin',
        'config' => [...], // mine.json configuration
        'status' => 'enabled'
    ]
]
```

--------------------------------

### MineAdmin Service Layer Implementation

Source: https://en.doc.mineadmin.com/plugin/develop

Provides a PHP implementation for the service layer of a MineAdmin plugin, handling application listing, downloading, installation, uninstallation, local installation listing, and local upload installation. It utilizes the MineAppStoreService and Plugin classes for core functionalities.

```php
<?php
declare(strict_types=1);

namespace Plugin\MineAdmin\AppStore\Service;

use App\Service\MineAppStoreService;
use Hyperf\Di\Annotation\Inject;
use Mine\AppStore\Plugin;
use Mine\Exception\MineException;

class Service
{
    #[Inject]
    protected MineAppStoreService $service;

    /**
     * Get application list
     */
    public function getAppList(array $params): array
    {
        return $this->service->getAppList($params);
    }

    /**
     * Download application
     */
    public function download(array $params): void
    {
        $app = $this->service->getAppInfo($params['identifier']);
        
        if (empty($app['download_url'])) {
            throw new MineException('This application cannot be downloaded', 500);
        }
        
        if (Plugin::hasLocalInstalled($params['identifier'])) {
            throw new MineException('Application already exists locally. To re-download, please delete the local application first', 500);
        }
        
        $this->service->download($params);
    }

    /**
     * Install application
     */
    public function install(array $params): void
    {
        $pluginName = $params['name'];
        
        if (!Plugin::hasLocal($pluginName)) {
            throw new MineException('Plugin does not exist', 500);
        }
        
        if (Plugin::hasLocalInstalled($pluginName)) {
            throw new MineException('Plugin already installed', 500);
        }
        
        Plugin::forceRefreshJsonPath($pluginName);
        Plugin::install($pluginName);
    }

    /**
     * Uninstall application
     */
    public function unInstall(array $params): void
    {
        $pluginName = $params['name'];
        
        if (!Plugin::hasLocalInstalled($pluginName)) {
            throw new MineException('Plugin not installed', 500);
        }
        
        Plugin::uninstall($pluginName);
    }

    /**
     * Get locally installed plugin list
     */
    public function getLocalAppInstallList(): array
    {
        $list = [];
        $plugins = Plugin::getLocalPlugins();
        
        foreach ($plugins as $name => $info) {
            $app = ['identifier' => $name];
            $app['name'] = $info['name'] ?? 'Unknown';
            $app['status'] = $info['status'] ?? false;
            $app['version'] = $info['version'] ?? '0.0.0';
            $app['description'] = $info['description'] ?? 'No description';
            $app['created_at'] = $info['created_at'] ?? '';
            $list[] = $app;
        }
        
        return $list;
    }

    /**
     * Local upload installation
     */
    public function uploadLocalApp(array $params): void
    {
        if (empty($params['path'])) {
            throw new MineException('Please upload the plugin package', 500);
        }
        
        // Extract and verify plugin package
        $zipFile = new \ZipArchive();
        $result = $zipFile->open($params['path']);
        
        if ($result !== true) {
            throw new MineException('Plugin package extraction failed', 500);
        }
        
        // Get plugin info and install
        $mineJson = $zipFile->getFromName('mine.json');
        if (!$mineJson) {
            throw new MineException('Invalid plugin package format, missing mine.json', 500);
        }
        
        $config = json_decode($mineJson, true);
        $pluginName = $config['name'] ?? null;
        
        if (!$pluginName) {
            throw new MineException('Plugin package configuration error', 500);
        }
        
        // Extract to plugin directory
        $targetPath = Plugin::getPluginPath($pluginName);
        $zipFile->extractTo($targetPath);
        $zipFile->close();
        
        // Refresh cache and install
        Plugin::forceRefreshJsonPath($pluginName);
        Plugin::install($pluginName);
    }
}

```

--------------------------------

### Install MineAdmin Code Generator Plugin

Source: https://en.doc.mineadmin.com/plugin/develop

Executes the installation process for the MineAdmin Code Generator plugin. This includes copying template files, language packs, publishing vendor assets, and running database migrations. It provides feedback on the installation progress and reports any errors.

```php
<?php
declare(strict_types=1);

namespace Plugin\MineAdmin\CodeGenerator;

use Hyperf\Command\Concerns\InteractsWithIO;
use Hyperf\Context\ApplicationContext;
use Hyperf\Contract\ApplicationInterface;
use Mine\Helper\Filesystem;
use Symfony\Component\Console\Input\ArrayInput;
use Symfony\Component\Console\Output\ConsoleOutput;
use Symfony\Component\Console\Output\NullOutput;

class InstallScript
{
    use InteractsWithIO;

    public function __invoke()
    {
        // Set output
        $this->output = new ConsoleOutput();
        
        try {
            $this->info('========================================');
            $this->info('MineAdmin Code Generator Plugin');
            $this->info('========================================');
            $this->info('Starting plugin installation...');
            
            // 1. Copy template files
            $this->copyTemplates();
            
            // 2. Copy language packs
            $this->copyLanguages();
            
            // 3. Publish dependency resources
            $this->publishVendor();
            
            // 4. Run database migrations
            $this->runMigrations();
            
            $this->info('Plugin installed successfully!');
            $this->info('========================================');
            
        } catch (\Throwable $e) {
            $this->error('Plugin installation failed: ' . $e->getMessage());
            throw $e;
        }
    }
    
    /**
     * Copy template files
     */
    protected function copyTemplates(): void
    {
        $source = dirname(__DIR__) . '/publish/template';
        $target = BASE_PATH . '/runtime/generate/template';
        
        if (!is_dir($target)) {
            mkdir($target, 0755, true);
        }
        
        Filesystem::copy($source, $target, false);
        $this->info('Template files copied successfully');
    }
    
    /**
     * Copy language packs
     */
    protected function copyLanguages(): void
    {
        $source = dirname(__DIR__) . '/languages';
        $target = BASE_PATH . '/storage/languages';
        
        Filesystem::copy($source, $target, false);
        $this->info('Language packs copied successfully');
    }
    
    /**
     * Publish dependency resources
     */
    protected function publishVendor(): void
    {
        $app = ApplicationContext::getContainer()->get(ApplicationInterface::class);
        $app->setAutoExit(false);
        
        $input = new ArrayInput([
            'command' => 'vendor:publish',
            'package' => 'hyperf/translation',
       
```

--------------------------------

### Search Condition Presets

Source: https://en.doc.mineadmin.com/front/component/ma-search/examples/methods-demo

Provides examples of preset search conditions for scenarios like 'today', 'thisWeek', and 'activeUsers', and how to apply them.

```typescript
const presetScenarios = {
  today: () => {
    searchRef.value?.setSearchForm({
      created_at: [
        dayjs().format('YYYY-MM-DD'),
        dayjs().format('YYYY-MM-DD')
      ]
    })
  },
  
  thisWeek: () => {
    searchRef.value?.setSearchForm({
      created_at: [
        dayjs().startOf('week').format('YYYY-MM-DD'),
        dayjs().endOf('week').format('YYYY-MM-DD')
      ]
    })
  },
  
  activeUsers: () => {
    searchRef.value?.setSearchForm({
      status: 'active',
      last_login: [
        dayjs().subtract(30, 'day').format('YYYY-MM-DD'),
        dayjs().format('YYYY-MM-DD')
      ]
    })
  }
}

const applyPreset = (scenario: keyof typeof presetScenarios) => {
  presetScenarios[scenario]()
}
```

--------------------------------

### Combined Validation (Password Confirmation and Date Range)

Source: https://en.doc.mineadmin.com/front/component/ma-search/examples/form-validation

Provides examples of validating multiple fields together, such as ensuring password confirmation matches the password and validating that an end date is not before a start date.

```typescript
// Password confirmation validation
{
  label: 'Confirm Password',
  prop: 'confirmPassword',
  render: 'input',
  props: { type: 'password' },
  rules: [
    {
      validator: (rule: any, value: string) => {
        const formData = searchRef.value?.getSearchForm()
        
        if (value !== formData?.password) {
          throw new Error('Passwords do not match')
        }
      },
      trigger: 'blur'
    }
  ]
}

// Date range validation
{
  label: 'End Date',
  prop: 'endDate',
  render: 'date-picker',
  rules: [
    {
      validator: (rule: any, value: string) => {
        const formData = searchRef.value?.getSearchForm()
        
        if (value && formData?.startDate && new Date(value) < new Date(formData.startDate)) {
          throw new Error('End date cannot be earlier than start date')
        }
      },
      trigger: 'change'
    }
  ]
}
```

--------------------------------

### Standard Plugin Directory Structure

Source: https://en.doc.mineadmin.com/plugin/examples

Illustrates the recommended directory layout for a typical plugin, including sections for backend code, frontend assets, database files, and publishable configurations.

```text
plugin/vendor-name/plugin-name/
├── mine.json                 # Plugin configuration
├── src/                      # PHP backend code
│   ├── ConfigProvider.php    # Configuration provider
│   ├── Controller/           # Controllers
│   ├── Service/             # Service layer
│   ├── Model/               # Models
│   ├── Command/             # Commands
│   ├── Listener/            # Event listeners
│   └── Middleware/          # Middleware
├── web/                     # Frontend code
│   ├── views/               # Vue components
│   ├── api/                 # API wrappers
│   ├── components/          # Shared components
│   └── locales/             # Localization
├── Database/                # Database
│   ├── Migrations/          # Migration files
│   └── Seeders/             # Seeders
└── publish/                 # Published files
    └── config.php           # Configuration files
```

--------------------------------

### Example Lazy Load Fields Setup

Source: https://en.doc.mineadmin.com/front/component/ma-form/examples/performance-demo

Defines example form fields that utilize lazy loading, including configuration for select and cascader components. It demonstrates how to trigger lazy loading on focus or mount.

```typescript
const createLazyLoadFields = (): MaFormItem[] => [
  {
    label: 'City Selection',
    prop: 'city',
    render: 'select',
    renderProps: {
      placeholder: 'Select city',
      loading: false
    },
    renderSlots: {
      default: () => [h('el-option', { label: 'Click to load...', value: '', disabled: true })]
    },
    // Lazy load on field focus
    onFocus: () => {
      lazyLoadManager.triggerLazyLoad('city')
    }
  },
  {
    label: 'Department Selection',
    prop: 'department',
    render: 'cascader',
    renderProps: {
      placeholder: 'Select department',
      options: []
    },
    // Lazy load on field mount
    onMounted: () => {
      lazyLoadManager.triggerLazyLoad('department')
    }
  }
]
```

--------------------------------

### User Information Fetching

Source: https://en.doc.mineadmin.com/front/advanced/login-welcome

Fetches user basic information, menu permissions, and role information, then initializes the route system.

```typescript
async requestUserInfo() {
  try {
    // Parallel requests for user data, menu permissions, role info
    const [userInfo, menuList, roleList] = await Promise.all([
      http.get('/admin/user/info'),          // User basic info
      http.get('/admin/menu/index'),         // Menu permission data
      http.get('/admin/role/index')          // Role permission data
    ])
    
    // Update Store state
    this.userInfo = userInfo.data
    this.menuList = menuList.data
    this.roleList = roleList.data
    
    // Initialize route system
    const routeStore = useRouteStore()
    await routeStore.initRoutes()
    
    return Promise.resolve(userInfo)
  } catch (error) {
    return Promise.reject(error)
  }
}
```

--------------------------------

### Verification: Database Connection

Source: https://en.doc.mineadmin.com/guide/start/fast-install

Verifies the connection to the MineAdmin database using a command-line tool.

```bash
# Check database connection
php bin/hyperf.php db:show
```

--------------------------------

### Create MineAdmin Plugin

Source: https://en.doc.mineadmin.com/plugin/guide

Creates a new MineAdmin plugin using the command line. This command generates the basic file structure and configuration for a plugin, allowing you to specify its name, type, author, and description.

```bash
php bin/hyperf.php mine-extension:create mycompany/hello-world \
    --name "Hello World" \
    --type mixed \
    --author "Your Name" \
    --description "My first MineAdmin plugin"
```

--------------------------------

### Plugin Configuration File (mine.json)

Source: https://en.doc.mineadmin.com/plugin/guide

Defines the metadata and configuration for a MineAdmin plugin. This JSON file includes details such as the plugin's name, version, author, description, and composer autoloading configuration.

```json
{
  "name": "mycompany/hello-world",
  "description": "My first MineAdmin plugin",
  "version": "1.0.0",
  "type": "mixed",
  "author": [
    {
      "name": "Your Name",
      "role": "developer"
    }
  ],
  "composer": {
    "psr-4": {
      "Plugin\\MyCompany\\HelloWorld\\": "src"
    },
    "config": "Plugin\\MyCompany\\HelloWorld\\ConfigProvider"
  }
}
```

--------------------------------

### Real-World Project Example: Using Translations in Dialog and Table

Source: https://en.doc.mineadmin.com/front/high/i18n

Provides a practical example of using translation functions obtained from `useTrans` within a Vue component for dynamic UI elements like dialog messages and table headers.

```vue
<script setup lang="tsx">
import type { TransType } from '@/hooks/auto-imports/useTrans.ts'

// Get internationalization object
const i18n = useTrans() as TransType
const t = i18n.globalTrans

// Using translations in dialog configuration
const maDialog: UseDialogExpose = useDialog({
  ok: ({ formType }, okLoadingState: (state: boolean) => void) => {
    // Show different messages based on operation type
    switch (formType) {
      case 'add':
        formRef.value.add().then((res: any) => {
          res.code === ResultCode.SUCCESS 
            ? msg.success(t('crud.createSuccess'))  // "创建成功"
            : msg.error(res.message)
        })
        break
      case 'edit':
        formRef.value.edit().then((res: any) => {
          res.code === 200 
            ? msg.success(t('crud.updateSuccess'))  // "修改成功"
            : msg.error(res.message)
        })
        break
    }
  },
})

// Using translations in table configuration
const options = ref<MaProTableOptions>({
  header: {
    mainTitle: () => t('baseUserManage.mainTitle'),
    subTitle: () => t('baseUserManage.subTitle'),
  },
})
</script>
```

--------------------------------

### MaSearch Component Examples

Source: https://context7_llms

Guides for the MaSearch component, covering basic and advanced search functionalities, collapsible search interfaces, custom action buttons, dynamic management of search items, responsive layouts, integration with tables, form validation, and method demonstrations.

```en
## MaSearch Component Examples

- [Basic Usage](/front/component/ma-search/examples/basic-usage.md)
- [Advanced Search](/front/component/ma-search/examples/advanced-search.md)
- [Collapsible Search](/front/component/ma-search/examples/collapsible-search.md)
- [Custom Action Buttons](/front/component/ma-search/examples/custom-actions.md)
- [Dynamic Management of Search Items](/front/component/ma-search/examples/dynamic-items.md)
- [Responsive Layout](/front/component/ma-search/examples/responsive-layout.md)
- [Table Integration](/front/component/ma-search/examples/table-integration.md)
- [Form Validation](/front/component/ma-search/examples/form-validation.md)
- [Method Demonstration](/front/component/ma-search/examples/methods-demo.md)
```

--------------------------------

### Permission Checks in Vue Script Setup

Source: https://en.doc.mineadmin.com/front/advanced/permission

Demonstrates how to use hasAuth, hasRole, and hasUser functions within a Vue component's script setup for conditional logic. Supports single values or arrays for checks, with examples of AND logic combination.

```vue
<script setup>
import hasAuth from '@/utils/permission/hasAuth'
import hasRole from '@/utils/permission/hasRole'
import hasUser from '@/utils/permission/hasUser'

// Permission code check - supports single permission or array
if (hasAuth('user:list') || hasAuth(['user:list', 'user:create'])) {
  // User management permission granted
  console.log('Has user management permission')
}

// Role check - supports single role or array
if (hasRole('SuperAdmin') || hasRole(['admin', 'manager'])) {
  // Administrator role granted
  console.log('Has admin permission')
}

// User check - supports single username or array
if (hasUser('admin') || hasUser(['admin', 'root'])) {
  // Specific user granted
  console.log('Specific user verified')
}

// Composite permission check example
const canManageUsers = hasAuth(['user:list', 'user:create']) && hasRole('admin')
if (canManageUsers) {
  // Both permission and role requirements met
}
</script>
```

--------------------------------

### MineAdmin AppStore Controller

Source: https://en.doc.mineadmin.com/plugin/develop

This PHP code defines the IndexController for the MineAdmin AppStore plugin. It handles requests for listing remote plugins, downloading, installing, uninstalling, and managing local plugin installations. It utilizes Hyperf annotations for routing, authentication, and permissions.

```php
<?php
declare(strict_types=1);

namespace Plugin\MineAdmin\AppStore\Controller;

use Hyperf\Di\Annotation\Inject;
use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\GetMapping;
use Hyperf\HttpServer\Annotation\PostMapping;
use Mine\Annotation\Auth;
use Mine\Annotation\Permission;
use Mine\Annotation\RemoteState;
use Plugin\MineAdmin\AppStore\Service\Service;
use Psr\Http\Message\ResponseInterface;

#[Controller(prefix: "admin/plugin/store")]
#[Auth]
class IndexController extends AbstractController
{
    #[Inject]
    protected Service $service;

    /**
     * Remote plugin list
     */
    #[GetMapping("index")]
    #[Permission("plugin:store:index")]
    public function index(): ResponseInterface
    {
        return $this->success(
            $this->service->getAppList($this->request->all())
        );
    }

    /**
     * Download plugin
     */
    #[PostMapping("download")]
    #[Permission("plugin:store:download")]
    public function download(): ResponseInterface
    {
        $params = $this->request->all();
        $this->service->download($params);
        return $this->success();
    }

    /**
     * Install plugin
     */
    #[PostMapping("install")]
    #[Permission("plugin:store:install")]
    public function install(): ResponseInterface
    {
        $params = $this->request->all();
        $this->service->install($params);
        return $this->success();
    }

    /**
     * Uninstall plugin
     */
    #[PostMapping("unInstall")]
    #[Permission("plugin:store:uninstall")]
    public function unInstall(): ResponseInterface
    {
        $params = $this->request->all();
        $this->service->unInstall($params);
        return $this->success();
    }

    /**
     * Local plugin installation list
     */
    #[GetMapping("getInstallList")]
    #[RemoteState]
    public function getInstallList(): ResponseInterface
    {
        return $this->success(
            $this->service->getLocalAppInstallList()
        );
    }

    /**
     * Local upload installation
     */
    #[PostMapping("uploadInstall")]
    #[Permission("plugin:store:uploadInstall")]
    public function uploadInstall(): ResponseInterface
    {
        return $this->success(
            $this->service->uploadLocalApp($this->request->all())
        );
    }
}
```

--------------------------------

### Implement Responsive Rendering in Slots

Source: https://en.doc.mineadmin.com/front/component/ma-form/examples/slots-examples

Illustrates how to create responsive slot content by checking window dimensions. The example applies different CSS classes ('mobile-help' or 'desktop-help') based on whether the screen width is less than 768px.

```typescript
{
  label: 'Responsive Slot',
  prop: 'responsiveSlot',
  render: 'input',
  itemSlots: {
    help: ({ item, model }) => {
      const isMobile = window.innerWidth < 768
      return h('div', {
        class: isMobile ? 'mobile-help' : 'desktop-help'
      }, 'Responsive help text')
    }
  }
}
```

--------------------------------

### Settings Service Configuration Example

Source: https://en.doc.mineadmin.com/front/high/provider

Illustrates the structure of the user custom configuration file (settings.config.ts) for the Settings Service, showing examples for system, API, and theme configurations.

```ts
// settings.config.ts
export default {
  // System basic configuration
  app: {
    name: 'MineAdmin',
    version: '3.0.0',
    logo: '/logo.png'
  },
  // API configuration
  api: {
    baseUrl: process.env.NODE_ENV === 'development' 
      ? 'http://localhost:9501'
      : 'https://api.example.com',
    timeout: 10000
  },
  // Theme configuration
  theme: {
    primaryColor: '#409eff',
    darkMode: 'auto'
  }
}
```