初始化本地仓库

2026-08-31 11:33:59 +08:00
commit 663f74b633
2390 changed files with 402918 additions and 0 deletions
@@ -0,0 +1,536 @@
+---
+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 无冲突。
+- 菜单、权限、路由一致。
+- 模板源前端完整。
+- 运行目录联调通过。
+- 卸载再安装不回退。
+
+若只完成运行目录修改，不能判定为插件开发真正完成。