---
name: cross-plugin-fullstack-development
description: Full-stack development workflow for Madong plugins. Covers plugin structure, backend CRUD and Swagger, frontend template source, menu import, install copy behavior, i18n, verification, and anti-regression rules for uninstall/reinstall scenarios.
globs:
  - "backend/plugin/**/*.php"
  - "backend/plugin/**/config/**/*.php"
  - "backend/plugin/**/resource/**/*.php"
  - "backend/plugin/**/resource/template/admin/**/*"
  - "frontend/admin/src/apps/**/*.vue"
  - "frontend/admin/src/apps/**/*.tsx"
  - "frontend/admin/src/apps/**/*.ts"
  - ".windsurf/skills/**/*.md"
---

# Madong 插件全流程开发技能

用于开发类似 `article` 这样的完整插件，覆盖从目录结构、后端 CRUD、Swagger、菜单导入、前端模板源、安装复制机制、国际化，到卸载重装后的防回退验证。

## 适用场景

- 新建一个完整业务插件。
- 为已有插件补齐后台 CRUD、前台模板、菜单和语言文件。
- 修复插件卸载再安装后的页面回退、菜单异常、Swagger 冲突。
- 将一次真实插件开发过程沉淀为可复用工作流。

## 总原则

1. 先核对项目真实实现，再使用 skill 或模板。
2. 插件前端的权威源目录是 `backend/plugin/{plugin}/resource/template/admin`，不是运行目录。
3. 安装后复制出来的 `frontend/admin/src/apps/{plugin}` 属于运行产物，不作为正式开发目录；若只改这里，卸载重装会回退。
4. 后端 Swagger 路由必须唯一，旧演示接口不可与新 CRUD 路由重复。
5. 插件菜单以安装导入的系统菜单为准，不依赖前端自动扫描插件路由生成侧边栏。
6. 前后端路径、权限码、菜单 component、i18n key 必须一致。
7. 插件 skill 若与真实项目不一致，先更新 skill 再继续生成或修改。
8. 插件开发顺序默认采用 template-first：后端完成后直接开发 `resource/template/admin`，不再单独维护运行目录。

## 先理解插件安装与复制机制

### 1. 模板源与运行目录

**模板源目录：**

```text
backend/plugin/{plugin}/resource/template/admin/
```

**安装后目标目录：**

```text
frontend/admin/src/apps/{plugin}/
```

当前项目会在插件安装时通过 `core\plugin\traits\TemplateTrait::copyTemplateDir('admin')`
把模板源整体复制到前端运行目录。

### 2. 关键结论

- 改 `frontend/admin/src/apps/{plugin}` 只会影响当前运行结果。
- 改 `backend/plugin/{plugin}/resource/template/admin` 才能影响未来安装结果。
- 只要模板源还是旧版，卸载再安装就会把旧版重新覆盖回来。

### 3. 正确维护顺序

修改插件前端时遵循：

1. 先完成后端开发与接口联调。
2. 后端完成后，直接在 `backend/plugin/{plugin}/resource/template/admin` 下开发前端模板源。
3. 不要把 `frontend/admin/src/apps/{plugin}` 作为正式开发目录。
4. 完成模板源后，通过插件安装或复制流程生成运行目录并验证结果。
5. 仅当用户明确要求排查运行态问题时，才临时查看运行目录，但不要把它作为主维护对象。

## 开发前检查

### 1. 确认插件真实目录结构

以 `article` 为例：

```text
backend/plugin/article/
├── app/
├── config/
├── resource/
│   ├── menu/
│   ├── template/admin/
│   └── ...
```

至少核对：

- `app/adminapi/controller`
- `app/service/admin`
- `app/dao`
- `app/model`
- `app/validate` 或 `app/adminapi/validate`
- `resource/template/admin/api`
- `resource/template/admin/views`
- `resource/template/admin/lang`
- `resource/menu/admin.php`
- `config/translation.php`
- `config/route.php`

### 2. 确认参考实现

优先寻找以下真实参考：

- 同类已完成插件
- 主项目现有 `BasicCrud` 页面
- 主项目已接好 Swagger 的 `Crud` 控制器
- 现有插件菜单定义
- 现有插件语言文件加载方式

