mrlee/MrleeAdmin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
MrleeAdmin/.windsurf/skills/cross-fullstack-admin-crud-feature/SKILL.md
T
mrlee 663f74b633 初始化本地仓库
2026-08-31 11:33:59 +08:00

12 KiB
Raw Permalink Blame History

name, description, globs
name description globs
cross-fullstack-admin-crud-feature Full-stack development workflow for Madong Admin CRUD features. Covers requirement analysis, existing implementation verification, backend migration/model/DAO/service/validate/schema/controller, frontend API/page/schema, menu permissions, migration execution, validation, and skill auto-evolution.
backend/app/**/*.php
backend/resource/database/migrations/**/*.php
backend/resource/data/menu/**/*.php
frontend/admin/src/api/**/*.ts
frontend/admin/src/views/**/*.vue
frontend/admin/src/views/**/*.tsx
.windsurf/skills/**/*.md

Madong Admin 全栈 CRUD 功能开发流程

用于开发类似“应用授权”这类后台管理功能，覆盖数据库、后端、前端、菜单权限、迁移执行与校验。

适用场景

  • 在 Admin 后台新增一个业务管理页面。
  • 需要新增数据库表、后端 CRUD、前端列表/表单/API。
  • 需要菜单入口和按钮权限。
  • 需要参考现有模块目录结构，例如 /tools/delegation、/setting/notice。
  • 需要自动生成字段或自定义操作，例如 Access Key / Secret Key 自动生成、重置密钥。

总原则

  1. 先核对项目真实实现，再使用 skill 或模板。
  2. 以现有项目代码为准，skill 与项目不一致时先更新 skill。
  3. 优先复用官方现有组件和基类。
  4. 不直接照搬 Laravel Artisan 命令，当前项目使用 Webman/Madong 命令体系。
  5. 数据库迁移执行前必须先 dry-run，确认会执行哪些迁移。
  6. 前后端路径、权限码、菜单码必须保持一致。

开发前检查

1. 确认参考模块

优先读取用户指定的参考模块。

常见参考：

  • frontend/admin/src/views/setting/notice
  • frontend/admin/src/views/tools/delegation
  • frontend/admin/src/api/tools/delegation
  • backend/app/adminapi/controller/notice/NoticeController.php
  • backend/app/adminapi/controller/plugin/PluginMadongAuthController.php

2. 确认真实项目规范

至少核对以下内容：

  • 后端控制器是否继承 app\adminapi\controller\Crud。
  • 模型是否继承 core\base\BaseModel。
  • DAO 是否继承 core\base\BaseDao。
  • Service 是否继承 core\base\BaseService。
  • Validate 是否继承 core\base\BaseValidate。
  • 前端 CRUD 是否使用 useCrud、CrudSchema、BasicCrud。
  • 前端 API 是否使用 BaseService 和 @/utils/http。
  • 表单组件名是否存在于 frontend/admin/src/components/form/components。
  • 菜单数据是否维护在 backend/resource/data/menu/admin.php。

后端开发流程

1. 数据库迁移

路径：

backend/resource/database/migrations/{timestamp}_create_{table}_table.php

当前项目雪花 ID 主键写法：

$table->bigInteger('id')->primary()->comment('主键');

不要使用 Laravel 默认的：

$table->id();

字段设计要求：

  • 主键使用雪花 ID。
  • 按需增加唯一索引、普通索引。
  • 状态字段常用 enabled，默认 1。
  • 时间字段按项目迁移写法使用 timestamps() 或项目已有封装。
  • 如果模型使用软删除，迁移需包含软删除字段。

2. Model

路径：

backend/app/model/{module}/{Model}.php

要求：

  • 继承 core\base\BaseModel。
  • 设置 $table。
  • 设置 $fillable。
  • 设置 $casts。
  • 如项目同类模型使用软删除，则保持一致。

3. DAO

路径：

backend/app/dao/{module}/{Model}Dao.php

要求：

  • 继承 core\base\BaseDao。
  • setModel() 返回模型类。
  • 如需关键字搜索，按项目已有 DAO 实现 getKeywordFields()。

4. Service

路径：

backend/app/service/admin/{module}/{Model}Service.php

要求：

  • 继承 core\base\BaseService。
  • 构造函数注入 DAO。
  • 自定义业务逻辑放在 Service。
  • 自动生成字段在 save() / create() 入口处理。
  • 自定义操作单独暴露方法，例如 resetSecret()。

