autoworkflow 3.1.5 → 3.5.0

package/.claude/skills/gorm.md

@@ -0,0 +1,409 @@
+# GORM Skill
+
+## Database Connection
+\`\`\`go
+package database
+
+import (
+    "fmt"
+    "log"
+    "os"
+    "time"
+
+    "gorm.io/driver/postgres"
+    "gorm.io/gorm"
+    "gorm.io/gorm/logger"
+)
+
+func Connect() (*gorm.DB, error) {
+    dsn := os.Getenv("DATABASE_URL")
+
+    // Configure logger
+    gormLogger := logger.New(
+        log.New(os.Stdout, "\\r\\n", log.LstdFlags),
+        logger.Config{
+            SlowThreshold:             200 * time.Millisecond,
+            LogLevel:                  logger.Warn,
+            IgnoreRecordNotFoundError: true,
+            Colorful:                  true,
+        },
+    )
+
+    db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
+        Logger:                 gormLogger,
+        SkipDefaultTransaction: true,  // Disable for performance
+        PrepareStmt:            true,  // Cache prepared statements
+    })
+    if err != nil {
+        return nil, fmt.Errorf("connect to database: %w", err)
+    }
+
+    // Configure connection pool
+    sqlDB, err := db.DB()
+    if err != nil {
+        return nil, err
+    }
+    sqlDB.SetMaxIdleConns(10)
+    sqlDB.SetMaxOpenConns(100)
+    sqlDB.SetConnMaxLifetime(time.Hour)
+
+    return db, nil
+}
+\`\`\`
+
+## Model Definition with Associations
+\`\`\`go
+package model
+
+import (
+    "time"
+
+    "gorm.io/gorm"
+)
+
+// Base model (alternative to gorm.Model with UUID)
+type Base struct {
+    ID        string         \`gorm:"type:uuid;primaryKey;default:gen_random_uuid()" json:"id"\`
+    CreatedAt time.Time      \`json:"created_at"\`
+    UpdatedAt time.Time      \`json:"updated_at"\`
+    DeletedAt gorm.DeletedAt \`gorm:"index" json:"-"\`
+}
+
+type User struct {
+    Base
+    Email     string  \`gorm:"uniqueIndex;size:255;not null" json:"email"\`
+    Name      string  \`gorm:"size:100;not null" json:"name"\`
+    Password  string  \`gorm:"size:255;not null" json:"-"\`
+    IsActive  bool    \`gorm:"default:true" json:"is_active"\`
+
+    // Associations
+    Profile   *Profile \`gorm:"constraint:OnDelete:CASCADE" json:"profile,omitempty"\`
+    Posts     []Post   \`gorm:"constraint:OnDelete:CASCADE" json:"posts,omitempty"\`
+    Roles     []Role   \`gorm:"many2many:user_roles" json:"roles,omitempty"\`
+}
+
+type Profile struct {
+    ID        string \`gorm:"type:uuid;primaryKey;default:gen_random_uuid()"\`
+    UserID    string \`gorm:"type:uuid;uniqueIndex"\`
+    Bio       string \`gorm:"type:text"\`
+    AvatarURL string \`gorm:"size:500"\`
+}
+
+type Post struct {
+    Base
+    Title     string \`gorm:"size:255;not null"\`
+    Content   string \`gorm:"type:text"\`
+    Published bool   \`gorm:"default:false"\`
+    AuthorID  string \`gorm:"type:uuid;index"\`
+
+    Author    *User      \`gorm:"foreignKey:AuthorID" json:"author,omitempty"\`
+    Tags      []Tag      \`gorm:"many2many:post_tags" json:"tags,omitempty"\`
+    Comments  []Comment  \`gorm:"constraint:OnDelete:CASCADE" json:"comments,omitempty"\`
+}
+
+type Tag struct {
+    ID    uint   \`gorm:"primaryKey"\`
+    Name  string \`gorm:"uniqueIndex;size:50"\`
+    Posts []Post \`gorm:"many2many:post_tags"\`
+}
+
+type Comment struct {
+    Base
+    PostID   string \`gorm:"type:uuid;index"\`
+    UserID   string \`gorm:"type:uuid;index"\`
+    Content  string \`gorm:"type:text;not null"\`
+
+    User *User \`gorm:"foreignKey:UserID"\`
+}
+
+type Role struct {
+    ID    uint   \`gorm:"primaryKey"\`
+    Name  string \`gorm:"uniqueIndex;size:50"\`
+    Users []User \`gorm:"many2many:user_roles"\`
+}
+\`\`\`
+
+## Hooks (Callbacks)
+\`\`\`go
+import (
+    "golang.org/x/crypto/bcrypt"
+    "gorm.io/gorm"
+)
+
+// BeforeCreate hook - hash password
+func (u *User) BeforeCreate(tx *gorm.DB) error {
+    if u.Password != "" {
+        hashed, err := bcrypt.GenerateFromPassword([]byte(u.Password), bcrypt.DefaultCost)
+        if err != nil {
+            return err
+        }
+        u.Password = string(hashed)
+    }
+    return nil
+}
+
+// AfterCreate hook - send welcome email
+func (u *User) AfterCreate(tx *gorm.DB) error {
+    // Queue welcome email (don't block)
+    go sendWelcomeEmail(u.Email)
+    return nil
+}
+
+// BeforeUpdate hook - validate changes
+func (u *User) BeforeUpdate(tx *gorm.DB) error {
+    // Hash password if changed
+    if tx.Statement.Changed("Password") {
+        hashed, err := bcrypt.GenerateFromPassword([]byte(u.Password), bcrypt.DefaultCost)
+        if err != nil {
+            return err
+        }
+        tx.Statement.SetColumn("Password", string(hashed))
+    }
+    return nil
+}
+
+// BeforeDelete hook - cleanup related data
+func (u *User) BeforeDelete(tx *gorm.DB) error {
+    // Archive user data before soft delete
+    return tx.Model(&Post{}).Where("author_id = ?", u.ID).Update("author_id", nil).Error
+}
+\`\`\`
+
+## CRUD Operations
+\`\`\`go
+package repository
+
+import (
+    "context"
+    "errors"
+
+    "gorm.io/gorm"
+)
+
+var ErrNotFound = errors.New("record not found")
+
+type UserRepository struct {
+    db *gorm.DB
+}
+
+func NewUserRepository(db *gorm.DB) *UserRepository {
+    return &UserRepository{db: db}
+}
+
+// Create
+func (r *UserRepository) Create(ctx context.Context, user *model.User) error {
+    return r.db.WithContext(ctx).Create(user).Error
+}
+
+// Find by ID with eager loading
+func (r *UserRepository) GetByID(ctx context.Context, id string) (*model.User, error) {
+    var user model.User
+    err := r.db.WithContext(ctx).
+        Preload("Profile").
+        Preload("Roles").
+        First(&user, "id = ?", id).Error
+
+    if errors.Is(err, gorm.ErrRecordNotFound) {
+        return nil, ErrNotFound
+    }
+    return &user, err
+}
+
+// Find by email
+func (r *UserRepository) GetByEmail(ctx context.Context, email string) (*model.User, error) {
+    var user model.User
+    err := r.db.WithContext(ctx).Where("email = ?", email).First(&user).Error
+    if errors.Is(err, gorm.ErrRecordNotFound) {
+        return nil, ErrNotFound
+    }
+    return &user, err
+}
+
+// Update specific fields
+func (r *UserRepository) Update(ctx context.Context, user *model.User) error {
+    return r.db.WithContext(ctx).
+        Model(user).
+        Select("Name", "Email", "IsActive").  // Only update these fields
+        Updates(user).Error
+}
+
+// Delete (soft delete with gorm.DeletedAt)
+func (r *UserRepository) Delete(ctx context.Context, id string) error {
+    result := r.db.WithContext(ctx).Delete(&model.User{}, "id = ?", id)
+    if result.RowsAffected == 0 {
+        return ErrNotFound
+    }
+    return result.Error
+}
+
+// Hard delete (permanent)
+func (r *UserRepository) HardDelete(ctx context.Context, id string) error {
+    return r.db.WithContext(ctx).Unscoped().Delete(&model.User{}, "id = ?", id).Error
+}
+\`\`\`
+
+## Transactions
+\`\`\`go
+// Manual transaction
+func (r *UserRepository) CreateWithProfile(ctx context.Context, user *model.User, profile *model.Profile) error {
+    return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+        if err := tx.Create(user).Error; err != nil {
+            return err  // Rollback
+        }
+
+        profile.UserID = user.ID
+        if err := tx.Create(profile).Error; err != nil {
+            return err  // Rollback
+        }
+
+        return nil  // Commit
+    })
+}
+
+// Nested transaction with savepoints
+func (r *UserRepository) ComplexOperation(ctx context.Context) error {
+    return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+        // First operation
+        if err := tx.Create(&user1).Error; err != nil {
+            return err
+        }
+
+        // Nested transaction (savepoint)
+        err := tx.Transaction(func(tx2 *gorm.DB) error {
+            if err := tx2.Create(&user2).Error; err != nil {
+                return err  // Rollback to savepoint
+            }
+            return nil
+        })
+        if err != nil {
+            // Savepoint rolled back, but outer transaction continues
+            log.Printf("nested transaction failed: %v", err)
+        }
+
+        return nil  // Commit outer transaction
+    })
+}
+\`\`\`
+
+## Scopes (Reusable Query Logic)
+\`\`\`go
+// Scope for active users only
+func ActiveUsers(db *gorm.DB) *gorm.DB {
+    return db.Where("is_active = ?", true)
+}
+
+// Scope for pagination
+func Paginate(page, perPage int) func(db *gorm.DB) *gorm.DB {
+    return func(db *gorm.DB) *gorm.DB {
+        if page <= 0 {
+            page = 1
+        }
+        if perPage <= 0 || perPage > 100 {
+            perPage = 20
+        }
+        offset := (page - 1) * perPage
+        return db.Offset(offset).Limit(perPage)
+    }
+}
+
+// Scope for date range
+func CreatedBetween(start, end time.Time) func(db *gorm.DB) *gorm.DB {
+    return func(db *gorm.DB) *gorm.DB {
+        return db.Where("created_at BETWEEN ? AND ?", start, end)
+    }
+}
+
+// Using scopes
+func (r *UserRepository) ListActive(ctx context.Context, page, perPage int) ([]model.User, int64, error) {
+    var users []model.User
+    var total int64
+
+    db := r.db.WithContext(ctx).Model(&model.User{}).Scopes(ActiveUsers)
+
+    // Get total count
+    if err := db.Count(&total).Error; err != nil {
+        return nil, 0, err
+    }
+
+    // Get paginated results
+    err := db.Scopes(Paginate(page, perPage)).
+        Order("created_at DESC").
+        Find(&users).Error
+
+    return users, total, err
+}
+\`\`\`
+
+## Complex Queries
+\`\`\`go
+// Join with subquery
+func (r *PostRepository) GetPopularPosts(ctx context.Context, minComments int) ([]model.Post, error) {
+    var posts []model.Post
+
+    subquery := r.db.Model(&model.Comment{}).
+        Select("post_id, COUNT(*) as comment_count").
+        Group("post_id").
+        Having("COUNT(*) >= ?", minComments)
+
+    err := r.db.WithContext(ctx).
+        Joins("JOIN (?) AS pc ON posts.id = pc.post_id", subquery).
+        Preload("Author").
+        Preload("Tags").
+        Order("pc.comment_count DESC").
+        Find(&posts).Error
+
+    return posts, err
+}
+
+// Raw SQL when needed
+func (r *UserRepository) GetUserStats(ctx context.Context, userID string) (*UserStats, error) {
+    var stats UserStats
+    err := r.db.WithContext(ctx).Raw(\`
+        SELECT
+            u.id,
+            u.name,
+            COUNT(DISTINCT p.id) as post_count,
+            COUNT(DISTINCT c.id) as comment_count
+        FROM users u
+        LEFT JOIN posts p ON p.author_id = u.id
+        LEFT JOIN comments c ON c.user_id = u.id
+        WHERE u.id = ?
+        GROUP BY u.id, u.name
+    \`, userID).Scan(&stats).Error
+
+    return &stats, err
+}
+\`\`\`
+
+## Migrations
+\`\`\`go
+func AutoMigrate(db *gorm.DB) error {
+    return db.AutoMigrate(
+        &model.User{},
+        &model.Profile{},
+        &model.Post{},
+        &model.Tag{},
+        &model.Comment{},
+        &model.Role{},
+    )
+}
+
+// For production, use a migration tool like golang-migrate
+\`\`\`
+
+## ✅ DO
+- Use \`WithContext(ctx)\` for all database operations
+- Use \`Preload\` for eager loading associations
+- Use scopes for reusable query logic
+- Use transactions for multi-step operations
+- Use \`Select\` to limit fields updated
+- Handle \`gorm.ErrRecordNotFound\` explicitly
+- Use prepared statements (\`PrepareStmt: true\`)
+
+## ❌ DON'T
+- Don't use \`Save()\` for partial updates (updates all fields)
+- Don't ignore hook errors
+- Don't use \`Find\` for single records (use \`First\` or \`Take\`)
+- Don't forget \`Unscoped()\` when querying soft-deleted records
+- Don't use \`AutoMigrate\` in production without review
+- Don't use raw SQL without parameterized queries