lv8girl/AGENTS.md

# AGENTS.md - lv8girl Project Guidelines

This document provides guidelines for AI agents working on the lv8girl project - a Go-based forum system.

## Project Overview

**lv8girl** is a Go + Gin + SQLite forum system with user registration, posts, comments, likes, private messages, and admin dashboard.

## Build & Development Commands

### Basic Commands
```bash
# Install dependencies
go mod tidy

# Run the application
go run ./cmd/server

# Build binary
go build -o lv8girl ./cmd/server

# Run tests (if any)
go test ./...

# Run specific test
go test ./internal/services -v

# Test coverage
go test ./... -cover
```

### Database Operations
```bash
# Database is automatically created at: data/lv8girl.db
# Auto-migration runs on application start
```

### Code Quality
```bash
# Format code
go fmt ./...

# Vet code for suspicious constructs
go vet ./...

# Static analysis
go install honnef.co/go/tools/cmd/staticcheck@latest
staticcheck ./...
```

## Code Style Guidelines

### General Principles
- Follow **Go standard conventions** and **effective Go guidelines**
- Use **layered architecture**: Controllers → Services → Repositories → Models
- Keep functions small and focused (single responsibility)
- Prefer composition over inheritance
- Handle errors properly - never ignore them

### Imports Organization
```go
import (
    // Standard library
    "fmt"
    "time"
    "net/http"

    // Third-party packages
    "github.com/gin-gonic/gin"
    "gorm.io/gorm"

    // Local packages (project-specific)
    "lv8girl/internal/models"
    "lv8girl/internal/services"
)
```

### Naming Conventions
- **Packages**: lowercase, single word, descriptive (e.g., `controllers`, `services`)
- **Interfaces**: `-er` suffix (e.g., `Repository`, `Handler`)
- **Variables**: camelCase, descriptive names
- **Constants**: PascalCase or ALL_CAPS for exported constants
- **Methods**: camelCase, verbs for actions (e.g., `GetUserByID`, `CreatePost`)

### Error Handling
```go
// Always check errors
if err != nil {
    return fmt.Errorf("context: %w", err)
}

// Use custom error types for domain errors
type ValidationError struct {
    Field   string
    Message string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("%s: %s", e.Field, e.Message)
}
```

### Types and Structs
```go
// Use JSON tags for API responses
type User struct {
    ID        uint      `json:"id"`
    Username  string    `json:"username"`
    Email     string    `json:"email"`
    CreatedAt time.Time `json:"created_at"`
}

// Use GORM tags for database models
type Discussion struct {
    ID      uint   `gorm:"primaryKey" json:"id"`
    Title   string `gorm:"size:200;not null" json:"title"`
    Content string `gorm:"type:text;not null" json:"content"`
}
```

### Function Signatures
```go
// Return errors as last parameter
func GetUserByID(id uint) (*models.User, error)

// Use context for cancellation and timeouts
func GetUser(ctx context.Context, id uint) (*models.User, error)

// Receiver names should be short (1-2 letters)
func (c *Controller) HandleRequest(ctx *gin.Context)
```

### Project Structure Patterns
```
cmd/server/main.go           # Application entry point
internal/config/             # Configuration management
internal/controllers/        # HTTP request handlers (Gin)
internal/services/          # Business logic layer
internal/repositories/       # Data access layer (GORM)
internal/models/            # Data models
internal/middleware/        # HTTP middleware
internal/routes/            # Route definitions
internal/utils/             # Utility functions
```

### Controller Patterns
```go
// Use dependency injection
type AuthController struct {
    authService *services.AuthService
}

func NewAuthController() *AuthController {
    return &AuthController{
        authService: services.NewAuthService(),
    }
}

// Handle HTTP requests with Gin
func (c *AuthController) Login(ctx *gin.Context) {
    // Parse input
    // Call service
    // Return response
}
```

### Service Layer Patterns
```go
// Services handle business logic
type AuthService struct {
    userRepo *repositories.UserRepository
}

func (s *AuthService) Login(login, password string) LoginResult {
    // Business logic
    // Call repositories
    // Return result
}
```

### Repository Patterns
```go
// Repositories handle database operations
type UserRepository struct {
    db *gorm.DB
}

func (r *UserRepository) FindByID(id uint) (*models.User, error) {
    var user models.User
    result := r.db.First(&user, id)
    return &user, result.Error
}
```

### Testing Guidelines
```go
// When adding tests, follow these patterns:
func TestUserService_CreateUser(t *testing.T) {
    // Arrange
    // Act  
    // Assert
}

// Use table-driven tests
func TestValidateUser(t *testing.T) {
    tests := []struct {
        name     string
        user     models.User
        expected error
    }{
        // test cases
    }
}
```

### Security Considerations
- Never commit secrets (session keys, passwords)
- Use environment variables for sensitive configuration
- Validate all user input
- Use prepared statements (GORM handles this)
- Hash passwords with bcrypt/scrypt

### Performance Guidelines
- Use connection pooling (GORM handles this)
- Implement pagination for lists
- Cache frequently accessed data
- Use indexes on frequently queried columns

### Documentation
- Document exported functions and types
- Use clear, concise comments for complex logic
- Update README.md for new features
- Keep API documentation in sync with code

## Common Tasks

### Adding a New Feature
1. Add model in `internal/models/`
2. Add repository methods in `internal/repositories/`
3. Add service logic in `internal/services/`
4. Add controller in `internal/controllers/`
5. Add routes in `internal/routes/routes.go`
6. Add templates in `templates/` (if needed)

### Database Migrations
- Models are auto-migrated on startup
- For manual migrations, create migration files
- Test migrations before applying to production

### API Endpoints
- Use RESTful conventions where appropriate
- Return appropriate HTTP status codes
- Use JSON for API responses
- Document API changes

## Development Workflow

1. **Before starting**: Run `go mod tidy` to ensure dependencies are current
2. **During development**: Use `go run ./cmd/server` for testing
3. **Before committing**: Run `go fmt ./...` and `go vet ./...`
4. **Testing**: Write tests for new functionality
5. **Documentation**: Update relevant documentation

## Project-Specific Notes

- Default admin credentials: `admin` / `admin123`
- Session secret is hardcoded in config - change for production
- Database path: `data/lv8girl.db`
- Server runs on port `:8989` by default
- Uses Gin web framework with HTML templates
- Uses GORM with SQLite (no CGO required)

## Troubleshooting

- **Database issues**: Check `data/` directory permissions
- **Import errors**: Run `go mod tidy`
- **Build errors**: Ensure Go 1.21+ is installed
- **Runtime errors**: Check logs for detailed error messages

## Resources

- [Go Documentation](https://golang.org/doc/)
- [Gin Framework](https://gin-gonic.com/docs/)
- [GORM Documentation](https://gorm.io/docs/)
- [Effective Go](https://golang.org/doc/effective_go)