majiayu000 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
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
| 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