@robsun/create-keystone-app 0.2.13 → 0.2.15

package/template/.codex/skills/keystone-dev/SKILL.md

@@ -1,103 +1,90 @@
----
-name: keystone-dev
-description: 基于 Keystone 平台开发业务模块。当用户需要创建新模块、添加业务功能、实现 CRUD、审批流程、数据导入导出、文件上传时使用。Use when creating modules, adding features, implementing CRUD, approval workflows, import/export, or file upload for Keystone platform.
----
-
-# Keystone 业务模块开发
-
-使用 Keystone 平台快速开发业务模块。
-
-## 工作流程
-
-1. **解析需求** → 识别所需能力
-2. **生成前端模块** → routes.tsx, pages/, services/, types.ts, locales/
-3. **生成后端模块** → handler/, service/, repository/, migrations/, i18n/
-4. **自动注册** → main.tsx + manifest.go + config.yaml
-5. **配置多语言** → 前端翻译文件 + 后端翻译键常量
-6. **输出调整建议**
-7. **补测试并执行** → 见 references/testing.md
-
-## 多语言最佳实践
-
-**前端**：
-- 所有用户可见文本必须使用 `t()` 翻译函数
-- 翻译键使用点记法：`{module}:{section}.{key}`
-- 避免硬编码文本，确保国际化覆盖率 100%
-
-**后端**：
-- 错误消息使用翻译键常量（keys.go）
-- API 响应消息根据请求语言返回
-- 使用 `i18n.T(c, key)` 获取翻译文本
-
-详见 [docs/I18N.md](../../docs/I18N.md)。
-
-## 能力选择矩阵
-
-根据需求关键词选用对应能力：
-
-| 需求关键词 | 前端能力 | 后端能力 |
-|-----------|---------|---------|
-| 列表、查询 | ProTable + 过滤 + 分页 | ListHandler + Repository |
-| 表单、编辑 | ProForm + 验证 | CreateHandler + UpdateHandler |
-| 导入、批量 | DataImporter | ImportHandler + Job队列 |
-| 导出、下载 | DataExporter | ExportHandler + Job队列 |
-| 上传、附件 | FileUpload | UploadHandler + 存储服务 |
-| 审批、流程 | ApprovalFlowEditor | 审批引擎 |
-| 权限 | PermissionGuard | 权限中间件 |
-
-审批流程与接入说明见 [references/approval.md](references/approval.md)。
-测试清单见 [references/testing.md](references/testing.md)。
-详细能力清单见 [references/CAPABILITIES.md](references/CAPABILITIES.md)。
-代码模板见 [references/TEMPLATES.md](references/TEMPLATES.md)。
-
-## 模块结构约定
-
-### 前端模块
-```
-apps/web/src/modules/{name}/
-├── index.ts              # registerModule()
-├── routes.tsx            # 路由 + 菜单 + 权限
-├── pages/
-│   ├── List.tsx          # ProTable
-│   ├── Detail.tsx
-│   └── Form.tsx          # ProForm
-├── services/api.ts
-├── types.ts
-├── locales/              # 多语言翻译
-│   ├── zh-CN/{module}.json
-│   └── en-US/{module}.json
-└── help/
-    └── index.md
-```
-
-### 后端模块
-```
-apps/server/internal/modules/{name}/
-├── module.go
-├── api/handler/
-├── domain/models/
-├── domain/service/
-├── infra/repository/
-├── i18n/                 # 多语言翻译
-│   ├── i18n.go
-│   ├── keys.go
-│   └── locales/
-│       ├── zh-CN.json
-│       └── en-US.json
-└── bootstrap/migrations/
-```
-
-## 权限命名
-
-格式: `{module}:{resource}:{action}`
-
-动作: view | create | update | delete | manage | export | import | approve
-
-## 注册步骤
-
-生成代码后需完成以下注册（**缺一不可**）：
-
-1. **前端导入** `main.tsx`: `import './modules/{name}'`
-2. **前端启用** `app.config.ts`: 添加到 `modules.enabled` 数组 ⚠️ **必须，否则菜单不显示**
-3. **后端注册** `manifest.go`: `import {name}module "app/internal/modules/{name}"` + `Register({name}module.NewModule())`
-4. **后端启用** `config.yaml`: 添加到 `modules.enabled`
+---
+name: keystone-dev
+description: Build and extend Keystone modules and features (frontend + backend) with consistent structure, permissions, i18n, help docs, and OpenAPI contracts. Use when adding new modules, routes, APIs, migrations, or updating the scaffold template in this repo.
+---
+# Keystone Dev
+
+## Core workflow
+1) Identify the target app root: this repo's scaffold template or a generated app.
+2) Create or update the module using the generator or the Example module as the baseline.
+3) Add or update tests for new behavior before finishing implementation.
+4) Wire frontend routes, menus, permissions, help docs, and i18n.
+5) Wire backend module registration, permissions, i18n, routes, migrations, and seeds.
+6) Update contracts and types when APIs change.
+7) Run the relevant checks before finishing.
+
+## Module creation
+- Use the generator when possible:
+  ```bash
+  pnpm create:module <module-name> [options]
+
+  Options:
+    --frontend-only    Only generate the frontend module
+    --backend-only     Only generate the backend module
+    --with-crud        Include CRUD example code
+    --with-approval    Include approval workflow code (implies --with-crud)
+    --skip-register    Skip auto registration steps
+  ```
+- Keep module names in kebab-case and consistent across frontend, backend, and permissions.
+- Prefer copying the Example module if you need a manual template.
+
+## Approval workflow (--with-approval)
+When using `--with-approval`, the generator creates:
+- **Backend**: `domain/service/approval.go` (Submit/Cancel), `domain/service/callback.go` (OnApproved/OnRejected), `api/handler/approval.go`
+- **Frontend**: `components/ApprovalActions.tsx` with status tags and action buttons
+- **Model updates**: Adds `draft/pending/approved/rejected` statuses and `ApprovalInstanceID` field
+- **I18n**: Approval-related translations in both languages
+- **Routes**: `POST /:id/submit` and `POST /:id/cancel` endpoints
+
+After generation, register the approval callback in `module.go`:
+```go
+func (m *Module) RegisterApprovalCallback(reg *approval.CallbackRegistry) error {
+    return reg.Register(service.ApprovalBusinessType, service.New{Pascal}ApprovalCallback(m.repo))
+}
+```
+
+## Frontend checklist (apps/web)
+- Add module at `apps/web/src/modules/<module>`.
+- In `index.ts`, call `loadModuleLocales` and `registerModule`.
+- In `routes.tsx`, set `handle.menu`, `handle.permission`, `handle.helpKey`, and use `labelKey`/`breadcrumbKey` for i18n.
+- Add help docs under `apps/web/src/modules/<module>/help/**` and keep `helpKey` aligned.
+- Add locale files in `apps/web/src/modules/<module>/locales/zh-CN/*.json` and `en-US/*.json`.
+
+## Backend checklist (apps/server)
+- Add module at `apps/server/internal/modules/<module>`.
+- Implement the Module interface in `module.go` and keep DDD layering (`api/`, `domain/`, `infra/`, `bootstrap/`).
+- Register permissions with `CreateMenuI18n`/`CreateActionI18n` using `{module}:{resource}:{action}`.
+- Register i18n in `RegisterI18n()` and provide `i18n/keys.go` + `i18n/locales/*.json`.
+- Register the module in `apps/server/internal/modules/manifest.go`.
+- Enable the module in `apps/server/config.yaml` (scaffold apps).
+
+## Testing development
+- Backend: add unit tests in package folders (`*_test.go`) or in `tests/unit`/`tests/integration`/`tests/perf`.
+- Frontend: add component or page tests alongside modules (e.g. `*.test.tsx`).
+- Cover critical paths first (permissions, validation, and data mutations).
+
+## Contracts and API types
+- Add or update OpenAPI specs under `contracts/NNN-<name>/`.
+- Update `CONTRACT_MAPPING` in `scripts/generate-api-types.mjs` for new contract folders.
+- Run `pnpm contracts:sync` and `pnpm -C packages/keystone-contracts generate` after contract changes.
+
+## Quality gates
+- For scaffold changes: `pnpm -C packages/create-keystone-app/template test`.
+- For contracts: `pnpm contracts:check` and `pnpm -C packages/keystone-contracts typecheck`.
+- For backend changes: `go test ./...`.
+
+## Key references
+- `packages/create-keystone-app/template/docs/CONVENTIONS.md`
+- `packages/create-keystone-app/template/docs/CODE_STYLE.md`
+- `packages/create-keystone-app/template/docs/I18N.md`
+- `packages/create-keystone-app/template/apps/web/src/modules/example`
+- `packages/create-keystone-app/template/apps/server/internal/modules/example`
+
+## Advanced templates (in `references/`)
+- `TEMPLATES.md` - 基础 CRUD + 高级业务模板（多实体、审批流、导入导出、前端高级组件）
+- `ADVANCED_PATTERNS.md` - 高级开发模式（跨模块依赖、状态机、缓存、并发控制、任务编排）
+- `PATTERNS.md` - 后端开发模式（分页、事务、批量、软删除、预加载、审批集成）
+- `CHECKLIST.md` - 模块开发完整自检清单
+- `GOTCHAS.md` - 常见陷阱与解决方案
+- `CAPABILITIES.md` - 平台完整能力清单
+- `TESTING.md` - 测试开发指南