@robsun/create-keystone-app 0.2.11 → 0.2.13

package/package.json

@@ -1,23 +1,23 @@
-{
-  "name": "@robsun/create-keystone-app",
-  "version": "0.2.11",
-  "scripts": {
-    "build": "node scripts/build.js",
-    "prepublishOnly": "node scripts/build.js && node scripts/prune-template-deps.js"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "create-keystone-app": "dist/create-keystone-app.js",
-    "create-keystone-module": "dist/create-module.js"
-  },
-  "files": [
-    "dist",
-    "template",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  }
-}
+{
+  "name": "@robsun/create-keystone-app",
+  "version": "0.2.13",
+  "scripts": {
+    "build": "node scripts/build.js",
+    "prepublishOnly": "node scripts/build.js && node scripts/prune-template-deps.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "create-keystone-app": "dist/create-keystone-app.js",
+    "create-keystone-module": "dist/create-module.js"
+  },
+  "files": [
+    "dist",
+    "template",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/template/.claude/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/.claude/skills/keystone-dev/references/CAPABILITIES.md

@@ -1,206 +1,261 @@
-# Keystone 包完整能力清单
-
-## 一、前端组件 (@robsun/keystone-web-core)
-
-### 1. 应用与路由
-```typescript
-import { KeystoneApp, createKeystoneRouter } from '@robsun/keystone-web-core'
-import { registerModule, registerRoutes, registerMenus, registerPermissions } from '@robsun/keystone-web-core'
-```
-
-### 2. 高级 UI 组件
-```typescript
-// 高级表格 - 过滤、分页、行选择、导出
-import { ProTable } from '@robsun/keystone-web-core'
-
-// 智能表单 - 自动验证、加载状态
-import { ProForm } from '@robsun/keystone-web-core'
-
-// 文件上传 - 拖拽、预览、多文件
-import { FileUpload } from '@robsun/keystone-web-core'
-
-// 数据导入向导
-import { DataImporter, ImportWizard, ColumnMapper, ValidationResult } from '@robsun/keystone-web-core'
-
-// 数据导出向导
-import { DataExporter, ExportWizard } from '@robsun/keystone-web-core'
-
-// 权限守卫
-import { PermissionGuard } from '@robsun/keystone-web-core'
-```
-
-### 3. 审批流系统
-```typescript
-import {
-  ApprovalFlowEditor,    // 流程编辑器
-  ApprovalFlowCanvas,    // 可视化画布
-  ApprovalNodeEditor,    // 节点编辑
-  ConditionEditor,       // 条件编辑
-  ApprovalStatus,        // 状态展示
-  ApprovalAction,        // 审批按钮
-  ApprovalHistory        // 审批历史
-} from '@robsun/keystone-web-core'
-```
-审批流程与接入说明见 [approval.md](approval.md)。
-
-### 4. 帮助系统
-```typescript
-import {
-  HelpButton, HelpDrawer, HelpSearch, HelpContent,
-  useCurrentHelpKey, useHelpSearch
-} from '@robsun/keystone-web-core'
-```
-
-### 5. 布局与主题
-```typescript
-import { MainLayout, antdTheme, useLayoutStore } from '@robsun/keystone-web-core'
-```
-
-### 6. 认证授权
-```typescript
-import { useAuthStore, useAuth, matchesPermission } from '@robsun/keystone-web-core'
-```
-
-### 7. 运行时服务
-```typescript
-import { api, setApiBaseUrl } from '@robsun/keystone-web-core'
-import { createExportJob, createImportJob } from '@robsun/keystone-web-core'
-import { listNotifications, markNotificationRead, fetchUnreadCount } from '@robsun/keystone-web-core'
-import { getJob, listJobs } from '@robsun/keystone-web-core'
-```
-
-### 8. 多语言 (i18n)
-```typescript
-// 翻译 Hook
-import { useTranslation } from 'react-i18next'
-
-// 使用示例
-const { t } = useTranslation()
-const title = t('module:key')  // 命名空间:键
-const description = t('common:actions.save')
-
-// 平台多语言配置
-import { getKeystoneConfig } from '@robsun/keystone-web-core'
-const locale = getKeystoneConfig().ui?.i18n?.defaultLocale // 'zh-CN' | 'en-US'
-
-// dayjs 本地化同步（自动完成）
-import dayjs from 'dayjs'
-dayjs.locale(getKeystoneConfig().ui?.locale?.dayjs ?? 'zh-cn')
-```
-
-**翻译文件组织**：
-```
-src/modules/{module}/locales/
-├── zh-CN/
-│   └── {namespace}.json
-└── en-US/
-    └── {namespace}.json
-```
-
-**命名空间约定**：
-- `common` - 通用文案（按钮、操作、状态等）
-- `auth` - 认证相关
-- `system` - 系统管理
-- `{module}` - 业务模块专属翻译
-
-### 9. Hooks
-```typescript
-import { useListState } from '@robsun/keystone-web-core'
-```
-
-### 10. 类型
-```typescript
-import type { ApiResponse, PaginatedData, PaginatedResponse } from '@robsun/keystone-web-core'
-import type { Permission, ModuleName, Action } from '@robsun/keystone-web-core'
-```
-
-## 二、后端能力 (Go)
-
-### 1. 模块系统
-```go
-type Module interface {
-    Name() string
-    RegisterRoutes(r *gin.RouterGroup)
-    RegisterPermissions() []Permission
-    Migrate(db *gorm.DB) error
-    Seed(db *gorm.DB) error
-}
-```
-
-### 2. 审批引擎
-```go
-approvalService.CreateInstance(...)
-approvalService.Approve(...)
-approvalService.Reject(...)
-approvalService.Cancel(...)
-```
-
-### 3. Job 队列
-```go
-jobService.CreateJob(...)
-jobService.GetJob(...)
-jobService.ListJobs(...)
-```
-
-### 4. 通知服务
-```go
-notificationService.SendNotification(...)
-notificationService.ListNotifications(...)
-notificationService.MarkRead(...)
-```
-
-### 5. 权限中间件
-```go
-middleware.RequirePermission("module:resource:action")
-```
-
-### 6. 存储服务
-```go
-storageService.Upload(...)
-storageService.Download(...)
-storageService.Delete(...)
-```
-
-### 7. 多语言 (i18n)
-```go
-// 获取当前请求语言环境
-import "github.com/robsuncn/keystone/infra/i18n"
-
-locale := i18n.GetLocale(c)  // 从请求头或参数获取
-
-// 翻译函数
-i18n.T(c, "module.key")                    // 基础翻译
-i18n.T(c, "module.greeting", "name", "张三") // 带变量
-i18n.Tf(c, "module.count", count)          // 复数形式
-
-// 错误消息翻译
-return errors.New(i18n.T(c, "module.errors.notFound"))
-```
-
-**翻译文件组织**：
-```
-internal/modules/{module}/i18n/
-├── i18n.go                    # 初始化
-├── keys.go                    # 翻译键常量
-└── locales/
-    ├── zh-CN.json
-    └── en-US.json
-```
-
-**翻译键常量定义**：
-```go
-package i18n
-
-const (
-    KeyItemCreated    = "example.item.created"
-    KeyItemNotFound   = "example.item.notFound"
-    KeyItemInvalid    = "example.item.invalid"
-)
-```
-
-**模块初始化**：
-```go
-func init() {
-    i18n.MustLoadModuleTranslations("example", Translations)
-}
-```
+# Keystone 包完整能力清单
+
+## 一、前端组件 (@robsun/keystone-web-core)
+
+### 1. 应用与路由
+```typescript
+import { KeystoneApp, createKeystoneRouter } from '@robsun/keystone-web-core'
+import { registerModule, registerRoutes, registerMenus, registerPermissions } from '@robsun/keystone-web-core'
+```
+
+### 2. 高级 UI 组件
+```typescript
+// 高级表格 - 过滤、分页、行选择、导出
+import { ProTable } from '@robsun/keystone-web-core'
+
+// 智能表单 - 自动验证、加载状态
+import { ProForm } from '@robsun/keystone-web-core'
+
+// 文件上传 - 拖拽、预览、多文件
+import { FileUpload } from '@robsun/keystone-web-core'
+
+// 数据导入向导
+import { DataImporter, ImportWizard, ColumnMapper, ValidationResult } from '@robsun/keystone-web-core'
+
+// 数据导出向导
+import { DataExporter, ExportWizard } from '@robsun/keystone-web-core'
+
+// 权限守卫
+import { PermissionGuard } from '@robsun/keystone-web-core'
+```
+
+### 3. 审批流系统
+```typescript
+import {
+  ApprovalFlowEditor,    // 流程编辑器
+  ApprovalFlowCanvas,    // 可视化画布
+  ApprovalNodeEditor,    // 节点编辑
+  ConditionEditor,       // 条件编辑
+  ApprovalStatus,        // 状态展示
+  ApprovalAction,        // 审批按钮
+  ApprovalHistory        // 审批历史
+} from '@robsun/keystone-web-core'
+```
+审批流程与接入说明见 [approval.md](approval.md)。
+
+### 4. 帮助系统
+```typescript
+import {
+  HelpButton, HelpDrawer, HelpSearch, HelpContent,
+  useCurrentHelpKey, useHelpSearch
+} from '@robsun/keystone-web-core'
+```
+
+### 5. 布局与主题
+```typescript
+import { MainLayout, antdTheme, useLayoutStore } from '@robsun/keystone-web-core'
+```
+
+### 6. 认证授权
+```typescript
+import { useAuthStore, useAuth, matchesPermission } from '@robsun/keystone-web-core'
+```
+
+### 7. 运行时服务
+```typescript
+import { api, setApiBaseUrl } from '@robsun/keystone-web-core'
+import { createExportJob, createImportJob } from '@robsun/keystone-web-core'
+import { listNotifications, markNotificationRead, fetchUnreadCount } from '@robsun/keystone-web-core'
+import { getJob, listJobs } from '@robsun/keystone-web-core'
+```
+
+### 8. 多语言 (i18n)
+```typescript
+// 翻译 Hook
+import { useTranslation } from 'react-i18next'
+
+// 使用示例
+const { t } = useTranslation()
+const title = t('module:key')  // 命名空间:键
+const description = t('common:actions.save')
+
+// 平台多语言配置
+import { getKeystoneConfig } from '@robsun/keystone-web-core'
+const locale = getKeystoneConfig().ui?.i18n?.defaultLocale // 'zh-CN' | 'en-US'
+
+// dayjs 本地化同步（自动完成）
+import dayjs from 'dayjs'
+dayjs.locale(getKeystoneConfig().ui?.locale?.dayjs ?? 'zh-cn')
+```
+
+**翻译文件组织**：
+```
+src/modules/{module}/locales/
+├── zh-CN/
+│   └── {namespace}.json
+└── en-US/
+    └── {namespace}.json
+```
+
+**命名空间约定**：
+- `common` - 通用文案（按钮、操作、状态等）
+- `auth` - 认证相关
+- `system` - 系统管理
+- `{module}` - 业务模块专属翻译
+
+### 9. Hooks
+```typescript
+import { useListState } from '@robsun/keystone-web-core'
+```
+
+### 10. 类型
+```typescript
+import type { ApiResponse, PaginatedData, PaginatedResponse } from '@robsun/keystone-web-core'
+import type { Permission, ModuleName, Action } from '@robsun/keystone-web-core'
+```
+
+## 二、后端能力 (Go)
+
+### 1. 模块系统
+```go
+type Module interface {
+    Name() string
+    RegisterRoutes(r *gin.RouterGroup)
+    RegisterPermissions() []Permission
+    Migrate(db *gorm.DB) error
+    Seed(db *gorm.DB) error
+}
+```
+
+### 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)
+    }
+}
+```
+
+### 4. Job 队列
+```go
+jobService.CreateJob(...)
+jobService.GetJob(...)
+jobService.ListJobs(...)
+```
+
+### 5. 通知服务
+```go
+notificationService.SendNotification(...)
+notificationService.ListNotifications(...)
+notificationService.MarkRead(...)
+```
+
+### 6. 权限中间件
+```go
+middleware.RequirePermission("module:resource:action")
+```
+
+### 7. 存储服务
+```go
+storageService.Upload(...)
+storageService.Download(...)
+storageService.Delete(...)
+```
+
+### 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"
+
+locale := i18n.GetLocale(c)  // 从请求头或参数获取
+
+// 翻译函数
+i18n.T(c, "module.key")                    // 基础翻译
+i18n.T(c, "module.greeting", "name", "张三") // 带变量
+i18n.Tf(c, "module.count", count)          // 复数形式
+
+// 错误消息翻译
+return errors.New(i18n.T(c, "module.errors.notFound"))
+```
+
+**翻译文件组织**：
+```
+internal/modules/{module}/i18n/
+├── i18n.go                    # 初始化
+├── keys.go                    # 翻译键常量
+└── locales/
+    ├── zh-CN.json
+    └── en-US.json
+```
+
+**翻译键常量定义**：
+```go
+package i18n
+
+const (
+    KeyItemCreated    = "example.item.created"
+    KeyItemNotFound   = "example.item.notFound"
+    KeyItemInvalid    = "example.item.invalid"
+)
+```
+
+**模块初始化**：
+```go
+func init() {
+    i18n.MustLoadModuleTranslations("example", Translations)
+}
+```