### Plugin Configuration via composer.json

Source: https://thinkadmin.top/system/plugin-install.html

Example of using the extra.plugin configuration to define initialization files during installation.

```json
{
  "plugin": {
    "init": {
      "config/plugin.php": "<?php return [];",  // 创建默认配置文件
      "data/init.json": "{}"                      // 创建初始化数据文件
    }
  }
}
```

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

### Full Controller Example with Data Filtering

Source: https://thinkadmin.top/system/helper-query.html

A complete controller implementation showing index query setup and a specific _index_page_filter for IP region lookup.

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

namespace app\\\admin\\\controller;

use think\\\admin\\\Controller;

/**
 * 系统操作日志
 * @class Oplog
 * @package app\\\admin\\\controller
 */
class Oplog extends Controller
{
    /**
     * 系统操作日志
     * @auth true
     * @menu true
     * @throws \\\think\\\Exception
     * @throws \\\think\\\db\\\exception\\\DataNotFoundException
     * @throws \\\think\\\db\\\exception\\\ModelNotFoundException
     * @throws \\\think\\\exception\\\DbException
     */
    public function index()
    {
        $this->title = '系统操作日志';
        $query = $this->_query($this->table)->like('action,node,content,username,geoip');
        $query->dateBetween('create_at')->order('id desc')->page();
    }

    /**
     * 列表数据处理
     * @param array $data
     * @throws \\\Exception
     */
    protected function _index_page_filter(array &$data)
    {
        $ip = new \\\Ip2Region();
        foreach ($data as &$vo) {
            $result = $ip->btreeSearch($vo['geoip']);
            $vo['isp'] = isset($result['region']) ? $result['region'] : '';
            $vo['isp'] = str_replace(['内网IP', '0', '|'], '', $vo['isp']);
        }
    }
}
```

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

### View Usage Examples

Source: https://thinkadmin.top/system/core-functions.html

Examples of rendering views and assigning template variables.

```php
// 返回视图
$this->fetch('user/index');

// 模板变量赋值
$this->assign('title', '用户管理');
// 或批量赋值
$this->assign(['title' => '用户管理', 'count' => 100]);
```

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

### Composer Installation Commands

Source: https://thinkadmin.top/system/plugin-install.html

Standard commands for installing plugins via Composer.

```bash
# 更新所有组件
composer update --optimize-autoloader

# 安装插件
composer require zoujingli/think-plugs-admin
```

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

### System User Controller Example

Source: https://thinkadmin.top/system/helper-save.html

A practical example of a System User controller demonstrating data state updates using mSave, input validation, and custom callback methods for pre- and post-update operations.

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

namespace app\admin\controller;

use think\admin\Controller;
use think\admin\model\SystemUser;

/**
 * 系统用户管理
 * @class User
 * @package app\admin\controller
 */
class User extends Controller
{
    /**
     * 修改数据状态
     * @auth true 
     */
    public function state()
    {
        // 实际项目中的安全检查示例
        $this->_checkInput();
        
        SystemUser::mSave($this->_vali([
            'status.in:0,1'  => '状态值范围异常！',
            'status.require' => '状态值不能为空！',
        ]));
    }

    /**
     * 检查输入变量（实际项目中的私有方法示例）
     */
    private function _checkInput()
    {
        // 防止删除系统超级账号
        if (in_array('10000', str2arr(input('id', '')))) {
            $this->error('系统超级账号禁止删除！');
        }
    }

    /**
     * 更新前置回调（在更新前进行数据过滤）
     * @param $query 查询对象
     * @param array $data 待更新的数据
     */
    protected function _save_filter($query, array &$data)
    {
        // 可以修改查询条件
        $query->where('is_deleted', 0);
        
        // 可以修改待更新的数据
        if (isset($data['status'])) {
            // 添加额外的数据
            $data['update_at'] = date('Y-m-d H:i:s');
        }
    }

    /**
     * 更新后置回调（通用回调）
     * @param bool $result 更新结果
     */
    protected function _save_result(bool $result)
    {
        if ($result) {
            sysoplog('系统用户管理', '更新用户状态成功');
        }
    }

    /**
     * 当一个控制器存在多个 save 操作时，可以指定回调前缀
     * @param bool $result 更新结果
     */
    protected function _state_save_result(bool $result)
    {
        // 可以根据 $result 状态返回结果 
        // 失败 $this->error(MESSAGE);
        // 成功 $this->success(MESSAGE);
    }
}
```

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

### Module Plugin Verification and Modification

Source: https://thinkadmin.top/system/plugin-install.html

Commands to verify module installation and an example of modifying the copied controller code.

```bash
# 1. 检查应用目录
ls -la app/admin/

# 2. 检查数据库迁移文件
ls -la database/migrations/

# 3. 检查 vendor 目录（应该已经被清理）
ls -la vendor/zoujingli/  # 应该看不到 think-plugs-admin 目录

# 4. 访问后台验证
# 浏览器访问：http://yourdomain.com/admin
```

