ddd-teaching-skill

Files (1)

• SKILL.md

SKILL.md (first lines)

# DDD Teaching — Aprendizaje Guiado con Goca

## Filosofía

DDD + Clean Architecture resuelven el problema de **código que muere lentamente**: lógica de negocio mezclada con frameworks, tests imposibles, cambios que cascada. La solución es la **Dependency Rule** — las dependencias apuntan hacia adentro.

Goca materializa esta arquitectura generando código en 4 capas:

```
Handler (adapter)  →  UseCase (app logic)  →  Repository (persistence)  →  Domain (pure)
     ↓                       ↓                        ↓                        ↓
   HTTP/gRPC           business logic              SQL/Redis               entities
```

Cada capa solo conoce la que está inmediatamente **dentro** de ella, y siempre a través de interfaces.

## Activación

Invocar este skill automáticamente cuando el usuario:
- Pregunte conceptos de DDD o Clean Architecture
- Quiera aprender a usar Goca paso a paso
- Pida "generar un feature completo" sin entender qué genera
- Muestre código con violaciones arquitectónicas (handler con GORM, usecase con http, etc.)

## Mapa Conceptual ↔ Comandos Goca

| Concepto DDD | Comando Goca | Archivo generado | Propósito |
|---|---|---|---|
| Entidad | `goca entity` | `internal/domain/product.go` | Pureza del dominio, invariantes |
| Value Object | `goca entity --validation` | `domain/product.go` — Validate() | Validación encapsulada |
| Repository interface | `goca repository --interface-only` | `repository/interfaces.go` | Contrato de persistencia |
| Repository impl | `goca repository -d postgres` | `repository/postgres_product.go` | GORM encapsulado |
| DTO / Application Service | `goca usecase` | `usecase/dto.go`, `service.go` | Separación capas |
| UseCase interface | `goca usecase` | `usecase/product_usecase.go` | Contrato para handlers |
| Handler / Adapter | `goca handler -t http` | `handler/http/product_handler.go` | Delivery |
| DI Container | `goca di` | `di/container.go` | Wiring |

---

## Flujo Guiado — 6 Pasos (con TDD)

Cada paso: **Concepto DDD** → **Comando Goca** → **Código generado** → **Test**

### Paso 1: Init — Scaffold del Proyecto

**Concepto:** Separación en capas limpias. El directorio `internal/` es la frontera — nada fuera de `internal/` puede importar lo de adentro, pero lo de adentro sí puede importar `pkg/`.

**Comando:**
```bash
goca init ecommerce --module github.com/myapp/ecommerce --database postgres
```

**Estructura generada:**
```
internal/
  domain/       ← Puro: sin imports externos, solo lógica de negocio
  usecase/      ← Solo importa domain + repository interfaces
  repository/   ← Implementa interfaces; conoce GORM, no el usecase
  handler/      ← Conoce interfaces de usecase, nunca repository directo
```

**Análisis:** Cada carpeta corresponde exactamente a un círculo de Clean Architecture. La regla de dependencia se aplica a nivel de import: `handler` → `usecase` → `repository` → `domain`. Prohibido saltar capas.

**Test:**
```bash
cd ecommerce && go build ./... && go vet ./...
# Debe pasar sin errores: es el esqueleto vacío pero correcto
```

---

### Paso 2: Entity — Domain Puro

**Concepto:** Una **entidad DDD** tiene identidad (ID) e **invariantes** — reglas que siempre deben cumplirse. Los **Value Objects** son inmutables y se comparan por valor. Ambos viven en `domain/` sin dependencias externas.

**Comando:**
```bash
goca entity Product --fields "name:string,price:float64,category:string" --validation --business-rules
```

**Código generado** (extraído de `cmd/templates.go` y `cmd/template_components.go`):
```go
// internal/domain/product.go
package domain

type Product struct {
    ID       int     `json:"id" gorm:"primaryKey"`
    Name     string  `json:"name" gorm:"type:varchar(255);not null"`
    Price    float64 `json:"price" gorm:"type:decimal(10,2);not null"`
    Category string  `json:"category" gorm:"type:varchar(100)"`
}

func (p *Product) Validate() error {
    if p.Name == "" {
        return errors.New("product name is required")
    }
    if p.Price <= 0 {
        return errors.New("product price must be positive")
    }
    return nil
}

func (p *Product) IsExpensive() bool {
    return p.Price > 1000
}
```

```go
// internal/domain/errors.go
package domain

import "errors"

var (
    ErrInvalidProductName  = errors.New("product name is required")
    ErrInvalidProductPrice = errors.New("product price must be positive")
)
```

From sazardev/goca, MIT.

More from sazardev/goca