Files

T

2026-08-31 11:33:59 +08:00

7.8 KiB

Raw Blame History

description

description
Madong 插件全流程开发执行工作流

插件开发执行 Workflow

用于按步骤执行一个 Madong 插件的完整开发流程，覆盖需求确认、目录核对、后端 CRUD、Swagger、菜单、前端模板源、安装验证，以及卸载重装防回退验证。

执行本 workflow 前，优先参考：

.windsurf/skills/cross-plugin-fullstack-development/SKILL.md

Step 1. 明确输入信息

先向用户确认以下信息，不完整时不要直接生成代码：

插件名，例如 article
插件显示名称
插件 key / 业务目录名
需要开发的模块列表，例如 content、category、tag
每个模块的数据库表名
字段定义、索引、是否软删除
后端路由前缀
权限码前缀
是否需要前台 API
是否需要菜单导入
是否要求卸载再安装后仍保留最新前端结构

如果用户给的是表结构或截图，先整理成统一规格后再继续。

Step 2. 核对现有插件与参考实现

优先读取并核对以下路径：

backend/plugin/{plugin}/app
backend/plugin/{plugin}/config
backend/plugin/{plugin}/resource/menu
backend/plugin/{plugin}/resource/template/admin
.windsurf/skills/cross-plugin-fullstack-development/SKILL.md

同时寻找至少一个真实参考实现：

同类已完成插件
主项目现有 BasicCrud 页面
现有 CRUD 控制器
现有插件菜单与语言文件

如果发现 skill 与真实项目结构不一致，先修正 skill，再继续开发。

Step 3. 建立开发计划

将任务拆成 3 到 5 个里程碑，并保持只有一个 in_progress：

后端结构与数据层
控制器、Swagger 与菜单
前端模板源开发与安装验证
重装验证与收口

如任务只是补模板源或补语言文件，可用更轻量计划。

Step 4. 搭建或核对后端数据层

按模块逐项处理：

迁移文件
Model
DAO
Service
Validate
Request / Response Schema

检查点：

主键是否使用项目当前雪花 ID 写法
字段、索引、软删除是否与需求一致
DAO / Service / Validate 基类是否与项目一致
命名空间是否在插件路径下正确展开
DAO / Service 是否显式导入 core\base\BaseDao / core\base\BaseService
Service 是否使用构造注入 DAO，而不是手动 new Dao()
如 DAO 重写 selectList()，方法签名是否与当前项目 BaseDao 一致
如果模块来自旧项目迁移，是否已确认当前项目是否仍需要 tenant_id

Step 5. 实现 Admin 控制器与标准 CRUD 路由

为每个模块实现 Admin 控制器，并保证：

继承 app\adminapi\controller\Crud
构造函数注入 Service 与 Validate
标准方法优先复用父类
路由前缀与前端 API 一致
权限码与菜单按钮权限一致

如存在旧 demo 控制器，先确认是否会与新 CRUD 冲突。

Step 6. 处理 Swagger / OpenAPI

在继续前端之前，必须先排除 Swagger 冲突。

逐项核对：

新旧控制器是否使用重复 path
OA\Get、OA\Post、OA\Put、OA\Delete 是否唯一
QueryRequest / FormRequest / Response Schema 是否对应
批量删除、详情、列表等接口注解是否与项目现有写法一致

如果旧演示接口与新接口冲突：

改到 legacy 路径
或迁移到单独演示控制器
不要直接删除未经确认的旧内容

Step 7. 配置插件菜单与权限

核对并维护：

backend/plugin/{plugin}/resource/menu/admin.php
菜单 component 路径
菜单 app 字段
权限码与控制器一致性

必须保证：

插件菜单来源于安装导入的系统菜单
不依赖前端自动扫描插件 routes 作为导航入口
component 指向插件 views 实际路径

Step 8. 在模板源实现前端

正式开发目录应放在：

backend/plugin/{plugin}/resource/template/admin/api
backend/plugin/{plugin}/resource/template/admin/views
backend/plugin/{plugin}/resource/template/admin/lang

