Entities define o modelo de domínio do projeto — as entidades, seus atributos, tipos lógicos, estados, ciclo de vida, relacionamentos e regras de negócio. É o documento que garante que arquitetura, contrato de API e implementação falem sobre os mesmos conceitos com os mesmos nomes.
Fase: 4 — Design de Sistema
Pré-requisito: Docs/user-stories.md · Docs/pages.md · Docs/flow.md aprovados
Template: Templates/Full/entities.md ou Templates/Quick/entities.md
Artefato oficial: Docs/entities.md
Próximos artefatos: Docs/architecture.md · Docs/contract.yaml
Quando criar ou revisar
- Projeto entra na fase de Design de Sistema
- Nova entidade de domínio identificada em user story, page ou flow
- Contrato de API precisa ser definido ou revisado
- Conflito de nomenclatura entre documentos
- Mudança de regra de negócio que afeta o ciclo de vida
Full vs Quick
| Situação | Template |
|---|---|
| Domínio novo com múltiplas entidades, estados e relações N:N | Templates/Full/entities.md |
| Feature com 1-2 entidades simples em domínio já conhecido | Templates/Quick/entities.md |
| Ambiguidade de regra ou relação surgiu | Migrar para Full na mesma task |
Tipos de entidade reconhecidos
central — conceito principal do domínio (ex.: Pedido, Usuário, Chamado)
apoio — suporta entidades centrais (ex.: Endereço, Configuração)
associação — representa relação N:N (ex.: UsuarioPerfil, ProdutoPedido)
configuração — parametrização do sistema (ex.: Preferências, Regra)
evento — registro de acontecimento (ex.: LogAuditoria, Notificação)
histórico — snapshot de estado anterior (ex.: HistóricoPedido)
transacional — operação com estado transitório (ex.: Pagamento, Transação)
catálogo — dado de referência estável (ex.: Categoria, TipoProduto)Estrutura — Entities Full
O template Full tem 13 seções.
1. Identificação
Nome do projeto:
Versão do documento:
Status: [rascunho | revisando | aprovado]
Documentos base: Docs/project.md, Docs/user-stories.md, Docs/pages.md, Docs/flow.md
Data de criação:
Última atualização:2. Objetivo do Documento
Cobre: entidades do domínio, atributos e tipos lógicos, identificadores, regras, validações, relacionamentos, estados, ciclo de vida.
Não cobre: SQL final, migrations, implementação de ORM, contrato detalhado de API, arquitetura de módulos.
3. Regras Gerais de Modelagem
Princípios:
- modelar conceitos do domínio antes da estrutura técnica
- evitar duplicidade conceitual
- nomear entidades de forma clara e estável
- separar entidade de apoio de entidade central
- refletir regras reais de negócio
Convenções obrigatórias:
- nomes de entidades no singular (User, Order, Ticket)
- atributos com nomes sem ambiguidade
- identificadores explícitos
- estados relevantes modelados
- relações descritas de forma legível
Diretriz para Dev e AI:
[como interpretar este documento antes de modelar banco, contrato ou código]4. Visão Geral do Domínio
Resumo do domínio: [o que o sistema gerencia em poucas linhas]
Entidades centrais:
- [entidade 1]
- [entidade 2]
Entidades auxiliares:
- [entidade de apoio]
Observações gerais: [preencher]5. Entidades do Projeto
Estrutura completa de cada entidade (ENT-001, ENT-002, ...):
### ENT-001 — [nome da entidade]
Nome: [singular, ex.: Ticket]
Descrição: [o que representa no domínio]
Tipo: [central | apoio | associação | evento | transacional | ...]
Responsabilidade: [qual papel cumpre no sistema]
Origem funcional: [quais histórias, páginas ou fluxos justificam]
Identificador principal:
- `id`: [UUID | autoincrement | ULID | ...]
Atributos:
- `id`: [tipo lógico] — [descrição]
- `status`: [enum] — [descrição]
- `createdAt`: [datetime] — [descrição]
- `updatedAt`: [datetime] — [descrição]
- `[campo]`: [tipo] — [descrição]
Atributos obrigatórios:
- [atributo 1]
Atributos opcionais:
- [atributo 1]
Regras de validação:
- [regra 1: ex.: name deve ter entre 3 e 100 caracteres]
- [regra 2: ex.: email deve ser único por organização]
Regras de negócio:
- [regra 1: ex.: Ticket só pode ser encerrado por quem o abriu ou pelo gestor]
Estados possíveis:
- [estado 1]
- [estado 2]
Transições de estado:
- [estado A] → [estado B]: [evento/ação que causa a transição]
Relacionamentos:
- pertence a [entidade]
- possui muitos [entidade]
- depende de [entidade] para existir
- referencia [entidade] (fraca)
Observações: [preencher]6. Relações Entre Entidades
Mapa textual de relações:
- [A] 1:N [B] — um A possui muitos B
- [A] N:N [C] — via tabela associativa [D]
- [A] 1:1 [E] — relação exclusiva
Entidades agregadoras ou pivôs:
- [entidade associativa]
Relações críticas do sistema:
- [relação que não pode ser violada]
Restrições de relacionamento:
- [entidade B só existe se A existir]7. Regras Transversais do Domínio
Regras que afetam múltiplas entidades:
- [regra 1]
- [regra 2]
Validações transversais:
- [validação que envolve 2+ entidades]
Restrições por perfil ou contexto:
- [perfil A não pode acessar entidade B]8. Estados e Ciclos de Vida
Para cada entidade com ciclo de vida relevante:
### Ciclo de vida: [Entidade]
Estados:
- rascunho → ativo → encerrado → arquivado
Eventos que causam transição:
- [usuário confirma] → rascunho para ativo
- [prazo expirado] → ativo para encerrado
Estados inválidos ou proibidos:
- [ex.: não pode voltar de encerrado para rascunho sem reabertura explícita]9. Campos Sensíveis, Críticos ou Auditáveis
Campos sensíveis: [senhas, tokens, CPF, dados bancários]
Campos críticos: [status, total, id de autor]
Campos auditáveis: [createdAt, updatedAt, changedBy]
Observações de compliance:[LGPD, PCI-DSS, retenção de dados]10. Dependências Funcionais
Entidades fundamentais para o MVP:
- [entidade 1]
- [entidade 2]
Entidades que dependem de outras para existir:
- [A depende de B]
- [C depende de D]
Entidades futuras ou opcionais:
- [entidade planejada para fase posterior]11. Diretrizes para os Próximos Documentos
Docs/architecture.md — como as entidades impactam módulos, serviços e camadas
Docs/contract.yaml — quais entidades são expostas ou trafegadas na API
Docs/structure.md — como o domínio influencia organização de pastas
Docs/deploy.md — dependências operacionais de persistência ou consistência
Docs/plan.md — entidades fundacionais que determinam ordem de implementação12. Síntese Operacional para Dev e AI
Entidades centrais: [preencher]
Relações mais importantes: [preencher]
Regras que não podem ser quebradas:[preencher]
Estados críticos do domínio: [preencher]
O que ainda está indefinido: [ponto 1]13. Aprovação
Status: [pendente | aprovado | revisando]
Aprovado por:
Data de aprovação:
Observações finais:Exemplo preenchido — entidade completa
### ENT-003 — Atendimento
Nome: Atendimento
Descrição: Registro de execução de um serviço técnico em campo,
vinculado a um chamado e a um técnico.
Tipo: transacional
Responsabilidade: Centraliza a prova de execução do serviço com foto,
assinatura e geolocalização.
Origem funcional: US-007 (registrar atendimento), US-008 (encerrar chamado),
PG-012 (tela de registro), FL-007 (fluxo de encerramento)
Identificador principal:
- `id`: UUID v4
Atributos:
- `id`: UUID — identificador único do atendimento
- `chamadoId`: UUID — chamado ao qual pertence (FK obrigatória)
- `tecnicoId`: UUID — técnico responsável (FK obrigatória)
- `fotoUrl`: string — URL da foto armazenada (obrigatória)
- `assinatura`: base64 — assinatura digital coletada (obrigatória ou justificativa)
- `justificativa`:string — motivo se cliente recusou assinar (opcional)
- `localizacao`: object — lat/lng no momento do registro
- `observacao`: string — nota textual do técnico (opcional)
- `status`: enum — [registrado, validado, rejeitado]
- `criadoEm`: datetime — timestamp de criação
- `atualizadoEm`:datetime — timestamp de última atualização
Atributos obrigatórios:
- chamadoId, tecnicoId, fotoUrl, (assinatura ou justificativa), criadoEm
Atributos opcionais:
- observacao, localizacao
Regras de validação:
- fotoUrl deve ser URL válida de storage configurado
- assinatura e justificativa são mutuamente exclusivos mas um é obrigatório
- localizacao.lat entre -90 e 90, localizacao.lng entre -180 e 180
Regras de negócio:
- Atendimento só pode existir se chamado estiver em status "em andamento"
- Criação de Atendimento move chamado para "aguardando confirmação"
- Apenas o técnico responsável pode criar o Atendimento do chamado
Estados possíveis:
- registrado, validado, rejeitado
Transições de estado:
- registrado → validado: gestor confirma atendimento
- registrado → rejeitado: gestor rejeita com justificativa
- rejeitado → registrado: técnico corrige e reenvia
Relacionamentos:
- pertence a Chamado (1:1 por chamado, em um dado momento)
- pertence a Tecnico (N:1)
- referencia Arquivo (fotoUrl aponta para Arquivo)
Observações:
- Dados de localização são opcionais mas recomendados para auditoriaEstrutura — Entities Quick
Para domínio já conhecido com poucas entidades novas:
## Resumo do domínio
[o que o sistema gerencia]
## Entidades principais
### ENT-001 — [nome]
Descrição: [o que representa]
Atributos principais:
- `id`: [tipo]
- `[campo]`: [tipo]
Regras principais:
- [regra]
Relacionamentos:
- [relacionamento]
Estados:
- [estado 1]
---
## Relações principais
- [A] 1:N [B]
- [A] N:N [C]
## Regras transversais
- [regra]
## Entidades críticas para o MVP
- [entidade]
## Direção para os próximos documentos
Docs/architecture.md: [orientação]
Docs/contract.yaml: [orientação]
## Síntese para Dev e AI
Entidades mais importantes: [preencher]
Relações críticas: [preencher]
Regras que precisam ser respeitadas: [preencher]
O que ainda está indefinido: [ponto]Prompt para gerar com agente
Atue como SystemAgent.
Objetivo: criar Docs/entities.md com base em Docs/user-stories.md
Carregue contexto base:
- GUIDE.md
- Skills/contracts.md
- Templates/Full/entities.md
- Docs/user-stories.md
- Docs/pages.md
- Docs/flow.md
Preencha as 13 seções do template Full.
Seção 4: resuma o domínio e liste entidades centrais vs auxiliares.
Seção 5: crie uma entrada completa por entidade identificada nas histórias.
Seção 6: mapa textual com cardinalidade de todas as relações.
Seção 8: ciclo de vida apenas para entidades com estado mutável.
Seção 9: liste campos sensíveis, críticos e auditáveis.
Seção 11: preencha orientação por artefato seguinte.
Não confunda campo técnico de implementação com entidade de domínio.
Marque [indefinido] onde houver lacuna.Definição de pronto
O entities está pronto quando:
- Todas as entidades centrais identificadas nas user stories têm entrada completa
- Atributos têm tipo lógico e descrição — não apenas nome
- Relacionamentos descritos com cardinalidade explícita
- Ciclo de vida documentado para entidades com estados mutáveis
- Seção 7 lista regras que afetam múltiplas entidades
- Seção 9 identifica campos sensíveis e auditáveis
- Seção 11 tem orientação para cada artefato seguinte
- Aprovação registrada na seção 13
Atenção
Entidade de domínio ≠ tabela de banco. Entities não define SQL — define conceitos do negócio. A modelagem de banco nasce daqui, mas não é este documento. Misturar os dois gera um entities que só funciona para um banco específico e perde o valor conceitual.
Erros comuns
| Erro | Correção |
|---|---|
| Campo técnico tratado como entidade ("RecordSet", "DTO") | Entidade de domínio representa conceito de negócio, não estrutura técnica |
| Atributo sem tipo lógico | Todo atributo tem tipo: string, UUID, enum, datetime, boolean, number |
| Relacionamento sem cardinalidade | Especificar 1:1, 1:N ou N:N com o que está em qual lado |
| Estados sem transições | Ciclo de vida sem eventos que causam transição não é ciclo de vida |
| Campos sensíveis não identificados | LGPD e compliance exigem que esses campos sejam marcados antes do contrato |
| Seção 11 em branco | Architecture e contract.yaml perdem a base conceitual do domínio |
Documentos que nascem de Entities
Docs/entities.md (aprovado)
↓
Docs/architecture.md — módulos e serviços organizados em torno das entidades
Docs/contract.yaml — schemas da API derivados dos atributos das entidades
Docs/structure.md — organização de pastas influenciada pelos agregados do domínio