```php
<?php
// app/admin/controller/User.php
// 可以自由修改这个文件，不受插件更新影响

namespace app\admin\controller;

use think\admin\Controller;

class User extends Controller
{
    // 可以添加自定义方法
    public function customMethod()
    {
        // 自定义逻辑
    }
    
    // 可以修改原有方法
    public function index()
    {
        // 修改后的逻辑
    }
}
```

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

### Standard Plugin Configuration Example

Source: https://thinkadmin.top/system/plugin-install.html

A complete configuration for a standard plugin that remains in the vendor directory.

```json
{
  "type": "think-admin-plugin",
  "name": "zoujingli/think-plugs-account",
  "description": "Account Plugin for ThinkAdmin",
  "require": {
    "php": ">7.1",
    "zoujingli/think-library": "^6.1|@dev"
  },
  "autoload": {
    "psr-4": {
      "plugin\\account\\": "src"
    }
  },
  "extra": {
    "think": {
      "services": [
        "plugin\\account\\Service"
      ]
    },
    "plugin": {
      "copy": {
        "stc/database": "database/migrations"  // 只复制数据库迁移文件
      }
    }
  }
}
```

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

### Complete Example: User Data Import

Source: https://thinkadmin.top/system/extra-import.html

A full example demonstrating the integration of frontend HTML, JavaScript, and backend PHP for importing user data from an Excel file.

```APIDOC
## Complete Example: User Data Import

### Description

This example combines the frontend HTML and JavaScript with the backend PHP logic to provide a complete solution for importing user data from an Excel file. It includes specific mappings for user fields and demonstrates data filtering and transformation.

### Frontend HTML

```html
{extend name="admin@public/container" /}

{block name="content"}
<div class="layui-card">
    <div class="layui-card-body">
        <div class="layui-form-item">
            <button class='layui-btn layui-btn-sm layui-btn-active' id="importUserBtn">
                <i class="layui-icon">&#xe67c;</i> Import User
            </button>
        </div>
    </div>
</div>
{/block}
```

### Frontend JavaScript

```javascript
{block name='script'}
<script>
$(function() {
    $('#importUserBtn').on('click', function() {
        require(['excel'], function(Excel) {
            Excel.push('{:url("import")}', 'Sheet1', {
                _: 1,  // First row is header, read from the second row
                '用户名': 'username',
                '昵称': 'nickname',
                '手机号': 'phone',
                '邮箱': 'email',
                '状态': 'status'
            }, function(item) {
                // Data filtering and transformation
                
                // Skip records with empty username
                if (!item.username || item.username.trim() === '') {
                    return false;
                }
                
                // Convert status value
                // ... (further transformation logic can be added here)
                
                return item;
            });
        });
    });
});
</script>
{/block}
```

### Backend PHP (Refer to the previous Backend PHP Code snippet for the controller implementation)

*The backend controller `app\admin\controller\User` with the `import` method should be implemented as shown in the previous section to handle the data received from `Excel.push`.*
```

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

### Module Plugin Installation Workflow

Source: https://thinkadmin.top/system/plugin-install.html

Commands and operations for installing module-based plugins that copy code directly into the app directory.

```bash
# 进入项目根目录
cd /path/to/your/project

# 安装模块插件
composer require zoujingli/think-plugs-admin
```

```bash
Loading composer repositories with package information
Updating dependencies
Lock file operations: 1 install, 0 updates, 0 removals
  - Locking zoujingli/think-plugs-admin (v6.1.0)
Writing lock file
Installing dependencies from lock file
  - Installing zoujingli/think-plugs-admin (v6.1.0)
    Downloading (100%)
    Extracting archive
```

```bash
# 执行操作：先删除 app/admin，再复制 src 内容
rm -rf app/admin
cp -r vendor/zoujingli/think-plugs-admin/src/* app/admin/
```

```bash
# 因为配置了 "clear": true
rm -rf vendor/zoujingli/think-plugs-admin/
```

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

### Simplified Project composer.json Configuration

Source: https://thinkadmin.top/system/plugin-developer.html

A minimal configuration example for linking a local plugin directory.

```json
{
  "type": "project",
  "require": {
    "zoujingli/think-plugs-account": "dev-master"
  },
  "repositories": {
    "ThinkPlugsAccount": {
      "type": "path",
      "url": "plugin/think-plugs-account"
    }
  }
}
```

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

### Define Installation and Uninstallation Events

Source: https://thinkadmin.top/system/plugin-install.html

Specify an event class to handle custom logic during plugin installation or removal.

```json
{
  "plugin": {
    "event": "plugin\\account\\InstallEvent"
  }
}
```

