Implementar Domain Entity (Camada de Domínio)

Regras Arquiteturais (NON-NEGOTIABLE)

1. Estruturas de dados puras: entidades são modelos Pydantic
2. SEM lógica de negócio: apenas validação de dados via Pydantic
3. SEM dependências externas: não importar services, repositories, etc.
4. Imutabilidade: preferir frozen=True quando possível
5. IDs prefixados: seguir padrão {prefix}_{uuid} (ex: exp_, grp_)

Estrutura de Arquivos

src/synth_lab/domain/
└── entities/
    ├── __init__.py
    └── {entity}.py           # Um arquivo por entidade

Convenções de nome:

• Arquivo: {entity}.py (singular, snake_case)
• Classe: {Entity} (PascalCase, singular)
• Campos: snake_case

Padrões de Código

Entidade Básica

"""
{Entity} domain entity for synth-lab.

Core business entity representing a {entity}.
"""

from datetime import datetime

from pydantic import BaseModel, Field


class {Entity}(BaseModel):
    """Core {entity} entity."""

    id: str = Field(
        ...,
        pattern=r"^{prefix}_[a-f0-9]{{8}}$",
        description="{Entity} ID ({prefix}_xxxxxxxx)",
    )
    name: str = Field(..., min_length=1, max_length=100, description="Name")
    description: str | None = Field(default=None, max_length=500)
    created_at: datetime = Field(default_factory=datetime.now)
    updated_at: datetime | None = Field(default=None)

Entidade com Nested Models

"""
{Entity} domain entity with nested structures.
"""

from datetime import datetime

from pydantic import BaseModel, Field


class NestedComponent(BaseModel):
    """Nested component of {Entity}."""

    field_a: str = Field(..., description="Field A")
    field_b: int = Field(default=0, ge=0, description="Field B")


class AnotherComponent(BaseModel):
    """Another nested component."""

    items: list[str] = Field(default_factory=list)
    metadata: dict[str, str] = Field(default_factory=dict)


class {Entity}(BaseModel):
    """Core {entity} entity with nested data."""

    id: str = Field(..., description="{Entity} ID")
    name: str = Field(..., min_length=1, max_length=100)
    created_at: datetime = Field(default_factory=datetime.now)

    # Nested models
    component: NestedComponent | None = Field(default=None)
    another: AnotherComponent | None = Field(default=None)

    # JSON field for flexible data
    data: dict | None = Field(default=None, description="Additional JSON data")

Entidade Imutável (para Value Objects)

"""
Immutable value object.
"""

from pydantic import BaseModel, Field


class Location(BaseModel, frozen=True):
    """Immutable location value object."""

    cidade: str = Field(..., description="City name")
    estado: str = Field(..., pattern=r"^[A-Z]{2}$", description="State (UF)")
    regiao: str | None = Field(default=None, description="Region")

Gerar ID

"""
ID generation helper.
"""

import uuid


def generate_{entity}_id() -> str:
    """Generate a new {entity} ID."""
    return f"{prefix}_{uuid.uuid4().hex[:8]}"


# Uso:
# id = generate_experiment_id()  # -> "exp_a1b2c3d4"

Exports em init.py

"""Domain entities exports."""

from synth_lab.domain.entities.{entity} import (
    {Entity},
    NestedComponent,
    generate_{entity}_id,
)

__all__ = [
    "{Entity}",
    "NestedComponent",
    "generate_{entity}_id",
]

Padrões de ID por Entidade

Checklist de Verificação

Antes de finalizar, verificar:

• Herda de pydantic.BaseModel
• Arquivo em domain/entities/ (singular)
• SEM imports de services, repositories, infrastructure
• SEM lógica de negócio (só validação Pydantic)
• ID com padrão {prefix}_{uuid} e regex de validação
• Campos com type hints e Field descriptions
• Nested models para dados complexos
• frozen=True para value objects imutáveis
• Função generate_{entity}_id() para gerar IDs
• Exports no __init__.py