Processo de Modelagem de Dados¶

Documento de Referência de Processo¶

Versão: 2.0 Escopo: Define o processo de Modelagem de Dados a ser executado dentro da Fase de Design, após a conclusão dos processos de Engenharia de Requisitos e Arquitetura de Software.

1. Objetivo¶

Este documento define como estruturar, documentar e manter o Modelo de Dados de um projeto, com nomenclatura e regras de rastreabilidade consistentes com os processos de Requisitos e Arquitetura já definidos, permitindo replicar o processo em qualquer novo projeto sem overhead desnecessário para um dev solo.

2. Processo (passo a passo)¶

2.1 Passo 1 — Levantar entidades a partir dos Requisitos e Casos de Uso¶

Cada substantivo relevante mencionado em RF-000, UC-000 ou US-000 é candidato a entidade.

Exemplo:
RF-016 "Sistema deve permitir consulta de prontuário por CID-10"
   → entidades candidatas: Prontuário, Paciente, EntradaProntuário

2.2 Passo 2 — Definir atributos e tipos¶

Para cada entidade, listar campos, tipos de dado e restrições (obrigatório, único, chave estrangeira).

2.3 Passo 3 — Definir relacionamentos e cardinalidade¶

Usar a notação de cardinalidade padrão (ver seção 4) para deixar claro 1:1, 1:N ou N:N entre entidades.

2.4 Passo 4 — Registrar decisões não óbvias como ADR¶

Escolhas de modelagem que fogem do óbvio (ex: desnormalização proposital, uso de JSON em vez de tabela relacional, soft delete) merecem um ADR-000, seguindo o mesmo processo já definido na Arquitetura.

## ADR-005

- **Decisão:** Usar soft delete (campo `deletado_em`) em vez de exclusão física na tabela Prontuário
- **`<` Backward:** RC-001 (retenção de log por 5 anos, exigência regulatória)
- **Por quê:** Auditoria exige histórico completo, mesmo de registros “excluídos”
- **Trade-off:** Queries precisam sempre filtrar `deletado_em IS NULL`

2.5 Passo 5 — Disponibilizar o Modelo para a Construction¶

O Modelo de Dados, uma vez definido, fica disponível como referência direta para a Fase de Construction. Não existe uma etapa formal de “gerar” um artefato de acompanhamento a partir dele — a própria migration é escrita com base no diagrama já documentado aqui, sem necessidade de um elo formal de rastreabilidade forward.

3. Nomenclatura¶

Elemento	Formato do ID	Exemplo
Entidade	Nome em PascalCase, sem prefixo numérico	`Paciente`, `Consulta`
Decisão de modelagem (quando não óbvia)	`ADR-000` (reaproveita a numeração de Arquitetura)	ADR-005

Não é necessário um prefixo próprio para entidades — o nome da entidade já é seu identificador único dentro do Modelo de Dados, assim como uma tabela é identificada pelo próprio nome num banco relacional.

4. Notação (Mermaid `erDiagram`)¶

4.1 Cardinalidade¶

Símbolo Mermaid	Significado
`\\|--\\|`	Um-para-um (1:1)
`\\|--o{`	Um-para-muitos (1:N)
`}o--o{`	Muitos-para-muitos (N:N)
`\\|--o\\|`	Um-para-zero-ou-um (1:0..1)

4.2 Template padrão de entidade¶

ENTIDADE {
    tipo campo PK "comentário opcional"
    tipo campo FK
    tipo campo UK "unique"
    tipo campo
}

6. Regra de Rastreabilidade Backward¶

Mesma convenção dos processos de ER e Arquitetura, mas apenas no sentido Backward — este documento não mantém um campo Forward formal:

Campo	Símbolo	Pergunta	Aponta para
Backward	`<`	De onde essa entidade/decisão veio?	RF/RNF, ADR

6.2 Cadeia de rastreabilidade¶

RF-000 / RNF-000 (Requisito)
        ↓ backward
    Entidade no Modelo de Dados
        ↓ backward (quando decisão não óbvia)
    ADR-000

8. Regra de decisão: quando registrar um ADR de modelagem¶

Situação	Precisa de ADR?
Entidade simples, mapeamento direto de um substantivo do requisito	Não
Escolha de tipo de dado óbvia (ex: `email` como string)	Não
Desnormalização proposital	Sim
Soft delete vs. exclusão física	Sim
Uso de campo JSON/JSONB em vez de tabelas relacionadas	Sim
Particionamento, sharding, ou estratégia de índice não trivial	Sim

Mesma lógica de filtro já usada para ASR na Arquitetura: só formaliza a decisão quando ela não é óbvia.

9. Manutenção do documento ao longo do projeto¶

O Modelo de Dados não é escrito uma vez e congelado — ele cresce incrementalmente:

Regra prática:

Nova entidade/feature → adicionar ao erDiagram existente, não criar novo arquivo
Mudança de schema em produção → atualizar o diagrama no mesmo commit da migration
Campo removido/renomeado → atualizar diagrama junto com a migration correspondente, nunca deixar o Mermaid dessincronizado do schema real

10. Estrutura de pastas¶

Design/
 01-Modelo-de-Dados.md

Assim como nos documentos de ER e Arquitetura, um único arquivo concentra todas as entidades — não se cria um arquivo por entidade. Decisões de modelagem não óbvias vivem em 02-Decisoes/ADR-000.md (pasta compartilhada com a Arquitetura), referenciadas a partir daqui.

11. Fluxograma Resumido do Processo¶

1. Levantar entidades a partir de RF/UC/US
        ↓
2. Definir atributos, tipos e restrições
        ↓
3. Definir relacionamentos e cardinalidade (Mermaid erDiagram)
        ↓
4. Registrar decisões não óbvias como ADR-000
        ↓
5. Modelo disponível → consumido diretamente pela Fase de Construction

12. Resumo Executivo¶

Levantar entidades a partir dos RF/UC/US já documentados na ER
Modelar em um único erDiagram Mermaid, mantido incrementalmente
Registrar decisões de modelagem não óbvias como ADR-000 (soft delete, desnormalização, JSON vs. relacional)
Rastrear apenas Backward: toda entidade declara sua origem (RF/ADR) — não há campo Forward formal apontando para Tasks ou outro artefato de acompanhamento
O diagrama nunca fica dessincronizado do schema real — toda mudança de schema atualiza o Mermaid no mesmo commit