@robsun/create-keystone-app 0.2.12 → 0.2.15

package/template/.codex/skills/keystone-dev/references/APPROVAL.md

@@ -50,11 +50,58 @@ approval:flow:view|create|edit|delete
 approval:instance:view|approve|cancel  
 approval:record:view|export
 
+## 流程版本控制
+
+审批流程支持版本管理，确保活跃实例不受流程修改影响：
+
+**状态生命周期**：`draft` → `published` → `deprecated`
+
+- **draft**: 草稿状态，可编辑，不能创建实例
+- **published**: 已发布，不可编辑，可创建实例
+- **deprecated**: 已废弃，不可编辑，不可创建新实例
+
+**操作方式**：
+```go
+// 发布流程（draft → published）
+approvalService.PublishFlow(ctx, tenantID, flowID)
+
+// 创建新版本（基于已发布流程）
+newFlow, err := approvalService.CreateNewVersion(ctx, tenantID, flowID)
+// 新版本为 draft 状态，ParentFlowID 指向原流程
+
+// 废弃旧版本（自动在发布新版本时执行）
+approvalService.DeprecateFlow(ctx, tenantID, flowID)
+```
+
+## 回调重试机制
+
+审批回调（OnApproved/OnRejected）支持自动重试：
+
+```go
+import approval "github.com/robsuncn/keystone/domain/approval/service"
+
+// 配置重试策略
+config := approval.RetryConfig{
+    MaxRetries:     3,              // 最大重试次数
+    InitialBackoff: time.Second,    // 初始退避时间
+    MaxBackoff:     30 * time.Second, // 最大退避时间
+    BackoffFactor:  2.0,            // 退避倍数（指数退避）
+}
+
+// 包装回调
+retryable := approval.NewRetryableCallback(myCallback, config)
+
+// 或使用异步执行器
+executor := approval.NewAsyncCallbackExecutor(registry, config, 100)
+```
+
 ## 集成自检
 - Flow code <= 50 且使用大写；business type 用短字符串。
 - approve/reject/cancel 使用 version 做乐观锁。
 - 变更接口时更新 OpenAPI 合同。
 - 新增默认流程时补迁移或 seed。
+- **新流程从 draft 开始，发布后才能创建实例**。
+- **使用 RetryableCallback 包装业务回调以增强可靠性**。
 
 测试清单见 [testing.md](testing.md)。
 

package/template/.codex/skills/keystone-dev/references/CAPABILITIES.md

@@ -129,39 +129,94 @@ type Module interface {
 
 ### 2. 审批引擎
 ```go
+// 基础操作
 approvalService.CreateInstance(...)
 approvalService.Approve(...)
 approvalService.Reject(...)
 approvalService.Cancel(...)
+
+// 流程版本控制
+approvalService.PublishFlow(...)   // draft → published
+approvalService.DeprecateFlow(...) // published → deprecated
+approvalService.CreateNewVersion(...) // 基于现有流程创建新版本
+```
+
+**流程状态生命周期**：`draft` → `published` → `deprecated`
+
+### 3. 审批回调重试
+```go
+import approval "github.com/robsuncn/keystone/domain/approval/service"
+
+// 带重试的回调包装
+config := approval.RetryConfig{
+    MaxRetries:     3,
+    InitialBackoff: time.Second,
+    MaxBackoff:     30 * time.Second,
+    BackoffFactor:  2.0,
+}
+retryable := approval.NewRetryableCallback(callback, config)
+
+// 异步回调执行器
+executor := approval.NewAsyncCallbackExecutor(registry, config, 100)
+executor.ExecuteApproved(ctx, businessType, tenantID, businessID, approverID)
+
+// 监听结果
+for result := range executor.Results() {
+    if !result.Success {
+        log.Error("callback failed", "error", result.Error)
+    }
+}
 ```
 
-### 3. Job 队列
+### 4. Job 队列
 ```go
 jobService.CreateJob(...)
 jobService.GetJob(...)
 jobService.ListJobs(...)
 ```
 
-### 4. 通知服务
+### 5. 通知服务
 ```go
 notificationService.SendNotification(...)
 notificationService.ListNotifications(...)
 notificationService.MarkRead(...)
 ```
 
-### 5. 权限中间件
+### 6. 权限中间件
 ```go
 middleware.RequirePermission("module:resource:action")
 ```
 
-### 6. 存储服务
+### 7. 存储服务
 ```go
 storageService.Upload(...)
 storageService.Download(...)
 storageService.Delete(...)
 ```
 
-### 7. 多语言 (i18n)
+### 8. 统一分页
+```go
+import "github.com/robsuncn/keystone/infra/pagination"
+
+// 解析请求参数
+req := pagination.ParseRequest(c) // 从 Gin context 获取 page, page_size
+
+// 方式一：使用 GORM Scope
+db.Scopes(pagination.Scope(req)).Find(&items)
+
+// 方式二：一步完成分页查询
+var items []Item
+total, err := pagination.Paginate(db.Where("tenant_id = ?", tenantID), req, &items)
+
+// 方式三：带预加载的分页
+total, err := pagination.PaginateWithPreload(db, req, &items, "Category", "Tags")
+
+// 构建响应
+resp := pagination.NewResponse(items, total, req)
+// resp.TotalPages(), resp.HasNextPage(), resp.HasPrevPage()
+```
+
+### 9. 多语言 (i18n)
 ```go
 // 获取当前请求语言环境
 import "github.com/robsuncn/keystone/infra/i18n"

package/template/.codex/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 日志 |
+| 翻译键不匹配 | 显示键而非文本 | 切换语言测试 |