初始化本地仓库

2026-08-31 11:33:59 +08:00
commit 663f74b633
2390 changed files with 402918 additions and 0 deletions
@@ -0,0 +1,279 @@
+---
+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. 搭建或核对后端数据层
+
+按模块逐项处理：
+
+1. 迁移文件
+2. Model
+3. DAO
+4. Service
+5. Validate
+6. 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`
+
+按模块实现：
+
+1. `api/index.ts`
+2. `views/{plugin_key}/{module}/index.vue`
+3. `views/{plugin_key}/{module}/schemas/index.tsx`
+4. `lang/zh-cn/zh.json`
+5. `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 时，优先按以下顺序排查：
+
+1. Service 是否显式导入 `core\base\BaseService`
+2. DAO 是否显式导入 `core\base\BaseDao`
+3. Service 是否错误地手动 `new Dao()`
+4. DAO 重写方法签名是否与当前 `BaseDao` 一致
+5. 模型关联名是否与 DAO `with([...])` 一致
+6. 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 无冲突
+- 菜单与权限可用
+- 模板源前端完整
+- 运行目录联调通过
+- 用户要求重装防回退时，已完成重装验证或已明确说明未验证部分
@@ -0,0 +1,22 @@
+---
+auto_execution_mode: 0
+description: Review code changes for bugs, security issues, and improvements
+---
+You are a senior software engineer performing a thorough code review to identify potential bugs.
+
+Your task is to find all potential bugs and code improvements in the code changes. Focus on:
+1. Logic errors and incorrect behavior
+2. Edge cases that aren't handled
+3. Null/undefined reference issues
+4. Race conditions or concurrency issues
+5. Security vulnerabilities
+6. Improper resource management or resource leaks
+7. API contract violations
+8. Incorrect caching behavior, including cache staleness issues, cache key-related bugs, incorrect cache invalidation, and ineffective caching
+9. Violations of existing code patterns or conventions
+
+Make sure to:
+1. If exploring the codebase, call multiple tools in parallel for increased efficiency. Do not spend too much time exploring.
+2. If you find any pre-existing bugs in the code, you should also report those since it's important for us to maintain general code quality for the user.
+3. Do NOT report issues that are speculative or low-confidence. All your conclusions should be based on a complete understanding of the codebase.
+4. Remember that if you were given a specific git commit, it may not be checked out and local code states may be different.