应用授权类功能示例：

  • 新增时自动生成 access_key。
  • 新增时自动生成 secret_key。
  • 重置时只更新 secret_key。
  • 密钥生成应使用安全随机源，例如 random_bytes()。

5. Validate

路径：

backend/app/adminapi/validate/{module}/{Model}Validate.php

要求：

  • 继承 core\base\BaseValidate。
  • 定义 $rule、$message、$scene。
  • store 场景不要求 id。
  • update 场景要求 id。
  • 自动生成字段不要暴露为必填输入。

6. Request / Response Schema

请求路径：

backend/app/adminapi/schema/request/{module}/{Model}FormRequest.php
backend/app/adminapi/schema/request/{module}/{Model}QueryRequest.php

响应路径：

backend/app/adminapi/schema/response/{module}/{Model}Response.php

要求：

  • FormRequest 继承项目实际存在的表单基类。
  • QueryRequest 使用项目实际存在的 BaseQueryRequest。
  • 不要引用不存在的 PageRequest。
  • OpenAPI 属性需与控制器 x: [SchemaConstants::X_SCHEMA_REQUEST => ...] 对应。

7. Controller

路径：

backend/app/adminapi/controller/{module}/{Model}Controller.php

要求：

  • 继承 Crud。
  • 构造函数注入 Service 和 Validate。
  • 标准接口调用 parent::index()、parent::show()、parent::store()、parent::update()、parent::destroy()。
  • 路由通过 OpenAPI Attribute 标注。
  • 权限码与前端和菜单保持一致。

推荐路由格式：

GET    /{module}/{resource}
GET    /{module}/{resource}/{id}
POST   /{module}/{resource}
PUT    /{module}/{resource}/{id}
DELETE /{module}/{resource}/{id}
POST   /{module}/{resource}/{id}/{custom-action}

应用授权示例：

/plugin/application-auth
/plugin/application-auth/{id}
/plugin/application-auth/{id}/reset-secret

前端开发流程

1. API

路径参考用户指定目录结构。

例如参考 /tools/delegation 时：

frontend/admin/src/api/tools/{feature}/index.ts
frontend/admin/src/api/tools/{feature}/types.ts

要求：

  • 使用 BaseService。
  • 使用 @/utils/http。
  • 基础路径与后端路由一致。
  • 自定义接口单独封装方法。

示例：

const baseUrl = '/plugin/application-auth'

2. 页面

路径参考用户指定目录结构。

例如参考 /tools/delegation 时：

frontend/admin/src/views/tools/{feature}/index.vue
frontend/admin/src/views/tools/{feature}/schemas/index.tsx

要求：

  • 使用 useCrud 和 BasicCrud。
  • CRUD 配置写在 schemas/index.tsx。
  • 不要使用项目未注册的表单组件。
  • 当前项目日期时间选择使用 DatePicker + componentProps.type = 'datetime'。
  • 当前项目 CrudSchema 列类型不支持 type: 'operate'，操作列由 BasicCrud 根据 tableActions / dropDownActions 自动生成。

3. 列表字段

按照用户需求定义：

  • 序号：type: 'index'
  • 名称：普通列
  • Access Key：建议列表遮罩显示
  • Secret Key：建议列表遮罩显示
  • 失效时间：使用 formatDateTime
  • 状态：使用 ApiDict
  • 描述：showOverflowTooltip
  • 创建时间：优先使用后端格式化字段，或 formatDateTime(created_at)
  • 操作：通过 CRUD 操作配置生成

4. 表单字段

自动生成字段不要出现在新增表单中。

应用授权示例：

  • name：必填
  • expired_at：可选
  • enabled：必填，默认 1
  • description：可选
  • access_key：后端自动生成，不手填
  • secret_key：后端自动生成，不手填

5. 自定义操作

例如重置 Secret Key：

  • 前端按钮放在 dropDownActions 或项目实际支持的操作配置中。
  • 按钮增加 auth。
  • 操作前使用 ElMessageBox.confirm 二次确认。
  • 成功后提示新密钥并刷新列表。

菜单与权限

菜单数据路径：

backend/resource/data/menu/admin.php

页面菜单示例字段：

"title"     => "应用授权",
"code"      => "plugin:application-auth:list",
"type"      => 2,
"path"      => "/tools/application-auth",
"component" => "/tools/application-auth/index",
"methods"   => "GET",

按钮权限建议补齐：

plugin:application-auth:create
plugin:application-auth:delete
plugin:application-auth:update
plugin:application-auth:read
plugin:application-auth:reset-secret

