Extra Engenharia de Software Moderna • Trilha Progressiva em 4 Níveis

🧭 Navegação Pedagógica

🎯 Nível 1: Fundamentos

Problema 15.1 — Redação de ADR Canônica: Escolha de Banco de Dados

Contexto: O time precisa escolher entre MongoDB e PostgreSQL para o novo sistema financeiro transacional com conformidade ACID. Redija a ADR-001 registrando a decisão.

Requisitos de Execução:

  1. Definir Título, Data e Status (Aceito).
  2. Seção de Contexto descrevendo os requisitos de conformidade ACID.
  3. Seção de Decisão justificando o PostgreSQL.
  4. Consequências positivas e negativas.

Resultado Esperado

# ADR-001: Adoção do PostgreSQL como Banco Relacional Principal

## Status
Aceito (2026-09-01)

## Contexto
O sistema gerencia movimentações financeiras reguladas pelo BACEN, exigindo garantias estritas de transações ACID e integridade referencial complexa.

## Decisão
Adotaremos o PostgreSQL 16 devido à maturidade de suporte a transações ACID, isolamento serializable e robustez operacional.

## Consequências
- **Positivas:** Prevenção de corrupção contábil e forte suporte da comunidade.
- **Negativas:** Esquema estrito exige migrações estruturadas via Flyway/Liquibase.

📤 Instruções de Entrega (Microsoft Teams)

  1. Salve o arquivo como: ADR_001_SeuNome.md
  2. Envie na tarefa: Atividade Cap 15 - ADRs e arc42
🔑 Gabarito de Código & Solução Comentada 
# ADR-001: Adoção do PostgreSQL como Banco Relacional Principal

## Status
Aceito (2026-09-01)

## Contexto
O sistema gerencia movimentações financeiras reguladas pelo BACEN, exigindo garantias estritas de transações ACID e integridade referencial complexa.

## Decisão
Adotaremos o PostgreSQL 16 devido à maturidade de suporte a transações ACID, isolamento serializable e robustez operacional.

## Consequências
- **Positivas:** Prevenção de corrupção contábil e forte suporte da comunidade.
- **Negativas:** Esquema estrito exige migrações estruturadas via Flyway/Liquibase.

Comentário: A clareza das consequências negativas é vital para que novos desenvolvedores entendam os trade-offs conscientemente assumidos.

🎯 Nível 2: Prática

Problema 15.2 — ADR de Substituição (Depreciação de Decisão Anterior)

Escreva a ADR-005 que substitui formalmente a ADR-002 (onde havia sido decidido usar polling HTTP a cada 5 segundos), migrando a comunicação para WebSockets devido ao aumento do volume de usuários.

🔑 Gabarito de Código & Solução Comentada 
# ADR-005: Migração de Polling HTTP para WebSockets para Cotações em Tempo Real

## Status
Aceito (Substitui a ADR-002)

## Contexto
Com o crescimento para 50.000 usuários simultâneos, o polling a cada 5s gerou sobrecarga severa de 10.000 req/s em idle no cluster de APIs.

## Decisão
Substituir o polling por conexões persistentes WebSocket com servidor Socket.IO/ws em Node.js com cluster Redis Adapter.

## Consequências
- **Positivas:** Redução de 85% no tráfego de rede e latência de cotação reduzida para < 50ms.
- **Negativas:** Necessidade de gerenciar estado de conexões abertas e heartbeat de ping/pong.

🎯 Nível 3: Integração

Problema 15.3 — Estrutura de Documentação Viva com o Template arc42

Mapeie as 12 seções canônicas do padrão internacional arc42 para documentação de arquitetura de software e preencha a Seção 1 (Introdução e Metas) e Seção 6 (Visão de Tempo de Execução).

🔑 Gabarito de Código & Solução Comentada 
### Estrutura arc42:
1. Introdução e Metas (Requisitos de qualidade essenciais)
2. Restrições Arquiteturais (Tecnológicas, organizacionais e regulatórias)
3. Escopo e Contexto (Contexto de negócio e técnico)
4. Estratégia de Solução (Decisões fundamentais)
5. Visão de Blocos (Nível 1, 2 e 3 do C4)
6. Visão de Tempo de Execução (Diagramas de sequência de cenários críticos)
7. Visão de Implantação (Infraestrutura física/nuvem)
8. Conceitos Transversais (Segurança, persistência, log)
9. Decisões Arquiteturais (Links para as ADRs)
10. Requisitos de Qualidade (Cenários de qualidade e árvore de utilidade)
11. Riscos e Débitos Técnicos
12. Glossário

🎯 Nível 4: Desafio

Problema 15.4 — Gerador de Índice Automatizado de ADRs com Python

Desenvolva um script em Python que percorra a pasta docs/adr/, leia o título e o status de cada arquivo .md e gere dinamicamente o arquivo docs/adr/README.md com uma tabela consolidada de governança arquitetural.

🔑 Gabarito de Código & Solução Comentada 
# build_adr_index.py
import os
import re

def gerar_indice_adrs(pasta_adrs):
    adrs = []
    
    for f in sorted(os.listdir(pasta_adrs)):
        if f.endswith(".md") and f != "README.md":
            caminho = os.path.join(pasta_adrs, f)
            with open(caminho, "r", encoding="utf-8") as arq:
                conteudo = arq.read()
                
            titulo_m = re.search(r"^#\s+(.*)$", conteudo, re.MULTILINE)
            status_m = re.search(r"##\s+Status\s*\n([^\n]+)", conteudo, re.IGNORECASE)
            
            titulo = titulo_m.group(1) if titulo_m else f
            status = status_m.group(1).strip() if status_m else "Desconhecido"
            adrs.append((f, titulo, status))
            
    with open(os.path.join(pasta_adrs, "README.md"), "w", encoding="utf-8") as out:
        out.write("# 🏛️ Registro de Decisões Arquiteturais (ADRs)\n\n")
        out.write("| Arquivo | Decisão Arquitetural | Status |\n")
        out.write("| :--- | :--- | :---: |\n")
        for f, tit, st in adrs:
            out.write(f"| [{f}]({f}) | {tit} | `{st}` |\n")
            
    print(f"✅ Índice de ADRs gerado com sucesso para {len(adrs)} decisões!")

if __name__ == "__main__":
    gerar_indice_adrs("docs/adr")