🗺️ JORNADA DO DESENVOLVEDOR BACKEND: DOS FUNDAMENTOS AO PROJETO INTEGRADOR

Bem-vindo(a) ao roteiro prático e estruturado de desenvolvimento web do curso de Gestão da Tecnologia da Informação (GTI - FATEC).

Este guia foi desenhado em 7 projetos progressivos e autoguiados, permitindo que você construa aplicações reais passo a passo, evoluindo do primeiro endpoint HTTP até uma arquitetura corporativa completa com banco de dados dual (SQLite no desenvolvimento local e PostgreSQL em produção). 🛡️🚀

🧭 O Mapa de Bordo da Sua Jornada

flowchart TD
    subgraph FASE1 ["🟢 FASE 1: FUNDAMENTOS & HTTP (Em Memória)"]
        P1["🏆 Projeto 1: API Simples (Flask + JSON)"]
    end

    subgraph FASE2 ["🟡 FASE 2: PERSISTÊNCIA BÁSICA & WEB SSR"]
        P2["🏆 Projeto 2: To-Do List (Flask + Jinja2 + SQLite + SQLAlchemy)"]
        P3["🏆 Projeto 3: Biblioteca Acadêmica (Relacionamento 1:N & JOINs)"]
    end

    subgraph FASE3 ["🟠 FASE 3: REGRAS DE NEGÓCIO & SEGURANÇA"]
        P4["🏆 Projeto 4: Vendas & Estoque (Relacionamento N:N & Transações ACID)"]
        P5["🏆 Projeto 5: Sistema com Autenticação (Bcrypt + Sessões Flask)"]
    end

    subgraph FASE4 ["🟣 FASE 4: TRANSIÇÃO DUAL & PRODUÇÃO"]
        P6["🏆 Projeto 6: Migrações com Alembic & PostgreSQL no Docker"]
        P7["🏆 Projeto 7: Projeto Integrador Oficial (10 Temas Setoriais)"]
    end

    FASE1 ==> FASE2 ==> FASE3 ==> FASE4

    style FASE1 fill:#e3f2fd,stroke:#1565c0
    style FASE2 fill:#e8f5e9,stroke:#2e7d32
    style FASE3 fill:#fff8e1,stroke:#f57f17
    style FASE4 fill:#f3e5f5,stroke:#7b1fa2

🏛️ A Filosofia do Banco Dual: SQLite (Dev) ➔ PostgreSQL (Prod)

[!IMPORTANT] A Regra de Ouro da Arquitetura de Dados: O SQLite não é um banco "descartável" ou "de brinquedo". Ele é o banco de dados oficial de desenvolvimento e aprendizado, pois permite executar aplicações completas em qualquer computador através de um único arquivo .db, com zero atrito de configuração e instalação.

Quando sua aplicação for para homologação ou produção, a camada do SQLAlchemy 2.0 permite trocar para o PostgreSQL 17 no Docker apenas alterando a variável DATABASE_URL no arquivo .env, sem reescrever uma única linha de lógica do sistema!

flowchart LR
    APP["🐍 Sua Aplicação Flask"] ==> ORM["🧱 SQLAlchemy 2.0 (Camada Abstrata)"]
    
    ORM -->|DATABASE_URL=sqlite:///dev.db| SQLITE["📁 SQLite Local (.db)<br/>• Setup instantâneo<br/>• Ideal para testes locais"]
    ORM -->|DATABASE_URL=postgresql://...| POSTGRES["🐘 PostgreSQL 17 (Docker)<br/>• Alta concorrência<br/>• Produção corporativa"]

    style APP fill:#e3f2fd,stroke:#1565c0
    style ORM fill:#fff8e1,stroke:#f57f17
    style SQLITE fill:#f1f8e9,stroke:#558b2f
    style POSTGRES fill:#e0f2f1,stroke:#00695c

🔨 PROJETO 1: API Simples em Memória (Flask + JSON)

Objetivo: Compreender o ciclo de Request/Response HTTP, verbos (GET, POST), parâmetros de rota e serialização JSON sem complexidade de banco de dados.
Conceitos: Flask, request.get_json(), jsonify(), Rotas e Métodos HTTP, Status Codes.

sequenceDiagram
    autonumber
    actor Cliente as 👤 Aluno / Navegador
    participant API as 🌐 Flask Router
    participant Schema as 📋 Validação de Entrada
    
    Cliente->>API: GET /api/v1/saudacao?nome=Carlos
    API->>Schema: Valida parâmetro 'nome'
    Schema-->>API: Parâmetro presente e válido
    API-->>Cliente: HTTP 200 OK {"mensagem": "Olá, Carlos!", "status": "online"}

💻 Código do Projeto 1 (`projeto1_api_simples.py`):

# projeto1_api_simples.py
import sys
from flask import Flask, request, jsonify

app = Flask(__name__)

# Banco de dados temporário em memória (Lista Python de dicionários)
banco_memoria = [
    {"id": 1, "titulo": "Estudar Engenharia de Software", "concluida": True},
    {"id": 2, "titulo": "Instalar VS Code e Python 3.11", "concluida": False}
]

@app.get("/tarefas")
def listar_todas():
    return jsonify(banco_memoria), 200

@app.post("/tarefas")
def criar_tarefa():
    dados = request.get_json()
    if not dados or "id" not in dados or "titulo" not in dados:
        return jsonify({"erro": "Campos 'id' e 'titulo' são obrigatórios"}), 400

    for t in banco_memoria:
        if t["id"] == dados["id"]:
            return jsonify({"erro": "ID já existente."}), 400

    nova_tarefa = {
        "id": dados["id"],
        "titulo": dados["titulo"],
        "concluida": bool(dados.get("concluida", False))
    }
    banco_memoria.append(nova_tarefa)
    return jsonify(nova_tarefa), 201

