声明式注册（PluginRegistrar）

app\basic\PluginRegistrar 让插件用代码声明菜单、按钮权限、后台配置，落库结构与后台管理完全同构。三个方法都幂等：命中相同 code/slug 则同步字段、无变化则跳过，可放在 boot() 或安装/启用钩子里重复调用。

必带 app_name

一切声明必须携带 app_name = 插件名，卸载时基座按 app_name 物理清理。

菜单

use app\basic\PluginRegistrar;

PluginRegistrar::menu([
    'app_name' => 'am_demo',
    'name'     => '工单管理',
    'code'     => 'am_demo:ticket',   // 全局唯一；禁止占用保留前缀 app:entry:*
    'type'     => 2,                  // 1 目录 / 2 菜单 / 3 按钮 / 4 外链
    'path'     => '/am_demo/ticket',
    'component'=> 'am_demo/ticket/index',
    'icon'     => 'ri:ticket-line',
    'parent_code' => 'am_demo',       // 可选：挂到本插件/基座某个目录下
]);

字段可选：pid / sort / is_hide / is_cache / is_fixed / is_full_page / is_iframe / status。

按钮权限

PluginRegistrar::permission([
    'app_name'   => 'am_demo',
    'title'      => '新增工单',
    'slug'       => 'am_demo:ticket:add',   // 冒号格式 {module}:{action}:{operation}
    'parent_code'=> 'am_demo:ticket',
]);

slug 与前端 #[Permission] / 权限指令一一对应。

后台配置 Schema

PluginRegistrar::configSchema([
    'app_name' => 'am_demo',
    'group'    => ['code' => 'am_demo_setting', 'name' => '工单设置'],
    'fields'   => [
        ['name' => '自动分派', 'key' => 'auto_assign', 'type' => 'switch', 'defaultValue' => 0],
        ['name' => '默认处理人', 'key' => 'assignee', 'type' => 'input'],
    ],
]);

声明后，后台「配置管理」会直接渲染出对应表单，插件即获得"声明即有配置界面"。字段已填的值不会被覆盖，只同步 schema。读取配置用基座缓存 ConfigCache::getConfig('am_demo_setting', 'am_demo')（务必传同一 app_name，否则命中不到缓存桶）。

与 install.sql 并存

静态 SQL 建菜单与声明式 API 可并存：声明式为增量，命中更新、缺失插入，不冲突。