@robsun/create-keystone-app 0.2.13 → 0.4.0

package/template/.codex/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/.codex/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)
-}
-```