if __name__ == "__main__":
    if "--server" in sys.argv:
        print("🚀 Servidor Flask do Projeto 1 rodando em http://127.0.0.1:5000")
        app.run(port=5000, debug=True)
    else:
        print("--- Teste Automatizado com Flask test_client() ---")
        with app.test_client() as client:
            res_get = client.get("/tarefas")
            print(f"GET /tarefas [Status {res_get.status_code}]: {res_get.get_json()}")
            
            res_post = client.post("/tarefas", json={"id": 3, "titulo": "Aprender Flask"})
            print(f"POST /tarefas [Status {res_post.status_code}]: {res_post.get_json()}")

🔨 PROJETO 2: To-Do List SSR (Flask + Jinja2 + SQLite + SQLAlchemy)

Objetivo: Construir a primeira aplicação Web completa com formulários HTML, renderização Server-Side (SSR) e persistência em arquivo SQLite real.
Conceitos: Jinja2 Templates (render_template), DeclarativeBase, Mapped, mapped_column, SessionLocal.

flowchart LR
    BROWSER["🌐 Browser (Formulário HTML)"] -->|POST /tarefas/nova| FLASK["🌐 Flask"]
    FLASK -->|Insere Registro| ORM["🧱 SQLAlchemy 2.0"]
    ORM -->|Grava em Disco| SQLITE[("📁 todo.db (SQLite)")]
    FLASK -->|Renderiza HTML com Dados| JINJA["🎨 Jinja2 Template"]
    JINJA -->|HTTP 302 / Redireciona| BROWSER

🔨 PROJETO 3: Biblioteca Acadêmica (Relacionamento 1:N & JOINs)

Objetivo: Modelar e consultar entidades com integridade referencial e chaves estrangeiras.
Conceitos: ForeignKey, relationship(), cascade="all, delete-orphan", select().join().

erDiagram
    CATEGORIA ||--o{ LIVRO : "1 categoria possui N livros"
    CATEGORIA {
        int id_categoria PK
        string nome
    }
    LIVRO {
        int id_livro PK
        string titulo
        string isbn
        int id_categoria FK
    }

🔨 PROJETO 4: Vendas & Estoque (Relacionamento N:N & Transações ACID)

Objetivo: Implementar tabelas associativas com atributos próprios (preço histórico e quantidade) e controle rigoroso de transações bancárias/comerciais (commit e rollback).
Conceitos: Tabela Associativa N:N, Transaction boundary, session.rollback().

erDiagram
    PEDIDO ||--o{ ITEM_PEDIDO : "contém"
    PRODUTO ||--o{ ITEM_PEDIDO : "está presente em"
    PEDIDO {
        int id_pedido PK
        datetime data_hora
        string status
    }
    ITEM_PEDIDO {
        int id_pedido PK, FK
        int id_produto PK, FK
        int quantidade
        decimal preco_unitario
    }
    PRODUTO {
        int id_produto PK
        string nome
        decimal preco_atual
        int estoque_atual
    }

🔨 PROJETO 5: Sistema com Autenticação e Segurança

Objetivo: Proteger recursos com hash seguro de senhas, sessões de usuário e proteção contra vulnerabilidades OWASP (SQL Injection, XSS, CSRF).
Conceitos: Passlib (Bcrypt), OAuth2PasswordBearer, JWT (JSON Web Tokens), HTTPOnly Cookies.

sequenceDiagram
    autonumber
    actor Usuario as 👤 Usuário
    participant App as 🌐 Flask Auth
    participant DB as 🛢️ Banco de Dados (SQLite/Postgres)

    Usuario->>App: POST /login (email, senha_plana)
    App->>DB: Busca usuário por email
    DB-->>App: Retorna hash_senha do banco
    App->>App: Valida bcrypt.verify(senha_plana, hash_senha)
    App-->>Usuario: Retorna Sessão / Cookie HTTP-Only

🔨 PROJETO 6: Transição Dual-Database com Alembic e PostgreSQL

Objetivo: Migrar a aplicação do ambiente local para produção no Docker usando migrações de schema automatizadas sem perda de dados.
Conceitos: Alembic, alembic revision --autogenerate, alembic upgrade head, docker-compose.yml.

flowchart TD
    M["🧱 SQLAlchemy Models (Python)"] --> A["🔄 Alembic CLI"]
    A -->|Gera Script de Migração| V["📄 versions/001_initial.py"]
    V -->|Executa no SQLite Local| S[("📁 SQLite (dev.db)")]
    V -->|Executa no PostgreSQL Docker| P[("🐘 PostgreSQL (portal_db)")]

🏆 PROJETO 7: O Projeto Integrador Oficial (Scaffold Full-Stack)

Objetivo: Desenvolver o projeto temático do grupo (dentre os 10 Temas Setoriais) com o Scaffold Oficial Padronizado:

examples/template_projeto_integrador/
├── 🐍 main.py                      (Flask com rotas Web SSR e REST API)
├── 🛢️ database.py                  (Dual Database transparente com SessionLocal)
├── 🧱 models.py                    (SQLAlchemy 2.0 com Mapped Type Hints)
├── 🌐 templates/                   (Jinja2 Server-Side Rendering)
├── 🧪 tests/                       (Pytest + Flask test_client em memória)
├── 🐳 docker-compose.yml           (PostgreSQL 17 multi-container)
└── 📄 README.md                    (Guia de execução rápida)

🎯 Próximo Passo:

👉 Acesse a Galeria dos 10 Projetos Integradores para escolher o tema do seu grupo e iniciar o desenvolvimento!

FATEC - GTI - DSM