📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados em Módulo 08: Bancos de Dados SQL e NoSQL. Recomendado revisar antes de começar.

🏥 Prontuário Médico Objeto-Relacional & Operadores JSONB no PostgreSQL

v1.0 — Tipos Semiestruturados, Índices Invertidos GIN e Consultas por Contenção

Trilha de Engenharia de Dados & Bancos de Dados — Projeto 7 de 10

• v1: Modelagem Relacional 3FN · PostgreSQL 16
• v2: Modelagem NoSQL · MongoDB 7.0
• v3: Estratégias de Cache · Redis 7.2
• v4: DBA Enterprise · Particionamento & RLS · PostgreSQL 16
• v5: Modelagem Visual EER & Stored Procedures · MySQL 8.0
• v6: Séries Temporais IoT · Apache Cassandra 5.0
• ➡️ v7 (este): Prontuário Objeto-Relacional & JSONB · PostgreSQL 16
• v8: Rastreamento de Fraudes em Grafos · Neo4j 5.x
• v9: Data Warehouse & Consultas OLAP · PostgreSQL 16
• v10: Persistência Poliglota Integrada · Postgres + Mongo + Redis

🎓 Nível Profissional Simulado: Arquiteto de Software / Especialista PostgreSQL. Em clínicas médicas e hospitais veterinários, dados de pacientes (cadastros, tutores, financeiro) exigem integridade relacional estrita (ACID), enquanto prescrições, dosagens e exames exigem flexibilidade dinâmica. O tipo JSONB no PostgreSQL une o melhor dos dois mundos.

🎯 Objetivo

Implementar uma arquitetura de banco de dados híbrida Objeto-Relacional no PostgreSQL 16 para prontuários clínicos veterinários, combinando integridade referencial com tabelas relacionais (tutores, animais) e documentos clínicos complexos em colunas JSONB, aceleradas por Índices Invertidos Generalizados (GIN) e operadores de busca profunda (@>, ->>).

🏗️ Diagrama do Modelo Híbrido Relacional + JSONB

erDiagram
    TUTORES ||--o{ ANIMAIS : "possui (1:N)"
    ANIMAIS ||--o{ ATENDIMENTOS_CLINICOS : "recebe (1:N)"

    TUTORES {
        int id PK
        string nome
        string cpf UK
        string telefone
        string endereco
    }

    ANIMAIS {
        int id PK
        int tutor_id FK
        string nome
        string especie
        string raca
        decimal peso_kg "CHECK > 0"
    }

    ATENDIMENTOS_CLINICOS {
        int id PK
        int animal_id FK
        string veterinario
        timestamp data_consulta
        jsonb prontuario_json "Indexado via GIN"
    }

🧑‍💼 Fase 1 — Levantamento de Requisitos

O Briefing do Cliente (Diretoria Clínica Veterinária)

“Nossos veterinários atendem desde cães e gatos até animais silvestres. Cada especialidade (oftalmologia, ortopedia, cardiologia) anota parâmetros completamente diferentes no prontuário. Não queremos um sistema rígido onde cada novo exame exija alterar o banco, mas também não podemos abrir mão de vincular com segurança o animal ao tutor responsável. Precisamos conseguir pesquisar instantaneamente quais animais já tomaram a vacina da Raiva ou receberam certo antibiótico.”

Requisitos Funcionais (RF) e Não-Funcionais (RNF)

📋 Fase 2 — Backlog & User Stories

🌿 Fase 3 — Engenharia em Equipe (Git Flow & Setup)

# Branch da funcionalidade
git checkout -b feature/US01-postgres-jsonb-prontuario

# Subir o PostgreSQL Clínico isolado
docker-compose up -d

# Conectar via psql
docker exec -it db_postgres_clinica psql -U vet_admin -d clinica_vet_db

🛠️ Fase 4 — Implementação Passo a Passo (sql/01_schema_jsonb.sql)

CREATE TABLE atendimentos_clinicos (
    id SERIAL PRIMARY KEY,
    animal_id INT NOT NULL REFERENCES animais(id) ON DELETE RESTRICT,
    veterinario VARCHAR(100) NOT NULL,
    data_consulta TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    prontuario_json JSONB NOT NULL
);

-- Índice GIN para busca profunda por contenção
CREATE INDEX idx_prontuario_gin ON atendimentos_clinicos USING GIN (prontuario_json);

🧭 Decisões Técnicas (ADRs)

• ADR 001: Adoção de arquitetura híbrida Objeto-Relacional com colunas JSONB indexadas por GIN para prontuários clínicos.

🚀 Como Executar no Laboratório

1. Abra o terminal na pasta deste projeto

No seu editor/IDE, abra a pasta deste projeto (File > Open Folder) ou navegue via terminal:

cd db_sql_07_postgres_jsonb_clinica

2. Execute a aplicação ou testes

docker-compose up -d
# Executar a suíte de testes automatizados:
python -m unittest tests/test_postgres_jsonb.py

[!TIP] Dica para execução a partir da raiz do repositório: Se você abriu o repositório completo no VS Code, basta navegar até a pasta antes de executar: cd catalogo_projetos/db_sql_07_postgres_jsonb_clinica

🧪 Testes de Validação & Asserções

-- Buscar atendimentos em que a vacina 'Raiva' foi aplicada via operador @>
SELECT a.nome AS animal, t.veterinario, t.data_consulta, t.prontuario_json->>'diagnostico' AS diagnostico
FROM atendimentos_clinicos t
JOIN animais a ON a.id = t.animal_id
WHERE t.prontuario_json @> '{"vacinas_aplicadas": ["Raiva"]}';

🏛️ Arquitetura Visual & Engenharia de Dados

A arquitetura abaixo demonstra o fluxo de persistência, otimização e isolamento dos componentes na subpasta sql/:

flowchart TD
    subgraph DDL["Modelagem & Schema (DDL)"]
        S1["Tabelas / Coleções"] --> S2["Constraints & Índices"]
    end
    subgraph DML["Regras & Automação (DML / PL)"]
        R1["Triggers / Aggregations"] --> R2["Procedimentos Transacionais"]
    end
    subgraph Perf["Otimização & Armazenamento"]
        P1["Planos EXPLAIN / Partições"] --> P2["Garantia de ACID / TTL"]
    end
    subgraph Homolog["Homologação & Qualidade"]
        Q1["Docker Compose & Scripts"] --> Q2["Checkpoints CP-01..05 PASS"]
    end

    DDL --> DML
    DML --> Perf
    Perf --> Homolog

    style DDL fill:#e3f2fd,stroke:#1976d2,stroke-width:1.5px
    style DML fill:#fffde7,stroke:#fbc02d,stroke-width:1.5px
    style Perf fill:#e8f5e9,stroke:#388e3c,stroke-width:1.5px
    style Homolog fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1.5px

🎯 Engenharia de Requisitos & Modelagem Formal

👤 User Stories (Histórias de Usuário)

⚙️ Requisitos Funcionais (RF)

🛡️ Requisitos Não-Funcionais (RNF)

🔗 Matriz de Rastreabilidade (RTM)

🏁 Checkpoints de Qualidade & Homologação