### 3. Windows 开发环境检查
在 Windows 下开发插件时，注意新插件目录创建本身未必会立即触发外层监控重启。
如果新插件接口返回 404，需要核对监控是否覆盖 `backend/plugin` 根目录变更。
## 插件目录与产物约定
## 后端
```text
backend/plugin/{plugin}/app/
├── adminapi/controller/
├── adminapi/validate/
├── api/controller/
├── dao/
├── model/
├── schema/request/
├── schema/response/
└── service/admin/
```
## 模板源前端
```text
backend/plugin/{plugin}/resource/template/admin/
├── api/index.ts
├── lang/
│   ├── zh-cn/zh.json
│   └── en/en.json
└── views/{plugin_key}/{module}/
    ├── index.vue
    └── schemas/index.tsx
```
## 安装后前端运行目录
```text
frontend/admin/src/apps/{plugin}/
├── api/index.ts
├── lang/
│   ├── zh-cn/zh.json
│   └── en/en.json
└── views/{plugin_key}/{module}/
    ├── index.vue
    └── schemas/index.tsx
```
## 后端开发流程

### 1. 数据库迁移

路径：

```text
backend/plugin/{plugin}/resource/database/migrations/
```

要求：

- 主键优先使用雪花 ID：`bigInteger('id')->primary()`。
- 按真实项目风格补齐索引、时间字段、软删除字段。
- 状态字段优先使用 `enabled` 或业务已有枚举字段。
- 不要直接照搬 Laravel 默认 `id()`。
- 不要从旧项目或旧插件盲目继承 `tenant_id`、多租户索引、租户作用域；必须先核对当前项目是否仍为单租户结构。

### 2. Model / DAO / Service / Validate

要求：

- Model 继承插件或项目当前实际使用的 `BaseModel`。
- DAO 继承 `core\base\BaseDao`。
- Service 继承 `core\base\BaseService`。
- Validate 继承 `core\base\BaseValidate`。
- 自定义业务逻辑放在 Service，不要塞进 Controller。

本项目额外要求：

- DAO / Service 文件中必须显式 `use core\base\BaseDao;`、`use core\base\BaseService;`，不能只写 `extends BaseDao/BaseService` 而省略导入。
- Service 构造函数使用容器注入 DAO，例如 `__construct(FooDao $dao)`，不要在 Service 内部手动 `new FooDao()`。
- 如果 DAO 重写 `selectList()`，方法签名必须与当前项目 `BaseDao` 保持一致，包括：
  - `string|array $field = '*'`
  - `int $page = 0`
  - `int $limit = 0`
  - `bool $search = false`
  - `?array $withoutScopes = null`
- `getKeywordFields()` 优先使用 `protected`，与当前项目已落地 DAO 风格保持一致。
- 若页面会通过 `Crud` 的 `format=select` 复用下拉，模型应提供 `getNameAttribute()`，把业务显示字段映射到 `name`，以兼容 `title / name / real_name / id` 标签解析顺序。
- JSON 字段应同时在 Model 中配置 `casts`，并在 Validate 中支持“数组或 JSON 字符串”两种输入形态。

### 3. Admin 控制器与 CRUD

控制器通常放在：

```text
backend/plugin/{plugin}/app/adminapi/controller/
```

要求：

- 继承 `app\adminapi\controller\Crud`。
- 构造函数注入 Service 和 Validate。
- 标准方法走 `parent::index()`、`parent::show()`、`parent::store()`、`parent::update()`、`parent::destroy()`。
- 路由路径与前端 `BaseService` 的 `baseUrl` 一致。

### 4. Swagger / OpenAPI 规范

插件最容易踩的坑之一是 Swagger 路由冲突。

必须遵守：

- 每个 `OA\Get`、`OA\Post`、`OA\Put`、`OA\Delete` 的 `path` 必须唯一。
- 新 CRUD 控制器不要和旧 demo Controller 使用相同路径。
- 若存在旧演示接口，迁移到 `legacy` 命名空间或改用不冲突路径。
- 详情、删除、批量删除等接口按项目现有 Swagger 属性写法统一。
- `IdRequest`、`BatchDeleteRequest`、`SchemaConstants::X_SCHEMA_REQUEST` 等参数约定要与项目现有控制器保持一致。

### 5. 路由与权限码

建议保持如下映射：

```text
GET    /{plugin}/{resource}
GET    /{plugin}/{resource}/{id}
POST   /{plugin}/{resource}
PUT    /{plugin}/{resource}/{id}
DELETE /{plugin}/{resource}/{id}
```

要求：

- `addAuth`、`editAuth`、`removeAuth`、`viewAuth` 与后端权限码一致。
- 菜单按钮权限码与控制器 `Permission` 属性一致。
- 不要出现前端权限码、后端权限码、菜单权限码三套不一致。

## 前端模板源开发流程

