@robsun/create-keystone-app 0.2.15 → 0.4.1

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

@@ -1,605 +0,0 @@
-# Keystone 后端开发模式
-
-> 本文档补充 TEMPLATES.md 中未覆盖的高级开发模式。
-
-## 1. 分页与过滤
-
-### 1.1 带分页的列表 Handler
-
-```go
-import "github.com/robsuncn/keystone/infra/pagination"
-
-func (h *Handler) List(c *gin.Context) {
-    tenantID := resolveTenantID(c)
-
-    // 解析分页参数
-    pageReq := pagination.ParseRequest(c) // 自动从 query string 获取 page, page_size
-
-    // 解析过滤参数
-    filter := parseFilter(c)
-
-    items, total, err := h.svc.List(c.Request.Context(), tenantID, filter, pageReq)
-    if err != nil {
-        response.InternalErrorI18n(c, modulei18n.MsgLoadFailed)
-        return
-    }
-
-    // 返回分页响应
-    response.Success(c, pagination.NewResponse(items, total, pageReq))
-}
-
-type ListFilter struct {
-    Status   *string `form:"status"`
-    Keyword  *string `form:"keyword"`
-    DateFrom *string `form:"date_from"`
-    DateTo   *string `form:"date_to"`
-}
-
-func parseFilter(c *gin.Context) ListFilter {
-    var filter ListFilter
-    _ = c.ShouldBindQuery(&filter)
-    return filter
-}
-```
-
-### 1.2 Repository 分页查询
-
-```go
-import "github.com/robsuncn/keystone/infra/pagination"
-
-func (r *Repository) List(
-    ctx context.Context,
-    tenantID uint,
-    filter ListFilter,
-    pageReq pagination.Request,
-) ([]models.Entity, int64, error) {
-    query := r.db.WithContext(ctx).
-        Model(&models.Entity{}).
-        Where("tenant_id = ?", tenantID)
-
-    // 应用过滤条件
-    if filter.Status != nil {
-        query = query.Where("status = ?", *filter.Status)
-    }
-    if filter.Keyword != nil && *filter.Keyword != "" {
-        keyword := "%" + *filter.Keyword + "%"
-        query = query.Where("name LIKE ? OR description LIKE ?", keyword, keyword)
-    }
-    if filter.DateFrom != nil {
-        query = query.Where("created_at >= ?", *filter.DateFrom)
-    }
-    if filter.DateTo != nil {
-        query = query.Where("created_at <= ?", *filter.DateTo)
-    }
-
-    // 使用统一分页工具
-    var items []models.Entity
-    total, err := pagination.Paginate(query.Order("created_at desc"), pageReq, &items)
-    return items, total, err
-}
-```
-
----
-
-## 2. 事务处理
-
-### 2.1 Service 层事务
-
-```go
-func (s *Service) CreateWithRelations(
-    ctx context.Context,
-    tenantID uint,
-    input CreateInput,
-) (*models.Entity, error) {
-    var result *models.Entity
-
-    err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
-        // 创建主实体
-        entity := &models.Entity{
-            Name: input.Name,
-        }
-        entity.TenantID = tenantID
-
-        if err := tx.Create(entity).Error; err != nil {
-            return err
-        }
-
-        // 创建关联实体
-        for _, itemInput := range input.Items {
-            item := &models.EntityItem{
-                EntityID: entity.ID,
-                Name:     itemInput.Name,
-            }
-            if err := tx.Create(item).Error; err != nil {
-                return err // 自动回滚
-            }
-        }
-
-        result = entity
-        return nil
-    })
-
-    return result, err
-}
-```
-
-### 2.2 Repository 层事务（推荐）
-
-```go
-// Repository 接收 *gorm.DB，可以是普通 db 或事务 tx
-type Repository struct {
-    db *gorm.DB
-}
-
-// 在 Service 中管理事务
-func (s *Service) Transfer(ctx context.Context, fromID, toID uint, amount int) error {
-    return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
-        // 创建使用事务的临时 repository
-        txRepo := repository.NewRepository(tx)
-
-        from, err := txRepo.FindByID(fromID)
-        if err != nil {
-            return err
-        }
-
-        to, err := txRepo.FindByID(toID)
-        if err != nil {
-            return err
-        }
-
-        from.Balance -= amount
-        to.Balance += amount
-
-        if err := txRepo.Update(ctx, from); err != nil {
-            return err
-        }
-        return txRepo.Update(ctx, to)
-    })
-}
-```
-
----
-
-## 3. 批量操作
-
-### 3.1 批量创建
-
-```go
-func (h *Handler) BatchCreate(c *gin.Context) {
-    tenantID := resolveTenantID(c)
-
-    var input struct {
-        Items []createInput `json:"items" binding:"required,min=1,max=100"`
-    }
-    if err := c.ShouldBindJSON(&input); err != nil {
-        response.BadRequestI18n(c, modulei18n.MsgInvalidPayload)
-        return
-    }
-
-    results, err := h.svc.BatchCreate(c.Request.Context(), tenantID, input.Items)
-    if err != nil {
-        response.InternalErrorI18n(c, modulei18n.MsgCreateFailed)
-        return
-    }
-
-    response.CreatedI18n(c, modulei18n.MsgBatchCreated, gin.H{
-        "created": len(results),
-        "items":   results,
-    })
-}
-
-// Service
-func (s *Service) BatchCreate(ctx context.Context, tenantID uint, inputs []Input) ([]models.Entity, error) {
-    entities := make([]models.Entity, 0, len(inputs))
-
-    for _, input := range inputs {
-        entity := models.Entity{
-            Name: strings.TrimSpace(input.Name),
-        }
-        entity.TenantID = tenantID
-        entities = append(entities, entity)
-    }
-
-    // GORM 批量插入
-    if err := s.repo.db.WithContext(ctx).CreateInBatches(&entities, 100).Error; err != nil {
-        return nil, err
-    }
-
-    return entities, nil
-}
-```
-
-### 3.2 批量删除
-
-```go
-func (h *Handler) BatchDelete(c *gin.Context) {
-    tenantID := resolveTenantID(c)
-
-    var input struct {
-        IDs []uint `json:"ids" binding:"required,min=1,max=100"`
-    }
-    if err := c.ShouldBindJSON(&input); err != nil {
-        response.BadRequestI18n(c, modulei18n.MsgInvalidPayload)
-        return
-    }
-
-    count, err := h.svc.BatchDelete(c.Request.Context(), tenantID, input.IDs)
-    if err != nil {
-        response.InternalErrorI18n(c, modulei18n.MsgDeleteFailed)
-        return
-    }
-
-    response.SuccessI18n(c, modulei18n.MsgBatchDeleted, gin.H{"deleted": count})
-}
-
-// Repository
-func (r *Repository) BatchDelete(ctx context.Context, tenantID uint, ids []uint) (int64, error) {
-    result := r.db.WithContext(ctx).
-        Where("tenant_id = ? AND id IN ?", tenantID, ids).
-        Delete(&models.Entity{})
-    return result.RowsAffected, result.Error
-}
-```
-
----
-
-## 4. 软删除与恢复
-
-### 4.1 模型定义
-
-```go
-import "gorm.io/gorm"
-
-type Entity struct {
-    models.BaseModel // 已包含 DeletedAt gorm.DeletedAt
-    Name string
-}
-
-// 查询时自动排除已删除记录
-// 如需查询已删除记录，使用 db.Unscoped()
-```
-
-### 4.2 恢复已删除记录
-
-```go
-func (r *Repository) Restore(ctx context.Context, tenantID, id uint) error {
-    return r.db.WithContext(ctx).
-        Unscoped().
-        Model(&models.Entity{}).
-        Where("tenant_id = ? AND id = ?", tenantID, id).
-        Update("deleted_at", nil).Error
-}
-
-func (r *Repository) FindDeletedByID(tenantID, id uint) (*models.Entity, error) {
-    var entity models.Entity
-    err := r.db.Unscoped().
-        Where("tenant_id = ? AND id = ? AND deleted_at IS NOT NULL", tenantID, id).
-        First(&entity).Error
-    if errors.Is(err, gorm.ErrRecordNotFound) {
-        return nil, ErrEntityNotFound
-    }
-    return &entity, err
-}
-```
-
----
-
-## 5. 关联查询
-
-### 5.1 预加载关联
-
-```go
-func (r *Repository) FindByIDWithItems(tenantID, id uint) (*models.Entity, error) {
-    var entity models.Entity
-    err := r.db.
-        Preload("Items").           // 预加载 has-many 关联
-        Preload("Category").        // 预加载 belongs-to 关联
-        Where("tenant_id = ? AND id = ?", tenantID, id).
-        First(&entity).Error
-    if errors.Is(err, gorm.ErrRecordNotFound) {
-        return nil, ErrEntityNotFound
-    }
-    return &entity, err
-}
-
-// 带条件的预加载
-func (r *Repository) FindWithActiveItems(tenantID, id uint) (*models.Entity, error) {
-    var entity models.Entity
-    err := r.db.
-        Preload("Items", "status = ?", "active").
-        Where("tenant_id = ? AND id = ?", tenantID, id).
-        First(&entity).Error
-    return &entity, err
-}
-```
-
-### 5.2 分页带预加载
-
-```go
-func (r *Repository) ListWithCategory(
-    ctx context.Context,
-    tenantID uint,
-    pageReq pagination.Request,
-) ([]models.Entity, int64, error) {
-    var items []models.Entity
-    query := r.db.WithContext(ctx).
-        Model(&models.Entity{}).
-        Where("tenant_id = ?", tenantID)
-
-    total, err := pagination.PaginateWithPreload(
-        query.Order("created_at desc"),
-        pageReq,
-        &items,
-        "Category", // 预加载的关联名
-    )
-    return items, total, err
-}
-```
-
----
-
-## 6. 乐观锁
-
-### 6.1 模型添加版本字段
-
-```go
-type Entity struct {
-    models.BaseModel
-    Name    string
-    Version int `gorm:"default:1" json:"version"`
-}
-```
-
-### 6.2 更新时检查版本
-
-```go
-func (r *Repository) UpdateWithVersion(ctx context.Context, entity *models.Entity) error {
-    result := r.db.WithContext(ctx).
-        Model(&models.Entity{}).
-        Where("id = ? AND version = ?", entity.ID, entity.Version).
-        Updates(map[string]interface{}{
-            "name":    entity.Name,
-            "version": entity.Version + 1,
-        })
-
-    if result.RowsAffected == 0 {
-        return ErrConcurrentModification
-    }
-    return result.Error
-}
-```
-
----
-
-## 7. 审计日志
-
-### 7.1 自动记录操作
-
-```go
-import "github.com/robsuncn/keystone/infra/audit"
-
-func (h *Handler) Update(c *gin.Context) {
-    // ... 业务逻辑 ...
-
-    // 记录审计日志
-    audit.Log(c, audit.Entry{
-        Action:     audit.ActionUpdate,
-        Module:     "module_name",
-        Resource:   "entity",
-        ResourceID: fmt.Sprintf("%d", id),
-        Details: map[string]interface{}{
-            "old": oldEntity,
-            "new": newEntity,
-        },
-    })
-
-    response.Success(c, entity)
-}
-```
-
----
-
-## 8. 导入导出 Job
-
-### 8.1 注册导入 Job
-
-```go
-func (m *Module) RegisterJobs(reg *jobs.Registry) error {
-    return reg.Register("import_entities", &ImportEntitiesJob{
-        repo: m.repo,
-    })
-}
-
-type ImportEntitiesJob struct {
-    repo *repository.Repository
-}
-
-func (j *ImportEntitiesJob) Execute(ctx context.Context, params jobs.Params) error {
-    fileID := params.GetString("file_id")
-    tenantID := params.GetUint("tenant_id")
-
-    // 读取文件、解析、批量插入
-    // 更新 job 进度
-    params.UpdateProgress(50)
-
-    // ... 处理逻辑 ...
-
-    params.UpdateProgress(100)
-    return nil
-}
-```
-
-### 8.2 创建导入 Job
-
-```go
-func (h *Handler) StartImport(c *gin.Context) {
-    tenantID := resolveTenantID(c)
-
-    var input struct {
-        FileID string `json:"file_id" binding:"required"`
-    }
-    if err := c.ShouldBindJSON(&input); err != nil {
-        response.BadRequestI18n(c, modulei18n.MsgInvalidPayload)
-        return
-    }
-
-    job, err := h.jobs.Create(c.Request.Context(), jobs.CreateInput{
-        Type:     "import_entities",
-        TenantID: tenantID,
-        Params: map[string]interface{}{
-            "file_id":   input.FileID,
-            "tenant_id": tenantID,
-        },
-    })
-    if err != nil {
-        response.InternalErrorI18n(c, modulei18n.MsgJobCreateFailed)
-        return
-    }
-
-    response.Success(c, job)
-}
-```
-
----
-
-## 9. 审批集成
-
-### 9.1 业务提交时创建审批实例
-
-```go
-func (s *Service) Submit(ctx context.Context, tenantID, id uint) error {
-    entity, err := s.repo.FindByID(tenantID, id)
-    if err != nil {
-        return err
-    }
-
-    if entity.Status != StatusDraft {
-        return ErrInvalidStatus
-    }
-
-    // 创建审批实例
-    instance, err := s.approval.CreateInstance(ctx, approval.CreateInstanceInput{
-        TenantID:     tenantID,
-        BusinessType: "entity_approval",
-        BusinessID:   id,
-        Context: map[string]interface{}{
-            "name":   entity.Name,
-            "amount": entity.Amount,
-        },
-    })
-    if err != nil {
-        return err
-    }
-
-    // 更新业务状态
-    entity.Status = StatusPending
-    entity.ApprovalInstanceID = &instance.ID
-    return s.repo.Update(ctx, entity)
-}
-```
-
-### 9.2 注册审批回调
-
-```go
-func (m *Module) RegisterApprovalCallback(registry *approval.CallbackRegistry) {
-    callback := &EntityApprovalCallback{repo: m.repo}
-
-    // 使用带重试的回调
-    retryable := approval.NewRetryableCallback(callback, approval.DefaultRetryConfig())
-    registry.Register("entity_approval", retryable)
-}
-
-type EntityApprovalCallback struct {
-    repo *repository.Repository
-}
-
-func (c *EntityApprovalCallback) OnApproved(ctx context.Context, tenantID, businessID, approverID uint) error {
-    entity, err := c.repo.FindByID(tenantID, businessID)
-    if err != nil {
-        return err
-    }
-
-    entity.Status = StatusApproved
-    return c.repo.Update(ctx, entity)
-}
-
-func (c *EntityApprovalCallback) OnRejected(ctx context.Context, tenantID, businessID, approverID uint, reason string) error {
-    entity, err := c.repo.FindByID(tenantID, businessID)
-    if err != nil {
-        return err
-    }
-
-    entity.Status = StatusRejected
-    entity.RejectReason = reason
-    return c.repo.Update(ctx, entity)
-}
-```
-
----
-
-## 10. 错误处理最佳实践
-
-### 10.1 使用 I18n 错误
-
-```go
-import (
-    "github.com/robsuncn/keystone/infra/i18n"
-    modulei18n "your-app/modules/xxx/i18n"
-)
-
-// 定义错误
-var (
-    ErrEntityNotFound = &i18n.I18nError{Key: modulei18n.MsgEntityNotFound}
-    ErrNameRequired   = &i18n.I18nError{Key: modulei18n.MsgNameRequired}
-    ErrAmountInvalid  = &i18n.I18nError{
-        Key:    modulei18n.MsgAmountInvalid,
-        Params: map[string]interface{}{"min": 0, "max": 1000000},
-    }
-)
-```
-
-### 10.2 Handler 错误处理
-
-```go
-func (h *Handler) Create(c *gin.Context) {
-    // ...
-
-    entity, err := h.svc.Create(ctx, tenantID, input)
-    if err != nil {
-        // 检查是否为 I18n 错误
-        var i18nErr *i18n.I18nError
-        if errors.As(err, &i18nErr) {
-            // 根据错误类型返回不同 HTTP 状态码
-            switch i18nErr.Key {
-            case modulei18n.MsgEntityNotFound:
-                response.NotFoundI18n(c, i18nErr.Key)
-            case modulei18n.MsgNameRequired, modulei18n.MsgAmountInvalid:
-                response.BadRequestI18n(c, i18nErr.Key)
-            default:
-                response.BadRequestI18n(c, i18nErr.Key)
-            }
-            return
-        }
-
-        // 未知错误
-        response.InternalErrorI18n(c, modulei18n.MsgCreateFailed)
-        return
-    }
-
-    response.CreatedI18n(c, modulei18n.MsgCreated, entity)
-}
-```
-
----
-
-## 快速参考
-
-| 模式 | 使用场景 | 关键 API |
-|------|---------|----------|
-| 分页 | 列表接口 | `pagination.ParseRequest()`, `pagination.Paginate()` |
-| 事务 | 多表操作 | `db.Transaction(func(tx *gorm.DB) error { ... })` |
-| 批量 | 导入/批量操作 | `db.CreateInBatches()`, `WHERE id IN ?` |
-| 软删除 | 数据保留 | `db.Unscoped()`, `Update("deleted_at", nil)` |
-| 预加载 | 关联查询 | `db.Preload("Relation")` |
-| 乐观锁 | 并发控制 | `WHERE version = ?`, `version + 1` |
-| 审批 | 业务流程 | `approval.CreateInstance()`, `CallbackRegistry` |