按模块实现：

api/index.ts
views/{plugin_key}/{module}/index.vue
views/{plugin_key}/{module}/schemas/index.tsx
lang/zh-cn/zh.json
lang/en/en.json

要求：

页面入口统一使用 BasicCrud
schemas 使用 CrudSchema
标准接口优先接 BaseService
i18n key 中英文成对补齐
表头索引等公共 key 必须统一
默认不要单独开发 frontend/admin/src/apps/{plugin}
通过安装流程生成运行目录并验证结果，而不是双份维护

Step 9. 安装插件并生成运行目录

当模板源完成后，安装插件或执行相应同步流程，确认以下目录被生成或更新：

frontend/admin/src/apps/{plugin}/api
frontend/admin/src/apps/{plugin}/views
frontend/admin/src/apps/{plugin}/lang

如果运行目录已存在旧文件，重点检查是否已被模板源最新内容覆盖。

Step 10. 基于安装结果验证页面

联调时重点检查：

页面是否为官方 BasicCrud 外观
列表接口返回是否与 items/total 结构兼容
增删改查是否可用
查询参数是否与后端真实支持格式一致
中英文是否存在缺词
菜单点击是否能打开正确页面
format=select 下拉是否能显示正确标签；若不显示，优先检查模型是否提供 getNameAttribute()
JSON 规则字段是否支持前端 textarea 文本输入与后端数组/字符串双形态校验

默认不要直接修改运行目录。只有在用户明确要求排查安装产物问题时，才临时查看或修补运行目录，并且必须把最终改动落实回模板源。

Step 11. 执行模板源一致性检查

在交付前强制执行以下比对：

安装生成后的运行目录是否与模板源一致
index.vue 是否按模板源生成
schemas/index.tsx 是否按模板源生成
api/index.ts 是否按模板源生成
lang/zh-cn/zh.json 是否按模板源生成
lang/en/en.json 是否按模板源生成

只改运行目录但未落实模板源，不算完成。

Step 12. 卸载再安装验证

若用户明确要求“重装后不要回退”，必须做这一步。

验证目标：

卸载插件后重新安装
确认模板源再次复制到运行目录后，页面仍是最新结构
确认未回退到旧 demo 样式
确认菜单、权限、Swagger 依旧正常

如果没有时间完整执行，也要明确告诉用户：

当前完成的是代码层同步
仍建议再做一次卸载重装验证

Step 13. 收口与交付

最终汇报时至少说明：

改了哪些后端文件
改了哪些模板源文件
是否通过安装方式验证了运行目录产物
是否补齐了菜单与语言
是否处理了 Swagger 冲突
是否完成重装防回退验证
是否顺手更新了相关 skill

Step 14. 常见二次排错顺序

当插件页面已打开但接口返回 500 时，优先按以下顺序排查：

Service 是否显式导入 core\base\BaseService
DAO 是否显式导入 core\base\BaseDao
Service 是否错误地手动 new Dao()
DAO 重写方法签名是否与当前 BaseDao 一致
模型关联名是否与 DAO with([...]) 一致
Validate 对 JSON 字段和枚举字段的写法是否与当前项目兼容

常见分支处理

分支 A. 仅修复插件前端页面样式

执行：

Step 2
Step 3
Step 8
Step 9
Step 10
Step 11
Step 13

分支 B. 仅修复重装后回退

执行：

Step 2
Step 3
Step 8
Step 11
Step 12
Step 13

分支 C. 修复 Swagger 冲突

执行：

Step 2
Step 3
Step 5
Step 6
Step 13

分支 D. 新建完整插件模块

执行全部步骤。

完成判定

满足以下条件，才可判定“插件开发完成”：

后端 CRUD 可运行
Swagger 无冲突
菜单与权限可用
模板源前端完整
运行目录联调通过
用户要求重装防回退时，已完成重装验证或已明确说明未验证部分

7.8 KiB Raw Blame History Unescape Escape