@robsun/create-keystone-app 0.2.15 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robsun/create-keystone-app",
-  "version": "0.2.15",
+  "version": "0.4.1",
   "publishConfig": {
     "access": "public"
   },

package/template/.claude/skills/keystone-implement/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: keystone-implement
+description: 根据需求文档实现 Keystone 模块。支持新增模块和迭代更新。触发词：实现模块、开发功能、REQ-XXX、添加字段、修改功能。
+---
+
+# Keystone Implement
+
+**⚠️ 执行规则**：
+1. 必须使用 `TodoWrite` 创建任务列表，包含所有 🔴 MUST 步骤
+2. 所有 🔴 MUST 步骤必须按顺序执行，不得跳过
+3. 每个步骤完成后必须在 TodoWrite 中标记为 completed
+4. 🟢 OPTIONAL 步骤可根据实际需求选择执行
+
+---
+
+## 模式判断
+
+| 场景 | 模式 | 特征 |
+|------|------|------|
+| 创建新模块 | 新增 | 模块目录不存在 |
+| 修改现有模块 | 迭代 | 模块目录已存在 |
+
+---
+
+## 新增模式
+
+**输入**: `requirements/REQ-{序号}-{module}.yaml`（completeness: approved）
+
+### 流程
+
+**⚠️ 重要**：开始执行前必须使用 `TodoWrite` 创建任务列表，包含以下所有 🔴 MUST 步骤。
+
+1. 🔴 **MUST: 解析需求** → 提取 module.name, fields, features
+2. 🔴 **MUST: 生成代码** → 按 `PATTERNS.md` 生成（含高级模式如审批/分页等）
+3. 🔴 **MUST: 模块注册** → 更新 manifest.go, config.yaml, main.tsx
+4. 🔴 **MUST: 构建验证** → `go build ./...` + `pnpm typecheck`
+5. 🔴 **MUST: 测试** → 参考 `TESTING.md`，执行测试命令并确保通过
+6. 🔴 **MUST: 验收** → 参考 `CHECKLIST.md`，逐项检查
+
+**验证要求**：
+- 所有 🔴 MUST 步骤必须执行并在 TodoWrite 中标记为 completed
+- 🟢 OPTIONAL 步骤可根据实际需求选择执行
+
+### 生成顺序
+
+| 后端 | 前端 |
+|------|------|
+| B2 Model → B5 Errors → B6 Repo | F3 Types → F4 API |
+| B4 Service → B3 Handler | F5 Page → F6 Locales |
+| B7-B9 i18n → B1 Module | F2 Routes → F1 Module |
+
+---
+
+## 迭代模式
+
+**输入**: 需求描述或更新后的 YAML
+
+### 常见场景
+
+| 变更类型 | 影响文件 |
+|----------|----------|
+| 添加字段 | Model, Handler Input, Service Input, Types, Page, Locales |
+| 修改字段 | 同上 |
+| 添加 API | Handler, Service, Repository, Routes, API Service |
+| 修改业务逻辑 | Service |
+| 添加高级功能 | 参考 `PATTERNS.md` 第六部分 |
+
+### 流程
+
+**⚠️ 重要**：开始执行前必须使用 `TodoWrite` 创建任务列表，包含以下所有 🔴 MUST 步骤。
+
+1. 🔴 **MUST: 分析变更** → 确定影响范围
+2. 🔴 **MUST: 定位文件** → 找到需要修改的文件
+3. 🔴 **MUST: 增量修改** → 保持现有代码风格
+4. 🔴 **MUST: 构建验证** → 确保编译通过
+5. 🔴 **MUST: 测试** → 参考 `TESTING.md`，更新并执行相关测试
+
+**验证要求**：
+- 所有 🔴 MUST 步骤必须执行并在 TodoWrite 中标记为 completed
+
+### 添加字段示例
+
+```
+需求：给 Customer 添加 phone 字段
+
+1. Model: 添加 Phone string `gorm:"size:50" json:"phone"`
+2. Handler: itemInput/itemUpdateInput 添加 Phone
+3. Service: ItemInput/ItemUpdateInput 添加 Phone，Create/Update 处理
+4. Types: Customer interface 添加 phone
+5. Page: columns 和 Form.Item 添加 phone
+6. Locales: fields.phone 添加翻译
+```
+
+---
+
+## 构建验证
+
+```bash
+cd apps/server && go build ./...
+pnpm -C apps/web typecheck
+```
+
+**错误处理**：错误信息 → 对照 PATTERNS.md → 修复 → 重新验证
+
+---
+
+## 参考文档
+
+| 文档 | 内容 |
+|------|------|
+| `PATTERNS.md` | 架构 + 约定 + 基础模式 + 高级模式 |
+| `TESTING.md` | 测试模板 |
+| `CHECKLIST.md` | 验收清单 |

