@robsun/create-keystone-app 0.2.13 → 0.2.15

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

@@ -0,0 +1,285 @@
+# Keystone 模块开发自检清单
+
+> 完成开发后逐项检查，确保模块完整且符合规范。
+
+## 1. 后端检查
+
+### 1.1 文件结构 ✓
+
+```
+[ ] module.go            - 实现所有 Module 接口方法
+[ ] api/handler/         - Handler 结构体 + CRUD 方法
+[ ] domain/models/       - 模型定义 + TableName()
+[ ] domain/service/      - Service + Input/UpdateInput 类型
+[ ] domain/service/errors.go - I18n 错误定义
+[ ] infra/repository/    - Repository 实现 Service 定义的接口
+[ ] i18n/keys.go         - 翻译键常量
+[ ] i18n/i18n.go         - RegisterLocales() 函数
+[ ] i18n/locales/        - zh-CN.json + en-US.json
+[ ] bootstrap/migrations/ - Migrate() 函数
+[ ] bootstrap/seeds/     - Seed() 函数（可选）
+```
+
+### 1.2 Module 接口 ✓
+
+```go
+[ ] Name()                - 返回模块名（小写）
+[ ] RegisterRoutes()      - 注册 API 路由
+[ ] RegisterModels()      - 返回模型列表
+[ ] RegisterPermissions() - 注册菜单 + 操作权限
+[ ] RegisterI18n()        - 调用 modulei18n.RegisterLocales()
+[ ] RegisterJobs()        - 注册后台任务（可为空）
+[ ] Migrate()             - 调用 migrations.Migrate()
+[ ] Seed()                - 调用 seeds.Seed()
+[ ] ensureServices()      - 延迟初始化 service
+```
+
+### 1.3 Handler 检查 ✓
+
+```go
+[ ] nil 检查             - if h == nil || h.svc == nil
+[ ] 租户隔离             - tenantID := resolveTenantID(c)
+[ ] 参数绑定             - c.ShouldBindJSON(&input)
+[ ] ID 解析              - hcommon.ParseUintParam(c, "id")
+[ ] I18n 错误处理        - errors.As(err, &i18nErr)
+[ ] 正确 HTTP 状态码     - BadRequest/NotFound/InternalError
+[ ] I18n 响应消息        - response.SuccessI18n/CreatedI18n
+```
+
+### 1.4 Service 检查 ✓
+
+```go
+[ ] 输入验证             - strings.TrimSpace(), 空值检查
+[ ] 状态验证             - status.IsValid()
+[ ] 租户 ID 设置         - entity.TenantID = tenantID
+[ ] 返回 I18n 错误       - return nil, ErrNameRequired
+```
+
+### 1.5 Repository 检查 ✓
+
+```go
+[ ] 租户过滤             - WHERE tenant_id = ?
+[ ] 上下文传递           - db.WithContext(ctx)
+[ ] 404 转换             - gorm.ErrRecordNotFound → service.ErrNotFound
+[ ] 排序                 - ORDER BY created_at desc
+```
+
+### 1.6 模型检查 ✓
+
+```go
+[ ] 继承 BaseModel       - models.BaseModel
+[ ] GORM 标签            - gorm:"size:200;not null"
+[ ] JSON 标签            - json:"name"
+[ ] TableName()          - 返回表名
+[ ] 状态枚举             - type Status string + IsValid()
+```
+
+### 1.7 权限注册 ✓
+
+```go
+[ ] 菜单权限             - reg.CreateMenuI18n("module:entity", ...)
+[ ] 查看权限             - module:entity:view
+[ ] 管理权限             - module:entity:manage
+[ ] 或细分权限           - :create, :update, :delete, :export, :import
+```
+
+### 1.8 翻译文件 ✓
+
+```
+[ ] keys.go 常量完整     - 所有消息键都有定义
+[ ] zh-CN.json           - 所有键都有中文翻译
+[ ] en-US.json           - 所有键都有英文翻译
+[ ] 翻译键格式           - module.entity.action
+```
+
+---
+
+## 2. 前端检查
+
+### 2.1 文件结构 ✓
+
+```
+[ ] index.ts             - registerRoutes() 调用
+[ ] routes.tsx           - 路由 + menu handle + permission
+[ ] types.ts             - 实体类型定义
+[ ] services/api.ts      - API 调用函数
+[ ] pages/               - 页面组件
+[ ] locales/zh-CN/       - 中文翻译
+[ ] locales/en-US/       - 英文翻译
+```
+
+### 2.2 路由检查 ✓
+
+```tsx
+[ ] lazyNamed            - 按需加载组件
+[ ] withSuspense         - Suspense 包装
+[ ] menu.labelKey        - 使用翻译键
+[ ] menu.icon            - Ant Design 图标
+[ ] menu.permission      - 权限码
+[ ] breadcrumbKey        - 面包屑翻译键
+[ ] permission           - 路由级权限
+[ ] helpKey              - 帮助文档键
+```
+
+### 2.3 API 服务检查 ✓
+
+```typescript
+[ ] 正确导入 api         - import { api } from '@robsun/keystone-web-core'
+[ ] 正确类型             - ApiResponse<T>
+[ ] 解构 data.data       - const { data } = await api.get<...>(...); return data.data
+[ ] 完整 CRUD            - list, get, create, update, delete
+```
+
+### 2.4 页面组件检查 ✓
+
+```tsx
+[ ] useTranslation       - const { t } = useTranslation('module')
+[ ] App.useApp           - const { message } = App.useApp()
+[ ] 加载状态             - loading, setLoading
+[ ] 错误处理             - try/catch + message.error
+[ ] Form.useForm         - const [form] = Form.useForm<FormValues>()
+[ ] 表单验证             - rules={[{ required: true, ... }]}
+[ ] Modal destroyOnHidden - 不要用 destroyOnClose
+[ ] 确认删除             - Popconfirm
+```
+
+### 2.5 翻译文件检查 ✓
+
+```json
+[ ] menu                 - 菜单标签
+[ ] page.title           - 页面标题
+[ ] page.createButton    - 创建按钮
+[ ] table.*              - 表格列标题
+[ ] form.*               - 表单标签和占位符
+[ ] status.*             - 状态枚举翻译
+[ ] messages.*           - 操作反馈消息
+```
+
+### 2.6 类型检查 ✓
+
+```typescript
+[ ] 实体类型完整         - 所有字段都有定义
+[ ] 状态联合类型         - type Status = 'active' | 'inactive'
+[ ] id 使用 number       - 后端是 uint
+[ ] 时间使用 string      - ISO 8601 格式
+```
+
+---
+
+## 3. 注册检查
+
+### 3.1 后端注册 ✓
+
+```
+[ ] manifest.go 导入     - import xxxmodule "app/internal/modules/xxx"
+[ ] manifest.go 注册     - Register(xxxmodule.NewModule())
+[ ] config.yaml 启用     - modules.enabled 包含模块名
+```
+
+### 3.2 前端注册 ✓
+
+```
+[ ] main.tsx 导入        - import './modules/xxx'
+[ ] app.config.ts 启用   - modules.enabled 包含模块名
+```
+
+---
+
+## 4. 质量检查
+
+### 4.1 代码检查 ✓
+
+```bash
+[ ] go build ./...       - 编译通过
+[ ] go test ./...        - 测试通过
+[ ] go vet ./...         - 无警告
+[ ] pnpm typecheck       - TypeScript 类型检查通过
+[ ] pnpm lint            - ESLint 检查通过
+```
+
+### 4.2 功能验证 ✓
+
+```
+[ ] 列表页加载           - 数据正确显示
+[ ] 创建功能             - 表单提交成功
+[ ] 编辑功能             - 数据回填 + 更新成功
+[ ] 删除功能             - 确认后删除成功
+[ ] 分页功能             - 翻页正常（如适用）
+[ ] 权限控制             - 无权限时按钮/菜单隐藏
+[ ] 多语言切换           - 中英文显示正确
+[ ] 错误提示             - 验证失败显示正确消息
+```
+
+---
+
+## 5. 快速验证命令
+
+```bash
+# 后端
+go build ./...
+go test ./... -v
+go vet ./...
+
+# 前端
+pnpm -C apps/web typecheck
+pnpm -C apps/web lint
+pnpm -C apps/web build
+
+# 运行验证
+make dev           # 启动后端
+pnpm -C apps/web dev  # 启动前端
+```
+
+---
+
+## 6. 审批流检查（--with-approval）
+
+### 6.1 后端审批 ✓
+
+```go
+[ ] 状态枚举完整         - draft/pending/approved/rejected/active/inactive
+[ ] ApprovalInstanceID   - 模型包含审批实例 ID 字段
+[ ] RejectReason         - 模型包含拒绝原因字段
+[ ] service/approval.go  - Submit() 和 Cancel() 方法
+[ ] service/callback.go  - OnApproved() 和 OnRejected() 实现
+[ ] handler/approval.go  - HTTP 处理器
+[ ] 审批路由             - POST /:id/submit, POST /:id/cancel
+[ ] 回调注册             - RegisterApprovalCallback() 在 module.go
+[ ] 审批类型常量         - ApprovalBusinessType = "module_approval"
+```
+
+### 6.2 前端审批 ✓
+
+```tsx
+[ ] ApprovalActions      - 状态标签 + 提交/撤回按钮组件
+[ ] 状态类型完整         - 'draft' | 'pending' | 'approved' | 'rejected'
+[ ] API 函数             - submit{Pascal}(), cancel{Pascal}Approval()
+[ ] 状态翻译             - status.draft/pending/approved/rejected
+[ ] 操作翻译             - actions.submit/cancelApproval
+[ ] 确认提示             - confirm.submit/cancel
+[ ] 消息翻译             - messages.submitSuccess/cancelSuccess
+```
+
+### 6.3 审批流验证 ✓
+
+```
+[ ] 草稿→提交            - 只有 draft 状态可提交
+[ ] 审批中→撤回          - 只有 pending 状态可撤回
+[ ] 回调幂等             - OnApproved/OnRejected 检查当前状态
+[ ] 上下文传递           - CreateInstance 包含业务信息
+[ ] 错误处理             - 状态不匹配返回 I18n 错误
+```
+
+---
+
+## 7. 常见遗漏
+
+| 遗漏项 | 后果 | 检查方法 |
+|--------|------|----------|
+| `app.config.ts` 未启用 | 菜单不显示 | 检查 modules.enabled |
+| `config.yaml` 未启用 | 模块不加载 | 检查 modules.enabled |
+| 缺少 TableName() | 表名错误 | 检查数据库表 |
+| 缺少 RegisterI18n() | 翻译不生效 | 检查错误消息 |
+| Handler nil 检查缺失 | 服务 panic | 启动时测试 API |
+| 缺少租户过滤 | 数据泄露 | 检查 SQL 日志 |
+| 翻译键不匹配 | 显示键而非文本 | 切换语言测试 |

