📚 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.

🏪 Modelagem Visual EER & Stored Procedures Transacionais no MySQL

v1.0 — Normalização Formal (1FN a 3FN), Bloqueio Pessimista e Controle de Crediário

Trilha de Engenharia de Dados & Bancos de Dados — Projeto 5 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 (este): Modelagem Visual EER & Stored Procedures · MySQL 8.0
• v6: Séries Temporais IoT · Apache Cassandra 5.0
• v7: 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: Desenvolvedor Pleno / Especialista SQL. No comércio varejista de bairro com crediário próprio (caderneta/fiado), a gestão de débitos e amortizações precisa de garantia transacional absoluta com bloqueio de concorrência (SELECT ... FOR UPDATE), evitando amortizações duplicadas ou saldos negativos.

🎯 Objetivo

Modelar um esquema visual EER para controle de vendas a prazo e amortização de fiado no MySQL 8.0, aplicando decomposição formal até a Terceira Forma Normal (3FN) e construindo uma Stored Procedure Transacional (sp_registrar_pagamento_fiado) com controle explícito de START TRANSACTION, COMMIT, ROLLBACK e bloqueio de linha.

🏗️ Diagrama de Entidade-Relacionamento Estendido (EER)

erDiagram
    CLIENTES ||--o{ VENDAS : "compra (1:N)"
    CLIENTES ||--o{ RECIBOS_PAGAMENTO : "amortiza (1:N)"
    VENDAS ||--|{ ITENS_VENDA : "possui (1:N)"
    PRODUTOS ||--o{ ITENS_VENDA : "vendido_em (1:N)"

    CLIENTES {
        int id PK
        string nome
        string cpf UK
        decimal saldo_devedor "CHECK >= 0"
        decimal limite_credito
    }

    PRODUTOS {
        int id PK
        string codigo_barras UK
        string nome
        decimal preco_venda "CHECK > 0"
        int estoque_atual "CHECK >= 0"
    }

    VENDAS {
        int id PK
        int cliente_id FK
        datetime data_venda
        enum forma_pagamento "A_VISTA|CREDIARIO_FIADO|CARTAO"
        decimal valor_total
    }

    RECIBOS_PAGAMENTO {
        int id PK
        int cliente_id FK
        decimal valor_pago "CHECK > 0"
        datetime data_pagamento
    }

🧑‍💼 Fase 1 — Levantamento de Requisitos

O Briefing do Cliente (Dono do Supermercado de Bairro)

“No nosso mercado, muitos clientes compram fiado e pagam aos poucos todo sábado. Tivemos casos em que dois caixas registraram o pagamento ao mesmo tempo e o saldo do cliente ficou negativado, ou o sistema caiu no meio do processo e o dinheiro sumiu do caixa sem dar baixa na conta do cliente. Precisamos de uma rotina blindada que bloqueie a conta durante o pagamento e garanta que o recibo só seja emitido se o débito for abatido com sucesso.”

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-mysql-stored-procedure

# Subir o MySQL isolado via Docker
docker-compose up -d

# Conectar via MySQL Client
docker exec -it db_mysql_varejo mysql -u lojista -plojistapassword varejo_db

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

DELIMITER $$
CREATE PROCEDURE sp_registrar_pagamento_fiado(
    IN p_cliente_id INT,
    IN p_valor_pago DECIMAL(10,2),
    OUT p_status_mensagem VARCHAR(100)
)
BEGIN
    DECLARE v_saldo_devedor DECIMAL(10,2);
    
    DECLARE EXIT HANDLER FOR SQLEXCEPTION
    BEGIN
        ROLLBACK;
        SET p_status_mensagem = 'ERRO: Falha ao processar a transação.';
    END;

    START TRANSACTION;
        SELECT saldo_devedor INTO v_saldo_devedor 
        FROM clientes 
        WHERE id = p_cliente_id FOR UPDATE;

        IF v_saldo_devedor IS NULL THEN
            SET p_status_mensagem = 'ERRO: Cliente inexistente.';
            ROLLBACK;
        ELSEIF p_valor_pago > v_saldo_devedor THEN
            SET p_status_mensagem = 'ERRO: Pagamento maior que o débito.';
            ROLLBACK;
        ELSE
            UPDATE clientes 
            SET saldo_devedor = saldo_devedor - p_valor_pago 
            WHERE id = p_cliente_id;

            INSERT INTO recibos_pagamento (cliente_id, valor_pago, data_pagamento)
            VALUES (p_cliente_id, p_valor_pago, NOW());

            SET p_status_mensagem = 'SUCESSO: Pagamento amortizado.';
            COMMIT;
        END IF;
END$$
DELIMITER ;

🧭 Decisões Técnicas (ADRs)

• ADR 001: Adoção de Stored Procedures com bloqueio pessimista FOR UPDATE para garantir consistência no crediário.

🚀 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_05_mysql_eer_procedures

2. Execute a aplicação ou testes

docker-compose up -d
# Executar a suíte de testes automatizados:
python -m unittest tests/test_mysql_procedures.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_05_mysql_eer_procedures

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

-- 1. Executar a Stored Procedure para amortizar R$ 150.00
CALL sp_registrar_pagamento_fiado(1, 150.00, @msg);
SELECT @msg AS resultado_operacao;

-- 2. Validar que o saldo devedor baixou para R$ 200.00
SELECT id, nome, saldo_devedor FROM clientes WHERE id = 1;
SELECT * FROM recibos_pagamento WHERE cliente_id = 1;

🏛️ 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