---
id: db-domain-modeling
agent: data-engineer
title: Modelar o domínio de dados
inputs: [story, arquitetura do @architect]
outputs: [modelo de domínio (entidades, relações, padrões de acesso), docs/data/domain-model.md]
elicit: true
modes: [interactive]
---

# Modelar o domínio de dados

**Objetivo:** entender o domínio real antes de qualquer DDL — quais são as entidades, como elas se
relacionam, e como vão ser lidas e escritas — produzindo um modelo de domínio que rastreia à story.

**Pré-condições:**
- A story (ou spec) que motiva a modelagem existe e descreve o quê precisa ser persistido. Se não há
  fonte de verdade, **pare** e elicito o escopo — eu não invento entidades (Constituição Art. IV).
- A arquitetura de sistema do @architect está disponível ou foi consultada. Se falta o contexto
  arquitetural (escolha de tecnologia, fronteiras de serviço), eu **peço ao @architect** — não decido
  arquitetura de sistema, isso não é meu.

## Passos

1. **Leia a story e a arquitetura completas.** Extraia cada substantivo de negócio que vira candidato
   a entidade e cada verbo que vira candidato a operação (leitura/escrita).
2. **Liste as entidades candidatas** com seus atributos essenciais. Para cada uma, pergunte: ela tem
   identidade própria e ciclo de vida? Se for só um atributo de outra, não é entidade.
3. **Mapeie as relações** entre entidades: 1:1, 1:N, N:N. Para cada relação, defina cardinalidade,
   obrigatoriedade e quem é o lado dono da foreign key.
4. **Documente os padrões de acesso** (PONTO DE ELICITAÇÃO — exige confirmação do usuário): como cada
   entidade vai ser consultada? Por qual chave? Com qual frequência? Quais joins quentes? Escala
   esperada por tabela? Esse mapa guia schema e índices depois — sem ele, eu modelo no escuro.
5. **Decida normalização pragmática.** Normalize por padrão; só desnormalize quando um padrão de
   acesso documentado justifica, e registre o porquê no modelo.
6. **Registre restrições de integridade e segurança de domínio:** quais regras o banco deve fazer
   cumprir (unicidade, valores válidos, propriedade do dado por usuário/tenant).
7. **Escreva o modelo** em `docs/data/domain-model.md`: entidades, atributos, relações, padrões de
   acesso e restrições — cada item com rastro à story. Esse é o input de `create-schema`.

## Critério de pronto (DoD)

- [ ] Toda entidade rastreia a um requisito da story (sem invenção)
- [ ] Cada relação tem cardinalidade, obrigatoriedade e lado dono da FK definidos
- [ ] Padrões de acesso confirmados pelo usuário no ponto de elicitação
- [ ] Decisões de desnormalização (se houver) justificadas por escrito
- [ ] Restrições de integridade/segurança de domínio listadas
- [ ] `docs/data/domain-model.md` escrito e pronto para alimentar `create-schema`

## Falha / recuperação

- **Story ambígua ou sem o dado necessário** → paro, registro a lacuna e devolvo ao @sm/@po. Não
  invento o requisito que falta.
- **Falta arquitetura/escolha de tecnologia** → escalo ao @architect; não decido arquitetura de
  sistema no lugar dele.
- **Usuário não consegue confirmar os padrões de acesso** → não avanço para o schema; um modelo sem
  padrão de acesso vira índice errado e schema retrabalhado.