package/template/.claude/skills/keystone-dev/references/GOTCHAS.md

@@ -0,0 +1,390 @@
+# Keystone 开发常见陷阱
+
+> 开发中容易踩的坑和解决方案。
+
+## 后端陷阱
+
+### G1: 菜单/模块不显示
+
+**症状**：模块代码写完，但菜单不出现或 API 404
+
+**原因**：未在配置中启用模块
+
+**解决**：
+```yaml
+# config.yaml
+modules:
+  enabled:
+    - example
+    - your_new_module  # 添加这行
+```
+
+```typescript
+// app.config.ts
+modules: {
+  enabled: ['example', 'your_new_module']  // 添加这里
+}
+```
+
+---
+
+### G2: Handler panic: nil pointer
+
+**症状**：调用 API 时服务 panic
+
+**原因**：Handler 或 Service 未初始化
+
+**错误代码**：
+```go
+func (h *Handler) List(c *gin.Context) {
+    items, _ := h.svc.List(c)  // h.svc 可能为 nil
+}
+```
+
+**正确代码**：
+```go
+func (h *Handler) List(c *gin.Context) {
+    if h == nil || h.svc == nil {
+        response.ServiceUnavailableI18n(c, modulei18n.MsgServiceUnavailable)
+        return
+    }
+    // ...
+}
+```
+
+---
+
+### G3: 数据跨租户泄露
+
+**症状**：用户能看到其他租户的数据
+
+**原因**：Repository 查询缺少租户过滤
+
+**错误代码**：
+```go
+func (r *Repository) List(ctx context.Context) ([]Entity, error) {
+    var items []Entity
+    r.db.Find(&items)  // 未过滤租户
+    return items, nil
+}
+```
+
+**正确代码**：
+```go
+func (r *Repository) List(ctx context.Context, tenantID uint) ([]Entity, error) {
+    var items []Entity
+    r.db.Where("tenant_id = ?", tenantID).Find(&items)
+    return items, nil
+}
+```
+
+---
+
+### G4: 翻译键显示为原始键
+
+**症状**：界面显示 `example.item.created` 而非翻译文本
+
+**原因**：
+1. 未调用 `RegisterI18n()`
+2. 翻译 JSON 文件路径错误
+3. 键名不匹配
+
+**检查**：
+```go
+// module.go 中必须有
+func (m *Module) RegisterI18n() error {
+    return modulei18n.RegisterLocales()  // 确保调用
+}
+
+// i18n/i18n.go
+//go:embed locales/*.json  // 确保路径正确
+var translations embed.FS
+```
+
+---
+
+### G5: GORM 自动更新 UpdatedAt 失效
+
+**症状**：更新记录后 `updated_at` 未变化
+
+**原因**：使用 `Updates()` 时只更新传入字段
+
+**解决**：使用 `Save()` 或显式设置
+```go
+// 方式一：使用 Save
+r.db.Save(entity)
+
+// 方式二：显式更新
+r.db.Model(entity).Updates(map[string]interface{}{
+    "name":       entity.Name,
+    "updated_at": time.Now(),
+})
+```
+
+---
+
+### G6: 软删除查不到数据
+
+**症状**：数据库有记录但查询返回空
+
+**原因**：GORM 自动添加 `deleted_at IS NULL` 条件
+
+**解决**：
+```go
+// 查询包含已删除记录
+r.db.Unscoped().Where("id = ?", id).First(&entity)
+
+// 恢复已删除记录
+r.db.Unscoped().Model(&Entity{}).
+    Where("id = ?", id).
+    Update("deleted_at", nil)
+```
+
+---
+
+### G7: 循环依赖导致编译失败
+
+**症状**：`import cycle not allowed`
+
+**原因**：service 和 repository 互相导入
+
+**错误结构**：
+```
+service/ → imports → repository/
+repository/ → imports → service/  // 循环!
+```
+
+**解决**：在 service 定义接口，repository 实现
+```go
+// service/service.go
+type EntityRepository interface {
+    FindByID(id uint) (*models.Entity, error)
+}
+
+// repository/repository.go
+// 实现 service.EntityRepository 接口，但不导入 service 包
+```
+
+---
+
+## 前端陷阱
+
+### G8: Modal destroyOnClose 无效
+
+**症状**：Modal 关闭后再打开，表单数据残留
+
+**原因**：Ant Design v6 API 变更
+
+**错误代码**：
+```tsx
+<Modal destroyOnClose>  // v6 已废弃
+```
+
+**正确代码**：
+```tsx
+<Modal destroyOnHidden>  // v6 使用这个
+```
+
+---
+
+### G9: 翻译不生效
+
+**症状**：`t('key')` 返回 key 本身
+
+**原因**：
+1. 未注册翻译文件
+2. 命名空间错误
+
+**检查**：
+```typescript
+// index.ts 中确保导入翻译文件
+import './locales/zh-CN/module.json'
+import './locales/en-US/module.json'
+
+// 使用时指定正确命名空间
+const { t } = useTranslation('module')  // 不是 'common'
+```
+
+---
+
+### G10: API 响应解构错误
+
+**症状**：`TypeError: Cannot read property 'xxx' of undefined`
+
+**原因**：响应结构是 `{ data: { data: {...} } }`
+
+**错误代码**：
+```typescript
+const response = await api.get<ApiResponse<Entity>>('/entity/1')
+return response.data  // 这是外层 data
+```
+
+**正确代码**：
+```typescript
+const { data } = await api.get<ApiResponse<Entity>>('/entity/1')
+return data.data  // 这是内层 data
+```
+
+---
+
+### G11: Table columns 类型错误
+
+**症状**：TypeScript 报类型不兼容
+
+**原因**：未使用 `ColumnsType<T>`
+
+**错误代码**：
+```tsx
+const columns = [
+    { title: 'Name', dataIndex: 'name' }
+]
+```
+
+**正确代码**：
+```tsx
+import type { ColumnsType } from 'antd/es/table'
+
+const columns: ColumnsType<Entity> = [
+    { title: 'Name', dataIndex: 'name', key: 'name' }
+]
+```
+
+---
+
+### G12: Form 验证不触发
+
+**症状**：点击提交按钮无反应
+
+**原因**：未正确使用 `Form.useForm()` 或 `validateFields()`
+
+**错误代码**：
+```tsx
+const handleSubmit = () => {
+    const values = form.getFieldsValue()  // 不会触发验证
+}
+```
+
+**正确代码**：
+```tsx
+const handleSubmit = async () => {
+    try {
+        const values = await form.validateFields()  // 会触发验证
+        // 处理提交
+    } catch {
+        return  // 验证失败，不提交
+    }
+}
+```
+
+---
+
+### G13: useCallback 依赖缺失
+
+**症状**：函数行为不符合预期，使用旧闭包值
+
+**原因**：useCallback 依赖数组不完整
+
+**错误代码**：
+```tsx
+const fetchData = useCallback(async () => {
+    const data = await listItems({ status: filter })  // filter 可能是旧值
+}, [])  // 缺少 filter 依赖
+```
+
+**正确代码**：
+```tsx
+const fetchData = useCallback(async () => {
+    const data = await listItems({ status: filter })
+}, [filter])  // 添加 filter 依赖
+```
+
+---
+
+### G14: 权限菜单不显示
+
+**症状**：有权限但菜单不出现
+
+**原因**：
+1. `app.config.ts` 未启用模块
+2. 权限码不匹配
+
+**检查**：
+```typescript
+// routes.tsx
+handle: {
+    menu: {
+        permission: 'module:entity:view',  // 确保格式正确
+    }
+}
+
+// 后端权限注册
+reg.CreateActionI18n(
+    "module:entity:view",  // 必须与前端一致
+    ...
+)
+```
+
+---
+
+## 性能陷阱
+
+### G15: N+1 查询
+
+**症状**：列表页加载慢，日志显示大量 SQL
+
+**原因**：循环中查询关联数据
+
+**错误代码**：
+```go
+entities, _ := repo.List(ctx, tenantID)
+for i := range entities {
+    entities[i].Category, _ = repo.GetCategory(entities[i].CategoryID)  // N次查询
+}
+```
+
+**正确代码**：
+```go
+// 使用 Preload
+r.db.Preload("Category").Find(&entities)
+
+// 或批量查询
+categoryIDs := extractIDs(entities)
+categories, _ := repo.GetCategoriesByIDs(categoryIDs)
+```
+
+---
+
+### G16: 无限重渲染
+
+**症状**：页面卡死，控制台显示大量渲染日志
+
+**原因**：useEffect 依赖数组包含每次渲染都变化的值
+
+**错误代码**：
+```tsx
+useEffect(() => {
+    fetchData()
+}, [{ page, pageSize }])  // 对象每次都是新引用
+```
+
+**正确代码**：
+```tsx
+useEffect(() => {
+    fetchData()
+}, [page, pageSize])  // 使用原始值
+```
+
+---
+
+## 快速排查表
+
+| 现象 | 首先检查 |
+|------|----------|
+| 404 Not Found | config.yaml + manifest.go 注册 |
+| 菜单不显示 | app.config.ts 启用 |
+| 翻译键原样显示 | RegisterI18n() + JSON 文件路径 |
+| nil pointer panic | Handler nil 检查 |
+| 数据泄露 | 租户 ID 过滤 |
+| TypeScript 报错 | 类型定义 + ColumnsType |
+| 表单验证无效 | validateFields() 使用 |
+| Modal 数据残留 | destroyOnHidden |