📚 Pré-requisitos Teóricos: este projeto consolida a Parte 01 — Spring Boot API e integra os clientes desenvolvidos nas Partes 02, 03 e 04.

🏛️ Projeto Lista de Tarefas 05 — Arquitetura, Automação e Docker com PostgreSQL

Seja muito bem-vindo à Parte 05 do ecossistema Lista de Tarefas!

Enquanto as partes anteriores focaram na construção individual dos serviços e frontends heterogêneos (Web, Desktop e Mobile), a Parte 05 assume o papel estratégico de Engenharia de Software, DevOps e Arquitetura de Sistemas.

Aqui você aprenderá a elevar a nossa Fonte Única da Verdade (SSOT) ao patamar de ambiente corporativo de produção:

  1. Substituir o banco volátil em memória (H2) pelo PostgreSQL 16, o banco de dados relacional open source líder de mercado.
  2. Empacotar a API Spring Boot em containers Docker utilizando o padrão profissional de Multi-stage Build (gerando imagens enxutas e seguras com JRE 21).
  3. Orquestrar serviços interdependentes com Docker Compose, configurando volumes persistentes, redes isoladas e Healthchecks para evitar condições de corrida (race conditions).
  4. Automatizar a governança do ecossistema através de scripts em PowerShell e Bash.
  5. Mapear a visão de futuro do ecossistema, estabelecendo as pontes entre tecnologias Web e seus correspondentes para Mobile Híbrido / Cross-platform.

🗺️ 1. Matriz Estratégica: Da Web ao Mobile Híbrido

Uma das maiores discussões da engenharia de software contemporânea é a escolha do ecossistema para construção de aplicações para dispositivos móveis: Nativo puro vs. Híbrido / Cross-platform baseado em tecnologias Web.

No nosso portal, organizamos essa esteira pedagógica de forma progressiva e comparativa:

Matriz Estratégica: Web SPA para Mobile Híbrido

O Roadmap da Trilha Web ➔ Mobile Cross-Platform:

E as Evoluções de Linguagens Nativas:

Todas essas frentes convergem para a mesma API Spring Boot e PostgreSQL padronizada nesta Parte 05!

🐳 2. Ecossistema Conteinerizado: Docker Compose + PostgreSQL

Para que múltiplos frontends operem de forma confiável sem que os dados se percam a cada reinicialização da máquina de desenvolvimento, a API e o banco de dados passam a residir em containers Docker gerenciados pelo Docker Compose:

Ecossistema Docker Compose e PostgreSQL

Pilares Arquiteturais da Conteinerização:

  1. Rede Isolada (tarefas_network):
    Os containers da API e do banco comunicam-se em uma rede bridge privada. A API acessa o PostgreSQL pelo hostname do serviço (db:5432).
  2. Exposição Controlada de Portas:
    Apenas a porta 8080 (API) e a porta 5432 (PostgreSQL) são mapeadas para o Host do desenvolvedor.
  3. Persistência Confiável com Volume Nomeado (tarefas_postgres_data):
    Os dados do PostgreSQL são salvos em um volume persistente gerenciado pelo Docker Engine. Mesmo que os containers sejam interrompidos (docker compose down), nenhuma tarefa é perdida.
  4. Healthcheck e Prevenção de Race Conditions:
    O Spring Boot só inicia após o container do PostgreSQL estar 100% pronto para aceitar conexões SQL, validado via comando pg_isready.

🗄️ Modelagem de Banco de Dados: PostgreSQL 16 (Relacional)

O esquema relacional garante integridade transacional ACID estrita:

erDiagram
    TB_TAREFAS {
        bigserial id PK "Chave Primária com Auto-Sequência"
        varchar_255 descricao "Descrição textual obrigatória (NOT NULL)"
        boolean concluida "Flag booleana de conclusão (DEFAULT false)"
    }

-- DDL gerado e validado no PostgreSQL 16:
CREATE TABLE IF NOT EXISTS tb_tarefas (
    id BIGSERIAL PRIMARY KEY,
    descricao VARCHAR(255) NOT NULL,
    concluida BOOLEAN NOT NULL DEFAULT FALSE
);
CREATE INDEX IF NOT EXISTS idx_tarefas_concluida ON tb_tarefas(concluida);

