Implementar Domain Entity (Camada de Domínio)
Regras Arquiteturais (NON-NEGOTIABLE)
- •Estruturas de dados puras: entidades são modelos Pydantic
- •SEM lógica de negócio: apenas validação de dados via Pydantic
- •SEM dependências externas: não importar services, repositories, etc.
- •Imutabilidade: preferir
frozen=Truequando possível - •IDs prefixados: seguir padrão
{prefix}_{uuid}(ex:exp_,grp_)
Estrutura de Arquivos
code
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
python
"""
{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
python
"""
{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)
python
"""
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
python
"""
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
python
"""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
| Entidade | Prefixo | Exemplo |
|---|---|---|
| Experiment | exp_ | exp_a1b2c3d4 |
| SynthGroup | grp_ | grp_f5e6d7c8 |
| Task | task_ | task_12345678 |
| Insight | ins_ | ins_abcdef12 |
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=Truepara value objects imutáveis - • Função
generate_{entity}_id()para gerar IDs - • Exports no
__init__.py