| name | elysia-module-dev |
| description | Elysia Admin full-stack module workflow: CRUD, schema, dict, menu/permission SQL, handoff SQL, form layout, page quality. Use for new modules, admin pages, RBAC, drizzle tables. 全栈模块开发、菜单权限、字典、Schema、Handoff SQL。 |
Elysia Admin Module Development
Follow this checklist; read .ai/ docs for details. NEVER skip steps.
When to Use
- New
server/src/modules/{group}-{name}/
- New
admin/src/views/{group}/{name}/
- Menu, button permissions, or data dict required
- Database schema design or verification
Triggers: CRUD module, business-*, menu permission, handoff sql, schema design, admin page
User phrases (中文): 按 module dev workflow, 走完整 SOP, 含菜单权限和 handoff SQL, 全栈模块, 先用脚手架, 脚手架已生成
10-Step Checklist
1. MCP
- MUST use Postgres MCP read-only for tables, dict, menu IDs (
.ai/AI_MCP_SETUP.md) — first for runtime data
- NEVER read
server/database/sql/pg.sql (stale backup; use MCP or schema files)
- If unavailable: declare fallback; use SQL subqueries or placeholders
2. Schema
- MUST check
server/database/schema/ first
- Main table:
...BaseSchema; sort field name MUST be sort
- Pure junction table: two FKs only; hard delete
- MUST ask developer before changing drizzle schema
- After schema edits:
db:push per .ai/AI_SCHEMA_GUIDE.md — check .ai/dev-preferences.local.md; ask once, then remember
- See
.ai/AI_SCHEMA_GUIDE.md
3. Module scaffold (standard CRUD — when schema exists & module is new)
- Read
.ai/AI_MODULE_SCAFFOLD.md
- From
server/: bun run create:module {slug} --tag "..." then bun run create:page {group} {name} --tag "..."
- Run in Agent mode when appropriate, or instruct user
- If scaffold ran: skip hand-writing CRUD boilerplate — go to steps 5–8 for incremental work
- If skipped: continue with step 4 as full backend generation
4. Plan (no code yet — if scaffold not used)
- Goal, module name, tables, CRUD, permissions, task/frontend need (≤5 lines)
5. Backend
- Scaffold already ran: edit
handle.ts / extend dto.ts only; do not regenerate route.ts from templates
- No scaffold:
dto.ts / handle.ts / route.ts / task.ts (optional); .ai/AI_CODE_EXAMPLES_BACKEND.md (section only); reference system-api/ only
dto.ts error (required): every validated field must include error with a readable Chinese user-facing message (error, not errorMessage); scaffold CreateDto auto-generates via fieldLabels- Cross-table data: call the owning module's exported PascalCase function from its
handle.ts; do NOT import another module's @database/schema for cross-table queries
meta.permission: group:name:action
6. Dict
- NEVER hardcode business enums in backend or frontend
- MCP query
system_dict_type / system_dict_data
- Missing items → handoff SQL
7. Frontend (if needed)
- Scaffold already ran: polish generated vue files; dict + layout per
.ai/AI_PAGE_QUALITY.md / .ai/AI_UI_LAYOUT.md
- No scaffold: reference
admin/src/views/system/user/ only
- Permission strings MUST match backend
- MUST read
.ai/AI_PAGE_QUALITY.md and .ai/AI_UI_LAYOUT.md before finishing
8. Handoff SQL
- Single file:
server/database/sql/{module-name}-init.sql
- Order: dict → menu/buttons → role permissions → seed data
- Menu INSERT MUST query live DB first (Postgres MCP)
- Deliver file only — developer runs manually; NEVER scripts/MCP execute/ad-hoc code to apply SQL
- See
.ai/AI_HANDOFF_SQL.md
9. Git Read-Only
- Allowed:
status / diff / log
- NEVER
add / commit / push / stash unless user explicitly asks
10. Optimization (on demand only)
- Default: no indexes/cache
- Only when clear performance need; state reason
- NEVER auto-add Redis for boilerplate CRUD
Delivery Format — MUST output in this order
- Plan (≤5 lines)
- Files changed / created
- Schema note (existing / proposed — ask before DDL)
- Code (by file)
- Handoff SQL path:
server/database/sql/{module}-init.sql
- MCP summary OR
"Postgres MCP unavailable" fallback
- Quality checklist (permissions ×3, dict, layout, git untouched)
Doc Index
| Doc | Purpose |
|---|
.ai/AI_MODULE_WORKFLOW.md | Full SOP |
.ai/AI_MODULE_SCAFFOLD.md | create:module + create:page CLI |
.ai/AI_CODE_EXAMPLES_BACKEND.md | Backend code templates |
.ai/AI_CODE_EXAMPLES_FRONTEND.md | Frontend code templates |
.ai/AI_PAGE_QUALITY.md | List/search/dialog quality |
.ai/AI_SCHEMA_GUIDE.md | Table design |
.ai/AI_HANDOFF_SQL.md | SQL templates |
.ai/AI_UI_LAYOUT.md | Form span layout |
.ai/AI_MCP_SETUP.md | MCP setup |
.ai/AI_CONTEXT_CAPSULE.md | One-page quick ref |