```php
<?php
namespace plugin\account;

class InstallEvent
{
    /**
     * 安装时执行
     */
    public static function onInstall(): void
    {
        // 创建必要的目录
        mkdir(syspath('runtime/account'), 0755, true);
        
        // 初始化配置
        sysconf('account.enabled', true);
        
        // 执行其他初始化操作
    }
    
    /**
     * 卸载时执行
     */
    public static function onRemove(): void
    {
        // 清理临时文件
        // 删除配置项
        // 执行其他清理操作
    }
}
```

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

### Development Version Installation

Source: https://thinkadmin.top/system/plugin-install.html

Commands to install unstable development versions of plugins.

```bash
# 安装开发版本
composer require zoujingli/think-plugs-admin dev-master

# 或者指定分支
composer require zoujingli/think-plugs-admin dev-develop
```

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

### Full Example: Question Bank Import

Source: https://thinkadmin.top/system/extra-import.html

A comprehensive example demonstrating how to import a question bank from an Excel file using Excel.push, including data transformation and filtering.

```javascript
{extend name="admin@public/container" /}

{block name="content"}
<div class="layui-card">
    <div class="layui-card-body">
        <div class="layui-form-item">
            <button class='layui-btn layui-btn-sm layui-btn-active' id="importTopicBtn">
                <i class="layui-icon">&#xe67c;</i> 导入题库
            </button>
        </div>
    </div>
</div>
{/block}

{block name='script'}
<script>
$(function() {
    $('#importTopicBtn').on('click', function() {
        require(['excel'], function(Excel) {
            Excel.push('{:url("import")}', 'Sheet1', {
                _: 1,  // 第一行是表头
                '序号': 'no',
                '题目': 'name',
                '选项A': 'option_a',
                '选项B': 'option_b',
                '选项C': 'option_c',
                '选项D': 'option_d',
                '正确答案': 'answer',
                '类型': 'type',
                '难度': 'level',
                '解析': 'analysis'
            }, function(item) {
                // 数据过滤和转换
                
                // 跳过题目为空的记录
                if (!item.name || item.name.trim() === '') {
                    return false;
                }
                
                // 转换类型
                if (item.type === '单选题') {
                    item.type = 1;
                } else if (item.type === '多选题') {
                    item.type = 2;
                } else if (item.type === '判断题') {
                    item.type = 3;
                } else {
                    item.type = 1; // 默认单选题
                }
                
                // 转换难度
                if (item.level === '简单') {
                    item.level = 1;
                } else if (item.level === '中等') {
                    item.level = 2;
                } else if (item.level === '困难') {
                    item.level = 3;
                } else {
                    item.level = 1; // 默认简单
                }
                
                // 设置默认值
                if (!item.option_a) item.option_a = '';
                if (!item.option_b) item.option_b = '';
                if (!item.option_c) item.option_c = '';
                if (!item.option_d) item.option_d = '';
                if (!item.analysis) item.analysis = '';
                
                return item;
            });
        });
    });
});
</script>
{/block}
```

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

### System User Management List Example

Source: https://thinkadmin.top/system/helper-query.html

An example controller action demonstrating the use of `SystemUser::mQuery()->layTable()` for managing system user data. It includes setting the page title, fetching base data, defining query conditions, and establishing data associations.

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

namespace app\admin\controller;

use think\admin\Controller;
use think\admin\helper\QueryHelper;
use think\admin\model\SystemBase;
use think\admin\model\SystemUser;