按钮节点：

  • type 使用 3。
  • is_show 使用 0。
  • path、component、icon 通常为 null。
  • methods 与接口方法保持一致。

迁移执行流程

当前项目没有 Laravel artisan 文件，不使用：

php artisan migrate
php artisan migrate:status

当前项目使用：

php webman madong-migrate status
php webman madong-migrate up --dry-run
php webman madong-migrate up

执行前必须 dry-run

php webman madong-migrate up --dry-run

确认输出中将执行的迁移文件。

注意：

  • madong-migrate up 会执行所有未执行迁移。
  • 当前命令不支持 Laravel 的 --path= 单文件迁移参数。
  • 如果只允许迁移单个文件，不要直接执行 madong-migrate up。

事务异常注意事项

如果执行迁移时出现：

There is no active transaction

常见原因：

  • MySQL DDL 会隐式提交事务。
  • 迁移命令将多个 DDL 包在事务中，可能导致事务管理器提交时发现事务已结束。

处理流程：

  1. 先不要重复执行迁移。
  2. 检查数据表是否已经创建成功。
  3. 执行 php webman madong-migrate status 查看迁移日志状态。
  4. 如果表已创建但日志未写入，需要谨慎补齐迁移日志或修复迁移命令事务逻辑后再处理。
  5. 不要盲目回滚或再次执行全部迁移，避免表已存在导致二次错误。

校验清单

后端校验

对新增 PHP 文件执行语法检查：

php -l app/model/{module}/{Model}.php
php -l app/dao/{module}/{Model}Dao.php
php -l app/service/admin/{module}/{Model}Service.php
php -l app/adminapi/validate/{module}/{Model}Validate.php
php -l app/adminapi/schema/request/{module}/{Model}FormRequest.php
php -l app/adminapi/schema/request/{module}/{Model}QueryRequest.php
php -l app/adminapi/schema/response/{module}/{Model}Response.php
php -l app/adminapi/controller/{module}/{Model}Controller.php
php -l resource/database/migrations/{migration_file}.php
php -l resource/data/menu/admin.php

前端校验

只检查新增文件：

pnpm exec eslint src/views/{module}/{feature}/index.vue src/views/{module}/{feature}/schemas/index.tsx src/api/{module}/{feature}/index.ts src/api/{module}/{feature}/types.ts

路径一致性校验

检查以下内容必须一致：

  • 后端 Controller OpenAPI path。
  • 前端 API baseUrl。
  • 菜单 path。
  • 菜单 component。
  • 前端 view 文件路径。
  • 权限码。

Skill 自动进化规则

开发过程中如果发现 skill 与真实项目不一致，必须先更新 skill，再继续使用。

需要自动进化的典型情况：

  • 迁移主键写法与项目不一致。
  • 前端 API 模板导入路径不一致。
  • 表单组件名不存在。
  • CRUD 列类型与 TypeScript 类型不一致。
  • 菜单权限结构与项目实际不一致。
  • 路由路径或权限码规则与项目实际不一致。

更新要求：

  • 只更新已验证的不一致点。
  • 不做无关重写。
  • 最终总结中说明更新了哪些 skill。

完整输出清单

完成一个 Admin 全栈 CRUD 功能后，应至少包含：

backend/resource/database/migrations/{migration}.php
backend/app/model/{module}/{Model}.php
backend/app/dao/{module}/{Model}Dao.php
backend/app/service/admin/{module}/{Model}Service.php
backend/app/adminapi/validate/{module}/{Model}Validate.php
backend/app/adminapi/schema/request/{module}/{Model}FormRequest.php
backend/app/adminapi/schema/request/{module}/{Model}QueryRequest.php
backend/app/adminapi/schema/response/{module}/{Model}Response.php
backend/app/adminapi/controller/{module}/{Model}Controller.php
frontend/admin/src/api/{section}/{feature}/index.ts
frontend/admin/src/api/{section}/{feature}/types.ts
frontend/admin/src/views/{section}/{feature}/index.vue
frontend/admin/src/views/{section}/{feature}/schemas/index.tsx
backend/resource/data/menu/admin.php

最终回复模板

完成后向用户说明：

  • 新增了哪些后端文件。
  • 新增了哪些前端文件。
  • 菜单和权限是否已配置。
  • 迁移是否执行，执行结果如何。
  • 校验命令和结果。
  • 是否自动进化了 skill。
  • 是否有需要用户后续处理的事项。
Reference in New Issue View Git Blame Copy Permalink