📑 3. Engenharia de Software & Especificação de Requisitos

3.1. Histórias de Usuário (DevOps & Arquitetura)

3.2. Requisitos Funcionais (RF)

ID Descrição Componente Envolvido
RF-A01 Orquestrar e inicializar em segundo plano os containers do PostgreSQL 16 e da API Spring Boot. infra-docker/docker-compose.yml
RF-A02 Persistir os esquemas relacionais e registros de tarefas no volume Docker nomeado tarefas_postgres_data. PostgreSQL 16
RF-A03 Configurar o Spring Boot para alternar automaticamente para o driver PostgreSQL quando ativado o profile docker. application-docker.properties
RF-A04 Monitorar o estado de prontidão do banco via pg_isready antes de liberar a inicialização do container da API. Docker Healthcheck
RF-A05 Fornecer scripts de automação com ações up, down, restart, logs, status e clean. infra-docker/docker-run.ps1 / docker-run.sh

3.3. Requisitos Não-Funcionais (RNF)

ID Categoria Descrição
RNF-A01 Segurança & Privilégios O container da API deve executar sob usuário sem privilégios de root (USER spring:spring).
RNF-A02 Desempenho de Build O Dockerfile deve adotar Multi-stage Build, separando o ambiente pesado de compilação (Maven+JDK 21) da imagem final (JRE 21 Jammy enxuta).
RNF-A03 Portabilidade 12-Factor As credenciais e URLs de conexão devem ser injetadas exclusivamente via variáveis de ambiente (SPRING_DATASOURCE_*).
RNF-A04 Resiliência & Idempotência Os comandos de subida e descida devem ser idempotentes e tolerantes a reinicializações parciais (restart: unless-stopped).
RNF-A05 Integridade ACID O banco PostgreSQL deve garantir conformidade transacional ACID com dialeto Hibernate oficial.

3.4. Casos de Uso do Sistema

flowchart LR
    Dev(("👨‍💻 Desenvolvedor / DevOps"))

    subgraph "Automação e Orquestração Docker"
        UC01["UC01: Orquestrar Ambiente com Docker Compose"]
        UC02["UC02: Persistir Tarefas no PostgreSQL"]
        UC03["UC03: Validar Resiliência e Reinício de Containers"]
        UC04["UC04: Monitorar Logs e Diagnóstico em Tempo Real"]
        UC05["UC05: Limpar Recursos e Reconstruir Imagens"]
    end

    Dev --> UC01
    Dev --> UC02
    Dev --> UC03
    Dev --> UC04
    Dev --> UC05

UC01: Orquestrar Ambiente com Docker Compose

UC02: Persistir Tarefas no PostgreSQL

UC03: Validar Resiliência e Reinício de Containers

3.5. Matriz de Rastreabilidade (RTM)

Caso de Uso História de Usuário Requisito Funcional Requisito Não-Funcional Artefato Responsável
UC01 US-A02, US-A04 RF-A01, RF-A04 RNF-A02, RNF-A04 infra-docker/docker-compose.yml, Dockerfile
UC02 US-A01 RF-A02, RF-A03 RNF-A03, RNF-A05 application-docker.properties, PostgreSQL
UC03 US-A01, US-A02 RF-A02 RNF-A04, RNF-A05 Volume tarefas_postgres_data
UC04 US-A05 RF-A05 RNF-A04 infra-docker/docker-run.ps1 / docker-run.sh
UC05 US-A03, US-A05 RF-A01, RF-A05 RNF-A01, RNF-A02 Dockerfile, infra-docker/docker-compose.yml

🛠️ 4. Estrutura de Arquivos da Parte 05