class User extends Controller
{
    public function index()
    {
        $this->type = $this->get['type'] ?? 'index';
        SystemUser::mQuery()->layTable(function () {
            // 前置操作：设置模板变量
            $this->title = '系统用户管理';
            $this->bases = SystemBase::items('身份权限');
        }, function (QueryHelper $query) {
            // 后置操作：设置查询条件
            $query->where(['is_deleted' => 0, 'status' => intval($this->type === 'index')]);
            
            // 关联查询用户身份资料
            $query->with(['userinfo' => static function ($query) {
                $query->field('code,name,content');
            }]);
            
            // 数据列表搜索过滤
```

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

### Plugin Installation and Maintenance Commands

Source: https://thinkadmin.top/system/plugin-install.html

Commands for verifying plugin installation, removing packages, and cleaning up database or static assets.

```bash
# 1. 检查插件目录
ls -la vendor/zoujingli/think-plugs-account/

# 2. 检查数据库迁移文件
ls -la database/migrations/

# 3. 检查插件是否注册（在代码中）
# 访问后台，查看是否有插件菜单
```

```bash
# 卸载插件（注意：不会删除数据库表和配置文件）
composer remove zoujingli/think-plugs-account
```

```sql
-- 通过数据库管理工具删除插件相关的表
DROP TABLE IF EXISTS `plugin_account_user`;
DROP TABLE IF EXISTS `plugin_account_auth`;
```

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

### Helper Methods Usage Examples

Source: https://thinkadmin.top/system/core-functions.html

Examples of using built-in helper methods for data validation and queue management.

```php
// 数据验证
$data = $this->_vali([
    'username.require' => '用户名不能为空！',
    'email.email'      => '邮箱格式不正确！',
    'status.in:0,1'    => '状态值范围异常！',
]);

// 创建异步任务
$this->_queue('重新计算所有会员级别', "xsync:member", 1, [], 0);
```

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

### Add New Language Example

Source: https://thinkadmin.top/system/core-language.html

Shows how to create a new language file (e.g., `ja-jp.php`) for adding a new language, including sample translations.

```php
<?php
// app/admin/lang/ja-jp.php
return [
    'welcome' => 'ようこそ',
    'login_success' => 'ログイン成功',
];
```

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

### Module Plugin Configuration Example

Source: https://thinkadmin.top/system/plugin-install.html

A complete configuration for a module plugin that copies files to the app directory and cleans up the vendor source.

```json
{
  "type": "think-admin-plugin",
  "name": "zoujingli/think-plugs-admin",
  "description": "Admin Plugin for ThinkAdmin",
  "require": {
    "php": ">7.1",
    "zoujingli/think-library": "^6.1|@dev"
  },
  "autoload": {
    "psr-4": {
      "app\\admin\\": "src"  // 注意：命名空间指向 app\admin
    }
  },
  "extra": {
    "think": {
      "services": [
        "app\\admin\\Service"
      ]
    },
    "plugin": {
      "copy": {
        "src": "!app/admin",  // 绝对复制：先删除 app/admin，再复制
        "stc/database": "database/migrations"
      },
      "clear": true  // 安装后清理原安装目录
    }
  }
}
```

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

### Programmatically Change Admin Entry Point

Source: https://thinkadmin.top/system/core-runtime.html

This example demonstrates how to change the admin entry point path programmatically using RuntimeService::set() in a deployment script.

```php
use think\admin\service\RuntimeService;

// 将后台入口从 /admin 改为 /myadmin
// RuntimeService::set() 的第一个参数是运行模式（null 表示不修改）
// 第二个参数是应用映射数组
RuntimeService::set(null, ['myadmin' => 'admin']);

// 修改后，访问地址变为：
// http://yourdomain.com/myadmin
// http://yourdomain.com/myadmin.html
// 原来的 /admin 路径将无法访问
```

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

### Automatic Menu Generation on Plugin Install

Source: https://thinkadmin.top/system/plugin-menus.html

Explains that during plugin installation, the system automatically calls the `menu()` method defined in the plugin's Service class to generate and write menu data into the `system_menu` table.

```php
// 插件安装时，自动调用 menu() 方法
// 自动写入 system_menu 数据表
// 用户可以直接看到插件的菜单
```

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

### API Controller Implementation

Source: https://thinkadmin.top/system/extra-signapi.html

Example of extending the Auth controller to handle specific business logic.

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

namespace app\data\controller\api;

use think\admin\helper\QueryHelper;
use think\admin\model\SystemUser;

/**
 * API 接口控制器示例
 * @class Api
 * @package app\data\controller\api
 */
class Api extends Auth
{
    /**
     * 获取用户列表
     * 接口地址：/data/api/getUserList
     */
    public function getUserList()
    {
        // 接收并验证参数（从 $this->data 中获取已解析的数据）
```

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

### Controller Response Usage Examples

Source: https://thinkadmin.top/system/core-functions.html

Common patterns for triggering success, error, and redirect responses.

```php
// 成功响应
$this->success('操作成功！', $data);

// 错误响应
$this->error('操作失败，请稍后重试！');

// 带跳转的成功响应
$this->success('数据保存成功！', admuri('admin/config/index'));

// URL 重定向
$this->redirect('/admin/user/index');

// URL 重定向
$this->redirect('/admin/user/index');
```

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

### Array to String Conversion Example

Source: https://thinkadmin.top/system/core-functions.html

Demonstrates converting arrays to strings using different separators and handling potential null values.

```php
// 数组转字符串
$authorize = ['10001', '10002', '10003'];
$str = arr2str($authorize); // 输出: "10001,10002,10003"
$str = arr2str($authorize, '|'); // 输出: "10001|10002|10003"
```

```php
// 字符串转数组
$str = "10001,10002,10003";
$arr = str2arr($str); // 输出: ['10001', '10002', '10003']
$arr = str2arr($str, '|'); // 输出: ['10001', '10002', '10003'] (如果使用 | 分隔符)
```

```php
// 实际应用示例（在控制器中）
$data['authorize'] = arr2str($data['authorize'] ?? []); // 保存权限数组
$data['authorize'] = str2arr($data['authorize'] ?? ''); // 读取权限数组
```

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

### Get User List with Pagination

Source: https://thinkadmin.top/system/extra-signapi.html

Use the mQuery method for model-based queries with pagination. This is the recommended approach for fetching lists of users.

```PHP
$data = $this->_vali([
            'page.integer' => '页码格式错误！',
            'limit.integer' => '每页数量格式错误！',
            'status.in:0,1' => '状态值范围异常！'
        ], $this->data, [$this, 'error']);

        // 使用模型方法进行查询（推荐方式）
        $query = SystemUser::mQuery();
        $query->where(['is_deleted' => 0])
              ->like('username,nickname')
              ->equal('status')
              ->order('id desc');
        
        // 返回分页查询结果
        $this->success("获取成功", $query->page(true, false));
```

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

### Deeply Nested Language Structure Example

Source: https://thinkadmin.top/system/core-language.html

Illustrates a deeply nested language array structure, with a recommendation to keep nesting to 2-3 levels for clarity.

```php
<?php
// 支持但不推荐：嵌套过深
return [
    'level1' => [
        'level2' => [
            'level3' => [
                'level4' => '值'  // 不推荐
            ]
        ]
    ]
];

// 推荐：保持 2-3 层
return [
    'menu' => [
        'user' => '用户管理',  // 2 层，推荐
    ],
];
```

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

### Tag Input Initialization

Source: https://thinkadmin.top/system/extra-adminjs.html

Initialize a tag input field, allowing users to enter multiple tags separated by commas. This example shows the HTML input setup and the JavaScript initialization.

```html
<input type="text" name="tags" value="标签1,标签2,标签3">
<script>
$(function() {
    $('input[name="tags"]').initTagInput();
});
</script>
```

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

### Start Listener Process

Source: https://thinkadmin.top/system/core-asynchronous.html

Start the ThinkAdmin queue listener process using the `xadmin:queue start` command. This command should be run in a persistent environment (e.g., using supervisor).

```bash
# 2. 启动监听进程
php think xadmin:queue start
```

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

### Global Framework Configuration

Source: https://thinkadmin.top/system/extra-adminjs.html

Setting up paths and dependencies for the application, including LayUI and RequireJS.

```javascript
// 应用根路径（自动计算）
window.appRoot = '/static/';
window.baseRoot = '/static/';
window.tapiRoot = '/admin'; // 或通过 window.taAdmin 自定义

// LayUI 配置
layui.config({base: baseRoot + 'plugs/layui_exts/'});

// RequireJS 配置（支持多种插件库）
require.config({
    baseUrl: baseRoot,
    paths: {
        'excel': ['plugs/admin/excel'],
        'queue': ['plugs/admin/queue'],
        'upload': [tapiRoot + '/api.upload/index?'],
        'validate': ['plugs/admin/validate'],
        // ... 更多插件
    }
});
```

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

### Custom File Upload Controller Example

Source: https://thinkadmin.top/system/core-upload.html

Example of a custom controller for handling file uploads in ThinkAdmin.

```APIDOC
## Custom Upload Controller Example

### Description
This PHP code demonstrates how to create a custom controller for file uploads in ThinkAdmin, including file validation and storage.

### Method
POST

### Endpoint
/admin/api.upload/index (custom implementation)

### Parameters
#### Request Body
- **file** (file) - Required - The file to be uploaded.

### Backend Processing Example
```php
<?php
declare(strict_types=1);

namespace app\admin\controller\api;

use think\admin\Controller;
use think\admin\Storage;

/**
 * 文件上传接口（自定义示例）
 * @class Upload
 * @package app\admin\controller\api
 */
class Upload extends Controller
{
    /**
     * 文件上传处理
     * @login true  // 需要登录验证
     */
    public function index()
    {
        // 1. 获取上传的文件
        $file = $this->request->file('file');
        if (empty($file)) {
            $this->error('请选择要上传的文件');
        }
        
        // 2. 验证文件类型（可选，系统已内置验证）
        $allowExts = str2arr(sysconf('storage.allow_exts', 'jpg,png,gif'));
        $ext = strtolower($file->extension());
        if (!in_array($ext, $allowExts)) {
            $this->error('不支持的文件类型！');
        }
        
        // 3. 验证文件大小（可选，系统已内置验证）
        $maxSize = sysconf('storage.max_size', 2097152);  // 默认 2MB
        if ($file->getSize() > $maxSize) {
            $this->error('文件大小超过限制！');
        }
        
        // 4. 生成文件名称（使用 hash 命名，防止冲突）
        $filename = Storage::name($file->getPathname(), $ext, 'upload');
        // 生成规则：upload/ab/cd1234567890abcdef1234567890ab.jpg
        // 其中 ab/cd 是 hash 的前两位，用于目录分散
        
        // 5. 上传文件到存储（自动选择配置的存储方式）
        $result = Storage::instance()->set(
            $filename,
            file_get_contents($file->getPathname())
        );
        
        // 6. 返回结果
        if ($result) {
            $this->success('上传成功', $result);
        } else {
            $this->error('上传失败，请稍后重试！');
        }
    }
}
```

### Response
#### Success Response (200)
- **code** (integer) - Status code, 1 for success, 0 for failure.
- **info** (string) - A message indicating the result of the operation.
- **data** (object) - Contains details about the uploaded file (similar to the standard API response).

#### Response Example
```json
{
    "code": 1,
    "info": "上传成功",
    "data": {
        "url": "https://example.com/upload/image.jpg",
        "key": "image/ab/cd1234567890abcdef1234567890ab.jpg",
        "hash": "cd1234567890abcdef1234567890ab",
        "file": "image.jpg"
    }
}
```
```

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

### Cross-Application Resource Loading with __PLUG__

Source: https://thinkadmin.top/system/core-variables.html

Demonstrates how `__PLUG__` correctly resolves paths for different applications, ensuring resource isolation and preventing conflicts.

```html
<!-- admin 应用的模板 -->
<script src="__PLUG__/js/admin.js"></script>
<!-- 替换后：/static/extra/admin/js/admin.js -->

<!-- index 应用的模板 -->
<script src="__PLUG__/js/index.js"></script>
<!-- 替换后：/static/extra/index/js/index.js -->
```

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

### Install PhpSpreadsheet Dependency (Shell)

Source: https://thinkadmin.top/system/extra-import.html

This command installs the PhpSpreadsheet library, which is used for parsing Excel files in PHP.

```shell
composer require phpoffice/phpspreadsheet
```

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

### 控制器 initialize 方法实现

Source: https://thinkadmin.top/system/core-functions.html

initialize() 方法在控制器实例化后自动调用，适用于初始化公共属性、权限检查或数据预处理。

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

namespace app\admin\controller;

use think\admin\Controller;
use think\admin\Storage;

/**
 * 系统文件管理
 * @class File
 * @package app\admin\controller
 */
class File extends Controller
{
    /**
     * 存储类型列表
     * @var array
     */
    protected $types;

    /**
     * 控制器初始化
     * @return void
     */
    protected function initialize()
    {
        // 初始化存储类型列表（所有方法都可以使用）
        $this->types = Storage::types();
        
        // 可以在这里进行权限检查、数据初始化等
        // 例如：检查用户是否有文件管理权限
    }

    /**
     * 文件列表
     * @auth true
     */
    public function index()
    {
        // $this->types 已经在 initialize() 中初始化
        $this->title = '系统文件管理';
        // ...
    }
}
```

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

namespace app\data\controller\api;

use think\admin\Controller;
use think\admin\service\InterfaceService;

/**
 * API 基础控制器
 * @class Auth
 * @package app\data\controller\api
 */
class Auth extends Controller
{
    /**
     * 当前请求数据
     * @var array
     */
    protected $data;

    /**
     * 接口账号信息
     * @var array
     */
    protected $user;

    /**
     * 接口服务对象
     * @var InterfaceService
     */
    protected $interface;

    /**
     * 接口授权初始化（从数据库读取账号）
     */
    protected function initialize()
    {
        // 接口实例初始化
        $this->interface = InterfaceService::instance();

        // 验证 appid 参数
        $map = $this->_vali(['appid.require' => '参数APPID不能为空！']);
        
        // 从数据库中查询账号
        $this->user = $this->app->db->name('AppUser')->where($map)->find();

        // 验证账号是否存在
        if (empty($this->user)) {
            $this->interface->error('接口账号不存在！');
        }

        // 验证账号状态
        if (empty($this->user['status'])) {
            $this->interface->error('接口账号已被禁用！');
        }

        // 接口数据初始化
        $this->interface->setAuth($this->user['appid'], $this->user['appkey']);
        
        // 获取并验证接口数据
        $this->data = $this->interface->getData();
    }
}
```

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

### Simulate HTTP GET Request

Source: https://thinkadmin.top/system/core-functions.html

Performs an HTTP GET request to a specified URL. Supports query parameters and custom cURL options.

```php
// 参数 string $url HTTP请求URL地址
// 参数 array|string $query GET请求参数
// 参数 array $options CURL参数
// 返回 boolean|string
http_get(string $url, $query = [], array $options = []);
```

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

### Handle GET and POST Requests Separately

Source: https://thinkadmin.top/system/helper-form.html

Demonstrates how to differentiate between GET requests for data preparation and POST requests for data submission within _form_filter.

```php
protected function _form_filter(array &$data)
{
    if ($this->request->isGet()) {
        // GET 请求：准备表单显示数据
        // 加载关联数据、设置默认值、权限检查等
        $data['authorize'] = str2arr($data['authorize'] ?? '');
        $this->auths = SystemAuth::items();
        $this->bases = SystemBase::items('身份权限');
        
        // 设置默认值
        if (empty($data['id'])) {
            $data['status'] = 1;
            $data['create_at'] = date('Y-m-d H:i:s');
        }
    } else {
        // POST 请求：处理表单提交
        // 数据验证、转换、业务逻辑处理等
        empty($data['username']) && $this->error('登录账号不能为空！');
        
        // 数据转换
        $data['authorize'] = arr2str($data['authorize'] ?? []);
        
        // 业务逻辑验证
        if (empty($data['id'])) {
            // 新增时的特殊处理
            $data['password'] = md5($data['username']);
        } else {
            // 编辑时的特殊处理
            unset($data['username']);  // 不允许修改用户名
        }
    }
}
```

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

### QueryHelper Initialization and Usage

Source: https://thinkadmin.top/system/helper-query.html

Covers various ways to initialize QueryHelper using models or controllers, and how to chain query methods.

```php
// 1.0. 使用模型创建查询器（推荐方式）
// SystemUser 是已继承基础模型 \think\admin\Model 的模型类，mQuery() 方法是自定义的查询构建器。
$query = SystemUser::mQuery();

// 1.1. 控制器中使用原生查询器（指定表名或模型名）
$query = $this->_query('SystemUser');

// 2.0. 使用 layTable 方法（推荐方式，支持动态高度、搜索绑定）
SystemUser::mQuery()->layTable(function () {
    $this->title = '系统用户管理';
}, function (QueryHelper $query) {
    $query->where(['is_deleted' => 0, 'status' => 1]);
    $query->like('username,nickname')->equal('status');
    $query->dateBetween('create_at')->order('id desc');
});

// 2.1. 使用传入的 URL 参数进行查询条件设置
// 这里使用了 `like` 和 `equal` 方法分别处理模糊查询和精确查询。
$query->like('username,sex')->equal('status');

// 3.0. 执行分页查询，分页结果会自动返回，便于前端展示。
$query->page();

// 4.0. 使用别名来处理 URL 参数与数据库字段不匹配的情况。
// 例如，URL 参数 'username_alias' 对应数据库中的 'username' 字段，
// 'user_status' 对应数据库中的 'status' 字段。
$get = ['username_alias' => 'admin', 'user_status' => 1];
$query = $this->_query('SystemUser', $get)->like('username#username_alias,sex')->equal('status#user_status');

// 5.0. 执行分页查询。
$query->page();

// 6.0. 额外的列表数据赋值到模板：
// 这里查询所有状态为 1 的用户列表，并将结果传递给模板变量 $userList。
$this->userList = $this->_query('SystemUser')->where(['status' => 1])->select();

// 7.0. 接收 URL 参数，进行查询条件设置。
// 假设 URL 参数 'username' 和 'sex' 使用 `like` 模糊查询，'status' 使用 `equal` 精确查询。
$get = ['status' => 1, 'username' => 'admin'];
$query = $this->_query('SystemUser', $get)->like('username,sex')->equal('status');

// 8.0. 执行分页查询并返回结果。
$query->page();
```

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

### Example of Manual Menu Addition (Problematic)

Source: https://thinkadmin.top/system/plugin-menus.html

Highlights the administrative burden when plugins do not use the menu system, necessitating manual addition of each menu item through the backend's menu management interface, which is time-consuming for multiple plugins.

```php
// ❌ 需要手动在后台添加菜单
// 系统管理 → 菜单管理 → 添加菜单
// 每个插件都要手动添加，工作量大
```

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

### FormHelper 模板渲染

Source: https://thinkadmin.top/system/helper-form.html

GET 请求时自动渲染对应的表单模板。

```php
// GET 请求时，自动加载数据并渲染模板
SystemUser::mForm('form');
// 自动查找模板：view/user/form.html
```

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

### Troubleshoot Storage Configuration

Source: https://thinkadmin.top/system/core-storage.html

Verify configuration parameters and test connectivity.

```php
// 1. 检查配置参数
$config = sysconf('storage');
// 确保 access_key、secret_key 等参数正确

// 2. 测试连接
try {
    $result = Storage::instance()->has('test.txt');
} catch (\Exception $e) {
    echo '连接失败：' . $e->getMessage();
}
```

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

### Example of No Plugin Menu Usage (Problematic)

Source: https://thinkadmin.top/system/plugin-menus.html

Illustrates the user experience issue when a plugin does not utilize the menu system, requiring users to manually input URLs to access plugin functions, leading to poor user experience and forgotten entry points.

```php
// ❌ 不使用插件菜单：用户不知道插件有哪些功能
// 需要手动输入 URL 访问：/admin/plugin-account/index
// 用户体验差，容易忘记功能入口
```

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

### Define Language Pack with Parameters

Source: https://thinkadmin.top/system/core-language.html

Demonstrates defining language entries with single, multiple, and repeated parameters using placeholders.

```php
<?php
// app/admin/lang/zh-cn.php
return [
    // 单个参数
    'welcome_user' => '欢迎，{name}！',
    
    // 多个参数
    'user_info' => '用户 {name}，年龄 {age} 岁，来自 {city}',
    
    // 参数可以重复使用
    'user_message' => '{name} 给 {name} 发送了消息',
];
```

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

### 定义模块路由

Source: https://thinkadmin.top/system/core-route.html

在模块的 `route` 目录下定义路由规则，支持 GET 和 ANY 请求映射到控制器方法。也可以使用数组形式返回路由定义。

```php
<?php
// app/admin/route/demo.php

// 访问入口 index.php
// 访问地址 https://yourdomain.com/admin/demo
// 路由配置 app/admin/route/demo.php
app()->route->get('demo', 'test'); // 访问 /admin/demo 映射到 /admin/test

// 访问入口 index.php
// 访问地址 https://yourdomain.com/admin/demo2
// 路由配置 app/admin/route/demo.php
app()->route->any('demo2', 'user/index'); // 访问 /admin/demo2 映射到 /admin/user/index

// 也可以返回数组方式定义路由
return [
    'demo' => 'test',
    'demo2' => 'user/index',
];
```

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

### Full Command Example for Wechat Auto Message

Source: https://thinkadmin.top/system/core-asynchronous.html

A complete example of a ThinkAdmin command that sends auto-messages to WeChat users. It includes argument handling, data querying, and message sending logic. Ensure the `WechatAuto` model and message sending service are correctly implemented.

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

namespace app\wechat\command;

use think\admin\Command;
use think\console\Input;
use think\console\input\Argument;
use think\console\Output;

class Auto extends Command
{
    private $openid;

    protected function configure()
    {
        $this->setName('xadmin:fansmsg');
        $this->addArgument('openid', Argument::OPTIONAL, 'wechat user openid', '');
        $this->addArgument('autocode', Argument::OPTIONAL, 'wechat auto message', '');
        $this->setDescription('Wechat Users Push AutoMessage for ThinkAdmin');
    }

    protected function execute(Input $input, Output $output)
    {
        $code = $input->getArgument('autocode');
        $this->openid = $input->getArgument('openid');
        
        // 参数验证
        if (empty($code)) {
            $this->setQueueError('Message Code cannot be empty');
            return;
        }
        if (empty($this->openid)) {
            $this->setQueueError('Wechat Openid cannot be empty');
            return;
        }

        // 查询数据
        $map = ['code' => $code, 'status' => 1];
        $data = WechatAuto::mk()->where($map)->find();
        if (empty($data)) {
            $this->setQueueError('Message Data Query failed');
            return;
        }

        // 处理业务逻辑
        $this->buildMessage($data->toArray());
    }

    private function buildMessage(array $data)
    {
        // 处理消息逻辑
        $result = $this->sendMessage('text', ['content' => $data['content']]);
        
        if (empty($result[0])) {
            $this->setQueueError($result[1]);
        } else {
            $this->setQueueSuccess($result[1]);
        }
    }
}
```

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

### Switch Runtime Mode Programmatically

Source: https://thinkadmin.top/system/core-runtime.html

Provides examples of switching the application's runtime mode to 'product' or 'debug' using RuntimeService::set() in code, followed by cache clearing.

```php
use think\admin\service\RuntimeService;

// 切换到生产模式
// 参数 'product' 表示生产模式
RuntimeService::set('product');

// 切换到开发模式
// 参数 'debug' 表示开发模式
RuntimeService::set('debug');

// 切换后建议清理缓存
// 确保新模式的配置立即生效
RuntimeService::clear();

```

```php
<?php
// 在命令行脚本中切换模式
// 例如：php think deploy

use think\admin\service\RuntimeService;

// 部署到生产环境时，切换到生产模式
RuntimeService::set('product');

// 清理缓存
RuntimeService::clear();

echo "已切换到生产模式\n";

```

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

### System Configuration

Source: https://thinkadmin.top/system/core-functions.html

Functions for getting and setting system configuration parameters.

```APIDOC
## ⚙️ 获取或配置系统参数

### Description
Retrieves or sets system configuration parameters.

### Method
sysconf

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the configuration parameter.
- **value** (mixed) - Optional - The value to set for the parameter. If omitted, the current value is returned.

### Request Example
```php
// Get a single configuration
$siteName = sysconf('base.site_name');

// Get configuration with a default value
$siteUrl = sysconf('base.site_url', 'https://thinkadmin.top');

// Set a single configuration
sysconf('base.site_name', 'ThinkAdmin');

// Batch set configurations
foreach ($post as $k => $v) {
    sysconf($k, $v);
}
```

### Returns
- **mixed** - The value of the configuration parameter, or void if setting.
```

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

### 配置路由调试模式

Source: https://thinkadmin.top/system/core-route.html

通过修改 `config/route.php` 文件中的配置项，可以开启或调整路由的调试模式。例如，设置 `url_route_on` 为 `true`。

```php
// config/route.php
return [
    'url_route_on' => true,
    'url_route_must' => false,
    'route_complete_match' => false,
    'url_domain_deploy' => false,
];
```

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

### Path Variable Replacement in Production Environment

Source: https://thinkadmin.top/system/core-variables.html

Demonstrates the resolution of `__FULL__` to the production domain name when the application is deployed.

```html
<!-- 模板中 -->
<script src="__FULL__/static/js/app.js"></script>

<!-- 生产环境替换后 -->
<script src="https://www.example.com/static/js/app.js"></script>
```