package/template/.claude/skills/keystone-implement/references/CHECKLIST.md

@@ -0,0 +1,91 @@
+# Keystone 模块验收清单
+
+## 后端检查
+
+### 文件结构
+- [ ] `module.go` - 实现所有 Module 接口
+- [ ] `api/handler/` - CRUD Handler
+- [ ] `domain/models/` - 模型 + TableName()
+- [ ] `domain/service/` - Service + errors.go
+- [ ] `infra/repository/` - Repository
+- [ ] `i18n/` - keys.go + i18n.go + locales/
+- [ ] `bootstrap/migrations/` - Migrate()
+
+### Module 接口
+- [ ] `Name()` 返回模块名
+- [ ] `RegisterRoutes()` 注册路由
+- [ ] `RegisterModels()` 返回模型
+- [ ] `RegisterPermissions()` 注册权限
+- [ ] `RegisterI18n()` 注册翻译
+- [ ] `Migrate()` 执行迁移
+
+### Handler
+- [ ] nil 检查: `if h == nil || h.svc == nil`
+- [ ] 租户隔离: `tenantID := resolveTenantID(c)`
+- [ ] i18n 错误响应
+
+### Service
+- [ ] 输入验证
+- [ ] 状态检查: `status.IsValid()`
+- [ ] 返回 i18n 错误
+
+### Repository
+- [ ] 租户过滤: `WHERE tenant_id = ?`
+- [ ] 上下文传递: `db.WithContext(ctx)`
+
+## 前端检查
+
+### 文件结构
+- [ ] `index.ts` - registerModule + loadModuleLocales
+- [ ] `routes.tsx` - 路由 + handle
+- [ ] `types.ts` - 类型定义
+- [ ] `services/` - API 调用
+- [ ] `locales/` - zh-CN + en-US
+
+### 路由配置
+- [ ] `handle.menu.labelKey` - i18n 键
+- [ ] `handle.menu.permission` - 权限
+- [ ] `handle.permission` - 路由权限
+
+### 组件
+- [ ] `useTranslation('module')` - 正确 namespace
+- [ ] `App.useApp()` - 获取 message
+- [ ] `destroyOnHidden` - 不用 destroyOnClose
+
+## 注册检查
+
+- [ ] `manifest.go` - 导入和注册模块
+- [ ] `config.yaml` - modules.enabled 包含模块
+- [ ] `main.tsx` - 导入模块
+- [ ] `app.config.ts` - modules.enabled 包含模块
+
+## 测试检查
+
+- [ ] Service 单元测试
+- [ ] `go test ./...` 通过
+- [ ] `pnpm -C apps/web typecheck` 通过
+
+## 常见陷阱
+
+| 问题 | 原因 | 解决 |
+|------|------|------|
+| 菜单不显示 | config 未启用 | 检查 `config.yaml` 和 `app.config.ts` |
+| Handler panic | nil 检查缺失 | 添加 `if h == nil` |
+| 数据泄露 | 缺租户过滤 | Repository 加 `tenant_id` 条件 |
+| 翻译显示键名 | namespace 错误 | 检查 `useTranslation` 参数 |
+| Modal 不重置 | 用了 destroyOnClose | 改用 `destroyOnHidden` |
+| API 解构错误 | 多层 data | `response.data.data.items` |
+| 权限不生效 | 未注册权限 | 检查 `RegisterPermissions` |
+| i18n NO_INSTANCE | 从 `react-i18next` 导入 | 必须从 `@robsun/keystone-web-core` 导入 `useTranslation` |
+| antd 主题失效 (--local) | antd 实例重复 | Vite config 添加 `dedupe: ['antd', '@ant-design/icons', '@ant-design/cssinjs']` |
+| 页面滚动条异常 | CSS reset 缺失 | 确保 global.css 包含 `box-sizing: border-box` 和 `body { margin: 0 }` |
+
+## 质量命令
+
+```bash
+# 后端
+go build ./... && go test ./... && go vet ./...
+
+# 前端
+pnpm -C apps/web typecheck && pnpm -C apps/web lint
+```