fullstack_tarefas_05_arquitetura/
├── assets/
│   ├── arquitetura_docker_postgres_ecosystem.svg  ← Diagrama conceitual do Docker + PostgreSQL
│   └── matriz_equivalencia_web_mobile.svg         ← Matriz estratégica Web -> Mobile Híbrido
├── infra-docker/docker-compose.yml                             ← Orquestração dos serviços api e db (PostgreSQL)
├── infra-docker/docker-run.ps1                                 ← Automação para Windows (PowerShell)
├── docker-run.sh                                  ← Automação para Linux / macOS (Bash)
├── 00_Guia_Principal.md                           ← Visão geral dos módulos de aprofundamento
├── 01_Backend_SpringBoot.md                       ← Refatoração e DTOs na API
├── 02_Frontend_Angular.md                         ← Boas práticas e componentização Web
├── 03_Desktop_JavaFX.md                           ← Comparativo desktop nativo
├── 04_Mobile_Android.md                           ← Padrões arquiteturais mobile
├── 05_Automacao_Bash.md                           ← Scripts avançados para Linux
├── 05_Automacao_PowerShell.md                     ← Scripts avançados para Windows
├── 06_Conclusao_Arquitetura.md                    ← Conclusões de engenharia e lições aprendidas
├── 07_Containerizacao_Docker_Postgres.md          ← Guia aprofundado de Docker e PostgreSQL
└── index.md                                       ← Este Hub Mestre de Arquitetura e Engenharia

🚀 5. Como Executar a Infraestrutura no Laboratório

1. Pré-requisito

Certifique-se de que o Docker Desktop (ou Docker Engine) esteja instalado e ativo no seu computador.

2. Subir os Containers

Navegue até a pasta da Parte 05 e execute o comando:

# No PowerShell (Windows):
cd catalogo_projetos/fullstack_tarefas_05_arquitetura
.\infra-docker/docker-run.ps1 up

Ou no terminal Linux / macOS:

cd catalogo_projetos/fullstack_tarefas_05_arquitetura
chmod +x docker-run.sh
./docker-run.sh up

3. Verificar o Status dos Containers

docker compose ps

Você verá os dois containers operando:

4. Testar a API Conectada ao PostgreSQL

Abra seu navegador ou cliente HTTP (Postman/curl):

curl http://localhost:8080/api/tarefas

Crie uma tarefa de teste:

curl -X POST http://localhost:8080/api/tarefas \
  -H "Content-Type: application/json" \
  -d '{"descricao": "Validar persistência no PostgreSQL", "concluida": false}'

5. Testar a Persistência de Dados

  1. Pare os containers: 
    docker compose down
  2. Suba novamente: 
    docker compose up -d
  3. Consulte as tarefas: 
    curl http://localhost:8080/api/tarefas

    A tarefa criada anteriormente continuará lá! Os dados não são perdidos porque residem no volume tarefas_postgres_data.

🧪 6. Matriz de Homologação & Testes de Aceitação

Checkpoint Ação Realizada Comando / Critério Resultado Esperado Status
CP-01 Subir containers em segundo plano docker compose up -d Containers db e api iniciados com status healthy. PASS ✅
CP-02 Verificar prontidão do PostgreSQL docker compose exec db pg_isready Retorno accepting connections na porta 5432. PASS ✅
CP-03 Testar consumo REST na API Docker curl -i http://localhost:8080/api/tarefas Resposta HTTP 200 OK com payload JSON válido. PASS ✅
CP-04 Cadastrar tarefa persistente via POST curl -X POST -H "Content-Type: application/json" -d '{"descricao":"Testar Docker","concluida":false}' http://localhost:8080/api/tarefas Retorno HTTP 201 Created e registro gravado no PostgreSQL. PASS ✅
CP-05 Testar resiliência com reinicialização docker compose restart && curl http://localhost:8080/api/tarefas Registro criado permanece intacto no volume tarefas_postgres_data. PASS ✅

📚 7. Módulos de Aprofundamento do Guia

Para explorar os detalhes específicos de cada camada refatorada, consulte os capítulos dedicados:

🏆 8. Conclusão & Próximos Passos

Com a conclusão da Parte 05, seu ecossistema full stack atinge a maturidade arquitetural:

👉 Próximo Passo: Parte 06 — Spring Boot + Vue.js ➔ Quasar Framework

Na Parte 06, você iniciará a tríade de equivalências Web ➔ Mobile conectando um cliente reativo em Vue.js 3 evoluindo para Quasar Framework sobre a infraestrutura Docker que você acabou de consolidar!