# Plugin Standard

## 当前结论
- `app/*` 负责本地多应用与过渡代码。
- `plugin/*` 负责插件业务实现。
- 插件分发优先于本地应用分发。
- 默认本地应用为 `app/index`。

插件标准由以下部分共同约束：
- `think\admin\Plugin`
- `think\admin\service\AppService`
- System 内置的 `plugin\system\helper\plugin\PluginMenuService`
- System 内置的 `plugin\system\helper\migration\PhinxExtend`
- `composer.json > extra.xadmin`
- `composer.json > extra.xadmin.publish.copy`
- 架构边界与安装边界测试

## 插件包标准

### 1. Composer 类型
- 参与运行时插件分发的组件统一使用 `think-admin-plugin`。
- 纯开发、交付辅助能力统一内置到 `ThinkPlugsSystem`，不再新增独立工具包。
- 安装协调组件 `ThinkPlugsInstall` 统一使用 `composer-plugin`，负责接管 Composer 生命周期内的自动发布与按需迁移。

### 2. 服务发现
- 必须通过 `extra.think.services` 注册插件服务类。
- 标准服务类命名为 `plugin\\{name}\\Service`。

### 3. 元数据
- `extra.xadmin.app` 只描述应用级元数据。
  必填：`code`、`name`
  可选：`prefix / prefixes / alias / space / document / description / platforms / license / icon / cover / super`
- `version`、`homepage` 等标准包字段继续使用 Composer 顶层定义，不再放到 `extra.xadmin.app`。
- `extra.xadmin.menu` 按需描述菜单显示、根节点、菜单项与存在性检测。
- `extra.xadmin.migrate` 按需描述主迁移脚本信息。
- `extra.xadmin.publish.copy` 按需描述资源发布规则，统一使用 `copy` 清单。

运行时插件最小 `composer.json` 骨架：

```json
{
  "type": "think-admin-plugin",
  "name": "vendor/demo-plugin",
  "description": "Demo Plugin for ThinkAdmin",
  "autoload": {
    "psr-4": {
      "plugin\\\\demo\\\\": "src"
    }
  },
  "extra": {
    "think": {
      "services": [
        "plugin\\\\demo\\\\Service"
      ]
    },
    "xadmin": {
      "app": {
        "code": "demo",
        "name": "演示插件",
        "prefix": "demo"
      }
    }
  }
}
```

纯工具组件可按需保留 `type=library`，并省略 `menu / migrate / publish` 等运行时块。

## 目录标准

### 1. 插件根目录
- `composer.json`
- `readme.md`
- `readme.api.md`
- `src`
- `stc`
- `tests`

### 2. 插件文档
- 每个插件根目录只保留两份说明文档：`readme.md` 与 `readme.api.md`。
- `readme.md` 只描述插件定位、边界、依赖与入口，不堆放接口明细、迁移细节或大段历史说明。
- `readme.api.md` 统一描述接口标准与接口列表。
- HTTP 插件在 `readme.api.md` 中按 `路由 + 请求方式 + 参数 JSONC` 组织，参数字段必须逐项写注释。
- HTTP 插件的 `readme.api.md` 必须补充标准 JSON 响应结构，至少说明 `code`、`info`、`data` 字段和常用状态码 `200/401/403/404/500`。
- 命令型或发布型组件在 `readme.api.md` 中按 `命令/配置入口 + 参数 JSONC` 组织，配置字段必须逐项写注释。
- 插件目录下不再追加第三份功能说明、临时接入文档或历史迁移说明，额外专题文档统一放到仓库 `docs/`。

### 3. `src` 根目录
- 必须保留 `Service.php`。
- 只有确实需要全局函数时才保留 `common.php`。
- 不再新增职责模糊的根级文件。

### 4. 常用子目录
- `controller`
- `model`
- `service`
- `view`
- `command`
- `lang`
- `worker`
- `tests`

## 运行时标准

### 1. 路由优先级
1. 先按插件前缀匹配。
2. 再按本地应用首段匹配。
3. 再按根目录全局路由目标声明匹配。
4. 再按动态插件切换匹配。
5. 最后回退到默认本地应用。

### 2. 标准入口
- 本地应用页面：`/{app}/{controller}/{action}`
- 插件页面：`/{plugin}/...`
- 插件接口：`/api/{plugin}/{controller}/{action}`

