@robsun/create-keystone-app 0.2.15 → 0.4.0

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

@@ -1,121 +0,0 @@
-# Keystone 审批接入流程
-
-## 目标
-本文只描述审批接入所需的表单 schema 与 context 映射等开发工作，
-流程节点与审批路径由人工在审批配置页面完成。
-
-## 适用场景
-- 新业务需要审批门禁（新业务类型）。
-- 既有业务接入审批门禁（在业务表单提交或关键业务动作前加审批）。
-
-## 不在范围
-- 配置审批流程与节点（由人工在流程配置页面完成）。
-- 修改 approval 基础模块或审批页面本身。
-- 改造审批权限体系或审批路由结构。
-
-## 开发路径选择
-- Greenfield：新业务从零引入审批。
-- Retrofit：已有业务接入审批。
-
-## 开发步骤 A：新业务（Greenfield）
-1) 前端配置 `approval.businessTypes` 标签映射（用于流程配置时选择表单），
-   流程配置页面的业务类型选择会作为 schema code 加载表单字段，需保持一致。
-2) 注册表单 schema（条件节点字段来源）。
-3) 在业务提交处创建审批实例，写入 context JSON 用于条件路由。
-4) 绑定 OnApproved/OnRejected 回调更新业务状态。
-5) 按测试清单执行（见 testing.md）。
-
-## 开发步骤 B：已有业务接入（Retrofit）
-1) 确认触发点与审批边界（业务表单提交或关键业务动作前）。
-2) 将现有字段映射为 context JSON（供条件节点判断）。
-3) 做幂等：按业务类型 + 业务 ID 查已有实例再创建。
-4) pending 期间阻断业务动作（状态拦截或硬拦截）。
-5) 决定是否回填存量数据（跳过或补建实例）。
-
-## 业务侧改动清单
-
-后端（业务模块内）
-- 在业务 service/handler 中调用审批服务创建实例（必要时通过 FlowMatcher 选 flow）。
-- 在业务模块注册审批回调，审批通过/驳回时更新业务状态。
-- 需要数据范围过滤时，实现 ApprovalContextResolver 并在应用装配时注入。
-- 如需默认 flow 或 schema，放在业务模块的迁移/seed 中，不改动审批模块。
-
-前端（业务模块内）
-- 配置 `approval.businessTypes` 标签映射，保证业务类型显示正确。
-- 流程配置使用已有审批管理页面，不做二次开发。
-
-## 权限说明
-使用系统既有审批权限码：
-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)。
-
-## 参考入口
-
-后端
-- domain/approval/service/service.go
-- domain/approval/service/flow_matcher.go
-- domain/approval/service/callback_registry.go
-- api/routes/approval_routes.go
-- contracts/011-approvals/approvals-api.yaml
-
-前端
-- packages/keystone-web-core/src/platform/config/appConfig.ts
-- packages/keystone-web-core/src/platform/core/approval/services/approvalService.ts
-- packages/keystone-web-core/src/platform/core/approval/stores/approvalStore.ts
-- packages/keystone-web-core/src/modules/keystone/approval/pages/*

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

@@ -1,261 +0,0 @@
-# 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)
-}
-```

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

@@ -1,285 +0,0 @@
-# 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 日志 |
-| 翻译键不匹配 | 显示键而非文本 | 切换语言测试 |