# madong-admin-skills
**Repository Path**: motion-code/madong-admin-skills
## Basic Information
- **Project Name**: madong-admin-skills
- **Description**: madong5.1 配套Ai技能
- **Primary Language**: other
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://madong.tech
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 4
- **Created**: 2026-04-10
- **Last Updated**: 2026-10-25
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README

# Madong Skills
Project AI skill library (Madong Standard Edition) — help AI understand your project conventions
[](https://github.com/madong-code/madong-admin)
[](#choose-by-scenario)
[](#quick-start)
[](./LICENSE)
[中文](./README.md) | **English**
Covers three domains — backend, front-end and cross-cutting — and distributes to various AI editors with one command.
> Target version: the `madong v5.1.0` refactored standard-edition repository
> - Backend: `backend/` (PHP 8.2 + Webman 2.2 + Laravel Eloquent)
> - Front-end: **one backend pulling multiple UI front-ends** — `template/admin` (fixed location, content can be swapped wholesale for an equivalent template of a different UI, distinguished by `package.json` name, e.g. `vue-vben-admin-ele` / `madong-vue` / `vue-vben-admin-antd`) + `template/web` (Nuxt 4 + Element Plus) + `template/install` (lightweight installer), all consuming the same backend API
> - Installer: `template/install`
## Quick Start
### Windows
```powershell
# Sync everything (default)
powershell -ExecutionPolicy Bypass -File skills\sync.ps1
# Sync only the editor(s) you use (recommended)
powershell -ExecutionPolicy Bypass -File skills\sync.ps1 -target codebuddy
powershell -ExecutionPolicy Bypass -File skills\sync.ps1 -target cursor
powershell -ExecutionPolicy Bypass -File skills\sync.ps1 -target trae
powershell -ExecutionPolicy Bypass -File skills\sync.ps1 -target copilot
powershell -ExecutionPolicy Bypass -File skills\sync.ps1 -target claude
powershell -ExecutionPolicy Bypass -File skills\sync.ps1 -target windsurf
powershell -ExecutionPolicy Bypass -File skills\sync.ps1 -target cline
powershell -ExecutionPolicy Bypass -File skills\sync.ps1 -target roo
powershell -ExecutionPolicy Bypass -File skills\sync.ps1 -target gemini
powershell -ExecutionPolicy Bypass -File skills\sync.ps1 -target qwen
```
### macOS / Linux
```bash
chmod +x skills/sync.sh
./skills/sync.sh # all
./skills/sync.sh codebuddy # CodeBuddy only
./skills/sync.sh claude windsurf cline roo gemini qwen # a few of them
```
After running, refer to the section for your editor:
### CodeBuddy
1. Run the sync script
2. Open **Settings → Skills**; all skills should be visible
3. In chat, type `@backend-controller` directly, or describe a need to trigger automatically
### Trae
| Feature | File location |
|---------|---------------|
| Skills | `.agents/skills/{name}/SKILL.md` |
| Rules | `.trae/rules/{name}/rule.md` |
### Cursor
- Rules appear automatically in the **Rules** manager (restart required)
- File: `.cursor/rules/{name}/rule.mdc`
### GitHub Copilot
- All conventions are aggregated in `.github/copilot-instructions.md` and read automatically
### Claude Code
| Feature | File location |
|---------|---------------|
| Skills | `.claude/skills/{name}/SKILL.md`, reference via `@skill-name` in chat |
### Windsurf
| Feature | File location |
|---------|---------------|
| Rules | `.windsurf/rules/{name}/rule.md` |
### Cline
| Feature | File location |
|---------|---------------|
| Rules | `.clinerules/{name}.md` |
### Roo Code
| Feature | File location |
|---------|---------------|
| Rules | `.roo/rules/{name}.md` |
### Gemini CLI
- All conventions aggregated in `GEMINI.md`, read automatically
### Qwen Code
- All conventions aggregated in `QCLAUDE.md`, read automatically
---
## Skill Source Structure
```text
skills/
├── README.md # ← this file
├── sync.ps1 # ← sync script (Windows PowerShell)
├── sync.sh # ← sync script (macOS / Linux bash)
├── backend/ # Backend conventions (each layered skill covers "framework layer + plugin side" in one file)
│ ├── controller/ # Controllers (adminapi/api/install + plugin side, with namespace mapping table)
│ ├── service/ # Service layer (inject DAO / transactions, framework + plugin)
│ ├── dao/ # Data access layer (BaseDao, framework + plugin)
│ ├── model/ # Eloquent models (soft delete / snowflake ID / Scope, framework + plugin)
│ ├── enum/ # PHP 8.1 native enums (framework + plugin)
│ ├── schema/ # DTOs (Request/Response, framework + plugin)
│ ├── validate/ # Validators (scenario validation, framework + plugin)
│ ├── route/ # Route registration (webman Route + annotations)
│ ├── middleware/ # Middleware
│ ├── event/ # Events
│ ├── listener/ # Listeners
│ ├── config/ # Configuration system (core.{group}.*)
│ ├── core/ # Framework core core/ package conventions
│ ├── generator/ # Full-stack code generator (core/business/generator)
│ ├── plugin/ # Plugin system "specific" parts (Install/config/info/resource + namespace root pattern)
│ └── command/ # Command script system (madong-plugin/make/install/config/metadata)
├── frontend/ # Front-end conventions (one backend, multiple UI front-ends)
│ ├── ARCHITECTURE.md # ★ Overall architecture: one backend · many front-ends · many UIs (must-read)
│ ├── shared/ # Shared across admin/web/install (api client / i18n / naming)
│ ├── admin/ # ★ Main admin (fixed directory location; UI can be swapped wholesale, distinguished by package.json name)
│ │ ├── SKILL.md # Determine current UI by name + conventions
│ │ └── INSTANCES.md # Possible UI identities (ele / madong-vue / antd ... mutually exclusive)
│ ├── web/ # Nuxt 4 + Element Plus admin (independent stack)
│ └── install/ # Installer (lightweight Element Plus app)
└── cross/ # Cross-cutting conventions
├── git-convention/ # Git commit convention (lefthook + commitlint + czg)
├── commit-convention/ # Commit message format (plugin name scope only)
├── lint-format/ # Lint/Format (oxlint + eslint + stylelint + oxfmt)
├── database/ # Database design conventions (tables / fields / migrations)
└── api-convention/ # Front-end/back-end API contract (shared by all front-ends)
```
### ★ Core Architecture: one backend pulling multiple UI front-ends
- `backend/` is the **single source of data and business logic**, unaware of the front-end UI.
- `template/admin` is a **fixed directory location whose content can be swapped wholesale for a functionally equivalent template of a different UI** (current: `vue-vben-admin-ele`; also available from Gitee `motion-code/madong-vue`; future `vue-vben-admin-antd`). Only one UI is active at any time, **distinguished by the `package.json` `name`**.
- `template/web` (Nuxt 4) and `template/install` (lightweight Ele) are two other independent front-end shells, also consuming the same backend.
- All front-ends share the same API contract (see `cross-api-convention`); **do not change the backend contract for a particular UI**.
- See `frontend/ARCHITECTURE.md`; read the "§0 Determine UI" section in `frontend/admin/SKILL.md` before modifying admin.
---
## Choose by Scenario
| Scenario | Recommended skills |
|----------|--------------------|
| Write backend CRUD | backend/controller + service + dao + model + validate + schema + route |
| Write an Admin page (any UI) | frontend/admin (first §0 determine UI by name) + frontend/shared/* |
| Switch / replace admin UI | frontend/ARCHITECTURE + frontend/admin/INSTANCES + frontend/admin §4 |
| Write Web (Nuxt) page | frontend/web/* + frontend/shared/* |
| Write Install page | frontend/install/* |
| Write / integrate a plugin | backend/plugin/* + backend/command (madong-plugin:*) |
| Scaffolding / command scripts | backend/command/* |
| Code generation | backend/generator/* + backend/command (madong-make:*) |
| Whole-project development | all of the above + cross/* |
## Quick Command Reference (backend)
```bash
# Plugins
php webman madong-plugin:develop:create # create a plugin template
php webman madong-plugin:develop:build # build a plugin
php webman madong-plugin:install # install (create tables / import menu / deploy front-end)
php webman madong-plugin:uninstall # uninstall
php webman madong-plugin:list # list plugins
# Single-file scaffolding (stubs in app/command/make/stubs)
php webman madong-make:controller
php webman madong-make:service
php webman madong-make:dao
php webman madong-make:model
php webman madong-make:validate
php webman madong-make:middleware
# Install / config / metadata
php webman install:madong # system install
php webman madong-download:template
php webman madong-config:mysql # write MySQL config
php webman madong:migrate-admin-menu # sync admin menu
php webman madong:permission:collect # collect permission codes
```
> Commands are based on Symfony Console, registered with `#[AsCommand]`, base class `app\command\BaseCommand` (supports SSE). See `backend/command`.
---
## General Project Conventions (for AI reference)
### Tech Stack
- Backend: PHP 8.2 + Workerman Webman 2.2 + **Laravel Eloquent 11** (uses `Illuminate\Database\Eloquent`, **not ThinkPHP**)
> ⚠️ **ORM stack prohibition (observe strictly when scanning/generating)**: this project's data layer uses only Laravel Eloquent; **ThinkPHP-style code is strictly forbidden**.
> - Base class namespaces are all `core\foundation\base\` (note: **foundation**, not `found`).
> - Models: `class X extends core\foundation\base\BaseModel`, fields via `$table`/`$fillable`/`$timestamps`, soft delete via the `SoftDeletes` trait.
> - Queries always go through Eloquent: `getModel()->query()`, `->where()`, `->find()`, `->first()`, `->get()`, `->paginate()`, `->create()`, `->update()`, `->delete()`, `->destroy()`.
> - Forbidden: ThinkPHP's `Db::name()`, `->where()->find()`, `->inc()`, `->dec()`, `->value()`, `->column()`, `->insertGetId()`, `fetchSql()`, `->findOrEmpty()`, `->saveAll()`, etc. — these cause logic errors and easily confuse the stack.
> - The only `Db::` in the framework (e.g. `MigrateCommand.php`) is Laravel's `Illuminate\Support\Facades\DB`, which is correct usage; do not change it.
- Front-end: `template/admin` = Vue 3 + Vite + TypeScript + **Vben Admin 5.7 (the active UI is decided by package.json name; default `vue-vben-admin-ele` / Element Plus, can be swapped wholesale for `madong-vue` etc.)** + Pinia
- Front-end: `template/web` = Nuxt 4 + TypeScript + Vite + Element Plus + Pinia + UnoCSS
- Database: MySQL 8.0+ (multi-tenant)
- Real-time: SSE (Server-Sent Events)
### Naming Conventions
| Scenario | Convention | Example |
|----------|------------|---------|
| Controller class | PascalCase + `Controller` suffix | `MenuController` |
| Service class | PascalCase + `Service` suffix | `MenuService` |
| DAO class | PascalCase + `Dao` suffix | `MenuDao` |
| Model class | PascalCase (no suffix) | `Menu` |
| Validator class | PascalCase + `Validate` suffix | `MenuValidate` |
| Schema Request | PascalCase + `Request` suffix | `MenuCreateRequest` |
| Schema Response | PascalCase + `Response` suffix | `MenuResponse` |
| Enum class | PascalCase (no suffix, PHP enum) | `MenuType` |
| Middleware class | PascalCase + `Middleware` suffix | `AdminAuthMiddleware` |
| Database table | `{prefix}_{module}_{table}` | `system_menu`, `member_user` |
| Database field | snake_case | `created_at`, `parent_id` |
| Route / permission code | `{app}.{module}.{action}` / `{module}:{model}:{action}` | `adminapi.menu.update` / `system:menu:update` |
| Front-end component | PascalCase .vue | `MenuModal.vue` |
| Front-end API function | camelCase | `getMenuList`, `createMenu` |
| Front-end route code | `{App}{Module}{Action}` | `SystemMenuList` |
| JSON response field | snake_case | `items`, `total`, `page_no`, `page_size` |
| Directory / file name | kebab-case | `system/menu/index.vue` |
### Controller Inheritance Chain
```
adminapi: Controller → Crud → Base(BaseController) [app/adminapi/controller/]
api: Controller → Base(BaseController) [app/api/controller/]
```
Base classes are located in `core/foundation/base/` (namespace `core\foundation\base`).
### Git Commit Convention (backend monorepo)
```
: # no scope by default
(): # only for changes inside plugin//
```
| type | Description |
|------|-------------|
| `feat` | New feature |
| `fix` | Bug fix |
| `refactor` | Refactoring |
| `style` | UI / style changes |
| `perf` | Performance improvement |
| `chore` | Build / tooling / config changes |
| `docs` | Documentation updates |
| `test` | Test-related |
| `revert` | Revert |
| `types` | Type definition changes |
| `release` | Release |
scope = plugin directory name (lowercase), used only for changes inside `plugin/`, e.g. `cms`, `pay`, `workflow`; all other changes have no scope.
```
feat(cms): add content model and column management
fix(pay): fix duplicate signature verification on callback
feat: add member points management page
fix: fix tenant list pagination issue
refactor: refactor menu service query logic
chore: upgrade webman framework to 2.2
```