### 3. 根路由声明
- 优先使用 `Route::bindApp()` 与 `Route::bindPlugin()`。
- 分组场景使用 `Route::appGroup()` 与 `Route::pluginGroup()`。
- 根路由里的目标地址必须写成目标应用内部的相对节点。

### 4. 动态切换
- `_plugin` 与 `X-Plugin-App` 仅作为调试入口。
- 默认关闭，不作为正式业务路由依赖。

### 5. JSON 响应标准
- HTTP JSON 接口统一返回 HTTP `200`，前后端不再使用 `1/0` 表示成功或失败。
- 业务状态统一写入 `code` 字段，不再重复返回 `status`。
- `200` 表示成功，业务数据通过 `data` 返回。
- `401` 表示未认证、登录过期、令牌无效或会话失效。
- `403` 表示已认证但无权限、账号禁用或访问被拒绝。
- `404` 表示接口或资源不存在。
- `500` 表示服务端异常或未分类业务异常。

## 插件服务标准

### 1. 基类
- 参与运行时插件发现、路由或菜单元数据注入的服务统一继承 `think\admin\Plugin`。
- 纯命令或工具组件如不参与运行时插件装配，可继续继承 `think\Service`。

### 2. 职责
- 注册插件运行时能力。
- 处理必要的中间件或路由挂载。
- 承接 `composer.json` 中声明的插件元数据与发布规则。
- 纯工具组件只承接命令注册或工程化能力，不承担运行时插件装配职责。

### 3. 非职责
- 不在服务类中堆放业务逻辑。
- 不在服务类中维护大量兼容桥接代码。
- 不在服务类中声明运行时元数据字段或 `menu()` 之类的旧入口。

## 菜单与权限标准
- 菜单数据统一来自 `composer.json > extra.xadmin.menu.items`。
- 菜单引用的控制器节点必须真实存在。
- 叶子节点必须同时声明 `@auth true` 与 `@menu true`。
- 菜单写入前必须经过 `PluginMenuService::assertMenus()` 校验。

## 数据库与发布标准
- 每个插件只保留一份最终安装迁移脚本。
- 主迁移脚本以插件内 `stc/database` 为准。
- 自动迁移开关统一来自 `composer.json > extra.xadmin.migrate`；未声明时只能提示，不能在 Composer 安装链路中强制建表。
- 发布资源统一来自 `composer.json > extra.xadmin.publish.copy`。
- 发布规则只保留 `copy`，结构化规则统一使用 `source: { to, force, exclude }` 或 `{ from, to, force, exclude }`。
- 自动发布与按需迁移统一由 `zoujingli/think-plugs-install` Composer plugin 驱动，根项目需通过 `config.allow-plugins` 显式允许。
- 首次 Composer 安装只执行发布，不自动建表；后续变更才依据 `extra.xadmin.migrate` 做自动迁移。
- 根目录 `database/migrations` 视为发布产物，不是主维护源。
- 共享表必须遵守固定归属，不允许多插件重复持有。

## 依赖标准
- 本地插件依赖统一走 Composer `path` repository。
- 依赖图必须尽量保持无环。
- `ThinkPlugsSystem` 可以依赖 `library / static / worker`，并内置 storage 与 helper 能力。
- 业务插件不应重新把共享基础能力耦回 `system` 或 `library`。

## 测试要求
- 新增插件必须通过安装边界、路由边界、目录边界和迁移边界测试。
- 菜单、入口、迁移和 URL 规则必须有最小回归覆盖。

## 新插件准入清单
1. 提供独立 `composer.json`。
2. 提供 `src/Service.php`。
3. 在 `extra.xadmin.app` 中声明 `code / prefix / name`。
4. 有后台菜单时，在 `extra.xadmin.menu` 中声明菜单元数据。
5. 需要发布资源时，在 `extra.xadmin.publish.copy` 中声明规则。
6. 需要安装表结构时，在 `stc/database` 中保留唯一主迁移脚本，并通过 `extra.xadmin.migrate` 声明主脚本。
7. 运行时插件服务继承 `think\admin\Plugin`；纯工具组件按需继承 `think\Service`。
8. 不在 `Service.php` 中声明元数据字段或 `menu()` 兼容入口。
9. 补齐最小安装与路由测试。