### 1. 后端完成后直接开发模板源

插件前端正式维护目录：

```text
backend/plugin/{plugin}/resource/template/admin/
```

后端完成后，直接在该目录开发插件前端。
默认不要单独开发 `frontend/admin/src/apps/{plugin}`。
运行目录只作为安装产物和验证结果使用。

### 2. index.vue 统一使用官方 BasicCrud

标准页面入口应为：

- `BasicCrud`
- `useCrud`
- `crudSchema`

不要继续保留插件 demo 里的：

- `el-card`
- 手写 `el-table`
- `fetchData()` 拉取列表

### 3. schemas/index.tsx

要求：

- 使用 `CrudSchema`。
- 列表接口优先接 `BaseService.list`。
- 标准 CRUD 页面使用 `crudApi.add/edit/remove/view`。
- `rowKey` 默认使用 `id`。
- 表头索引统一使用 `article.common.columns.index` 这类语言键。
- 查询条件使用项目真实后端支持的查询参数格式，例如 `LIKE_name`、`LIKE_title`。

### 4. API 层

插件模板 API 通常放在：

```text
backend/plugin/{plugin}/resource/template/admin/api/index.ts
```

要求：

- 使用 `BaseService` 生成标准 CRUD Service。
- 仍可保留兼容旧页面的 `pluginApi` 包装方法。
- `baseUrl` 必须与后端控制器路径一致。
- 自定义只读接口可继续使用 `request.get()` 封装。
- 如运行目录为调试临时新增了 API 类型、Service 或语言键，最终必须同步回模板源，否则插件重装后会回退。

### 5. i18n 语言文件

路径：

```text
backend/plugin/{plugin}/resource/template/admin/lang/zh-cn/zh.json
backend/plugin/{plugin}/resource/template/admin/lang/en/en.json
```

要求：

- 语言文件根对象使用插件名，例如 `article`。
- 如果 `schemas` 中使用了：
  - `common.columns.index`
  - `modules.*.search.*`
  - `modules.*.form.*`
  - `modules.*.columns.*`
  则中英文都必须补齐。
- 不要只改中文不改英文，也不要只改运行目录不改模板源。

## 插件菜单与路由加载规则

### 1. 插件菜单来源

插件侧边栏应来自**安装时导入的系统菜单**，不是前端自动扫描插件 `routes/index.ts`。

因此：

- 不要依赖 `frontend/admin/src/apps/{plugin}/routes/index.ts` 自动显示菜单。
- 插件安装后应由 `sys_menu` 数据决定导航是否出现。

### 2. 菜单 component 路径

菜单中的 `component` 应填写相对 `views` 的组件路径，并包含插件 key 目录段。

例如页面文件：

```text
frontend/admin/src/apps/article/views/article/content/index.vue
```

则菜单 component 应使用类似：

```text
/article/content/index
```

### 3. meta.module

安装导入菜单时，`app` 字段应默认使用插件名 `{plugin}`，以便运行时生成：

```text
meta.module = {plugin}
```

这样组件加载器才会到：

```text
frontend/admin/src/apps/{plugin}/views...
```

去查找页面。

## 防回退规则

这是插件开发最重要的回归规则。

### 1. 何时会回退

满足以下条件时，卸载再安装会回退：

- 你只改了 `frontend/admin/src/apps/{plugin}`。
- 模板源 `backend/plugin/{plugin}/resource/template/admin` 仍是旧版。
- 重装时安装器重新复制旧模板源。

### 2. 如何避免回退

每次插件前端修改完成后，必须检查：

- `index.vue` 是否同步到模板源。
- `schemas/index.tsx` 是否同步到模板源。
- `api/index.ts` 是否同步到模板源。
- `lang/zh-cn/zh.json` 与 `lang/en/en.json` 是否同步到模板源。

### 3. 最终交付规则

若用户要求“以后重装不要丢”，交付标准不是“当前页面能看”，而是：

- 运行目录正常。
- 模板源正常。
- 卸载后重装仍正常。

## 推荐开发顺序

1. 明确插件名、模块名、路由、权限码。
2. 建迁移、模型、DAO、Service、Validate、Controller。
3. 接好 Swagger 注解，先排除路由冲突。
4. 配置菜单与权限。
5. 在模板源下实现前端 `api + index.vue + schemas + lang`。
6. 安装插件，复制模板到运行目录。
7. 在运行目录联调。
8. 如联调时临时改了运行目录，最终再同步回模板源。
9. 卸载再安装，确认不回退。

## 验证清单

### 后端验证

- 启动后无 Swagger `Unable to merge @OA\Get()` 等冲突。
- CRUD 路由与权限码可正常访问。
- 列表接口返回 `items/total`，与 `Crud::formatNormal()` 对齐。
- 删除接口支持单个 `id` 或批量 `ids`，与项目基类能力一致。

### 前端验证

- 页面使用官方 `BasicCrud` 外观。
- 列表数据结构与 `BaseService` 返回兼容。
- 中英文切换无缺失 key。
- 菜单能正常打开到对应插件页面。

### 重装验证

- 卸载插件。
- 重新安装插件。
- 确认 `frontend/admin/src/apps/{plugin}` 被重新复制后，页面仍保持最新结构。
- 确认没有回退到旧 `el-table` demo 版本。

## 常见坑位

### 1. Swagger 冲突

原因：

- 新旧控制器共用了同一路径。
- 旧 `ArticleController` demo 接口未迁移。

处理：

- 迁移旧接口到 `legacy` 路径。
- 新 CRUD 控制器使用正式资源路径。

### 2. 重装后页面回退

原因：

- 只改运行目录，没改模板源。

处理：

- 以模板源为主，运行目录为辅。

### 3. 插件菜单显示异常

原因：

- 把插件前端 routes 自动扫描混进了静态路由。
- 未安装插件也显示菜单。

处理：

- 插件导航仅依赖后端导入菜单。
- 不把 apps 自动扫描结果混进后端菜单模式。

### 4. 模板目录编辑器报别名错误

现象：

- `@/components/crud`
- `@/locales`
- `@/enums`

原因：

- 模板源目录不是主前端 tsconfig 的真实编译入口。

结论：

- 这是编辑器静态提示，不等于安装后运行目录会构建失败。
- 但模板源文件内容仍要与运行目录保持一致。

### 5. 插件第二批模块可打开但接口 500

常见根因：

- Service 忘记显式导入 `core\base\BaseService`
- DAO 忘记显式导入 `core\base\BaseDao`
- Service 构造器手动 `new Dao()`，未按项目真实风格使用容器注入
- DAO 重写 `selectList()` 但方法签名与当前 `BaseDao` 不一致

处理：

- 优先对照同插件已可用一期模块的 DAO / Service 写法，不要只凭旧记忆生成。
- 修复顺序优先：`use` 导入 -> 构造注入 -> 方法签名 -> 关联字段 / validate。

### 6. 旧项目字段迁移后前端下拉不显示名称

常见根因：

- 模型没有提供 `name` 访问器
- `Crud::formatSelect()` 只能按 `title / name / real_name / id` 兜底取标签

处理：

- 为需要复用 `format=select` 的模型增加 `getNameAttribute()`，将实际显示字段映射到 `name`。

### 7. JSON 规则字段仅在后端可存，前端表单难以维护

处理建议：

- 后端 Validate 接受数组和 JSON 字符串双形态。
- 模型 `casts` 统一转为数组。
- 模板源 `schemas` 中优先使用 textarea 输入 JSON 文本，并同步中英文 placeholder。

### 8. Windows 下修改插件 Seeder / Install 后重装仍执行旧逻辑

现象：

- 已修改 `backend/plugin/{plugin}/resource/database/seeds/*.php` 或 `backend/plugin/{plugin}/Install.php`。
- 重新点击插件安装后，菜单等流程有变化，但 Seeder 结果仍像旧代码。
- 日志看不到新的种子插入 SQL。

常见根因：

- Windows 开发态 `config/process.php` 中 `process.monitor.constructor.options.enable_file_monitor` 被关闭。
- 运行中的 Webman 进程未重载，仍持有旧版类定义。
- `SeedTrait::runSeed()` 使用 `require_once`，同一进程内不会重新加载已声明 Seeder 类。

处理：

- 确认 `backend/config/process.php` 的 `enable_file_monitor` 在 Windows 开发态也开启。
- 修改插件 `Seeder / Install / Controller / Service / Dao` 后，若不确定是否已重载，先手动重启后端进程再验证。
- 排查“重装插件不生效”时，不要只盯安装接口日志，还要先确认当前进程是否加载了最新代码。

## 输出契约

当用户要求“完成一个插件开发”时，至少应交付：

- 后端 CRUD 可运行。
- Swagger 无冲突。
- 菜单、权限、路由一致。
- 模板源前端完整。
- 运行目录联调通过。
- 卸载再安装不回退。

若只完成运行目录修改，不能判定为插件开发真正完成。