🎓 Portal do Curso: FATEC - GTI - DSM

📂 Acesse seu conteúdo

🔗 Atalhos Rápidos

🛠️ Ferramentas Recomendadas (2023.1)

Para um melhor aproveitamento das disciplinas técnicas, reunimos abaixo as principais ferramentas, linguagens e utilitários utilizados no mercado e nas aulas. 🛡️

🌐 Editores Online

💻 IDEs e Editores de Código 2023.1

🧩 Extensões Essenciais (VS Code)

🐘 Banco de Dados

☕ Linguagens e Ambientes

⛓️ Controle de Versão e Gestão

📐 Modelagem e Design

🧪 Aprendizado e Algoritmos

🎨 Multimídia e Imagem

🎬 Áudio e Vídeo

📂 Utilitários Sistêmicos

[!IMPORTANT] 📗 Dica de Uso: Para os bancos de dados (MySQL e PostgreSQL), recomendamos desativar o serviço no boot automático para economizar RAM, iniciando-os manualmente apenas quando necessário.

🛠️ Ferramentas Recomendadas (2024.1)

Programas e Scripts

🔗 Acessar Programas e Scripts

🩺 GUIA DE TROUBLESHOOTING E FAQ DE ENGENHARIA

Durante o desenvolvimento de software e persistência de dados, encontrar erros e exceções no terminal faz parte natural da jornada de aprendizado.

Este guia reúne os erros mais comuns enfrentados pelos estudantes, explicando a causa raiz, o que a mensagem técnica significa e o passo a passo exato para resolver o problema em segundos. 🛡️⚡

🧭 Índice Rápido de Diagnóstico

flowchart TD
    E["🚨 Encontrou um Erro?"] --> API["🌐 1. Erros de API, Flask & Pydantic (400, 404, 405, Porta 5000)"]
    E --> ORM["🛢️ 2. Erros de Banco & SQLAlchemy (IntegrityError, Lock)"]
    E --> ENV["🐳 3. Erros de Docker, Portas & Venv (Porta 5432 Ocupada)"]
    E --> MIG["🔄 4. Erros de Alembic & Migrations (Multiple Heads)"]
    E --> JINJA["🎨 5. Erros de Template Jinja2 (TemplateNotFound)"]

    style E fill:#fee2e2,stroke:#ef4444
    style API fill:#e0f2fe,stroke:#0284c7
    style ORM fill:#fef3c7,stroke:#d97706
    style ENV fill:#dcfce7,stroke:#16a34a
    style MIG fill:#f3e8ff,stroke:#9333ea
    style JINJA fill:#fce7f3,stroke:#db2777

🌐 1. Erros de API, Flask 3.x e Pydantic

❌ Erro 1.1: Porta 5000 já em uso (OSError: [WinError 10048])

• Sintoma: Ao executar python -m app.main, o terminal exibe OSError: [WinError 10048] Only one usage of each socket address is normally permitted.
• Causa Raiz: Uma instância anterior do servidor Flask ainda está rodando em segundo plano no Windows e segurando a porta 5000.
• Como Resolver: Abra o PowerShell e encerre os processos Python ativos:

Get-Process python* | Stop-Process -Force

❌ Erro 1.2: 400 Bad Request ao validar payload com Pydantic

• Sintoma: Ao enviar uma requisição POST ou PUT, a API retorna 400 Bad Request com o detalhe do erro do Pydantic ou request.get_json() retorna None.
• Causa Raiz: O cliente não enviou o cabeçalho Content-Type: application/json ou faltou algum campo obrigatório exigido pelo Schema.
• Como Resolver:
  1. No PowerShell com Invoke-RestMethod, garanta o parâmetro -ContentType "application/json".
  2. Verifique se o JSON contém todas as chaves exigidas pelo schema Pydantic.
  3. No handler do Flask, utilize sempre tratamento com bloco try/except:

dados = request.get_json() or {}
try:
    payload = MeuSchema(**dados)
except Exception as err:
    return jsonify({"detail": str(err)}), 400

❌ Erro 1.3: 405 Method Not Allowed

• Sintoma: Ao submeter um formulário ou chamar um endpoint, o navegador exibe 405 Method Not Allowed.
• Causa Raiz: O endpoint foi registrado para um verbo HTTP (ex: @app.get("/usuarios")), mas a requisição foi feita usando outro método (ex: POST).
• Como Resolver:
  1. No formulário HTML, confira a tag: <form action="/usuarios" method="POST">.
  2. No arquivo do router Flask, certifique-se de que o método HTTP coincide:

@router.route("/usuarios", methods=["POST"])
# ou:
@router.post("/usuarios")

❌ Erro 1.4: Erro de CORS (Blocked by CORS Policy)

• Sintoma: O frontend não consegue se comunicar com a API e o console do navegador exibe: Access to XMLHttpRequest at 'http://localhost:5000/api' has been blocked by CORS policy.
• Causa Raiz: Por segurança, navegadores bloqueiam requisições JavaScript vindas de origens/portas diferentes.
• Como Resolver: Adicione os headers CORS ou utilize flask-cors:

@app.after_request
def add_cors_headers(response):
    response.headers["Access-Control-Allow-Origin"] = "*"
    response.headers["Access-Control-Allow-Headers"] = "Content-Type,Authorization"
    response.headers["Access-Control-Allow-Methods"] = "GET,POST,PUT,DELETE,OPTIONS"
    return response

🛢️ 2. Erros de Banco de Dados & SQLAlchemy 2.0

❌ Erro 2.1: sqlalchemy.exc.IntegrityError: NOT NULL constraint failed

• Sintoma: Falha ao tentar salvar um registro com session.commit().
• Causa Raiz: O modelo possui uma coluna com nullable=False (ou Mapped[str] sem | None), mas o objeto foi instanciado sem preencher esse valor.
• Como Resolver: Garanta que todos os campos obrigatórios sejam passados no construtor do modelo antes de executar session.add():

# ❌ Incorreto:
novo_cliente = Cliente(email="carlos@email.com") # Faltou o nome!

# ✅ Correto:
novo_cliente = Cliente(nome="Carlos Silva", email="carlos@email.com")

❌ Erro 2.2: sqlite3.OperationalError: database is locked

• Sintoma: O SQLite trava e emite erro informando que o arquivo de banco de dados está bloqueado.
• Causa Raiz: Uma sessão anterior abriu uma transação de escrita e não foi encerrada com session.commit(), session.rollback() ou session.close(), ou o banco está aberto para edição concorrente em outra ferramenta (como DB Browser).
• Como Resolver:
  1. Garanta que a função get_db() utilize yield e finally: db.close().
  2. Feche conexões manuais abertas em ferramentas externas.
  3. No database.py, configure timeout para o SQLite:

engine = create_engine(
    "sqlite:///dev.db",
    connect_args={"timeout": 30} # Aguarda até 30s antes de falhar
)

❌ Erro 2.3: sqlalchemy.orm.exc.DetachedInstanceError

• Sintoma: Erro ao acessar um relacionamento (ex: usuario.pedidos) no template Jinja2 ou após sair da função de rota.
• Causa Raiz: O SQLAlchemy usa carregamento preguiçoso (Lazy Loading) por padrão. Quando a sessão do banco foi fechada pelo get_db(), o objeto perdeu a conexão ativa necessária para buscar os dados filhos.
• Como Resolver: Utilize joinedload() ou selectinload() na consulta para trazer os relacionamentos de forma ansiosa (Eager Loading):

from sqlalchemy.orm import selectinload

stmt = select(Usuario).options(selectinload(Usuario.pedidos)).where(Usuario.id == 1)
usuario = session.scalars(stmt).first()

🐳 3. Erros de Docker, Portas e Ambiente Virtual

❌ Erro 3.1: Bind for 0.0.0.0:5432 failed: port is already allocated

• Sintoma: Ao rodar docker compose up -d, o terminal acusa que a porta 5432 já está em uso.
• Causa Raiz: O serviço do PostgreSQL nativo do Windows já está rodando em segundo plano e ocupando a porta 5432 da máquina física.
• Como Resolver (Opção A — Parar o serviço do Windows):
  • Abra o PowerShell como Administrador e execute:

Stop-Service postgresql*

• Como Resolver (Opção B — Mudar a porta no docker-compose.yml):
  • Mude o mapeamento para usar a porta 5433 no seu computador:

ports:
  - "5433:5432" # 5433 no Windows -> 5432 dentro do container

• Atualize seu .env: DATABASE_URL=postgresql://postgres:senha@localhost:5433/meu_db.

❌ Erro 3.2: Erro de Permissão ao Ativar o Venv no PowerShell (Script Execution Policy)

• Sintoma: Ao rodar .\venv\Scripts\Activate.ps1, o PowerShell exibe: não pode ser carregado porque a execução de scripts foi desabilitada neste sistema.
• Causa Raiz: Política de segurança padrão do Windows para scripts locais.
• Como Resolver: Abra o PowerShell e libere para o seu usuário atual:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

🔄 4. Erros de Migrações com Alembic

❌ Erro 4.1: alembic.util.exc.CommandError: Target database is not up to date

• Sintoma: Erro ao tentar rodar alembic revision --autogenerate.
• Causa Raiz: Existem migrações anteriores no histórico que ainda não foram aplicadas no banco de dados atual.
• Como Resolver: Aplique todas as migrações pendentes antes de gerar uma nova:

alembic upgrade head
alembic revision --autogenerate -m "nova_alteracao"
alembic upgrade head

❌ Erro 4.2: Conflito de Versões (Multiple head revisions are present)

• Sintoma: Conflito após fazer git pull de alterações de outro colega de grupo no Projeto Integrador.
• Causa Raiz: Dois alunos criaram migrações simultaneamente em branches separadas.
• Como Resolver: Crie uma migração de merge para unir as duas pontas:

alembic merge heads -m "merge_conflitos"
alembic upgrade head

🎨 5. Erros de Template e Renderização Jinja2

❌ Erro 5.1: jinja2.exceptions.TemplateNotFound: index.html

• Sintoma: A aplicação Flask falha com erro de template não encontrado ao tentar renderizar a view.
• Causa Raiz: O caminho informado no template_folder do Flask está incorreto ou a pasta templates não está no mesmo nível do diretório app/.
• Como Resolver: Configure o caminho absoluto baseado na raiz do diretório app/:

from pathlib import Path
from flask import Flask, render_template

BASE_DIR = Path(__file__).resolve().parent
app = Flask(__name__, template_folder=str(BASE_DIR / "templates"))

❌ Erro 5.2: jinja2.exceptions.UndefinedError: 'item' is undefined

• Sintoma: A página quebra durante a renderização no navegador.
• Causa Raiz: O template .html tenta acessar uma variável {{ item.nome }}, mas ela não foi passada nos argumentos do render_template(...).
• Como Resolver: Verifique a rota no main.py e certifique-se de passar o objeto nomeado no retorno:

@app.route("/detalhes/<int:id>")
def detalhes(id: int):
    item_do_banco = ...
    return render_template("detalhes.html", item=item_do_banco)

📑 CHEATSHEETS DE ENGENHARIA E BANCO DE DADOS

Este guia reúne as sintaxes e comandos mais utilizados no dia a dia do desenvolvimento backend corporativo, servindo como material oficial de consulta rápida para laboratórios práticos, avaliações e desenvolvimento de Projetos Integradores. ⚡🛡️

🧱 1. SQLAlchemy 2.0 (CRUD & Consultas Modernas)

flowchart LR
    S["select(Model)"] --> W[".where(...)"]
    W --> J[".join(...)"]
    J --> O[".order_by(...)"]
    E["session.scalars(...).all()"]
    
    S --> W
    W --> J
    J --> O
    O --> E
    
    style S fill:#e3f2fd,stroke:#1565c0
    style W fill:#fff8e1,stroke:#f57f17
    style J fill:#e8f5e9,stroke:#2e7d32
    style O fill:#f3e5f5,stroke:#7b1fa2
    style E fill:#e0f2f1,stroke:#00695c

📋 Mapeamento Declarativo de Modelos:

from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
from sqlalchemy import String, Integer, ForeignKey, Numeric
from decimal import Decimal

class Base(DeclarativeBase):
    pass

class Cliente(Base):
    __tablename__ = "clientes"
    id_cliente: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    nome: Mapped[str] = mapped_column(String(100), nullable=False)
    limite_credito: Mapped[Decimal] = mapped_column(Numeric(10, 2), default=Decimal("0.00"))
    pedidos: Mapped[list["Pedido"]] = relationship(back_populates="cliente", cascade="all, delete-orphan")

🔍 Operações de CRUD:

from sqlalchemy import select, func
from sqlalchemy.orm import selectinload

# 1. READ (Buscar por ID):
cliente = session.get(Cliente, 1)

# 2. READ (Filtrar múltiplos com WHERE e ORDER BY):
stmt = select(Cliente).where(Cliente.limite_credito > 1000).order_by(Cliente.nome.asc())
clientes = session.scalars(stmt).all()

# 3. READ (Com Eager Loading de Relacionamento):
stmt = select(Cliente).options(selectinload(Cliente.pedidos)).where(Cliente.id_cliente == 1)
cliente_com_pedidos = session.scalars(stmt).first()

# 4. CREATE (Inserir novo registro):
novo = Cliente(nome="Transportadora VIP", limite_credito=Decimal("5000.00"))
session.add(novo)
session.commit()
session.refresh(novo) # Popula o ID gerado

# 5. UPDATE (Atualizar campos):
cliente.limite_credito = Decimal("7500.00")
session.commit()

# 6. DELETE (Excluir registro):
session.delete(cliente)
session.commit()

# 7. AGGREGATE (Contagem e Média):
stmt = select(func.count(Cliente.id_cliente), func.avg(Cliente.limite_credito))
total, media = session.execute(stmt).one()

🌐 2. Flask 3.x & SQLAlchemy 2.0 (Rotas, Blueprints e JSON)

from flask import Flask, Blueprint, request, jsonify
from pydantic import BaseModel, Field
from sqlalchemy.orm import Session
from sqlalchemy import select

app = Flask(__name__)
bp = Blueprint("clientes", __name__, url_prefix="/api")

# Schema Pydantic de Entrada (Validação de Tipos)
class ClienteCreate(BaseModel):
    nome: str = Field(..., min_length=3, max_length=100)
    limite_credito: float = Field(0.0, ge=0.0)

# Rota POST (Criar registro com Validação Pydantic)
@bp.post("/clientes")
def criar_cliente():
    dados = request.get_json() or {}
    try:
        payload = ClienteCreate(**dados)
    except Exception as err:
        return jsonify({"detail": str(err)}), 400

    with SessionLocal() as session:
        cliente = Cliente(**payload.model_dump())
        session.add(cliente)
        session.commit()
        session.refresh(cliente)
        return jsonify({
            "id_cliente": cliente.id_cliente,
            "nome": cliente.nome,
            "limite_credito": float(cliente.limite_credito)
        }), 201

# Rota GET (Buscar por ID com Tratamento de Erro 404)
@bp.get("/clientes/<int:id_cliente>")
def buscar_cliente(id_cliente: int):
    with SessionLocal() as session:
        cliente = session.get(Cliente, id_cliente)
        if not cliente:
            return jsonify({"detail": "Cliente não encontrado."}), 404
        return jsonify({
            "id_cliente": cliente.id_cliente,
            "nome": cliente.nome,
            "limite_credito": float(cliente.limite_credito)
        }), 200

app.register_blueprint(bp)

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000, debug=True)

🛢️ 3. SQL Corporativo (DML, DQL e Relatórios)

📋 Ordem Obrigatória de Execução da Consulta:

1. FROM & JOIN (Localiza as tabelas)
2. WHERE (Filtra linhas individuais)
3. GROUP BY (Agrupa dados)
4. HAVING (Filtra grupos calculados)
5. SELECT (Projeta colunas e funções)
6. ORDER BY (Ordena o resultado)
7. LIMIT & OFFSET (Pagina os dados)

💻 Queries de Alto Desempenho:

-- 1. INNER JOIN (Relatório com 2 tabelas):
SELECT p.id_pedido, c.nome, p.valor_total
FROM pedido p
INNER JOIN cliente c ON p.id_cliente = c.id_cliente
WHERE p.status = 'CONCLUIDO';

-- 2. LEFT JOIN (Encontrar clientes que NUNCA compraram):
SELECT c.id_cliente, c.nome
FROM cliente c
LEFT JOIN pedido p ON c.id_cliente = p.id_cliente
WHERE p.id_pedido IS NULL;

-- 3. GROUP BY + HAVING (Categorias com faturamento > R$ 10.000):
SELECT categoria, COUNT(*) AS total_itens, SUM(preco) AS faturamento
FROM produto
GROUP BY categoria
HAVING SUM(preco) > 10000
ORDER BY faturamento DESC;

-- 4. Subquery com EXISTS (Mais rápida que IN):
SELECT nome FROM fornecedor f
WHERE EXISTS (
    SELECT 1 FROM materia_prima mp 
    WHERE mp.id_fornecedor = f.id_fornecedor AND mp.estoque_atual < 10
);

-- 5. INSERT com RETURNING (Retorna ID gerado sem segundo SELECT):
INSERT INTO clientes (nome, limite_credito) 
VALUES ('Logística Express', 3000.00) 
RETURNING id_cliente, nome;

🐳 4. Git & Docker Compose (Terminal do Desenvolvedor)

🧰 CAPÍTULO 00: KIT DE SOBREVIVÊNCIA — FUNDAMENTOS COMUNS

🎯 Objetivos de Aprendizagem

Estimativa de dedicação: 3 horas de estudo autoguiado. Ao final deste capítulo, você será capaz de:

• 🔹 Navegar pastas e executar scripts pelo terminal do VS Code.
• 🔹 Versionar um projeto com Git e enviá-lo para o GitHub (clone, add, commit, push).
• 🔹 Ler e escrever classes Python com @dataclass, @property e validação de dados.
• 🔹 Interpretar um payload JSON e montar/entender um comando curl contra uma API REST.

🏢 Por que isso importa (Cenário TecProExpress)

Todas as atividades práticas do curso — Engenharia de Software e Banco de Dados — giram em torno da TecProExpress, uma empresa fictícia de logística. Desde a primeira semana, os roteiros já pedem para você "clonar o repositório", "rodar python script.py" ou "testar com curl" sem parar para explicar esses três movimentos. Este capítulo existe para que, quando isso acontecer, você já tenha feito esse gesto pelo menos uma vez.

🧠 1. Terminal e VS Code

Um terminal é apenas um jeito de conversar com o computador por texto em vez de cliques. Os três comandos que você vai repetir centenas de vezes neste curso:

Instale também as extensões recomendadas do projeto: abra a pasta do repositório no VS Code e aceite a notificação para instalar o pacote definido em .vscode/extensions.json (Python, SQLTools, Docker, Draw.io).

🧠 2. Git e GitHub do Zero

Git guarda o histórico do seu código no seu computador. GitHub guarda uma cópia desse histórico na nuvem, para o professor avaliar e para você nunca perder o trabalho.

flowchart LR
    A["📁 Pasta local"] -->|"git init / git clone"| B["📦 Repositório Git local"]
    B -->|"git add ."| C["🗂️ Área de Stage"]
    C -->|"git commit -m '...'"| D["📌 Commit (snapshot local)"]
    D -->|"git push"| E["☁️ GitHub (remoto)"]

    style A fill:#e3f2fd,stroke:#1e88e5
    style D fill:#fff8e1,stroke:#fbc02d
    style E fill:#e8f5e9,stroke:#43a047

🛠️ O ciclo que você vai repetir toda semana

# 1. Clone o repositório de atividades (uma única vez)
git clone https://github.com/SEU-USUARIO/atividades-banco-de-dados.git
cd atividades-banco-de-dados

# 2. Depois de editar/criar arquivos, veja o que mudou
git status

# 3. Selecione o que vai entrar no commit
git add .

# 4. Registre um snapshot com uma mensagem clara
git commit -m "feat: adiciona script da atividade 01"

# 5. Envie para o GitHub
git push

🔍 Detalhamento do Comando:

• git status: mostra o que mudou desde o último commit — rode antes de qualquer outro comando, sempre.
• git add .: coloca todos os arquivos modificados na fila do próximo commit.
• git commit -m "...": a mensagem deve dizer o quê e por quê (ex: fix: corrige cálculo de frete, não mudanças).
• git push: só depois disso o professor consegue ver seu trabalho no GitHub.

🧠 3. Python Essencial e POO

Praticamente todo capítulo teórico do curso (Engenharia de Software e Banco de Dados) usa classes Python para modelar entidades do mundo real. Os quatro ingredientes que você precisa reconhecer:

💻 Código Completo e Autocontido (produto.py)

"""
Módulo: produto.py
Domínio: Representação de um produto do catálogo da TecProExpress.
Execução: python produto.py
"""
from dataclasses import dataclass, field

@dataclass
class Produto:
    nome: str
    preco: float
    tags: list[str] = field(default_factory=list)

    @property
    def preco_formatado(self) -> str:
        """Atributo calculado: formata o preço como moeda brasileira."""
        return f"R$ {self.preco:.2f}"

    def aplicar_desconto(self, percentual: float) -> None:
        if not 0 <= percentual <= 100:
            raise ValueError("Percentual de desconto deve estar entre 0 e 100.")
        self.preco -= self.preco * (percentual / 100)


if __name__ == "__main__":
    produto = Produto(nome="Notebook TecPro X1", preco=3500.00, tags=["eletronico", "oferta"])
    print(f"Antes do desconto: {produto.preco_formatado}")

    produto.aplicar_desconto(10)
    print(f"Depois de 10% de desconto: {produto.preco_formatado}")

🚀 Como Executar

python produto.py

🖥️ Saída Esperada no Terminal

Antes do desconto: R$ 3500.00
Depois de 10% de desconto: R$ 3150.00

🔍 Detalhamento do Código:

• field(default_factory=list): evita o erro clássico de usar uma lista vazia ([]) diretamente como valor padrão em Python.
• aplicar_desconto: valida o percentual antes de aplicar — o objeto nunca fica em um estado inconsistente (preço negativo, por exemplo).
• @property: repare que chamamos produto.preco_formatado, sem parênteses — para quem usa a classe, parece um atributo comum.

🧠 4. JSON e HTTP/REST na Prática

Desde a Atividade 06 (Engenharia de Software) e a Atividade 06 (Banco de Dados), os roteiros pedem para testar uma API com curl. Aqui está o que você precisa para não ficar copiando sem entender.

JSON é só um dicionário Python escrito como texto:

{
  "nome": "Notebook TecPro X1",
  "preco": 3500.00,
  "tags": ["eletronico", "oferta"]
}

HTTP é o "idioma" que o navegador (ou o curl) usa para conversar com um servidor:

🔍 Anatomia de um curl

curl -X POST "http://127.0.0.1:5000/api/pacotes" \
     -H "Content-Type: application/json" \
     -d '{"codigo": "BR123456", "peso_kg": 2.5}'

• -X POST: qual verbo HTTP usar.
• "http://127.0.0.1:5000/...": o endereço do servidor — 127.0.0.1 é "meu próprio computador"; 5000 é a porta onde o servidor está escutando.
• -H "Content-Type: application/json": avisa ao servidor que o corpo da requisição é JSON.
• -d '{...}': o corpo (body) da requisição — os dados que você está enviando.

💡 Checkpoint de Lógica

🧪 Quiz de Fixação e Autoavaliação

🛠️ Ponte para a Sua Trilha

📌 Resumo Executivo & Key Takeaways

• Terminal: cd para navegar, python arquivo.py para executar — é só isso que você precisa para começar.
• Git: o ciclo status → add → commit -m "..." → push se repete em toda entrega do curso.
• POO em Python: @dataclass gera o construtor; @property cria atributos calculados; valide dados no construtor para evitar objetos inconsistentes.
• HTTP/REST: verbo (GET/POST/...) + endereço + corpo JSON é a receita de toda requisição que você vai testar com curl neste curso.

Engenharia de Software e Aplicações

📋 PLANO DE ENSINO ATUALIZADO

Carga Horária: 80 aulas presenciais + 40 atividades autônomas
Curso: Tecnólogo - FATEC

🎯 OBJETIVO GERAL

Capacitar o aluno a aplicar princípios da Engenharia de Software no desenvolvimento de sistemas, utilizando metodologias, técnicas e ferramentas modernas para análise, projeto, implementação e validação de software.

🧪 METODOLOGIA

• Aulas expositivas + práticas.
• Aprendizado baseado em projetos (PBL).
• Estudos de caso reais.
• Uso de ferramentas do mercado (Git, Docker, Jira, Figma).

📊 AVALIAÇÃO

🚀 DIFERENCIAL TECNOLÓGICO

Integração de stacks modernas para o projeto final:

• Backend: Spring Boot (Java)
• Frontend: Angular
• Banco: PostgreSQL
• DevOps: Docker & Git

🧭 MÓDULOS DO CURSO

📖 BIBLIOGRAFIA BÁSICA

• PILONE, Dan; MILES, Russell. Use A Cabeça - Desenvolvimento de Software.
• PRESSMAN, R. S. Engenharia de Software.
• SOMERVILLE, I. Engenharia de Software.

📖 BIBLIOGRAFIA COMPLEMENTAR

• GUEDES, G. UML 2 – Uma Abordagem Prática.
• YOURDON, E. Análise Estruturada Moderna.

🧰 CAPÍTULO 00: KIT DE SOBREVIVÊNCIA — ENGENHARIA DE SOFTWARE

🎯 Objetivos de Aprendizagem

Estimativa de dedicação: 2 horas de estudo autoguiado. Ao final deste capítulo, você será capaz de:

• 🔹 Ler (não desenhar) os três diagramas UML mais usados no curso: Casos de Uso, Classes e Sequência.
• 🔹 Subir seu primeiro servidor Flask e responder a uma requisição real.
• 🔹 Escrever e rodar seu primeiro teste automatizado com pytest.

🏢 Por que isso importa

A Atividade 05 já pede um Diagrama de Casos de Uso, a Atividade 06 já pede para rodar um servidor Flask real e testá-lo com curl, e a Atividade 09 já pede testes com pytest — tudo isso antes da teoria completa de cada tópico ter sido consolidada. Este capítulo adianta o mínimo necessário para você não travar nesses pontos.

🧠 1. Como Ler um Diagrama UML

Você não precisa saber desenhar UML perfeitamente ainda — precisa saber ler os três tipos que mais aparecem no curso.

📌 Caso de Uso: "o que o sistema faz, por quem"

Um boneco (ator) se conecta a ações (óvalos). Uma seta pontilhada com <<include>> significa "esse caso de uso sempre aciona o outro".

flowchart LR
    Cliente(("👤 Cliente"))
    UC1(["Rastrear Pacote"])
    UC2(["Cadastrar Pacote"])
    UC3(["Validar CEP"])

    Cliente --> UC1
    Cliente --> UC2
    UC2 -.->|"《include》"| UC3

    style Cliente fill:#e3f2fd,stroke:#1e88e5
    style UC3 fill:#fff8e1,stroke:#fbc02d

Leitura: o Cliente pode Rastrear ou Cadastrar um Pacote; cadastrar sempre inclui validar o CEP.

📌 Classes: "quais entidades existem e como se relacionam"

Cada caixa é uma classe (atributos em cima, métodos embaixo). O número perto da linha é a multiplicidade (quantos de cada lado).

classDiagram
    class Cliente {
        -nome: str
        -email: str
    }
    class Pacote {
        -codigo: str
        -peso_kg: float
        +calcular_frete() float
    }
    Cliente "1" --> "*" Pacote : envia

Leitura: 1 Cliente pode enviar * (zero ou muitos) Pacotes.

📌 Sequência: "quem chama quem, em que ordem, ao longo do tempo"

Cada linha vertical é um participante. As setas horizontais são mensagens, lidas de cima para baixo.

sequenceDiagram
    actor Cliente
    participant App as App Web
    participant API as API Flask

    Cliente->>App: Rastrear pacote BR123456
    App->>API: GET /api/pacotes/BR123456
    activate API
    API-->>App: 200 OK + status JSON
    deactivate API
    App-->>Cliente: Mostra status na tela

Leitura: o Cliente pede à tela, a tela pede à API, a API responde, a tela mostra o resultado — nessa ordem exata.

🧠 2. Flask: Seu Primeiro "Hello World"

A partir da Atividade 06, você vai rodar um servidor Flask de verdade. Vamos fazer isso uma vez, com calma.

📋 Instalação

pip install flask

💻 Código Completo (app.py)

"""
Módulo: app.py
Primeiro servidor Flask da jornada TecProExpress.
Execução: python app.py
"""
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/")
def index():
    return "🚚 TecProExpress API no ar!"

@app.route("/api/saudacao", methods=["POST"])
def saudacao():
    dados = request.get_json() or {}
    nome = dados.get("nome", "visitante")
    return jsonify({"mensagem": f"Olá, {nome}! Bem-vindo à TecProExpress."}), 200

if __name__ == "__main__":
    print("🚀 Servidor Flask ativo em: http://127.0.0.1:5000")
    app.run(debug=True, port=5000)

🚀 Como Executar

python app.py

🌐 Testando com curl (em outro terminal)

curl -X POST http://127.0.0.1:5000/api/saudacao \
     -H "Content-Type: application/json" \
     -d "{\"nome\": \"Ana\"}"

🖥️ Resposta Esperada

{"mensagem": "Olá, Ana! Bem-vindo à TecProExpress."}

🔍 Detalhamento do Código:

• @app.route("/api/saudacao", methods=["POST"]): registra a rota e o verbo HTTP aceito.
• request.get_json(): lê o corpo JSON enviado no -d do curl.
• jsonify(...): converte o dicionário Python de volta em uma resposta JSON válida.
• app.run(debug=True, port=5000): debug=True recarrega o servidor sozinho a cada alteração salva — ótimo durante o desenvolvimento.

🧠 3. pytest em 10 Minutos

📋 Instalação

pip install pytest

💻 Código Completo (test_saudacao.py)

Salve no mesmo diretório do app.py criado acima:

"""
Módulo: test_saudacao.py
Execução: pytest test_saudacao.py -v
"""
import pytest
from app import app


@pytest.fixture
def client():
    app.config["TESTING"] = True
    with app.test_client() as client:
        yield client


def test_saudacao_com_nome(client):
    resposta = client.post("/api/saudacao", json={"nome": "Ana"})
    assert resposta.status_code == 200
    assert "Ana" in resposta.get_json()["mensagem"]


def test_saudacao_sem_nome(client):
    resposta = client.post("/api/saudacao", json={})
    assert resposta.status_code == 200
    assert "visitante" in resposta.get_json()["mensagem"]

🚀 Como Executar

pytest test_saudacao.py -v

🖥️ Saída Esperada no Terminal

test_saudacao.py::test_saudacao_com_nome PASSED                        [ 50%]
test_saudacao.py::test_saudacao_sem_nome PASSED                        [100%]

============================== 2 passed in 0.08s ===============================

🔍 Detalhamento do Código:

• @pytest.fixture: prepara algo reutilizável (aqui, um cliente de testes) para cada função de teste que o receber como parâmetro.
• app.test_client(): simula requisições HTTP contra o Flask sem precisar subir o servidor de verdade — mais rápido e mais confiável.
• assert: se a condição for falsa, o teste falha e o pytest mostra exatamente qual valor era esperado.

💡 Checkpoint de Lógica

🧪 Quiz de Fixação e Autoavaliação

🛠️ Ponte para a Ação

📌 Resumo Executivo & Key Takeaways

• UML: Casos de Uso mostram quem faz o quê; Classes mostram quais entidades existem; Sequência mostra a ordem das chamadas ao longo do tempo.
• Flask: uma rota é uma função decorada com @app.route; request.get_json() lê a entrada, jsonify() formata a saída.
• pytest: app.test_client() testa rotas Flask sem precisar de um servidor real rodando — é assim que a Atividade 09 e o pipeline de CI/CD da Atividade 16 funcionam.

📚 CAPÍTULO 01: INTRODUÇÃO E NATUREZA DO SOFTWARE

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Compreender a evolução histórica da Engenharia de Software, a crise do software de 1968 e os princípios da Conferência da OTAN.
• 🔹 Diferenciar software como produto de engenharia (projetado e evolutivo) versus produtos de manufatura física (sujeitos a desgaste de peças).
• 🔹 Analisar a arquitetura de tipos de dados, mutabilidade e integridade no ecossistema moderno em Python 3.11+.
• 🔹 Implementar classes com encapsulamento defensivo e validação de integridade para serviços corporativos.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Imagine que você acaba de ingressar como Engenheiro de Software Júnior na TecProExpress, uma empresa nacional de logística expressa que opera 50.000 encomendas/dia. A diretoria herdou um sistema monolítico legado de 15 anos que se tornou frágil, lento e difícil de manter.

O Desafio: Seu objetivo não é apenas escrever linhas de código, mas transformar a prática empírica em uma disciplina de engenharia rigorosa, garantindo que novos módulos sejam construídos com baixo acoplamento, alta coesão e prontidão para evolução sustentável nos próximos anos.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. A Natureza Singular do Software

Ao contrário de pontes ou automóveis, o software não se desgasta pelo atrito físico. Ele se degrada por alterações mal projetadas, acúmulo de débito técnico e divergência entre a especificação e as regras de negócio.

flowchart TD
    subgraph "PRODUTOS FÍSICOS VS SOFTWARE"
        subgraph Hardware ["🏭 Manufatura Física"]
            H1["Projeto Inicial"] --> H2["Linha de Montagem"]
            H2 --> H3["Desgaste Físico por Atrito"]
            H3 --> H4["Substituição de Peças"]
        end
        subgraph Software ["💻 Engenharia de Software"]
            S1["Elicitação & Design"] --> S2["Construção Lógica"]
            S2 --> S3["Degradação por Complexidade"]
            S3 --> S4["Refatoração & Evolução Contínua"]
        end
    end
    style Hardware fill:#fff3e0,stroke:#e65100
    style Software fill:#e1f5fe,stroke:#0277bd

3.2. Os 4 Pilares da Engenharia de Software

A Engenharia de Software estrutura-se na integração equilibrada entre Pessoas, Processos, Métodos e Ferramentas:

flowchart LR
    P["👥 Pessoas<br>(Stakeholders & Times)"] --> PR["⚙️ Processos<br>(Ágil, Scrum, Kanban)"]
    PR --> M["📐 Métodos<br>(UML, DDD, Testes)"]
    M --> F["🛠️ Ferramentas<br>(Python, Git, CI/CD, Docker)"]
    
    style P fill:#e8f5e9,stroke:#2e7d32
    style PR fill:#ede7f6,stroke:#4527a0
    style M fill:#e3f2fd,stroke:#1565c0
    style F fill:#fbe9e7,stroke:#d84315

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

No código corporativo moderno, a aplicação dos princípios de orientação a objetos e auto-defesa de integridade impede que estados inconsistentes sejam criados na memória.

📋 Pré-requisitos e Instalação

Este módulo utiliza exclusivamente recursos nativos do Python 3.11+ (dataclasses e decimal). Nenhuma instalação externa é necessária:

# Ambiente padrão Python 3.11+ (sem dependências externas)

💻 Código Completo e Autocontido (tecpro_frete.py)

Crie o arquivo tecpro_frete.py e insira o código abaixo:

"""
Módulo: tecpro_frete.py
Domínio: Validação e cálculo defensivo de encomendas corporativas.
Stack: Python 3.11+
"""
from dataclasses import dataclass
from decimal import Decimal

@dataclass(frozen=True)
class Encomenda:
    codigo_rastreio: str
    peso_kg: Decimal
    valor_declarado: Decimal
    destino_uf: str

    def __post_init__(self):
        if not self.codigo_rastreio or len(self.codigo_rastreio) < 8:
            raise ValueError("Código de rastreio inválido (mínimo 8 caracteres).")
        if self.peso_kg <= Decimal("0.0"):
            raise ValueError("O peso da encomenda deve ser estritamente positivo.")
        if self.valor_declarado < Decimal("0.0"):
            raise ValueError("O valor declarado não pode ser negativo.")

    def calcular_seguro(self, taxa_percentual: Decimal = Decimal("0.01")) -> Decimal:
        """Calcula a taxa de seguro proporcional ao valor declarado."""
        return self.valor_declarado * taxa_percentual

if __name__ == "__main__":
    try:
        pacote = Encomenda(
            codigo_rastreio="BR-SP-2026-001",
            peso_kg=Decimal("2.450"),
            valor_declarado=Decimal("1500.00"),
            destino_uf="SP"
        )
        seguro = pacote.calcular_seguro()
        print("✅ Encomenda criada com sucesso!")
        print(f"📦 Pacote: {pacote.codigo_rastreio} | Seguro: R$ {seguro:.2f}")
    except ValueError as erro:
        print(f"❌ Falha de integridade: {erro}")

🚀 Como Executar

Execute o script no terminal:

python tecpro_frete.py

🖥️ Saída Esperada no Terminal

✅ Encomenda criada com sucesso!
📦 Pacote: BR-SP-2026-001 | Seguro: R$ 15.00

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• Engenharia vs Programação: Programar é escrever código funcional; Engenharia de Software é construir sistemas sustentáveis, testáveis e escaláveis ao longo de décadas.
• Degradação de Software: O software degrada por alterações desordenadas e falta de testes, não por desgaste de peças.
• Pilares de Excelência: Pessoas, Processos, Métodos e Ferramentas trabalhando de forma sinérgica.
• Auto-defesa de Dados: Validar dados no momento da instanciação impede a propagação silenciosa de bugs na aplicação.

🔄 CAPÍTULO 02: MODELOS DE PROCESSO DE SOFTWARE

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Compreender as características, forças e limitações dos modelos Cascata, Prototipação, Espiral e Incremental.
• 🔹 Avaliar e selecionar o modelo de ciclo de vida ideal com base na volatilidade de requisitos, criticidade de segurança e prazos.
• 🔹 Analisar o impacto da gestão de riscos e feedback contínuo no custo de alteração de software.
• 🔹 Implementar um sistema de máquina de estados em Python 3.11+ para rastrear o ciclo de vida de transição de fases.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, a diretoria de TI está iniciando dois novos projetos simultâneos:

1. Módulo de Telemetria e Frenagem Crítica: Integrado diretamente ao computador de bordo da frota pesada (risco de vida em caso de falha).
2. App de Chat do Motorista com IA: Ferramenta experimental para interação em tempo real com o suporte (requisitos muito voláteis).

O Desafio: A equipe técnica não pode aplicar a mesma estratégia de processo para ambos os produtos. Você deve estruturar a governança de processos, aplicando o modelo preditivo formal para o módulo crítico e o modelo incremental adaptativo para o app experimental.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. Panorama dos Modelos de Ciclo de Vida

Um modelo de processo de software prescreve a ordem das atividades, os critérios de entrada/saída de cada fase e as estratégias de validação com os clientes.

flowchart TD
    subgraph PROCESSOS ["PARADIGMAS DE PROCESSO"]
        W["🌊 Cascata (Waterfall)<br>Sequencial & Preditivo"]
        I["🔄 Incremental / Iterativo<br>Entregas Parciais & Evolutivas"]
        P["🎨 Prototipação<br>Validação de UI & Descoberta"]
        E["🌀 Espiral (Boehm)<br>Orientado a Riscos & Ciclos"]
    end
    
    style W fill:#e1f5fe,stroke:#0284c7
    style I fill:#dcfce7,stroke:#16a34a
    style P fill:#fef3c7,stroke:#d97706
    style E fill:#f3e5f5,stroke:#7b1fa2

3.2. Cascata vs. Incremental: Análise de Custo da Mudança

No modelo Cascata, o custo de corrigir um requisito mal compreendido na fase de testes pode ser até 100× maior do que na fase inicial de elicitação. No modelo Incremental, o feedback frequente reduz o retrabalho.

flowchart LR
    subgraph Cascata ["🌊 Modelo Cascata"]
        R1["Requisitos"] --> D1["Design"] --> C1["Código"] --> T1["Testes"] --> O1["Operação"]
    end
    
    subgraph Incremental ["🚀 Modelo Incremental"]
        direction TB
        Inc1["Incremento 1: MVP Core (4 semanas)"]
        Inc2["Incremento 2: Pagamentos & API (3 semanas)"]
        Inc3["Incremento 3: Relatórios & BI (3 semanas)"]
        Inc1 --> Inc2 --> Inc3
    end
    
    style Cascata fill:#fee2e2,stroke:#ef4444
    style Incremental fill:#dcfce7,stroke:#16a34a

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

Implementação de um motor de ciclo de vida de fases de projeto com validação estrita de transições.

📋 Pré-requisitos e Instalação

Este módulo utiliza exclusivamente recursos nativos do Python 3.11+ (enum). Nenhuma instalação externa é necessária:

# Ambiente padrão Python 3.11+ (sem dependências externas)

💻 Código Completo e Autocontido (ciclo_vida_processo.py)

Crie o arquivo ciclo_vida_processo.py e insira o código abaixo:

"""
Módulo: ciclo_vida_processo.py
Domínio: Automação e rastreamento de estágios do processo de software.
Stack: Python 3.11+
"""
from enum import Enum, auto

class FaseProcesso(Enum):
    CONCEPCAO = auto()
    REQUISITOS = auto()
    DESENHO_ARQUITETURAL = auto()
    IMPLEMENTACAO = auto()
    TESTES_INTEGRACAO = auto()
    DEPLOY_PRODUCAO = auto()

class CicloVidaProjeto:
    def __init__(self, nome_projeto: str, modelo: str = "INCREMENTAL"):
        self.nome_projeto = nome_projeto
        self.modelo = modelo
        self.fase_atual = FaseProcesso.CONCEPCAO
        self.historico_fases: list[FaseProcesso] = [self.fase_atual]

    def transicionar(self, proxima_fase: FaseProcesso, criterios_aceite_atendidos: bool):
        """Valida se os critérios de qualidade da fase atual foram satisfeitos antes de avançar."""
        if not criterios_aceite_atendidos:
            raise PermissionError(
                f"❌ Transição bloqueada: Critérios de aceite incompletos para sair de {self.fase_atual.name}."
            )
        self.fase_atual = proxima_fase
        self.historico_fases.append(self.fase_atual)
        print(f"🚀 [{self.nome_projeto}] Avançou com sucesso para a fase: {self.fase_atual.name}")

if __name__ == "__main__":
    projeto_core = CicloVidaProjeto("TecPro-Telemetria", modelo="CASCATA")

    # 1. Avançando com critérios satisfeitos
    projeto_core.transicionar(FaseProcesso.REQUISITOS, criterios_aceite_atendidos=True)
    projeto_core.transicionar(FaseProcesso.DESENHO_ARQUITETURAL, criterios_aceite_atendidos=True)

    # 2. Tentativa de avanço com pendências de qualidade
    try:
        projeto_core.transicionar(FaseProcesso.IMPLEMENTACAO, criterios_aceite_atendidos=False)
    except PermissionError as err:
        print(err)

🚀 Como Executar

Execute o script no terminal:

python ciclo_vida_processo.py

🖥️ Saída Esperada no Terminal

🚀 [TecPro-Telemetria] Avançou com sucesso para a fase: REQUISITOS
🚀 [TecPro-Telemetria] Avançou com sucesso para a fase: DESENHO_ARQUITETURAL
❌ Transição bloqueada: Critérios de aceite incompletos para sair de DESENHO_ARQUITETURAL.

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• Processos são Guias: Um processo de software estrutura as atividades da equipe para transformar requisitos de negócio em valor de produção com previsibilidade.
• Modelo Cascata: Adequado para domínios altamente regulados e com requisitos imutáveis; vulnerável a mudanças tardias.
• Modelo Incremental: Base das metodologias ágeis modernas; reduz o risco de construir o produto errado ao colher feedback contínuo.
• Modelo Espiral: Abordagem de alta maturidade com ênfase na identificação e neutralização antecipada de riscos técnicos e de negócio.

⚙️ CAPÍTULO 03: AS ATIVIDADES DO PROCESSO

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Compreender as quatro atividades universais de qualquer processo de software: Especificação, Projeto & Implementação, Validação e Evolução (Sommerville/Pressman).
• 🔹 Mapear o fluxo de rastreabilidade bidirecional entre requisitos de negócio, arquitetura, código-fonte e suíte de testes.
• 🔹 Distinguir verificação ("Estamos construindo o produto corretamente?") de validação ("Estamos construindo o produto correto?").
• 🔹 Implementar uma esteira de validação em Python 3.11+ para rastreamento de artefatos de entrega.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, um novo sistema de Rastreamento de Cargas e Frotas em Tempo Real foi aprovado para produção. Durante a primeira auditoria de governança, identificou-se que muitas funcionalidades codificadas não possuíam requisitos documentados e não eram cobertas por testes automatizados.

O Desafio: Seu objetivo é instituir a disciplina das 4 atividades universais do processo, criando uma esteira onde nenhum código chega a produção sem especificação prévia, implementação alinhada e validação automatizada.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. As Quatro Atividades Universais

Independentemente de a equipe utilizar métodos ágeis (Scrum/Kanban) ou abordagens tradicionais, todo processo de software executa quatro atividades fundamentais:

flowchart TD
    subgraph ATIVIDADES ["AS 4 ATIVIDADES UNIVERSAIS DO PROCESSO (SOMMERVILLE)"]
        direction LR
        E["📋 1. ESPECIFICAÇÃO<br>O que o sistema deve fazer<br>(Requisitos & Regras)"] 
        --> D["📐 2. PROJETO & CÓDIGO<br>Como o sistema será estruturado<br>(Arquitetura & Implementação)"]
        --> V["🧪 3. VALIDAÇÃO<br>Garantir que funciona e atende<br>(Testes Unitários & E2E)"]
        --> EV["🚀 4. EVOLUÇÃO<br>Adaptação a novas demandas<br>(Refatoração & Manutenção)"]
        EV -.-> E
    end
    
    style E fill:#e0f2fe,stroke:#0284c7
    style D fill:#ede7f6,stroke:#5e35b1
    style V fill:#dcfce7,stroke:#16a34a
    style EV fill:#fef3c7,stroke:#d97706

3.2. Matriz de Rastreabilidade de Engenharia

A rastreabilidade garante que cada requisito tenha correspondência direta em classes de código e casos de teste:

flowchart LR
    RF["Requisito Funcional<br>RF01: Check-in de Carga"] --> UC["Caso de Uso / Endpoint<br>POST /api/cargas/"]
    UC --> CL["Classe de Domínio<br>Carga (models.py)"]
    CL --> UT["Teste Automatizado<br>test_checkin_carga()"]
    
    style RF fill:#e3f2fd,stroke:#1565c0
    style UC fill:#f3e5f5,stroke:#7b1fa2
    style CL fill:#fff8e1,stroke:#f57f17
    style UT fill:#dcfce7,stroke:#16a34a

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

Implementação de uma estrutura de rastreamento de artefatos de processo com validação de cobertura.

📋 Pré-requisitos e Instalação

Este módulo utiliza exclusivamente recursos nativos do Python 3.11+ (dataclasses). Nenhuma instalação externa é necessária:

# Ambiente padrão Python 3.11+ (sem dependências externas)

💻 Código Completo e Autocontido (rastreabilidade_processo.py)

Crie o arquivo rastreabilidade_processo.py e insira o código abaixo:

"""
Módulo: rastreabilidade_processo.py
Domínio: Auditoria de rastreabilidade entre Requisitos, Código e Testes.
Stack: Python 3.11+
"""
from dataclasses import dataclass, field

@dataclass
class ItemRastreabilidade:
    id_requisito: str
    descricao_negocio: str
    endpoint_rest: str
    testes_associados: list[str] = field(default_factory=list)

    @property
    def coberto_por_testes(self) -> bool:
        return len(self.testes_associados) > 0

class AuditoriaProcesso:
    def __init__(self):
        self.itens: dict[str, ItemRastreabilidade] = {}

    def registrar_item(self, item: ItemRastreabilidade):
        self.itens[item.id_requisito] = item

    def relatorio_cobertura(self):
        total = len(self.itens)
        cobertos = sum(1 for item in self.itens.values() if item.coberto_por_testes)
        print("\n📊 RELATÓRIO DE RASTREABILIDADE DO PROCESSO:")
        print(f"Total de Requisitos Mapeados: {total}")
        print(f"Requisitos com Testes Automatizados: {cobertos}/{total} ({(cobertos/total)*100:.1f}%)")
        for item in self.itens.values():
            status = "✅ COBERTO" if item.coberto_por_testes else "❌ SEM TESTES"
            print(f" - [{item.id_requisito}] {item.descricao_negocio} -> {status}")

if __name__ == "__main__":
    auditoria = AuditoriaProcesso()
    auditoria.registrar_item(ItemRastreabilidade(
        id_requisito="RF-01",
        descricao_negocio="Registro de Entrada de Veículo",
        endpoint_rest="POST /api/checkin/",
        testes_associados=["test_checkin_sucesso", "test_checkin_vaga_ocupada"]
    ))
    auditoria.registrar_item(ItemRastreabilidade(
        id_requisito="RF-02",
        descricao_negocio="Emissão de Relatório Financeiro",
        endpoint_rest="GET /api/relatorios/faturamento",
        testes_associados=[]
    ))
    auditoria.relatorio_cobertura()

🚀 Como Executar

Execute o script no terminal:

python rastreabilidade_processo.py

🖥️ Saída Esperada no Terminal

📊 RELATÓRIO DE RASTREABILIDADE DO PROCESSO:
Total de Requisitos Mapeados: 2
Requisitos com Testes Automatizados: 1/2 (50.0%)
 - [RF-01] Registro de Entrada de Veículo -> ✅ COBERTO
 - [RF-02] Emissão de Relatório Financeiro -> ❌ SEM TESTES

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• 4 Atividades Canônicas: Especificação (O quê), Projeto & Código (Como), Validação (Testes) e Evolução (Melhoria Contínua).
• Rastreabilidade Bidirecional: Cada linha de código corporativo deve ser justificada por um requisito e validada por ao menos um teste automatizado.
• Verificação vs Validação: Construir o software sem bugs (Verificação) e garantir que ele resolve o problema certo (Validação).
• Evolução Contínua: Mais de 60% do custo total de um software ao longo do seu ciclo de vida é gasto na fase de evolução e manutenção.

⚡ CAPÍTULO 04: METODOLOGIAS ÁGEIS (SCRUM, KANBAN E XP)

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Compreender os 4 valores e os 12 princípios do Manifesto Ágil de 2001 e sua aplicação na engenharia moderna.
• 🔹 Dominar a tríade de papéis (Product Owner, Scrum Master, Developers), eventos e artefatos do framework Scrum.
• 🔹 Aplicar os princípios de fluxo puxado, visibilidade e limites de trabalho em progresso (WIP) do método Kanban.
• 🔹 Implementar práticas de engenharia de software do Extreme Programming (XP), incluindo Test-Driven Development (TDD) e Refatoração contínua.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, a diretoria precisa lançar o novo portal de Autoatendimento e Rastreamento de Encomendas em apenas 8 semanas para atender à demanda da Black Friday. O modelo tradicional em cascata levaria 6 meses apenas na fase de especificação.

O Desafio: Sua equipe foi organizada em um Squad Ágil Multidisciplinar. Você aplicará Scrum para a governança de entregas em Sprints quinzenais, Kanban para controlar o fluxo de tarefas no board e práticas de XP (TDD com Pytest) para garantir código sustentável e sem regressões.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. Os 4 Valores do Manifesto Ágil (2001)

Em 2001, 17 líderes de software reuniram-se em Utah e sintetizaram os pilares da agilidade:

flowchart TD
    subgraph MANIFESTO ["OS 4 VALORES DO MANIFESTO ÁGIL"]
        V1["👥 Indivíduos e interações<br>MAIS QUE processos e ferramentas"]
        V2["💻 Software em funcionamento<br>MAIS QUE documentação abrangente"]
        V3["🤝 Colaboração com o cliente<br>MAIS QUE negociação de contratos"]
        V4["🔄 Responder a mudanças<br>MAIS QUE seguir um plano rígido"]
    end
    
    style MANIFESTO fill:#f0fdf4,stroke:#16a34a
    style V1 fill:#dcfce7,stroke:#15803d
    style V2 fill:#dcfce7,stroke:#15803d
    style V3 fill:#dcfce7,stroke:#15803d
    style V4 fill:#dcfce7,stroke:#15803d

3.2. Ciclo de Vida do Scrum

O Scrum estrutura o desenvolvimento em iterações curtas chamadas Sprints (1 a 4 semanas), gerando um incremento de produto potencialmente publicável:

flowchart LR
    PB["📋 Product Backlog<br>(Priorizado pelo PO)"] --> SP["🎯 Sprint Planning<br>(Seleção do Time)"]
    SP --> SB["📝 Sprint Backlog"]
    SB --> SPRINT["🏃 Sprint (2 Semanas)<br>Daily Scrum (15 min)"]
    SPRINT --> INC["🚀 Incremento de Produto<br>(Definition of Done)"]
    INC --> REV["🔍 Sprint Review<br>(Feedback do Cliente)"]
    REV --> RET["💡 Retrospectiva<br>(Melhoria Contínua)"]
    RET --> SP
    
    style PB fill:#e0f2fe,stroke:#0284c7
    style SP fill:#ede7f6,stroke:#5e35b1
    style SPRINT fill:#fef3c7,stroke:#d97706
    style INC fill:#dcfce7,stroke:#16a34a
    style REV fill:#fce4ec,stroke:#c2185b
    style RET fill:#f3e5f5,stroke:#7b1fa2

3.3. Kanban e Limites de WIP (Work in Progress)

O Kanban foca em otimizar o fluxo de entrega visualizando o trabalho e limitando o número de tarefas simultâneas:

flowchart LR
    subgraph KANBAN ["QUADRO KANBAN COM LIMITES DE WIP"]
        direction LR
        B["Backlog<br>(Sem limite)"] --> A["A Fazer<br>(WIP: 5)"]
        A --> DEV["Em Dev<br>(WIP: 3)"]
        DEV --> TEST["Em Testes<br>(WIP: 2)"]
        TEST --> DONE["Concluído<br>(Done)"]
    end
    style KANBAN fill:#f8fafc,stroke:#64748b
    style DEV fill:#fee2e2,stroke:#ef4444
    style TEST fill:#fef3c7,stroke:#d97706
    style DONE fill:#dcfce7,stroke:#16a34a

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

Implementação do ciclo TDD (Test-Driven Development) do Extreme Programming (Red ➔ Green ➔ Refactor).

📋 Pré-requisitos e Instalação

No terminal do seu ambiente virtual, instale o executor de testes Pytest:

pip install pytest

💻 Código Completo e Autocontido (calculador_frete_tdd.py)

Crie o arquivo calculador_frete_tdd.py e insira o código abaixo integralmente:

"""
Módulo: calculador_frete_tdd.py
Prática XP: Desenvolvimento guiado por testes com Pytest.
Stack: Python 3.11+ | Pytest
"""
from decimal import Decimal
import pytest

# --- PASSO 1: RED -> GREEN (Implementação que atende a especificação) ---
def calcular_taxa_urgencia(peso_kg: Decimal, expressa: bool) -> Decimal:
    """Calcula taxa adicional para fretes prioritários."""
    if peso_kg <= Decimal("0.0"):
        raise ValueError("O peso deve ser maior que zero.")

    taxa_base = peso_kg * Decimal("5.00")
    if expressa:
        return taxa_base * Decimal("1.50")
    return taxa_base

# --- SUÍTE DE TESTES UNITÁRIOS COM PYTEST ---
def test_frete_convencional():
    resultado = calcular_taxa_urgencia(peso_kg=Decimal("2.0"), expressa=False)
    assert resultado == Decimal("10.00")

def test_frete_expresso_com_adicional():
    resultado = calcular_taxa_urgencia(peso_kg=Decimal("2.0"), expressa=True)
    assert resultado == Decimal("15.00")

def test_peso_invalido_deve_lancar_excecao():
    with pytest.raises(ValueError, match="maior que zero"):
        calcular_taxa_urgencia(peso_kg=Decimal("-1.0"), expressa=True)

if __name__ == "__main__":
    print("🚀 Executando lógica de frete demonstrativa:")
    val = calcular_taxa_urgencia(Decimal("4.0"), True)
    print(f"Taxa calculada: R$ {val:.2f}")

    print("\n🧪 Disparando suíte automatizada do Pytest:")
    pytest.main(["-v", __file__])

🚀 Como Executar

Você pode executar diretamente com o interpretador Python ou através do runner do Pytest:

# Execução direta com Python (dispara a lógica e a suíte interna)
python calculador_frete_tdd.py

# Ou execução formal pelo CLI do Pytest
pytest -v calculador_frete_tdd.py

🖥️ Saída Esperada no Terminal

🚀 Executando lógica de frete demonstrativa:
Taxa calculada: R$ 30.00

🧪 Disparando suíte automatizada do Pytest:
============================= test session starts =============================
calculador_frete_tdd.py::test_frete_convencional PASSED                  [ 33%]
calculador_frete_tdd.py::test_frete_expresso_com_adicional PASSED        [ 66%]
calculador_frete_tdd.py::test_peso_invalido_deve_lancar_excecao PASSED   [100%]
============================== 3 passed in 0.05s ==============================

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• Manifesto Ágil: Valoriza pessoas, software funcional, colaboração e resposta a mudanças acima de planos inflexíveis.
• Scrum: Framework iterativo-incremental baseado em papéis (PO, SM, Devs), eventos (Planning, Daily, Review, Retrospective) e artefatos.
• Kanban: Gestão visual do fluxo de trabalho com limites explícitos de WIP para evitar sobrecarga e eliminar gargalos.
• XP & TDD: Excelência técnica com testes automatizados escritos antes do código de produção (Red-Green-Refactor).

📋 CAPÍTULO 05: FUNDAMENTOS DE REQUISITOS

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Diferenciar rigorosamente Requisitos Funcionais (RF), Requisitos Não-Funcionais (RNF) e Regras de Negócio (RN).
• 🔹 Classificar RNFs segundo o modelo de qualidade FURPS+ (Functionality, Usability, Reliability, Performance, Supportability).
• 🔹 Formular requisitos mensuráveis, claros e sem ambiguidades ("a tela deve ser rápida" ➔ "latência p95 < 200ms").
• 🔹 Implementar contratos de dados e validações semânticas em Python 3.11+ utilizando Pydantic v2.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, o departamento jurídico e o time de infraestrutura emitiram diretrizes mandatórias: o novo portal corporativo deve atender à LGPD (anonimização de dados de motoristas) e garantir tempo de resposta inferior a 500ms durante o pico de tráfego de 10.000 requisições/minuto.

O Desafio: Como Analista de Requisitos e Arquiteto de Software, você deve traduzir as dores dos usuários e as imposições legais em especificações técnicas precisas, separando o que é comportamento funcional (RF) do que é atributo arquitetural de qualidade (RNF).

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. A Tríade dos Requisitos de Software

Um requisito é uma condição ou capacidade necessária que o software deve possuir para resolver um problema real:

flowchart TD
    subgraph TRIADE ["A TRÍADE DE ESPECIFICAÇÃO DE SOFTWARE"]
        RF["⚡ REQUISITOS FUNCIONAIS (RF)<br>O QUE o sistema faz<br>Ex: Cadastrar motorista, Emitir cupom"]
        RNF["🛡️ REQUISITOS NÃO-FUNCIONAIS (RNF)<br>COMO o sistema opera (Qualidade)<br>Ex: Tempo de resposta < 200ms, Criptografia AES-256"]
        RN["⚖️ REGRAS DE NEGÓCIO (RN)<br>DIRETRIZES corporativas e leis<br>Ex: Desconto de 10% para compras acima de R$ 500,00"]
    end
    
    style RF fill:#e0f2fe,stroke:#0284c7
    style RNF fill:#ede7f6,stroke:#5e35b1
    style RN fill:#fef3c7,stroke:#d97706

3.2. Classificação de RNFs pelo Modelo FURPS+

O modelo FURPS+ (Hewlett-Packard / Rational) categoriza os requisitos de qualidade em 5 dimensões essenciais:

flowchart TD
    root["🛡️ Modelo FURPS+ (Dimensões de Qualidade)"]
    
    root --> F["1. Functionality (Funcionalidade)<br>• Capacidades e Segurança<br>• Conformidade de Negócio"]
    root --> U["2. Usability (Usabilidade)<br>• Fatores Humanos e UX<br>• Consistência de Interface"]
    root --> R["3. Reliability (Confiabilidade)<br>• MTBF e Tolerância a Falhas<br>• Recuperabilidade"]
    root --> P["4. Performance (Desempenho)<br>• Throughput e Tempo de Resposta<br>• Consumo de Memória"]
    root --> S["5. Supportability (Suportabilidade)<br>• Manutenibilidade e Testabilidade<br>• Portabilidade e Configuração"]
    
    style root fill:#eff6ff,stroke:#2563eb,stroke-width:2px
    style F fill:#f0fdf4,stroke:#16a34a
    style U fill:#fffbeb,stroke:#d97706
    style R fill:#fee2e2,stroke:#ef4444
    style P fill:#ede7f6,stroke:#7c3aed
    style S fill:#e0f2fe,stroke:#0284c7

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

Implementação de validação de requisitos funcionais e regras de negócio com Pydantic v2:

📋 Pré-requisitos e Instalação

O esquema utiliza o validador EmailStr do Pydantic, que requer a biblioteca email-validator:

pip install "pydantic[email]"

💻 Código Completo e Autocontido (requisitos_contrato.py)

Crie o arquivo requisitos_contrato.py e insira o código abaixo integralmente:

"""
Módulo: requisitos_contrato.py
Domínio: Validação estrita de contratos de dados (Pydantic v2).
Stack: Python 3.11+ | Pydantic v2
"""
from decimal import Decimal
from pydantic import BaseModel, Field, EmailStr, field_validator

class RequisitoMotoristaSchema(BaseModel):
    # RF: Cadastro de motorista parceiro
    nome_completo: str = Field(..., min_length=3, max_length=100, description="Nome do motorista")
    cpf: str = Field(..., pattern=r"^\d{3}\.\d{3}\.\d{3}-\d{2}$", description="CPF formatado")
    email: EmailStr
    cnh_categoria: str = Field(..., description="Categoria da CNH (B, C, D, E)")
    score_avaliacao: Decimal = Field(default=Decimal("5.0"), ge=0, le=5)

    # RN: Regra de Negócio - Motoristas de carga pesada exigem CNH C, D ou E
    @field_validator("cnh_categoria")
    @classmethod
    def validar_cnh_valida(cls, v: str) -> str:
        categorias_permitidas = {"B", "C", "D", "E"}
        v_upper = v.upper()
        if v_upper not in categorias_permitidas:
            raise ValueError(f"Categoria CNH inválida. Permitidas: {categorias_permitidas}")
        return v_upper

if __name__ == "__main__":
    try:
        motorista_valido = RequisitoMotoristaSchema(
            nome_completo="Carlos Eduardo Silva",
            cpf="123.456.789-00",
            email="carlos.motorista@email.com",
            cnh_categoria="D"
        )
        print("✅ Requisito Funcional atendido com dados válidos:")
        print(motorista_valido.model_dump_json(indent=2))
    except Exception as err:
        print(f"❌ Violação de Requisito: {err}")

🚀 Como Executar

Execute o script no terminal:

python requisitos_contrato.py

🖥️ Saída Esperada no Terminal

✅ Requisito Funcional atendido com dados válidos:
{
  "nome_completo": "Carlos Eduardo Silva",
  "cpf": "123.456.789-00",
  "email": "carlos.motorista@email.com",
  "cnh_categoria": "D",
  "score_avaliacao": "5.0"
}

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• RF vs RNF vs RN: RF define o comportamento funcional (O quê); RNF define os critérios de qualidade (Como); RN define as políticas do negócio.
• FURPS+: Framework consolidado de engenharia para elicitação abrangente de requisitos de qualidade.
• Mensurabilidade: Requisitos não-funcionais devem conter métricas quantificáveis para permitir testes de aceitação automatizados.
• Validação por Contrato: Modelos Pydantic v2 garantem que as regras de integridade dos requisitos sejam respeitadas em tempo de execução.

🔍 CAPÍTULO 06: ELICITAÇÃO E LEVANTAMENTO DE REQUISITOS

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Compreender as principais técnicas de elicitação: Entrevistas estruturadas/semiestruturadas, Workshops (JAD), Questionários, Etnografia (Observação) e Prototipagem.
• 🔹 Identificar e gerenciar conflitos de interesses entre diferentes perfis de stakeholders corporativos.
• 🔹 Construir Personas e Mapas de Empatia para desvendar dores reais e comportamentos dos usuários finais.
• 🔹 Implementar scripts em Python 3.11+ para processamento e estruturação de dados colhidos em questionários de elicitação.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, a diretoria de operações quer automatizar o processo de triagem de pacotes nos centros de distribuição. No entanto, os operadores de galpão usam luvas grossas e trabalham em ritmo acelerado, enquanto os gerentes de logística querem relatórios complexos com dezenas de campos para preenchimento.

O Desafio: Se o analista de requisitos apenas entrevistar a diretoria em uma sala com ar-condicionado, o aplicativo será um fracasso no chão de fábrica. Você deve aplicar técnicas de observação direta (etnografia) e prototipação rápida para elicitar as restrições ergonômicas e funcionais reais.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. O Processo de Elicitação de Requisitos

Elicitar não é apenas "coletar" (como se os requisitos estivessem prontos em uma gaveta), mas sim descobrir, articular e negociar as necessidades com os stakeholders:

flowchart LR
    D["🔍 Descoberta<br>(Entrevistas & Etnografia)"] --> C["📊 Classificação & Organização<br>(Agrupamento por Domínio)"]
    C --> N["🤝 Negociação & Priorização<br>(MoSCoW & Trade-offs)"]
    N --> DOC["📝 Especificação Preliminar<br>(User Stories / Casos de Uso)"]
    DOC -.-> D
    
    style D fill:#e0f2fe,stroke:#0284c7
    style C fill:#ede7f6,stroke:#5e35b1
    style N fill:#fef3c7,stroke:#d97706
    style DOC fill:#dcfce7,stroke:#16a34a

3.2. Comparativo de Técnicas de Elicitação

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

Script para estruturação de dados de entrevistas de elicitação e extração de requisitos preliminares.

📋 Pré-requisitos e Instalação

Este módulo utiliza exclusivamente recursos nativos do Python 3.11+ (dataclasses). Nenhuma instalação externa é necessária:

# Ambiente padrão Python 3.11+ (sem dependências externas)

💻 Código Completo e Autocontido (analise_elicitacao.py)

Crie o arquivo analise_elicitacao.py e insira o código abaixo:

"""
Módulo: analise_elicitacao.py
Domínio: Consolidação de respostas de stakeholders e mapeamento de dores.
Stack: Python 3.11+
"""
from dataclasses import dataclass

@dataclass
class RespostaEntrevista:
    stakeholder_id: str
    papel: str  # Operador, Gerente, Cliente
    dor_relatada: str
    funcionalidade_desejada: str
    impacto_estimado: int  # 1 a 5 (5 = Crítico)

def processar_requisitos_prioritarios(respostas: list[RespostaEntrevista], corte_impacto: int = 4) -> list[str]:
    """Filtra e consolida as funcionalidades com maior impacto para compor o MVP."""
    prioritarias = [
        f"[{r.papel.upper()}] {r.funcionalidade_desejada} (Motivação: {r.dor_relatada})"
        for r in respostas if r.impacto_estimado >= corte_impacto
    ]
    return prioritarias

if __name__ == "__main__":
    dados_campo = [
        RespostaEntrevista("STK-01", "Operador", "Leitor de código de barras falha com pouca luz", "Modo lanterna automática no app", 5),
        RespostaEntrevista("STK-02", "Gerente", "Falta de visão dos pacotes atrasados no dia", "Dashboard de alertas em tempo real", 5),
        RespostaEntrevista("STK-03", "Cliente", "Desejo escolher a cor do tema da tela de rastreio", "Tema escuro personalizado", 2)
    ]

    mvp_items = processar_requisitos_prioritarios(dados_campo)
    print("📋 ITENS ELICITADOS PRIORITÁRIOS PARA O BACKLOG:")
    for item in mvp_items:
        print(f" ✔️ {item}")

🚀 Como Executar

Execute o script no terminal:

python analise_elicitacao.py

🖥️ Saída Esperada no Terminal

📋 ITENS ELICITADOS PRIORITÁRIOS PARA O BACKLOG:
 ✔️ [OPERADOR] Modo lanterna automática no app (Motivação: Leitor de código de barras falha com pouca luz)
 ✔️ [GERENTE] Dashboard de alertas em tempo real (Motivação: Falta de visão dos pacotes atrasados no dia)

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• Elicitação é Investigação: Requisitos são descobertos através da combinação de entrevistas, observação e prototipação.
• Diversidade de Fontes: Ouvir apenas a liderança gera sistemas que a operação rejeita; ouvir apenas a operação gera sistemas fora da estratégia da empresa.
• Etnografia e Contexto: O chão de fábrica e o campo impõem restrições que nenhuma reunião de escritório revela.
• Personas: Ferramenta poderosa para manter o time focado no valor real do usuário durante todo o ciclo de vida do software.

📝 CAPÍTULO 07: ESPECIFICAÇÃO DE REQUISITOS (ERS E USER STORIES)

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Compreender a estrutura de uma Especificação de Requisitos de Software (ERS / SRS) segundo as normas IEEE 830 e ISO/IEC/IEEE 29148.
• 🔹 Formular Histórias de Usuário (User Stories) segundo o acrônimo INVEST (Independent, Negotiable, Valuable, Estimable, Small, Testable).
• 🔹 Escrever Critérios de Aceite estruturados utilizando a sintaxe Gherkin / BDD (Dado / Quando / Então).
• 🔹 Implementar testes automatizados em Python 3.11+ com pytest que validam diretamente os cenários descritos em Gherkin.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, um cliente corporativo de grande porte assinou um contrato para integração de API de cálculo de fretes em tempo real. No entanto, o desenvolvedor backend implementou a resposta retornando prazos em dias úteis, enquanto o cliente esperava dias corridos.

O Desafio: A ausência de critérios de aceite inequívocos na ERS gerou 3 semanas de retrabalho e desgaste comercial. Como Engenheiro de Software, você deve formalizar a especificação através de User Stories claras e cenários executáveis em Gherkin que sirvam como contrato técnico e base de testes automatizados.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. ERS Tradicional (IEEE 830) vs. User Stories Ágeis (INVEST)

A documentação de requisitos evoluiu de especificações volumosas para artefatos enxutos e orientados a valor de negócio:

flowchart TD
    subgraph MODELOS_ESPECIFICACAO ["EVOLUÇÃO DA ESPECIFICAÇÃO"]
        direction LR
        ERS["📄 ERS Tradicional (IEEE 830)<br>• Seções exaustivas<br>• Contrato formal rígido<br>• Ideal para sistemas críticos"]
        US["📋 User Story Ágil (INVEST)<br>• Como [ator] Quero [meta] Para [benefício]<br>• Critérios de Aceite em Gherkin<br>• Conversação contínua"]
    end
    style ERS fill:#e1f5fe,stroke:#0284c7
    style US fill:#dcfce7,stroke:#16a34a

3.2. A Tríade da User Story: Os 3 Cs de Ron Jeffries

Uma História de Usuário completa é composta por três elementos:

1. Cartão (Card): A descrição sintética no formato "Como... Quero... Para que...".
2. Conversa (Conversation): A discussão entre o Product Owner e a equipe técnica para detalhar nuances.
3. Confirmação (Confirmation): Os Critérios de Aceite que determinam quando a história está concluída.

flowchart LR
    C1["📇 Cartão (Card)<br>Como [Ator] Quero [Ação] Para [Benefício]"] --> C2["🗣️ Conversa (Conversation)<br>Alinhamento técnico & regras"]
    C2 --> C3["✅ Confirmação (Confirmation)<br>Cenários BDD / Critérios de Aceite"]
    
    style C1 fill:#e0f2fe,stroke:#0284c7
    style C2 fill:#ede7f6,stroke:#5e35b1
    style C3 fill:#dcfce7,stroke:#16a34a

3.3. Sintaxe BDD / Gherkin (Dado - Quando - Então)

Cenário: Cálculo de frete expresso para capitais
  Dado que o cliente está autenticado na API
  E o endereço de destino pertence à capital "São Paulo"
  Quando o cliente solicita o frete de um pacote de 2.0 kg
  Então o sistema deve retornar o valor de R$ 15.00
  E o prazo de entrega deve ser de "1 dia útil"

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

Implementação do teste automatizado com Pytest traduzindo os cenários Gherkin (BDD).

📋 Pré-requisitos e Instalação

No terminal do seu ambiente virtual, instale o executor de testes Pytest:

pip install pytest

💻 Código Completo e Autocontido (test_calculo_frete_bdd.py)

Crie o arquivo test_calculo_frete_bdd.py e insira o código abaixo integralmente:

"""
Módulo: test_calculo_frete_bdd.py
Domínio: Testes de aceitação automatizados espelhando cenários BDD.
Stack: Python 3.11+ | Pytest
"""
from decimal import Decimal
import pytest

# Implementação do serviço de frete
def calcular_frete_entrega(peso_kg: Decimal, eh_capital: bool, expresso: bool) -> tuple[Decimal, int]:
    """Retorna (valor_reais, prazo_dias_uteis)."""
    if peso_kg <= Decimal("0.0"):
        raise ValueError("Peso inválido.")

    valor_base = Decimal("10.00") + (peso_kg * Decimal("2.50"))
    prazo = 3

    if eh_capital:
        prazo -= 1
    if expresso:
        valor_base *= Decimal("1.30")
        prazo = 1

    return (valor_base.quantize(Decimal("0.01")), prazo)

# --- CENÁRIOS BDD IMPLEMENTADOS COM PYTEST ---
def test_cenario_frete_expresso_capital():
    # Dado: Pacote de 2.0 kg para Capital em modo Expresso
    peso = Decimal("2.0")

    # Quando: Solicita o frete
    valor, prazo = calcular_frete_entrega(peso_kg=peso, eh_capital=True, expresso=True)

    # Então: Valida valor e prazo
    assert valor == Decimal("19.50")  # (10 + 5) * 1.30 = 19.50
    assert prazo == 1

def test_cenario_frete_convencional_interior():
    valor, prazo = calcular_frete_entrega(peso_kg=Decimal("1.0"), eh_capital=False, expresso=False)
    assert valor == Decimal("12.50")
    assert prazo == 3

if __name__ == "__main__":
    v, p = calcular_frete_entrega(Decimal("2.0"), True, True)
    print(f"✅ Cenário Validado: Frete R$ {v:.2f} em {p} dia(s) útil(eis)")

    print("\n🧪 Disparando suíte automatizada de cenários BDD com Pytest:")
    pytest.main(["-v", __file__])

🚀 Como Executar

Execute diretamente com Python ou pelo CLI do Pytest:

# Execução direta com Python (executa lógica e testes)
python test_calculo_frete_bdd.py

# Ou execução formal pelo Pytest
pytest -v test_calculo_frete_bdd.py

🖥️ Saída Esperada no Terminal

✅ Cenário Validado: Frete R$ 19.50 em 1 dia(s) útil(eis)

🧪 Disparando suíte automatizada de cenários BDD com Pytest:
============================= test session starts =============================
test_calculo_frete_bdd.py::test_cenario_frete_expresso_capital PASSED    [ 50%]
test_calculo_frete_bdd.py::test_cenario_frete_convencional_interior PASSED [100%]
============================== 2 passed in 0.04s ==============================

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• ERS vs User Story: A ERS tradicional documenta o contrato exaustivo (IEEE 830); as User Stories documentam a intenção de valor de forma incremental.
• INVEST: Guia de excelência para granularidade e qualidade de histórias de backlog.
• BDD & Gherkin: Linguagem comum entre desenvolvedores, testadores e analistas de negócio (Dado / Quando / Então).
• Especificação Executável: Testes com Pytest transformam critérios de aceite em garantias automáticas contra regressão.

🛡️ CAPÍTULO 08: VALIDAÇÃO E GESTÃO DE REQUISITOS

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Avaliar a qualidade de requisitos aplicando os 5 critérios de Sommerville (Validade, Consistência, Completeza, Realismo e Verificabilidade).
• 🔹 Compreender a economia do erro e a regra de custo exponencial de correção (Regra 1:10:100).
• 🔹 Construir e manter Matrizes de Rastreabilidade de Requisitos (RTM) para análise de impacto em mudanças.
• 🔹 Implementar um sistema de controle de solicitações de mudança (Change Requests) em Python 3.11+.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, a equipe de desenvolvimento identificou um grave conflito durante o sprint: o Requisito RF-02 (Cadastro) determinava que o CPF de clientes poderia ser editado a qualquer momento, enquanto o Requisito RF-45 (Segurança e Auditoria Fiscal) proibia qualquer alteração de chaves primárias de identificação fiscal.

O Desafio: Como Analista de Requisitos Sênior, você deve realizar a auditoria cruzada de requisitos, identificar ambiguidades e contradições antes que as tabelas de banco de dados e APIs sejam construídas, formalizando um comitê de controle de mudanças (Change Control Board - CCB).

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. Os 5 Pilares de Validação de Requisitos (Sommerville)

A validação assegura que a especificação reflete a intenção real do negócio sem contradições lógicas:

flowchart TD
    subgraph PILARES ["5 CRITÉRIOS DE VALIDAÇÃO DE REQUISITOS"]
        V["1. VALIDADE: O software resolve a necessidade real?"]
        C["2. CONSISTÊNCIA: Existem requisitos contraditórios?"]
        CP["3. COMPLETEZA: Todas as exceções e fluxos alternativos foram previstos?"]
        R["4. REALISMO: É viável implementar dentro do prazo e orçamento?"]
        VF["5. VERIFICABILIDADE: É possível escrever um teste automatizado para comprovar?"]
    end
    
    style PILARES fill:#f8fafc,stroke:#475569
    style V fill:#e0f2fe,stroke:#0284c7
    style C fill:#ede7f6,stroke:#5e35b1
    style CP fill:#dcfce7,stroke:#16a34a
    style R fill:#fef3c7,stroke:#d97706
    style VF fill:#fee2e2,stroke:#ef4444

3.2. Fluxo de Gestão de Mudanças (Change Management)

Requisitos de software mudam continuamente devido a novas leis, estratégias de mercado e tecnologias:

flowchart LR
    REQ["📢 Solicitação de Mudança<br>(Change Request)"] --> IMP["🔍 Análise de Impacto<br>(Custo, Prazo & RTM)"]
    IMP --> CCB["⚖️ Comitê CCB<br>(Aprovação/Rejeição)"]
    CCB -->|Aprovado| UPD["📝 Atualização de ERS<br>& Backlog Sprint"]
    CCB -->|Rejeitado| LOG["📁 Arquivamento Justificado"]
    
    style REQ fill:#e0f2fe,stroke:#0284c7
    style IMP fill:#ede7f6,stroke:#5e35b1
    style CCB fill:#fef3c7,stroke:#d97706
    style UPD fill:#dcfce7,stroke:#16a34a
    style LOG fill:#fee2e2,stroke:#ef4444

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

Implementação de um motor de gestão de mudanças e análise de impacto.

📋 Pré-requisitos e Instalação

Este módulo utiliza exclusivamente recursos nativos do Python 3.11+ (dataclasses e enum). Nenhuma instalação externa é necessária:

# Ambiente padrão Python 3.11+ (sem dependências externas)

💻 Código Completo e Autocontido (gestao_mudancas_ccb.py)

Crie o arquivo gestao_mudancas_ccb.py e insira o código abaixo integralmente:

"""
Módulo: gestao_mudancas_ccb.py
Domínio: Análise de impacto e aprovação de Change Requests (CR).
Stack: Python 3.11+
"""
from dataclasses import dataclass, field
from enum import Enum, auto

class StatusMudanca(Enum):
    SUBMETIDA = auto()
    EM_ANALISE_IMPACTO = auto()
    APROVADA_CCB = auto()
    REJEITADA = auto()

@dataclass
class SolicitacaoMudanca:
    id_cr: str
    descricao: str
    requisitos_impactados: list[str]
    horas_estimadas: int
    custo_adicional: float
    status: StatusMudanca = StatusMudanca.SUBMETIDA

class ComiteControleMudancas:
    def __init__(self, limite_orcamento_livre: float = 5000.00):
        self.limite_orcamento_livre = limite_orcamento_livre
        self.solicitacoes: dict[str, SolicitacaoMudanca] = {}

    def registrar_cr(self, cr: SolicitacaoMudanca):
        self.solicitacoes[cr.id_cr] = cr

    def deliberar(self, id_cr: str) -> str:
        cr = self.solicitacoes.get(id_cr)
        if not cr:
            raise KeyError("CR não encontrada.")

        if cr.custo_adicional <= self.limite_orcamento_livre and cr.horas_estimadas <= 40:
            cr.status = StatusMudanca.APROVADA_CCB
            return f"✅ [{cr.id_cr}] APROVADA: Impacto de {len(cr.requisitos_impactados)} requisito(s) dentro do limite."
        else:
            cr.status = StatusMudanca.EM_ANALISE_IMPACTO
            return f"⚠️ [{cr.id_cr}] RETIDA: Requer aprovação da Diretoria Executiva (Custo: R$ {cr.custo_adicional:.2f})."

if __name__ == "__main__":
    ccb = ComiteControleMudancas()
    cr1 = SolicitacaoMudanca("CR-001", "Adição de PIX no Checkout", ["RF-08", "RF-09"], 16, 2400.00)
    cr2 = SolicitacaoMudanca("CR-002", "Migração completa de banco legado", ["RF-01", "RF-02", "RNF-01"], 120, 18000.00)

    ccb.registrar_cr(cr1)
    ccb.registrar_cr(cr2)

    print(ccb.deliberar("CR-001"))
    print(ccb.deliberar("CR-002"))

🚀 Como Executar

Execute o script no terminal:

python gestao_mudancas_ccb.py

🖥️ Saída Esperada no Terminal

✅ [CR-001] APROVADA: Impacto de 2 requisito(s) dentro do limite.
⚠️ [CR-002] RETIDA: Requer aprovação da Diretoria Executiva (Custo: R$ 18000.00).

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• Validação Precoce: Validar requisitos no papel é a forma mais barata de garantir a qualidade e a sustentabilidade de um software.
• 5 Pilares de Qualidade: Validade, Consistência, Completeza, Realismo e Verificabilidade.
• Gestão de Mudanças (CCB): Mudanças são inevitáveis no ciclo de vida de TI, mas devem ser formalmente auditadas em custo e prazo.
• Matriz de Rastreabilidade: Permite avaliar em segundos quais módulos e testes serão impactados quando um requisito mudar.

📐 CAPÍTULO 09: FUNDAMENTOS DA MODELAGEM E UML

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Compreender o papel da UML (Unified Modeling Language - OMG) como linguagem visual padrão da indústria para especificação e design de sistemas.
• 🔹 Dominar o Modelo 4+1 Visões de Arquitetura de Philippe Kruchten (Lógica, Implementação, Processo, Implantação e Casos de Uso).
• 🔹 Classificar a taxonomia da UML 2.5 entre Diagramas Estruturais (estáticos) e Comportamentais (dinâmicos).
• 🔹 Construir diagramas arquiteturais profissionais utilizando a abordagem Diagrams as Code com Mermaid e Draw.io.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, a primeira versão do sistema de Gestão de Hubs Logísticos falhou antes do deploy em produção. Cada desenvolvedor implementou as entidades de banco com nomes diferentes (Cliente, Usuario, Destinatario), gerando incompatibilidade total entre os microsserviços.

O Desafio: Como Arquiteto de Software, você deve instituir a cultura de Modeling First (Diagrams as Code). Nenhuma linha de código ou tabela relacional deve ser criada sem que a planta baixa arquitetural e as interfaces de classes tenham sido previamente modeladas e validadas pela equipe.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. O Modelo 4+1 Visões de Philippe Kruchten

Para atender às necessidades de diferentes públicos (desenvolvedores, clientes, operadores e analistas), a arquitetura é organizada em 5 visões integradas:

flowchart TD
    subgraph KRUCHTEN ["MODELO 4+1 VISÕES DE ARQUITETURA (KRUCHTEN)"]
        UC["🎯 5. VISÃO DE CASOS DE USO<br>(Usuários Finais & Requisitos de Negócio)"]
        
        V1["🧠 1. Visão Lógica<br>(Classes, Pacotes & DER)<br>Público: Desenvolvedores"]
        V2["⚡ 2. Visão de Processos<br>(Threads, Concorrência & SLA)<br>Público: Integradores"]
        V3["📦 3. Visão de Implementação<br>(Módulos, Bibliotecas & Git)<br>Público: Programadores"]
        V4["🌐 4. Visão de Implantação<br>(Servidores, Docker, Nuvem & Redes)<br>Público: DevOps & SRE"]
        
        UC --> V1
        UC --> V2
        UC --> V3
        UC --> V4
    end
    
    style KRUCHTEN fill:#f8fafc,stroke:#475569
    style UC fill:#fef3c7,stroke:#d97706
    style V1 fill:#e0f2fe,stroke:#0284c7
    style V2 fill:#ede7f6,stroke:#5e35b1
    style V3 fill:#dcfce7,stroke:#16a34a
    style V4 fill:#fee2e2,stroke:#ef4444

3.2. Taxonomia dos Diagramas da UML 2.5

A UML 2.5 padroniza 14 diagramas divididos em duas grandes famílias:

flowchart TD
    subgraph UML ["TAXONOMIA DA UML 2.5"]
        ESTRUTURA["🧱 DIAGRAMAS ESTRUTURAIS (ESTÁTICOS)<br>• Diagrama de Classes<br>• Diagrama de Componentes<br>• Diagrama de Implantação<br>• Diagrama de Pacotes<br>• Diagrama de Objetos"]
        COMPORTAMENTO["⚡ DIAGRAMAS COMPORTAMENTAIS (DINÂMICOS)<br>• Diagrama de Casos de Uso<br>• Diagrama de Sequência<br>• Diagrama de Atividades<br>• Diagrama de Transição de Estados<br>• Diagrama de Comunicação"]
    end
    
    style ESTRUTURA fill:#e0f2fe,stroke:#0284c7
    style COMPORTAMENTO fill:#dcfce7,stroke:#16a34a

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

Implementação da planta de classes modelada em código Python com tipagem, relacionamentos estruturados e exportação Diagrams as Code (Mermaid).

📋 Pré-requisitos e Instalação

Este módulo utiliza exclusivamente recursos nativos do Python 3.11+ (dataclasses e decimal). Nenhuma instalação externa é necessária:

# Ambiente padrão Python 3.11+ (sem dependências externas)

💻 Código Completo e Autocontido (modelo_logistica_classes.py)

Crie o arquivo modelo_logistica_classes.py e insira o código abaixo integralmente:

"""
Módulo: modelo_logistica_classes.py
Domínio: Transposição de diagrama de classes UML (Kruchten 4+1) e exportação Diagrams as Code.
Stack: Python 3.11+
"""
from dataclasses import dataclass, field
from decimal import Decimal

@dataclass
class PontoParada:
    id_ponto: int
    endereco: str
    concluido: bool = False

@dataclass
class RotaEntrega:
    id_rota: str
    motorista_responsavel: str
    pontos: list[PontoParada] = field(default_factory=list)
    quilometragem_total: Decimal = Decimal("0.0")

    def adicionar_parada(self, parada: PontoParada) -> None:
        self.pontos.append(parada)

    def calcular_progresso(self) -> float:
        if not self.pontos:
            return 0.0
        concluidos = sum(1 for p in self.pontos if p.concluido)
        return (concluidos / len(self.pontos)) * 100.0

    def gerar_mermaid_class_diagram(self) -> str:
        """Exporta a estrutura da planta lógica em notação Diagrams as Code (Mermaid)."""
        return (
            "classDiagram\n"
            "    class RotaEntrega {\n"
            "        +String id_rota\n"
            "        +String motorista_responsavel\n"
            "        +Decimal quilometragem_total\n"
            "        +adicionar_parada(PontoParada)\n"
            "        +calcular_progresso() float\n"
            "    }\n"
            "    class PontoParada {\n"
            "        +Int id_ponto\n"
            "        +String endereco\n"
            "        +Boolean concluido\n"
            "    }\n"
            '    RotaEntrega "1" *-- "many" PontoParada : contem'
        )

if __name__ == "__main__":
    rota = RotaEntrega("ROTA-2026-SP", "Marcos Antunes", quilometragem_total=Decimal("45.8"))
    rota.adicionar_parada(PontoParada(1, "Av. Paulista, 1000", concluido=True))
    rota.adicionar_parada(PontoParada(2, "Rua Augusta, 500", concluido=False))

    print(f"📦 Rota: {rota.id_rota} | Motorista: {rota.motorista_responsavel}")
    print(f"📊 Progresso da Rota: {rota.calcular_progresso():.1f}%")
    print("\n📐 DIAGRAMA MERMAID GERADO (DIAGRAMS AS CODE):")
    print(rota.gerar_mermaid_class_diagram())

🚀 Como Executar

Execute o script no terminal:

python modelo_logistica_classes.py

🖥️ Saída Esperada no Terminal

📦 Rota: ROTA-2026-SP | Motorista: Marcos Antunes
📊 Progresso da Rota: 50.0%

📐 DIAGRAMA MERMAID GERADO (DIAGRAMS AS CODE):
classDiagram
    class RotaEntrega {
        +String id_rota
        +String motorista_responsavel
        +Decimal quilometragem_total
        +adicionar_parada(PontoParada)
        +calcular_progresso() float
    }
    class PontoParada {
        +Int id_ponto
        +String endereco
        +Boolean concluido
    }
    RotaEntrega "1" *-- "many" PontoParada : contem

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• UML é o Padrão da Indústria: Permite comunicação visual inequívoca entre analistas, arquitetos e desenvolvedores.
• Modelo 4+1: Estrutura o sistema nas visões Lógica, Processo, Implementação e Implantação em torno dos Casos de Uso.
• Estático vs Dinâmico: Diagramas Estruturais mostram o que o sistema é; Diagramas Comportamentais mostram o que o sistema faz ao longo do tempo.
• Diagrams as Code: Garante que a arquitetura visual seja versionada no Git lado a lado com o código-fonte.

🎭 CAPÍTULO 10: DIAGRAMA DE CASOS DE USO (CONCEITOS)

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Compreender a finalidade do Diagrama de Casos de Uso na captura de requisitos funcionais sob a perspectiva do usuário (Ivar Jacobson / UML).
• 🔹 Identificar Atores Primários, Atores Secundários (Sistemas Externos/APIs) e o Limite do Sistema (System Boundary).
• 🔹 Modelar diagramas de casos de uso profissionais com sintaxe declarativa Mermaid e Draw.io.
• 🔹 Evitar o anti-pattern de desenhar sequências temporais e fluxogramas dentro do diagrama de casos de uso.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, a diretoria executiva solicitou uma visão consolidada de todas as operações do novo Módulo de Gestão de Fretes e Frotas. Eles não desejam ver tabelas de banco de dados ou detalhes de infraestrutura, mas precisam entender com clareza quais ações podem ser executadas pelo Motorista, pelo Operador de Logística e pelo Gateway Bancário.

O Desafio: Seu objetivo como Analista de Sistemas é construir a "foto panorâmica" de escopo funcional do sistema através do Diagrama de Casos de Uso, estabelecendo com precisão o que está dentro do escopo do software (System Boundary) e quais entidades externas interagem com ele.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. A Tríade do Diagrama de Casos de Uso

O diagrama organiza-se em torno de 3 elementos gráficos padronizados pela UML:

1. Atores (Actors): Entidades externas que interagem com o sistema (usuários, sensores ou sistemas legados).
2. Casos de Uso (Use Cases - Elipses): Conjuntos de ações realizadas pelo sistema que geram um resultado de valor observável para o ator.
3. Limite do Sistema (Subject Boundary - Retângulo): Delimita o que pertence ao software que será construído versus o que é externo.

flowchart LR
    subgraph SIS ["🏢 SISTEMA TECPROEXPRESS (SYSTEM BOUNDARY)"]
        direction TB
        UC1(["📦 Registrar Pacote"])
        UC2(["🗺️ Rastrear Entrega"])
        UC3(["💳 Processar Pagamento"])
    end
    
    A1["👤 Operador Logístico"] --> UC1
    A2["👤 Cliente Final"] --> UC2
    UC3 --> S1["🏛️ Gateway de Pagamento (API)"]
    
    style SIS fill:#f8fafc,stroke:#475569
    style UC1 fill:#e0f2fe,stroke:#0284c7
    style UC2 fill:#e0f2fe,stroke:#0284c7
    style UC3 fill:#e0f2fe,stroke:#0284c7
    style A1 fill:#dcfce7,stroke:#16a34a
    style A2 fill:#dcfce7,stroke:#16a34a
    style S1 fill:#ede7f6,stroke:#5e35b1

3.2. Atores Primários vs. Atores Secundários

• Ator Primário: Inicia a interação com o sistema para atingir uma meta pessoal de negócio (ex: o Cliente buscando rastrear seu pacote).
• Ator Secundário (Ator de Suporte): É acionado pelo sistema para fornecer serviços auxiliares (ex: a API de Envio de SMS ou o Serviço de Cobrança Bancária).

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

Mapeamento de casos de uso para controladores REST com Flask 3.x em Python 3.11+.

📋 Pré-requisitos e Instalação

No terminal do seu ambiente virtual, instale o microframework Flask:

pip install flask

💻 Código Completo e Autocontido (rotas_casos_uso.py)

Crie o arquivo rotas_casos_uso.py e insira o código abaixo integralmente:

"""
Módulo: rotas_casos_uso.py
Domínio: Transposição de casos de uso UML para endpoints REST com Flask 3.x.
Stack: Python 3.11+ | Flask 3.x
"""
from flask import Flask, request, jsonify

app = Flask(__name__)

# Base de dados em memória para simulação operacional
PACOTES_DB = {
    "BR123456": {"codigo": "BR123456", "status": "EM TRANSITO", "localizacao": "Hub São Paulo"}
}

# Caso de Uso 1: Registrar Pacote (Ator: Operador Logístico)
@app.post("/api/pacotes/")
def uc_registrar_pacote():
    """UC01: Permite ao Operador Logístico cadastrar um novo pacote no sistema."""
    dados = request.get_json()
    if not dados or "codigo" not in dados or "peso_kg" not in dados:
        return jsonify({"status": "ERRO", "mensagem": "Campos 'codigo' e 'peso_kg' são obrigatórios."}), 400

    PACOTES_DB[dados["codigo"]] = {
        "codigo": dados["codigo"],
        "peso_kg": dados["peso_kg"],
        "destino": dados.get("destino", "NÃO INFORMADO"),
        "status": "REGISTRADO"
    }
    return jsonify({"status": "SUCESSO", "mensagem": f"Pacote {dados['codigo']} registrado com sucesso."}), 201

# Caso de Uso 2: Rastrear Entrega (Ator: Cliente Final)
@app.get("/api/pacotes/<codigo>/rastreio")
def uc_rastrear_entrega(codigo: str):
    """UC02: Permite ao Cliente Final consultar o status em tempo real do pacote."""
    pacote = PACOTES_DB.get(codigo)
    if not pacote:
        return jsonify({"status": "ERRO", "detalhe": f"Pacote '{codigo}' não localizado."}), 404
    return jsonify(pacote), 200

# Ponto de Entrada Executável
if __name__ == "__main__":
    print("🚀 TESTE DE CONTROLADORES REST FLASK (CASOS DE USO UML)")
    print("=" * 65)

    # Execução de testes de integração automáticos via Flask Test Client nativo
    client = app.test_client()

    # 1. Simulação do Caso de Uso 1 (Operador cadastra pacote)
    print("1. [UC01 - Operador] Registrando pacote:")
    resp_post = client.post("/api/pacotes/", json={"codigo": "BR999888", "peso_kg": 3.5, "destino": "Curitiba/PR"})
    print(f"   Status HTTP: {resp_post.status_code}")
    print(f"   Resposta: {resp_post.get_json()}\n")

    # 2. Simulação do Caso de Uso 2 (Cliente rastreia pacote)
    print("2. [UC02 - Cliente] Rastreando entrega cadastrada:")
    resp_get = client.get("/api/pacotes/BR123456/rastreio")
    print(f"   Status HTTP: {resp_get.status_code}")
    print(f"   Resposta: {resp_get.get_json()}\n")

    # 3. Cenário de Falha (Pacote não encontrado)
    print("3. [UC02 - Exceção] Consultando código inexistente:")
    resp_404 = client.get("/api/pacotes/XX000000/rastreio")
    print(f"   Status HTTP: {resp_404.status_code}")
    print(f"   Resposta: {resp_404.get_json()}")
    print("=" * 65)
    print("💡 Dica: Para iniciar o servidor HTTP interativo na porta 5000, descomente: # app.run(port=5000, debug=True)")
    # app.run(port=5000, debug=True)

🚀 Como Executar

Execute o script no terminal:

python rotas_casos_uso.py

🖥️ Saída Esperada no Terminal

🚀 TESTE DE CONTROLADORES REST FLASK (CASOS DE USO UML)
=================================================================
1. [UC01 - Operador] Registrando pacote:
   Status HTTP: 201
   Resposta: {'mensagem': 'Pacote BR999888 registrado com sucesso.', 'status': 'SUCESSO'}

2. [UC02 - Cliente] Rastreando entrega cadastrada:
   Status HTTP: 200
   Resposta: {'codigo': 'BR123456', 'localizacao': 'Hub São Paulo', 'status': 'EM TRANSITO'}

3. [UC02 - Exceção] Consultando código inexistente:
   Status HTTP: 404
   Resposta: {'detalhe': "Pacote 'XX000000' não localizado.", 'status': 'ERRO'}
=================================================================
💡 Dica: Para iniciar o servidor HTTP interativo na porta 5000, descomente: # app.run(port=5000, debug=True)

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• Visão de Escopo: O Diagrama de Casos de Uso apresenta as capacidades do sistema sob a ótica do usuário e de sistemas externos.
• Atores: Papéis que interagem com o sistema (não confunda com pessoas individuais).
• Fronteira do Sistema: Delimita a responsabilidade da equipe técnica de desenvolvimento.
• Nomenclatura Semântica: Sempre use [Verbo no Infinitivo] + [Objeto] expressando uma meta real de negócio.

🎭 CAPÍTULO 11: CASOS DE USO (PRÁTICA E RELAÇÕES)

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Distinguir e aplicar com precisão os três relacionamentos da UML entre casos de uso: «include» (inclusão obrigatória), «extend» (extensão condicional) e Generalização/Especialização.
• 🔹 Estruturar especificações textuais completas de casos de uso contendo Fluxo Principal (Caminho Feliz), Fluxos Alternativos e Fluxos de Exceção.
• 🔹 Modelar diagramas com pontos de extensão (Extension Points) claros no Mermaid e Draw.io.
• 🔹 Implementar o padrão de handlers condicionais e exceções em Python 3.11+ refletindo os fluxos modelados.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, a equipe de desenvolvimento modelou um caso de uso para "Emitir Frete". No entanto, quando o cliente solicita entrega expressa aos domingos, uma taxa especial de seguro adicional precisa ser contratada condicionalmente. Além disso, toda emissão de frete exige obrigatoriamente a validação do token JWT de autenticação.

O Desafio: Você deve modelar corretamente esses comportamentos utilizando as relações «include» para a autenticação obrigatória e «extend» com ponto de extensão condicional para o seguro especial de domingo, evitando duplicação de lógica e garantindo clareza técnica.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. As Relações entre Casos de Uso na UML

flowchart TD
    subgraph RELACOES_UC ["RELAÇÕES NA UML ENTRE CASOS DE USO"]
        direction TB
        UC_BASE(["📦 Emitir Frete (Base)"])
        
        UC_INC(["🔐 Validar Token JWT<br>(Obrigatório)"])
        UC_EXT(["🛡️ Contratar Seguro Especial<br>(Opcional / Condicional)"])
        
        UC_BASE -.->|"«include»"| UC_INC
        UC_EXT -.->|"«extend» [Se for Domingo]"| UC_BASE
    end
    
    style UC_BASE fill:#e0f2fe,stroke:#0284c7
    style UC_INC fill:#ede7f6,stroke:#5e35b1
    style UC_EXT fill:#fef3c7,stroke:#d97706

3.2. Comparativo: «include» vs. «extend» vs. Generalização

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

Implementação dos fluxos principal, de extensão («extend») e de inclusão obrigatória («include») em Python 3.11+.

📋 Pré-requisitos e Instalação

Este módulo utiliza exclusivamente recursos nativos do Python 3.11+ (dataclasses e decimal). Nenhuma instalação externa é necessária:

# Ambiente padrão Python 3.11+ (sem dependências externas)

💻 Código Completo e Autocontido (emissoes_frete_regras.py)

Crie o arquivo emissoes_frete_regras.py e insira o código abaixo integralmente:

"""
Módulo: emissoes_frete_regras.py
Domínio: Aplicação das relações de caso de uso (Include, Extend e Exceções).
Stack: Python 3.11+
"""
from dataclasses import dataclass
from decimal import Decimal

class TokenInvalidoException(Exception):
    pass

@dataclass
class SolicitacaoFrete:
    token_jwt: str
    peso_kg: Decimal
    entrega_domingo: bool

# Caso de Uso Incluído («include» obrigatório)
def validar_token_jwt(token: str):
    if not token or token != "TOKEN_SEGURO_2026":
        raise TokenInvalidoException("❌ Acesso negado: Token JWT ausente ou inválido.")

# Caso de Uso Extensor («extend» condicional)
def aplicar_seguro_domingo(valor_base: Decimal) -> Decimal:
    print(" 🛡️ [«extend»] Ponto de Extensão Ativado: Adicionando Seguro Especial de Domingo (+15%)")
    return valor_base * Decimal("1.15")

# Caso de Uso Base
def emitir_frete(solicitacao: SolicitacaoFrete) -> Decimal:
    # 1. Executa o «include» obrigatório
    validar_token_jwt(solicitacao.token_jwt)

    # 2. Fluxo Principal
    valor_base = solicitacao.peso_kg * Decimal("12.00")

    # 3. Ponto de Extensão («extend»)
    if solicitacao.entrega_domingo:
        valor_base = aplicar_seguro_domingo(valor_base)

    return valor_base

if __name__ == "__main__":
    try:
        sol = SolicitacaoFrete("TOKEN_SEGURO_2026", Decimal("5.0"), entrega_domingo=True)
        valor_final = emitir_frete(sol)
        print(f"✅ Frete emitido com sucesso: R$ {valor_final:.2f}")
    except TokenInvalidoException as erro:
        print(erro)

🚀 Como Executar

Execute o script no terminal:

python emissoes_frete_regras.py

🖥️ Saída Esperada no Terminal

 🛡️ [«extend»] Ponto de Extensão Ativado: Adicionando Seguro Especial de Domingo (+15%)
✅ Frete emitido com sucesso: R$ 69.00

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• «include»: Comportamento compartilhado e obrigatório para o término do caso base.
• «extend»: Comportamento modular e condicional acionado em pontos de extensão pré-definidos.
• Direção das Setas: Base ➔ «include» ➔ Compartilhado | Extensor ➔ «extend» ➔ Base.
• Especificação Textual: Caminho Feliz (Principal), Alternativos e Exceções devem ser detalhados para guiar o time de testes e desenvolvimento.

🏛️ CAPÍTULO 12: DIAGRAMA DE CLASSES (CONCEITOS)

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Compreender a estrutura do Diagrama de Classes da UML como pilar fundamental da modelagem estática e da Programação Orientada a Objetos (POO).
• 🔹 Dominar a representação dos três compartimentos canônicos: Nome da Classe, Atributos Tipados e Métodos com Assinaturas de Retorno.
• 🔹 Aplicar os modificadores de visibilidade da UML: Público (+), Privado (-), Protegido (#) e Pacote (~).
• 🔹 Mapear classes UML para código Python 3.11+ utilizando propriedades protegidas (@property) e modelos do SQLAlchemy 2.0.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, a equipe financeira identificou um bug crítico: funções espalhadas pelo sistema alteravam diretamente a variável saldo de motoristas parceiros sem registrar o log de auditoria e sem validar se o valor ficaria negativo.

O Desafio: Como Arquiteto de Software, você deve redesenhar o domínio aplicando o princípio do Encapsulamento. A classe CarteiraDigital deve manter o saldo estritamente privado (-), expondo apenas métodos públicos de depósito e saque com validação defensiva de integridade.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. Anatomia da Classe na UML 2.5

Uma classe é representada na UML por um retângulo com três compartimentos horizontais:

classDiagram
    class CarteiraDigital {
        -String idCarteira
        -Decimal saldoPrivado
        #String idTitular
        +depositar(Decimal valor) bool
        +sacar(Decimal valor) bool
        +consultarSaldo() Decimal
    }

3.2. Modificadores de Visibilidade e Encapsulamento

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

📋 Pré-requisitos e Instalação

Este exemplo utiliza exclusivamente módulos da biblioteca padrão do Python (decimal), não necessitando de bibliotecas de terceiros:

python --version  # Requer Python 3.11 ou superior

💻 Código Completo e Autocontido (carteira_digital.py)

Transposição da classe modelada na UML para código Python com encapsulamento defensivo e validações de invariantes de negócio:

"""
Módulo: carteira_digital.py
Domínio: Encapsulamento e proteção de saldo financeiro.
"""
from decimal import Decimal

class CarteiraDigital:
    def __init__(self, id_carteira: str, titular: str, saldo_inicial: Decimal = Decimal("0.00")):
        self.id_carteira: str = id_carteira          # + Público
        self._titular: str = titular                 # # Protegido
        self.__saldo: Decimal = saldo_inicial        # - Privado

    def depositar(self, valor: Decimal) -> bool:
        """+ Método Público para entrada de recursos com validação."""
        if valor <= Decimal("0.00"):
            raise ValueError("O valor de depósito deve ser estritamente positivo.")
        self.__saldo += valor
        return True

    def sacar(self, valor: Decimal) -> bool:
        """+ Método Público com trava de saldo insuficiente."""
        if valor <= Decimal("0.00"):
            raise ValueError("Valor de saque inválido.")
        if valor > self.__saldo:
            raise PermissionError("❌ Saldo insuficiente na carteira.")
        self.__saldo -= valor
        return True

    @property
    def saldo(self) -> Decimal:
        """+ Getter público controlado."""
        return self.__saldo

if __name__ == "__main__":
    print("--- Teste de Encapsulamento da Carteira Digital ---")
    carteira = CarteiraDigital("CRT-2026-99", "Marcos Silva", Decimal("500.00"))
    carteira.depositar(Decimal("250.00"))
    carteira.sacar(Decimal("100.00"))
    print(f"Titular: {carteira._titular}")
    print(f"✅ Saldo da Carteira {carteira.id_carteira}: R$ {carteira.saldo:.2f}")

    # Teste de violação de regra de negócio
    try:
        carteira.sacar(Decimal("1000.00"))
    except PermissionError as e:
        print(f"Validação defensiva disparada: {e}")

🚀 Como Executar

Execute o script diretamente no terminal:

python carteira_digital.py

🖥️ Saída Esperada no Terminal

--- Teste de Encapsulamento da Carteira Digital ---
Titular: Marcos Silva
✅ Saldo da Carteira CRT-2026-99: R$ 650.00
Validação defensiva disparada: ❌ Saldo insuficiente na carteira.

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• Planta Estática: O Diagrama de Classes define a estrutura de dados e as operações fundamentais do sistema.
• 3 Compartimentos: Nome da Classe, Atributos Tipados e Métodos com assinaturas.
• Encapsulamento Estrito: Atributos devem ser privados (-) ou protegidos (#); métodos de negócio compõem a interface pública (+).
• Mapeamento ORM: Classes UML conectam-se diretamente às tabelas relacionais do SQLAlchemy e schemas do Pydantic.

🧬 CAPÍTULO 13: HERANÇA, POLIMORFISMO E ASSOCIAÇÕES

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Diferenciar e aplicar os 4 relacionamentos essenciais da UML: Associação Simples, Agregação (losango vazio), Composição (losango preenchido) e Generalização/Herança (triângulo vazio).
• 🔹 Distinguir Agregação (relação fraca 'tem-um', ciclo de vida independente) de Composição (relação forte 'parte-todo', ciclo de vida dependente e exclusão em cascata).
• 🔹 Aplicar Polimorfismo e Classes Abstratas (abc.ABC) para garantir desacoplamento e extensibilidade.
• 🔹 Implementar relacionamentos no SQLAlchemy 2.0 com relationship() e cascade="all, delete-orphan".

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, a plataforma de e-commerce e faturamento processa pedidos compostos por múltiplos itens. Se um Pedido for cancelado ou excluído do banco de dados, todos os seus ItensPedido associados devem ser automaticamente eliminados (Composição). No entanto, o Produto do catálogo continua existindo para outras vendas (Agregação).

O Desafio: Como Arquiteto de Software, você deve modelar as relações entre as classes com as cardinalidades corretas, garantindo que o ciclo de vida dos objetos reflita as regras de negócio e a integridade referencial do banco de dados.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. Panorama dos Relacionamentos entre Classes na UML

classDiagram
    class Pedido {
        +int idPedido
        +date dataEmissao
        +calcularTotal() Decimal
    }
    class ItemPedido {
        +int quantidade
        +Decimal precoUnitario
        +subtotal() Decimal
    }
    class Produto {
        +int idProduto
        +string nome
        +Decimal preco
    }
    class Cliente {
        +int idCliente
        +string nome
    }
    
    Cliente "1" --> "0..*" Pedido : Associação
    Pedido "1" *-- "1..*" ItemPedido : Composição (Todo-Parte Forte)
    ItemPedido "0..*" o-- "1" Produto : Agregação (Parte Fraca)

3.2. Comparativo: Agregação vs. Composição vs. Herança

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

📋 Pré-requisitos e Instalação

Este exemplo utiliza os módulos padrão abc, decimal e dataclasses, sem necessidade de pacotes externos:

python --version  # Requer Python 3.11 ou superior

💻 Código Completo e Autocontido (modelo_pedido_composicao.py)

Implementação de Composição Forte e Polimorfismo de Estratégia de Desconto em Python 3.11+:

"""
Módulo: modelo_pedido_composicao.py
Domínio: Composição forte e polimorfismo de regras de frete e desconto.
"""
from abc import ABC, abstractmethod
from decimal import Decimal
from dataclasses import dataclass

# --- POLIMORFISMO DE ESTRATÉGIA DE DESCONTO ---
class RegraDesconto(ABC):
    @abstractmethod
    def calcular_desconto(self, valor_bruto: Decimal) -> Decimal:
        pass

class DescontoClientePadrao(RegraDesconto):
    def calcular_desconto(self, valor_bruto: Decimal) -> Decimal:
        return Decimal("0.00")

class DescontoClienteVIP(RegraDesconto):
    def calcular_desconto(self, valor_bruto: Decimal) -> Decimal:
        return valor_bruto * Decimal("0.10") # 10% OFF

# --- COMPOSIÇÃO: Pedido e ItemPedido ---
@dataclass
class ItemPedido:
    descricao: str
    quantidade: int
    preco_unitario: Decimal

    def subtotal(self) -> Decimal:
        return self.quantidade * self.preco_unitario

class Pedido:
    def __init__(self, id_pedido: int, estrategia_desconto: RegraDesconto):
        self.id_pedido = id_pedido
        self.estrategia_desconto = estrategia_desconto
        self.itens: list[ItemPedido] = [] # Composição: itens pertencem ao ciclo deste pedido

    def adicionar_item(self, descricao: str, quantidade: int, preco: Decimal):
        self.itens.append(ItemPedido(descricao, quantidade, preco))

    def calcular_total_bruto(self) -> Decimal:
        return sum((item.subtotal() for item in self.itens), Decimal("0.00"))

    def calcular_total_liquido(self) -> Decimal:
        bruto = self.calcular_total_bruto()
        desconto = self.estrategia_desconto.calcular_desconto(bruto)
        return bruto - desconto

if __name__ == "__main__":
    print("--- Simulação de Pedidos com Composição e Polimorfismo ---")
    
    # Pedido 1: Cliente Padrão (Sem Desconto)
    pedido_padrao = Pedido(1001, DescontoClientePadrao())
    pedido_padrao.adicionar_item("Teclado Mecânico", 1, Decimal("350.00"))
    print(f"📦 Pedido #{pedido_padrao.id_pedido} (Padrão):")
    print(f"   Bruto: R$ {pedido_padrao.calcular_total_bruto():.2f} | Líquido: R$ {pedido_padrao.calcular_total_liquido():.2f}")

    # Pedido 2: Cliente VIP (10% OFF)
    pedido_vip = Pedido(1002, DescontoClienteVIP())
    pedido_vip.adicionar_item("Monitor Dell 27", 2, Decimal("1200.00"))
    pedido_vip.adicionar_item("Teclado Mecânico", 1, Decimal("350.00"))
    print(f"🌟 Pedido #{pedido_vip.id_pedido} (VIP 10% OFF):")
    print(f"   Bruto: R$ {pedido_vip.calcular_total_bruto():.2f} | Líquido: R$ {pedido_vip.calcular_total_liquido():.2f}")

🚀 Como Executar

Execute o script diretamente no terminal:

python modelo_pedido_composicao.py

🖥️ Saída Esperada no Terminal

--- Simulação de Pedidos com Composição e Polimorfismo ---
📦 Pedido #1001 (Padrão):
   Bruto: R$ 350.00 | Líquido: R$ 350.00
🌟 Pedido #1002 (VIP 10% OFF):
   Bruto: R$ 2750.00 | Líquido: R$ 2475.00

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• Associação: Relação genérica de conhecimento entre duas classes.
• Agregação (Losango Vazio): Vínculo fraco; as partes continuam existindo de forma independente.
• Composição (Losango Cheio): Vínculo forte de posse existencial; exclusão em cascata obrigatória.
• Polimorfismo: Desacoplamento através de classes base abstratas (abc.ABC), permitindo trocar algoritmos sem quebrar os clientes.

🔀 CAPÍTULO 14: DIAGRAMA DE SEQUÊNCIA E APIS REST

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Compreender a representação temporal de troca de mensagens entre objetos no Diagrama de Sequência da UML 2.5.
• 🔹 Dominar a sintaxe visual de Linhas de Vida (Lifelines), Barras de Ativação (Execution Occurrences), Mensagens Síncronas (->>), Assíncronas (-)) e Retornos (-->>).
• 🔹 Modelar fluxos completos de requisições HTTP REST (Request-Response Cycle) conectando Cliente, Gateway, Serviços e Banco de Dados.
• 🔹 Implementar rotas Flask integradas com serviços de domínio espelhando rigorosamente a ordem do diagrama de sequência.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, a equipe de engenharia identificou uma latência excessiva durante o processo de Checkout e Emissão de Etiqueta. O time de frontend culpava o banco de dados, o DBA culpava a rede e a equipe backend culpava a API externa de CEP.

O Desafio: Como Arquiteto de Software, você deve desenhar o Diagrama de Sequência da UML para rastrear a linha do tempo exata das chamadas de rede e processamento síncrono/assíncrono, identificando gargalos e estabelecendo contratos REST claros e determinísticos em Flask.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. Anatomia do Diagrama de Sequência da UML

O tempo flui verticalmente de cima para baixo. Cada participante possui uma linha de vida vertical com barras que indicam períodos em que o objeto está executando operações ativas:

sequenceDiagram
    autonumber
    actor C as 📱 App do Motorista
    participant API as 🌐 Flask (Gateway)
    participant SVC as 🧠 FreteService
    participant DB as 🛢️ PostgreSQL
    
    C->>+API: POST /api/fretes/calcular (distancia_km, peso_kg, expresso)
    API->>+SVC: processar_calculo(distancia, peso, expresso)
    SVC->>+DB: SELECT taxa_km FROM tabelas_frete...
    DB-->>-SVC: taxa_km = 2.50
    SVC-->>-API: { valor_total: 316.25, prazo_horas: 24 }
    API-->>-C: 200 OK { valor_total: 316.25, prazo_horas: 24 }

3.2. Notação de Mensagens na UML 2.5

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

📋 Pré-requisitos e Instalação

Instale o micro-framework Flask no seu ambiente virtual:

pip install flask

💻 Código Completo e Autocontido (sequence_api_frete.py)

Implementação do fluxo síncrono de cálculo de frete com Flask 3.x, refletindo a interação modelada no Diagrama de Sequência:

"""
Módulo: sequence_api_frete.py
Domínio: Endpoint REST Flask refletindo a sequência síncrona de cálculo de frete.
"""
from decimal import Decimal
import sys
from flask import Flask, request, jsonify

app = Flask(__name__)

# 1. Camada de Serviço (Service Layer)
class FreteService:
    @staticmethod
    def processar_calculo(distancia_km: Decimal, peso_kg: Decimal, expresso: bool = False) -> dict:
        taxa_base_km = Decimal("2.50")
        valor = (distancia_km * taxa_base_km) + (peso_kg * Decimal("3.00"))
        prazo = 24
        
        if expresso:
            valor *= Decimal("1.25")
            prazo = 8
            
        return {
            "valor_total": float(valor.quantize(Decimal("0.01"))),
            "prazo_horas": prazo,
            "status": "CALCULADO_COM_SUCESSO"
        }

# 2. Rota REST (Controller / Gateway)
@app.post("/api/fretes/calcular")
def endpoint_calcular_frete():
    """Reflete o Passo 1 do Diagrama de Sequência: POST /api/fretes/calcular."""
    dados = request.get_json()
    if not dados:
        return jsonify({"erro": "Payload JSON ausente ou inválido"}), 400

    try:
        distancia = Decimal(str(dados.get("distancia_km", 0)))
        peso = Decimal(str(dados.get("peso_kg", 0)))
        expresso = bool(dados.get("expresso", False))

        if distancia <= Decimal("0.00") or peso <= Decimal("0.00"):
            return jsonify({"erro": "distancia_km e peso_kg devem ser maiores que zero"}), 400

        resultado = FreteService.processar_calculo(distancia, peso, expresso)
        return jsonify(resultado), 200

    except Exception as ex:
        return jsonify({"erro": f"Falha no processamento: {str(ex)}"}), 400

if __name__ == "__main__":
    if "--server" in sys.argv:
        print("🚀 Iniciando servidor Flask em http://127.0.0.1:5000...")
        app.run(port=5000, debug=True)
    else:
        print("--- Simulação de Requisições HTTP com Flask test_client() ---")
        with app.test_client() as client:
            # Cenário 1: Frete Padrão (120.5 km, 5 kg) -> (120.5*2.50) + (5*3.00) = 301.25 + 15 = 316.25
            res1 = client.post("/api/fretes/calcular", json={
                "distancia_km": 120.5,
                "peso_kg": 5.0,
                "expresso": False
            })
            print(f"Cenário 1 (Frete Padrão) [Status {res1.status_code}]: {res1.get_json()}")

            # Cenário 2: Frete Expresso (120.5 km, 5 kg, expresso) -> 316.25 * 1.25 = 395.31
            res2 = client.post("/api/fretes/calcular", json={
                "distancia_km": 120.5,
                "peso_kg": 5.0,
                "expresso": True
            })
            print(f"Cenário 2 (Frete Expresso) [Status {res2.status_code}]: {res2.get_json()}")

            # Cenário 3: Validação de Payload com Erro
            res3 = client.post("/api/fretes/calcular", json={
                "distancia_km": -10.0,
                "peso_kg": 5.0
            })
            print(f"Cenário 3 (Validação Defensiva) [Status {res3.status_code}]: {res3.get_json()}")

🚀 Como Executar

Execute o script de teste automatizado diretamente no terminal:

python sequence_api_frete.py

Para iniciar o servidor HTTP e testar com ferramentas como Postman, cURL ou VS Code REST Client:

python sequence_api_frete.py --server

🖥️ Saída Esperada no Terminal

--- Simulação de Requisições HTTP com Flask test_client() ---
Cenário 1 (Frete Padrão) [Status 200]: {'prazo_horas': 24, 'status': 'CALCULADO_COM_SUCESSO', 'valor_total': 316.25}
Cenário 2 (Frete Expresso) [Status 200]: {'prazo_horas': 8, 'status': 'CALCULADO_COM_SUCESSO', 'valor_total': 395.31}
Cenário 3 (Validação Defensiva) [Status 400]: {'erro': 'distancia_km e peso_kg devem ser maiores que zero'}

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• Visão Temporal: O Diagrama de Sequência é o modelo comportamental mais utilizado para mapear a ordem cronológica de APIs REST e microsserviços.
• Linhas de Vida & Barras de Ativação: Indicam os participantes e os momentos exatos de processamento ativo.
• Mensagens Síncronas vs Assíncronas: Diferenciam chamadas diretas de eventos desacoplados em filas e mensageria.
• Endpoints em Flask: Implementam de forma limpa e síncrona as transições modeladas no diagrama de sequência, facilitando testes com test_client().

🔄 CAPÍTULO 15: DIAGRAMAS DINÂMICOS (ESTADOS E ATIVIDADES)

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Modelar o ciclo de vida completo de entidades reativas utilizando o Diagrama de Máquina de Estados da UML (David Harel).
• 🔹 Dominar a sintaxe formal de transições: Evento [Condição de Guarda] / Ação Executada.
• 🔹 Construir Diagramas de Atividades com particionamento em Raias (Swimlanes), bifurcações de decisão e nós de sincronização paralela (Fork e Join).
• 🔹 Implementar o padrão comportamental State Pattern e máquinas de estados finitos (FSM) em Python 3.11+.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, os motoristas estavam conseguindo alterar o status de um pacote diretamente de "Aguardando Coleta" para "Entregue ao Destinatário", pulando a etapa obrigatória de "Em Rota de Entrega" e sem coletar a assinatura digital do cliente.

O Desafio: Como Engenheiro de Software, você deve modelar formalmente a Máquina de Estados Finita do pacote e o Diagrama de Atividades com Raias do processo de entrega, garantindo que o backend bloqueie qualquer transição de status ilegal ou desordenada.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. Diagrama de Máquina de Estados da UML

Mapeia os estados discretos pelos quais um objeto passa durante sua existência em resposta a eventos:

stateDiagram-v2
    [*] --> CRIADO : Criação do Pacote
    CRIADO --> COLETADO : Motorista Coleta no Hub
    COLETADO --> EM_TRANSITO : Saída para Entrega [Veículo Alocado]
    EM_TRANSITO --> TENTATIVA_FALHA : Cliente Ausente / Notificar SAC
    TENTATIVA_FALHA --> EM_TRANSITO : Nova Tentativa [Tentativas < 3]
    TENTATIVA_FALHA --> DEVOLVIDO_HUB : Excedeu Limite [Tentativas >= 3]
    EM_TRANSITO --> ENTREGUE : Assinatura Coletada / Enviar Recibo
    ENTREGUE --> [*]
    DEVOLVIDO_HUB --> [*]

3.2. Diagrama de Atividades com Raias (Swimlanes) e Fork / Join

Organiza o fluxo de trabalho distribuindo as responsabilidades entre os diferentes departamentos/atores:

flowchart TD
    subgraph CLIENTE ["👤 Cliente"]
        A1["Fazer Pedido"] --> A2["Efetuar Pagamento"]
    end
    
    subgraph GATEWAY ["🏛️ Gateway Pagamento"]
        A2 --> B1{"Pagamento Aprovado?"}
    end
    
    subgraph LOGISTICA ["🚚 Centro Logístico"]
        B1 -- Sim --> FORK["Barra Fork (Paralelo)"]
        FORK --> C1["Separar Estoque"]
        FORK --> C2["Emitir Nota Fiscal"]
        C1 --> JOIN["Barra Join (Sincronização)"]
        C2 --> JOIN
        JOIN --> C3["Despachar Encomenda"]
    end
    
    B1 -- Não --> A3["Notificar Erro Pagamento"]
    
    style FORK fill:#fef3c7,stroke:#d97706
    style JOIN fill:#fef3c7,stroke:#d97706
    style C3 fill:#dcfce7,stroke:#16a34a

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

📋 Pré-requisitos e Instalação

Este exemplo utiliza os módulos padrão enum do Python, sem necessidade de pacotes externos:

python --version  # Requer Python 3.11 ou superior

💻 Código Completo e Autocontido (maquina_estados_pacote.py)

Implementação de uma Máquina de Estados Finitos (FSM) com validação estrita de transições de ciclo de vida:

"""
Módulo: maquina_estados_pacote.py
Domínio: Validação de transições de ciclo de vida de encomendas com FSM.
"""
from enum import Enum, auto

class EstadoPacote(Enum):
    CRIADO = auto()
    COLETADO = auto()
    EM_TRANSITO = auto()
    ENTREGUE = auto()
    CANCELADO = auto()

class PacoteFSM:
    # Tabela de transições permitidas: EstadoAtual -> Lista de Próximos Estados Legais
    TRANSIÇÕES_VALIDAS = {
        EstadoPacote.CRIADO: {EstadoPacote.COLETADO, EstadoPacote.CANCELADO},
        EstadoPacote.COLETADO: {EstadoPacote.EM_TRANSITO, EstadoPacote.CANCELADO},
        EstadoPacote.EM_TRANSITO: {EstadoPacote.ENTREGUE, EstadoPacote.COLETADO},
        EstadoPacote.ENTREGUE: set(), # Estado Final
        EstadoPacote.CANCELADO: set()  # Estado Final
    }

    def __init__(self, codigo_rastreio: str):
        self.codigo_rastreio = codigo_rastreio
        self.estado_atual = EstadoPacote.CRIADO

    def transicionar_para(self, novo_estado: EstadoPacote):
        permitidos = self.TRANSIÇÕES_VALIDAS.get(self.estado_atual, set())
        if novo_estado not in permitidos:
            raise ValueError(
                f"❌ Transição Ilegal: Não é permitido mudar de {self.estado_atual.name} para {novo_estado.name}."
            )
        self.estado_atual = novo_estado
        print(f"📦 Pacote [{self.codigo_rastreio}] transicionou com sucesso para: {self.estado_atual.name}")

if __name__ == "__main__":
    print("--- Simulação da Máquina de Estados (FSM) de Logística ---")
    pacote = PacoteFSM("BR-2026-99")
    pacote.transicionar_para(EstadoPacote.COLETADO)
    pacote.transicionar_para(EstadoPacote.EM_TRANSITO)
    pacote.transicionar_para(EstadoPacote.ENTREGUE)
    
    # Tentativa ilegal de transição a partir de um estado final
    try:
        pacote.transicionar_para(EstadoPacote.CRIADO)
    except ValueError as err:
        print(err)

🚀 Como Executar

Execute o script diretamente no terminal:

python maquina_estados_pacote.py

🖥️ Saída Esperada no Terminal

--- Simulação da Máquina de Estados (FSM) de Logística ---
📦 Pacote [BR-2026-99] transicionou com sucesso para: COLETADO
📦 Pacote [BR-2026-99] transicionou com sucesso para: EM_TRANSITO
📦 Pacote [BR-2026-99] transicionou com sucesso para: ENTREGUE
❌ Transição Ilegal: Não é permitido mudar de ENTREGUE para CRIADO.

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• Diagrama de Estados: Foca nas mudanças de situação interna de uma única entidade ao longo do tempo.
• Sintaxe de Transição: Evento [Guarda Booleana] / Ação Executada.
• Diagrama de Atividades: Modela o fluxo de trabalho global, decisões lógicas e sincronização paralela (Fork/Join).
• Raias (Swimlanes): Atribuem responsabilidades claras para cada etapa do processo corporativo.

🧪 CAPÍTULO 16: QUALIDADE DE SOFTWARE (SQA)

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Compreender os fundamentos de Software Quality Assurance (SQA) e as 8 características de qualidade da norma ISO/IEC 25010.
• 🔹 Avaliar a Complexidade Ciclomática de McCabe e o índice de manutenibilidade de bases de código.
• 🔹 Executar ferramentas de análise estática de código (Linters, Flake8, Ruff e Radon) no ecossistema Python 3.11+.
• 🔹 Instituir Quality Gates e métricas de governança em esteiras de integração contínua.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, após 1 ano de entregas aceleradas, o sistema central tornou-se lento e qualquer nova alteração gerava bugs inesperados em outros módulos não relacionados. O tempo médio para corrigir uma falha simples saltou de 2 horas para 4 dias úteis.

O Desafio: Como Engenheiro de Qualidade de Software (SQA Lead), você deve auditar a base de código utilizando a norma ISO/IEC 25010 e ferramentas de análise estática, estabelecendo métricas de complexidade e bloqueando deploys de código com alto débito técnico.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. As 8 Características de Qualidade da Norma ISO/IEC 25010

A norma internacional ISO/IEC 25010 estrutura a qualidade de produto de software em 8 dimensões complementares:

flowchart TD
    root["🌐 ISO/IEC 25010: Qualidade de Produto de Software"]
    
    root --> C1["1. Adequação Funcional<br>(Completeza, Correção)"]
    root --> C2["2. Eficiência de Performance<br>(Tempo, Recursos, Capacidade)"]
    root --> C3["3. Compatibilidade<br>(Coexistência, Interoperabilidade)"]
    root --> C4["4. Usabilidade<br>(Operabilidade, Acessibilidade)"]
    root --> C5["5. Confiabilidade<br>(Maturidade, Tolerância a Falhas)"]
    root --> C6["6. Segurança<br>(Confidencialidade, Integridade)"]
    root --> C7["7. Manutenibilidade<br>(Modularidade, Reusabilidade, Testabilidade)"]
    root --> C8["8. Portabilidade<br>(Adaptabilidade, Instalabilidade)"]
    
    style root fill:#eff6ff,stroke:#2563eb,stroke-width:2px
    style C1 fill:#f0fdf4,stroke:#16a34a
    style C2 fill:#f0fdf4,stroke:#16a34a
    style C3 fill:#fffbeb,stroke:#d97706
    style C4 fill:#fffbeb,stroke:#d97706
    style C5 fill:#fee2e2,stroke:#ef4444
    style C6 fill:#fee2e2,stroke:#ef4444
    style C7 fill:#ede7f6,stroke:#7c3aed
    style C8 fill:#ede7f6,stroke:#7c3aed

3.2. Complexidade Ciclomática de Thomas McCabe

Mede o número de caminhos linearmente independentes no fluxo de controle de um método: $$\text{Complexidade } V(G) = E - N + 2P$$ (Onde $E$ = arestas, $N$ = nós de decisão e $P$ = componentes conexos).

flowchart TD
    subgraph MCCABE ["COMPLEXIDADE CICLOMÁTICA E RISCO"]
        R1["1 a 10: Código Simples (Baixo Risco)"]
        R2["11 a 20: Complexidade Moderada (Risco Médio)"]
        R3["21 a 50: Alta Complexidade (Alto Risco / Difícil Testar)"]
        R4["> 50: Código Não-Testável (Risco Crítico / Refatorar Urgente)"]
    end
    style R1 fill:#dcfce7,stroke:#16a34a
    style R2 fill:#fef3c7,stroke:#d97706
    style R3 fill:#fee2e2,stroke:#ef4444
    style R4 fill:#b91c1c,stroke:#7f1d1d,color:#fff

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

📋 Pré-requisitos e Instalação

Este exemplo utiliza o módulo ast (Abstract Syntax Trees) nativo da biblioteca padrão do Python:

python --version  # Requer Python 3.11 ou superior

💻 Código Completo e Autocontido (sqa_analisador_qualidade.py)

Implementação de analisador estático de complexidade ciclomática de McCabe $V(G)$ via AST em Python 3.11+:

"""
Módulo: sqa_analisador_qualidade.py
Domínio: Auditoria estática de código e cálculo de complexidade ciclomática.
"""
import ast

class AnalisadorComplexidade(ast.NodeVisitor):
    def __init__(self):
        self.complexidade = 1 # Caminho base linear

    def visit_If(self, node):
        self.complexidade += 1
        self.generic_visit(node)

    def visit_For(self, node):
        self.complexidade += 1
        self.generic_visit(node)

    def visit_While(self, node):
        self.complexidade += 1
        self.generic_visit(node)

def calcular_complexidade_codigo(codigo_fonte: str) -> int:
    arvore_sintatica = ast.parse(codigo_fonte)
    analisador = AnalisadorComplexidade()
    analisador.visit(arvore_sintatica)
    return analisador.complexidade

if __name__ == "__main__":
    print("--- Auditoria Estática de Complexidade Ciclomática (SQA) ---")
    
    codigo_exemplo = """
def calcular_frete_complicado(peso, distancia, expresso, vip):
    if peso > 10:
        if distancia > 100:
            if expresso:
                return 150.0
            elif vip:
                return 120.0
    return 50.0
"""
    v_g = calcular_complexidade_codigo(codigo_exemplo)
    print(f"📊 Complexidade Ciclomática V(G) do método: {v_g}")
    if v_g <= 10:
        print("✅ Qualidade Aprovada: Método com baixa complexidade e alta testabilidade.")
    else:
        print("⚠️ Alerta SQA: Método com excesso de bifurcações aninhadas. Refatore!")

🚀 Como Executar

Execute o script diretamente no terminal:

python sqa_analisador_qualidade.py

🖥️ Saída Esperada no Terminal

--- Auditoria Estática de Complexidade Ciclomática (SQA) ---
📊 Complexidade Ciclomática V(G) do método: 5
✅ Qualidade Aprovada: Método com baixa complexidade e alta testabilidade.

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• SQA Sistêmico: A qualidade deve ser construída e garantida em todas as fases do processo, não apenas testada no final.
• ISO/IEC 25010: Modelo internacional com 8 características canônicas para auditoria de software.
• Complexidade Ciclomática: Métodos com $V(G) \le 10$ são sustentáveis; métodos acima de 20 devem ser refatorados imediatamente.
• Quality Gates: Automação com linters e testes bloqueando commits de baixa qualidade na esteira de CI.

🧪 CAPÍTULO 17: ESTRATÉGIAS DE TESTE E AUTOMAÇÃO

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Dominar a Pirâmide de Testes de Mike Cohn: Testes Unitários (base rápida), Testes de Integração (meio com banco em memória) e Testes E2E (topo).
• 🔹 Diferenciar Testes de Caixa-Preta (baseados em requisitos/comportamento) de Testes de Caixa-Branca (baseados na cobertura estrutural de código e branches).
• 🔹 Aplicar técnicas de Mocking, Test Fixtures e injeção de dependências no pytest.
• 🔹 Implementar testes automatizados de endpoints HTTP com o test_client nativo do Flask e Pytest.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, após uma atualização na rotina de cálculo de cubagem de fretes, o faturamento gerou R$ 45.000,00 em cobranças a menor antes que alguém percebesse o erro em produção. A equipe realizava apenas testes manuais clicando na interface do sistema.

O Desafio: Como Engenheiro de Testes de Software, você deve abolir testes manuais em rotinas críticas, construindo uma suíte automatizada com Pytest que execute 100% dos testes unitários e de integração em menos de 10 segundos a cada commit.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. A Pirâmide de Testes de Mike Cohn

Estrutura recomendada para maximizar a velocidade de feedback e minimizar o custo de manutenção:

flowchart TD
    subgraph PIRAMIDE ["PIRÂMIDE DE TESTES DE SOFTWARE"]
        E2E["🌐 1. Testes Ponta a Ponta (E2E / UI)<br>Lentos, caros, poucos (Topo)"]
        INT["⚙️ 2. Testes de Integração (APIs & DB em memória)<br>Velocidade média, validam contratos (Meio)"]
        UNIT["🧪 3. Testes Unitários (Funções, Classes & Regras Puras)<br>Milissegundos, baratos, milhares (Base da Pirâmide)"]
        
        E2E --> INT --> UNIT
    end
    
    style E2E fill:#fee2e2,stroke:#ef4444
    style INT fill:#fef3c7,stroke:#d97706
    style UNIT fill:#dcfce7,stroke:#16a34a

3.2. Caixa-Preta vs. Caixa-Branca

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

📋 Pré-requisitos e Instalação

Instale o Flask e o Pytest no seu ambiente virtual:

pip install flask pytest

💻 Código Completo e Autocontido (test_api_integracao.py)

Implementação de testes de integração com o test_client nativo do Flask e fixtures do Pytest:

"""
Módulo: test_api_integracao.py
Domínio: Testes de integração de endpoints REST com Flask test_client e Pytest.
"""
import pytest
from flask import Flask, request, jsonify

app = Flask(__name__)

BANCO_DADOS_MOCK = {}

@app.post("/itens/")
def criar_item():
    dados = request.get_json()
    if not dados:
        return jsonify({"detail": "Payload JSON ausente"}), 400

    nome = dados.get("nome")
    preco = dados.get("preco", 0.0)

    if not nome:
        return jsonify({"detail": "Nome é obrigatório"}), 400
    if preco <= 0:
        return jsonify({"detail": "Preço deve ser positivo."}), 400

    BANCO_DADOS_MOCK[nome] = preco
    return jsonify({"status": "CRIADO", "item": nome, "preco": preco}), 201

@app.get("/itens/<nome>")
def consultar_item(nome: str):
    if nome not in BANCO_DADOS_MOCK:
        return jsonify({"detail": "Item não encontrado."}), 404
    return jsonify({"item": nome, "preco": BANCO_DADOS_MOCK[nome]}), 200

# --- SUÍTE PYTEST ---
@pytest.fixture
def client():
    """Fixture Pytest que fornece o cliente de testes isolado do Flask."""
    app.config["TESTING"] = True
    BANCO_DADOS_MOCK.clear()
    with app.test_client() as client:
        yield client

def test_criar_item_com_sucesso(client):
    resposta = client.post("/itens/", json={"nome": "Notebook", "preco": 3500.00})
    assert resposta.status_code == 201
    assert resposta.get_json()["item"] == "Notebook"

def test_criar_item_preco_invalido_deve_retornar_400(client):
    resposta = client.post("/itens/", json={"nome": "Mouse", "preco": -10.00})
    assert resposta.status_code == 400
    assert "Preço deve ser positivo" in resposta.get_json()["detail"]

def test_consultar_item_inexistente_deve_retornar_404(client):
    resposta = client.get("/itens/ItemFantasma")
    assert resposta.status_code == 404

def test_fluxo_completo_cadastro_e_consulta(client):
    post_res = client.post("/itens/", json={"nome": "Teclado", "preco": 250.00})
    assert post_res.status_code == 201
    
    get_res = client.get("/itens/Teclado")
    assert get_res.status_code == 200
    assert get_res.get_json()["preco"] == 250.00

if __name__ == "__main__":
    print("🧪 Executando suíte com Pytest...")
    pytest.main(["-v", __file__])

🚀 Como Executar

Você pode executar o arquivo diretamente com o interpretador Python ou através do runner do Pytest:

# Execução direta via Python
python test_api_integracao.py

# Ou via runner padrão do Pytest
pytest -v test_api_integracao.py

🖥️ Saída Esperada no Terminal

🧪 Executando suíte com Pytest...
============================= test session starts =============================
rootdir: C:\Temp\portal_mdbook
collected 4 items

test_api_integracao.py::test_criar_item_com_sucesso PASSED               [ 25%]
test_api_integracao.py::test_criar_item_preco_invalido_deve_retornar_400 PASSED [ 50%]
test_api_integracao.py::test_consultar_item_inexistente_deve_retornar_404 PASSED [ 75%]
test_api_integracao.py::test_fluxo_completo_cadastro_e_consulta PASSED   [100%]

============================== 4 passed in 0.05s ==============================

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• Pirâmide de Testes: Base ampla de Testes Unitários + Camada intermediária de Integração + Topo enxuto de E2E.
• Caixa-Preta vs Caixa-Branca: Foco em comportamento funcional e valores limites versus cobertura estrutural de branches.
• FIRST Principles: Testes devem ser rápidos, isolados, repetíveis, auto-validáveis e tempestivos.
• Automação no CI: Nenhum código deve ser aceito em produção sem que 100% da suíte de testes automatizados esteja verde.

🔧 CAPÍTULO 18: MANUTENÇÃO E EVOLUÇÃO DE SOFTWARE

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Classificar as 4 modalidades canônicas de manutenção segundo a norma ISO/IEC 14764: Corretiva, Adaptativa, Perfectiva e Preventiva.
• 🔹 Compreender as Leis de Evolução de Software de Manny Lehman (Mudança Contínua, Complexidade Crescente, Declínio de Qualidade).
• 🔹 Calcular e gerenciar o Débito Técnico (Technical Debt) utilizando a metáfora financeira de Ward Cunningham.
• 🔹 Aplicar técnicas estruturadas de Refatoração de Código (Refactoring) catalogadas por Martin Fowler com a segurança de testes automatizados.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, o módulo central de roteirização de entregas completou 4 anos em produção. No início, cada sprint entregava 10 novas funcionalidades; hoje, a equipe mal consegue entregar 2, gastando 80% do tempo apagando incêndios causados por bugs em código acoplado e sem documentação.

O Desafio: Como Engenheiro de Manutenção e Arquiteto de Software, você deve instituir uma política contínua de pagamento de débito técnico, reservando 20% da capacidade de cada sprint para refatoração preventiva e perfectiva (Boy Scout Rule: "Deixe o acampamento mais limpo do que você o encontrou").

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. As 4 Modalidades de Manutenção de Software (ISO/IEC 14764)

flowchart TD
    subgraph MANUTENCAO ["OS 4 TIPOS DE MANUTENÇÃO DE SOFTWARE"]
        C["🐛 1. MANUTENÇÃO CORRETIVA (Reativa)<br>Correção de bugs e falhas em produção."]
        A["🔄 2. MANUTENÇÃO ADAPTATIVA (Proativa/Reativa)<br>Adaptação a novos ambientes (migração de SO, nuvem, leis fiscais)."]
        P["✨ 3. MANUTENÇÃO PERFECTIVA (Proativa)<br>Melhoria de desempenho, refatoração de código e novas funcionalidades."]
        PR["🛡️ 4. MANUTENÇÃO PREVENTIVA (Proativa)<br>Correção de problemas latentes antes que se tornem incidentes reais."]
    end
    
    style C fill:#fee2e2,stroke:#ef4444
    style A fill:#e0f2fe,stroke:#0284c7
    style P fill:#dcfce7,stroke:#16a34a
    style PR fill:#fef3c7,stroke:#d97706

3.2. A Metáfora do Débito Técnico (Ward Cunningham)

Fazer alterações rápidas e "gambiarras" para bater prazos é como contrair um empréstimo financeiro: traz liquidez no curto prazo, mas acumula juros na forma de complexidade. Se o principal não for pago através de refatoração, a taxa de entrega da equipe cai a zero.

flowchart LR
    ATALHO["⚡ Atalho de Código / Sem Testes<br>(Empréstimo Rápido)"] --> DUIDA["📈 Débito Técnico Acumulado"]
    DUIDA --> JUROS["💸 Juros Mensais:<br>Bugs Frequentes & Entregas Lentas"]
    JUROS --> FALENCIA["⛔ Falência do Software / Reescrever do Zero"]
    
    DUIDA -.->|Refatoração Contínua| PAGO["✅ Débito Pago & Código Sustentável"]
    
    style ATALHO fill:#fef3c7,stroke:#d97706
    style DUIDA fill:#fee2e2,stroke:#ef4444
    style FALENCIA fill:#b91c1c,stroke:#7f1d1d,color:#fff
    style PAGO fill:#dcfce7,stroke:#16a34a

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

📋 Pré-requisitos e Instalação

Este exemplo utiliza os recursos nativos do Python (decimal), sem necessidade de pacotes externos:

python --version  # Requer Python 3.11 ou superior

💻 Código Completo e Autocontido (refatoracao_exemplo.py)

Exemplo prático de Refatoração Perfectiva aplicando Guard Clauses, eliminação de aninhamento excessivo (Arrow Anti-Pattern) e tipagem estrita:

"""
Módulo: refatoracao_exemplo.py
Domínio: Aplicação do padrão Guard Clauses e eliminação de duplicação.
"""
from decimal import Decimal

# --- CÓDIGO ANTES DA REFATORAÇÃO (Espaguete / Alta Complexidade) ---
def calcular_desconto_legado(cliente_tipo, valor_total, dias_atraso):
    resultado = 0
    if valor_total > 100:
        if dias_atraso == 0:
            if cliente_tipo == "VIP":
                resultado = valor_total * 0.15
            else:
                resultado = valor_total * 0.05
        else:
            resultado = 0
    else:
        resultado = 0
    return resultado

# --- CÓDIGO APÓS A REFATORAÇÃO PERFECTIVA (Clean Code / Baixa Complexidade) ---
def calcular_desconto_refatorado(cliente_tipo: str, valor_total: Decimal, dias_atraso: int) -> Decimal:
    """Refatoração com Guard Clauses e tipagem estrita."""
    if valor_total <= Decimal("100.00") or dias_atraso > 0:
        return Decimal("0.00")
    
    taxa = Decimal("0.15") if cliente_tipo.upper() == "VIP" else Decimal("0.05")
    return (valor_total * taxa).quantize(Decimal("0.01"))

if __name__ == "__main__":
    print("--- Comparativo de Refatoração: Legado vs. Guard Clauses ---")
    
    # Caso 1: VIP adimplente > R$ 100
    v_antes = calcular_desconto_legado("VIP", 200, 0)
    v_depois = calcular_desconto_refatorado("VIP", Decimal("200.00"), 0)
    print(f"Caso 1 [VIP, R$ 200, sem atraso]: Legado = R$ {v_antes:.2f} | Refatorado = R$ {v_depois:.2f}")
    assert v_antes == float(v_depois)

    # Caso 2: Padrão adimplente > R$ 100
    v_antes_padrao = calcular_desconto_legado("PADRAO", 200, 0)
    v_depois_padrao = calcular_desconto_refatorado("PADRAO", Decimal("200.00"), 0)
    print(f"Caso 2 [Padrão, R$ 200, sem atraso]: Legado = R$ {v_antes_padrao:.2f} | Refatorado = R$ {v_depois_padrao:.2f}")
    assert v_antes_padrao == float(v_depois_padrao)

    # Caso 3: Cliente com atraso
    v_atraso = calcular_desconto_refatorado("VIP", Decimal("500.00"), 3)
    print(f"Caso 3 [VIP, com 3 dias de atraso]: Desconto = R$ {v_atraso:.2f}")
    assert v_atraso == Decimal("0.00")

    print("✅ Todos os comportamentos preservados com sucesso após a refatoração!")

🚀 Como Executar

Execute o script diretamente no terminal:

python refatoracao_exemplo.py

🖥️ Saída Esperada no Terminal

--- Comparativo de Refatoração: Legado vs. Guard Clauses ---
Caso 1 [VIP, R$ 200, sem atraso]: Legado = R$ 30.00 | Refatorado = R$ 30.00
Caso 2 [Padrão, R$ 200, sem atraso]: Legado = R$ 10.00 | Refatorado = R$ 10.00
Caso 3 [VIP, com 3 dias de atraso]: Desconto = R$ 0.00
✅ Todos os comportamentos preservados com sucesso após a refatoração!

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• 4 Tipos de Manutenção: Corretiva (Bugs), Adaptativa (Ambiente), Perfectiva (Qualidade/Refatoração) e Preventiva (Previsão de Falhas).
• Débito Técnico: Metáfora que quantifica o custo oculto de atalhos e decisões de engenharia de baixa qualidade.
• Leis de Lehman: O software degrada naturalmente a menos que receba investimentos contínuos de refatoração.
• Boy Scout Rule: Manter o hábito diário de limpar e melhorar pequenos trechos de código em cada commit.

🌿 CAPÍTULO 19: GERÊNCIA DE CONFIGURAÇÃO (SCM) E GIT

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Dominar os fundamentos de Software Configuration Management (SCM), Linhas de Base (Baselines), Itens de Configuração (CIs) e Auditoria de Configuração (IEEE 828).
• 🔹 Aplicar estratégias avançadas de ramificação com Git (GitFlow: main, develop, feature/*, release/*, hotfix/*).
• 🔹 Padronizar o histórico de commits utilizando o padrão da indústria Conventional Commits (feat:, fix:, refactor:, test:).
• 🔹 Estruturar releases segundo o Versionamento Semântico (SemVer: MAJOR.MINOR.PATCH).

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, mais de 40 desenvolvedores atuam simultaneamente no repositório do sistema de fretes. Sem regras de governança, alterações incompletas eram enviadas diretamente para a branch main, quebrando o ambiente de homologação e sobrescrevendo códigos de outros colegas de time.

O Desafio: Como Engenheiro de Release e SCM, você deve instituir a política de governança de código: proteção de branch main, fluxo GitFlow estrito, Conventional Commits e pipelines de validação com pre-commit hooks que bloqueiam código sem formatação ou com testes quebrados.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. O Fluxo de Trabalho GitFlow

Estratégia consolidada de isolamento de branches para times multidisciplinares:

gitGraph
    commit id: "v1.0.0" tag: "v1.0.0"
    branch develop
    checkout develop
    commit id: "Setup Inicial"
    branch feature/checkout
    checkout feature/checkout
    commit id: "feat: add pix"
    commit id: "test: pix handler"
    checkout develop
    merge feature/checkout id: "Merge feature"
    branch release/1.1.0
    checkout release/1.1.0
    commit id: "docs: changelog"
    checkout main
    merge release/1.1.0 id: "Merge release" tag: "v1.1.0"
    checkout develop
    merge release/1.1.0 id: "Sync develop"

3.2. Versionamento Semântico 2.0.0 (SemVer)

O formato MAJOR.MINOR.PATCH comunica a compatibilidade das atualizações:

flowchart TD
    subgraph SEMVER ["VERSIONAMENTO SEMÂNTICO (SemVer)"]
        M["🔴 MAJOR (ex: 2.0.0)<br>Alterações incompatíveis com versões anteriores (Breaking Changes)"]
        MI["🟡 MINOR (ex: 1.2.0)<br>Adição de novas funcionalidades mantendo total compatibilidade regressiva"]
        P["🟢 PATCH (ex: 1.1.3)<br>Correções de bugs e patches de segurança sem alteração de API"]
    end
    style M fill:#fee2e2,stroke:#ef4444
    style MI fill:#fef3c7,stroke:#d97706
    style P fill:#dcfce7,stroke:#16a34a

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

📋 Pré-requisitos e Instalação

Este exemplo utiliza os módulos padrão re e sys do Python, sem necessidade de pacotes externos:

python --version  # Requer Python 3.11 ou superior

💻 Código Completo e Autocontido (validar_conventional_commits.py)

Script em Python para validação automatizada de mensagens de commit (Pre-commit Hook) seguindo a especificação Conventional Commits:

"""
Módulo: validar_conventional_commits.py
Domínio: Auditoria de mensagens de commit segundo a convenção da indústria.
"""
import re
import sys

# Padrão: tipo(escopo opcional): descrição
PADRAO_COMMIT = r"^(feat|fix|docs|style|refactor|test|chore|ci)(\([a-z0-9_-]+\))?:\s[a-z0-9].{5,72}$"

def validar_mensagem_commit(mensagem: str) -> bool:
    mensagem = mensagem.strip()
    if not re.match(PADRAO_COMMIT, mensagem):
        print(f"❌ FORMATO DE COMMIT INVÁLIDO: '{mensagem}'")
        print("   Exemplos corretos:")
        print("   - feat(fretes): adicionar calculo de cubagem por volume")
        print("   - fix(auth): corrigir expiracao do token jwt")
        print("   - test(pedidos): adicionar testes de integracao com pytest")
        return False
    print(f"✅ Commit válido: '{mensagem}'")
    return True

if __name__ == "__main__":
    print("--- Auditoria de Mensagens de Commit (Conventional Commits) ---")
    
    # 1. Caso válido
    msg_correta = "feat(rastreio): integrar websocket de notificacao em tempo real"
    ok1 = validar_mensagem_commit(msg_correta)
    assert ok1 is True

    # 2. Caso inválido (sem tipo e formato fora do padrão)
    msg_errada = "arrumando bug no login"
    ok2 = validar_mensagem_commit(msg_errada)
    assert ok2 is False

🚀 Como Executar

Execute o script diretamente no terminal:

python validar_conventional_commits.py

🖥️ Saída Esperada no Terminal

--- Auditoria de Mensagens de Commit (Conventional Commits) ---
✅ Commit válido: 'feat(rastreio): integrar websocket de notificacao em tempo real'
❌ FORMATO DE COMMIT INVÁLIDO: 'arrumando bug no login'
   Exemplos corretos:
   - feat(fretes): adicionar calculo de cubagem por volume
   - fix(auth): corrigir expiracao do token jwt
   - test(pedidos): adicionar testes de integracao com pytest

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• SCM é Governança: Controla a evolução ordenada e rastreável de todos os artefatos de código, modelos e configurações.
• GitFlow: Isola o trabalho em branches dedicadas (feature, develop, release, hotfix, main).
• Conventional Commits: Cria um histórico de commits legível por humanos e por ferramentas de automação de changelog.
• SemVer: Regra global de transparência (MAJOR.MINOR.PATCH) para evolução de bibliotecas e APIs.

🚀 CAPÍTULO 20: CONCLUSÃO, DEVSECOPS E MÉTRICAS DORA

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Integrar todas as disciplinas de Engenharia de Software (Processos, Requisitos, Modelagem UML, Qualidade e SCM) sob a cultura DevSecOps.
• 🔹 Dominar as 4 Métricas DORA (DevOps Research and Assessment): Deployment Frequency, Lead Time for Changes, Change Failure Rate e Failed Deployment Recovery Time / MTTR.
• 🔹 Compreender o princípio de Shift-Left Security (Segurança desde as primeiras etapas do ciclo de vida).
• 🔹 Consolidar a entrega do seu Projeto Integrador conectando a arquitetura ao deploy contínuo em produção.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, a alta liderança instituiu uma meta de transformação digital: transformar a empresa em uma organização de alta performance de engenharia (Elite Performer). Para isso, o tempo entre a concepção de uma funcionalidade e sua entrada em produção deve ser reduzido de 3 meses para menos de 1 dia, com taxa de falha de mudança inferior a 5%.

O Desafio: Como Líder Técnico de Engenharia de Software e DevSecOps, você deve orquestrar a cultura, as ferramentas de automação e os testes contínuos para garantir que os 10 Projetos Integradores operem com estabilidade, segurança e observabilidade contínua.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. O Ciclo Infinito de DevSecOps

A segurança e a qualidade deixam de ser uma etapa final isolada e passam a permear cada fase do ciclo de entrega:

flowchart LR
    subgraph DEV ["💻 DESENVOLVIMENTO (DEV)"]
        direction LR
        P["Plan"] --> C["Code"] --> B["Build"] --> T["Test"]
    end
    
    subgraph SEC ["🛡️ SEGURANÇA (SEC)"]
        direction TB
        SAST["SAST / DAST"]
        SCA["SCA (Dependências)"]
        AUDIT["Auditoria de Acessos"]
    end
    
    subgraph OPS ["⚙️ OPERAÇÕES (OPS)"]
        direction LR
        R["Release"] --> D["Deploy"] --> O["Operate"] --> M["Monitor"]
    end
    
    T --> SEC
    SEC --> R
    M -.-> P
    
    style DEV fill:#e0f2fe,stroke:#0284c7
    style SEC fill:#fef3c7,stroke:#d97706
    style OPS fill:#dcfce7,stroke:#16a34a

3.2. As 4 Métricas DORA da Engenharia de Alta Performance

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

📋 Pré-requisitos e Instalação

Este exemplo utiliza os módulos padrão dataclasses do Python, sem necessidade de pacotes externos:

python --version  # Requer Python 3.11 ou superior

💻 Código Completo e Autocontido (calculador_metricas_dora.py)

Implementação de um motor de avaliação contínua de maturidade DevOps baseado nas 4 Métricas DORA do Google:

"""
Módulo: calculador_metricas_dora.py
Domínio: Avaliação contínua de performance e maturidade de engenharia.
"""
from dataclasses import dataclass

@dataclass
class MetricasDORA:
    squad_nome: str
    deploys_por_mes: int
    lead_time_horas: float
    taxa_falha_percentual: float
    tempo_recuperacao_horas: float

    def classificar_maturidade(self) -> str:
        if (self.deploys_por_mes >= 30 and 
            self.lead_time_horas <= 24 and 
            self.taxa_falha_percentual <= 5.0 and 
            self.tempo_recuperacao_horas <= 1.0):
            return "🏆 ELITE PERFORMER (Nível Google / Amazon / Netflix)"
        elif self.deploys_por_mes >= 4 and self.lead_time_horas <= 168:
            return "🥈 HIGH / MEDIUM PERFORMER (Boa maturidade ágil)"
        else:
            return "⚠️ LOW PERFORMER (Alerta: Alto risco e processos lentos)"

if __name__ == "__main__":
    print("--- Auditoria de Métricas DORA de Engenharia de Software ---")
    
    # Squad A: Práticas Modernas de CI/CD e Testes Automatizados
    squad_alpha = MetricasDORA(
        squad_nome="Squad Alpha (Logística Core)",
        deploys_por_mes=45,
        lead_time_horas=3.5,
        taxa_falha_percentual=2.1,
        tempo_recuperacao_horas=0.5
    )
    
    # Squad B: Processos Manuais e Deploys Esporádicos
    squad_beta = MetricasDORA(
        squad_nome="Squad Beta (Legado)",
        deploys_por_mes=1,
        lead_time_horas=720.0,
        taxa_falha_percentual=48.0,
        tempo_recuperacao_horas=48.0
    )

    for squad in [squad_alpha, squad_beta]:
        print(f"\n📊 {squad.squad_nome}:")
        print(f"   Deploys/mês: {squad.deploys_por_mes} | Lead Time: {squad.lead_time_horas}h")
        print(f"   Taxa Falha: {squad.taxa_falha_percentual}% | MTTR: {squad.tempo_recuperacao_horas}h")
        print(f"   Classificação: {squad.classificar_maturidade()}")

🚀 Como Executar

Execute o script diretamente no terminal:

python calculador_metricas_dora.py

🖥️ Saída Esperada no Terminal

--- Auditoria de Métricas DORA de Engenharia de Software ---

📊 Squad Alpha (Logística Core):
   Deploys/mês: 45 | Lead Time: 3.5h
   Taxa Falha: 2.1% | MTTR: 0.5h
   Classificação: 🏆 ELITE PERFORMER (Nível Google / Amazon / Netflix)

📊 Squad Beta (Legado):
   Deploys/mês: 1 | Lead Time: 720.0h
   Taxa Falha: 48.0% | MTTR: 48.0h
   Classificação: ⚠️ LOW PERFORMER (Alerta: Alto risco e processos lentos)

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• Engenharia de Ponta a Ponta: O ciclo de vida do software é contínuo, integrando pessoas, processos, requisitos, arquitetura e qualidade.
• DevSecOps: A segurança e os testes automatizados são responsabilidade de todos do time desde o primeiro dia.
• Métricas DORA: A excelência de um squad mede-se pela frequência de entrega, tempo de ciclo, baixa taxa de falha e recuperação rápida.
• Profissional do Futuro: O Engenheiro de Software moderno é um solucionador de problemas de negócio guiado por rigor técnico e boas práticas.

📅 CRONOGRAMA — PROJETOS II (ENGENHARIA DE SOFTWARE)

Planejamento de 20 semanas acadêmicas com atividades práticas lineares e autoguiadas, cobrindo todo o ciclo de vida moderno de engenharia e operações de software. 🛡️🧩

📈 Composição da Nota

A disciplina segue o modelo de avaliação da Fatec (Regulamento Geral dos Cursos Superiores de Graduação das Fatecs, Deliberação CEETEPS nº 106/2025). Sem pesos ou pontuações fracionadas por atividade — apenas média aritmética simples. Detalhamento completo, regra do Exame e exemplos de cálculo em docs/institucional/SISTEMA_AVALIACAO_FATEC.md (repositório do projeto).

As semanas de P1 (8) e P2 (15) seguem o calendário oficial do 2º semestre de 2026 (docs/institucional/Calendario-Fatec-Assis-2026.pdf e docs/institucional/FATEC-Calendario 2026-2.jpeg: P1 em 21–25/09, P2 em 13–19/11), considerando que a turma de ES tem aula às sextas-feiras — por isso o corte de período não cai num meio redondo (8 e 12 atividades, não 10 e 10). Note que a semana de P2 é diferente da usada em Banco de Dados (semana 16), porque BD tem aula às terças e ES às sextas — a mesma janela oficial de prova cai em semanas de curso distintas para cada turma. As datas mudam a cada semestre e precisam ser conferidas no calendário vigente; a quantidade de questões da prova também é livre para o professor definir. O que não muda é o cálculo: prova 0–10 com peso igual entre questões; A1/A2 como média aritmética simples das notas do período.

Média Final = (P1 + P2 + A1 + A2) / 4

Aprovação: Média Final ≥ 6,0, com frequência mínima de 75%.

Direito ao Exame (Art. 34 do Regulamento): aluno reprovado por nota (Média Final < 6,0) que cumpriu a frequência mínima de 75% — sem piso mínimo de nota. A forma exata de cálculo da nota pós-exame é proposta pela Coordenação de Curso; a convenção adotada neste componente ((Média Final + Exame) / 2 ≥ 6,0) está pendente de validação formal e detalhada em docs/institucional/SISTEMA_AVALIACAO_FATEC.md.

💡 Nota: o Projeto Integrador Final (Atv 10, Fase I) e o Projeto Final Avançado (Atv 20, Fase II) permanecem como as últimas atividades de cada período — entram na média A1/A2 como qualquer outra atividade, sem peso extra.

⚠️ Esta metodologia está sujeita a alteração conforme decisão da Unidade/Coordenação de Curso. Qualquer mudança será informada previamente aos alunos, antes de entrar em vigor.

🚀 Guia do Aluno & Manual de Início Rápido do Projeto Integrador

Bem-vindo(a) ao Projeto Integrador Interdisciplinar (GTI - FATEC)! Este manual foi criado para orientar você e sua equipe na construção de uma aplicação web corporativa funcional ponta a ponta, integrando os conhecimentos de Engenharia de Software, Banco de Dados e Programação Orientada a Objetos em Python. 🛡️🧩

🎯 1. O que é o Projeto Integrador (PI)?

O Projeto Integrador simula o ambiente profissional de uma Software House ou time de TI corporativo. Você e seu time atuarão como Analistas de Sistemas, percorrendo todo o ciclo de vida de desenvolvimento:

graph LR
    E1["1. Elicitação<br/>(User Stories & Trello)"] --> E2["2. Modelagem<br/>(UML & DER no Draw.io)"]
    E2 --> E3["3. Backend & API<br/>(Flask & SQLAlchemy)"]
    E3 --> E4["4. Frontend Web<br/>(Jinja2 & Bootstrap 5)"]
    E4 --> E5["5. Banco Dual & CI/CD<br/>(SQLite / Docker Postgres)"]

    style E1 fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px
    style E2 fill:#fff8e1,stroke:#fbc02d,stroke-width:2px
    style E3 fill:#e8f5e9,stroke:#43a047,stroke-width:2px
    style E4 fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px
    style E5 fill:#ffebee,stroke:#e53935,stroke-width:2px

👥 2. Formação da Equipe & Papéis Ágeis (2 a 4 Alunos)

Cada integrante assume um papel principal no projeto (com atuação colaborativa em código):

🧭 3. Como Escolher o Tema na Galeria (Matriz 5 Setores × 2 Níveis)

A galeria conta com 10 Projetos Oficiais organizados nos 5 Grandes Setores da Economia Brasileira:

┌──────────────────────────────────────────────────────────────────────────────────┐
│ 🏭 SETOR 1: INDÚSTRIA & PRODUÇÃO                                                 │
│    🟢 Nível 1: PI 01 — ManuTrack (Manutenção Preventiva de Máquinas)             │
│    🔴 Nível 2: PI 02 — StockFlow (Almoxarifado Industrial, Lotes & Curva ABC)    │
├──────────────────────────────────────────────────────────────────────────────────┤
│ 🛒 SETOR 2: COMÉRCIO & VAREJO                                                    │
│    🟢 Nível 1: PI 03 — PDVLite (Frente de Caixa & Balcão de Vendas)              │
│    🔴 Nível 2: PI 04 — ShopFlow (E-commerce B2C, Catálogo & Carrinho)            │
├──────────────────────────────────────────────────────────────────────────────────┤
│ 🛠️ SETOR 3: SERVIÇOS & TECNOLOGIA                                                │
│    🟢 Nível 1: PI 05 — ParkFlow (Estacionamentos & Tarifação)                    │
│    🔴 Nível 2: PI 06 — ServiceFlow (Ordens de Serviço & Gestão de SLA)           │
├──────────────────────────────────────────────────────────────────────────────────┤
│ 🌾 SETOR 4: AGROPECUÁRIA & AGRONEGÓCIO                                           │
│    🟢 Nível 1: PI 07 — AgroSafe (Insumos Agrícolas & Defensivos)                 │
│    🔴 Nível 2: PI 08 — CattleFlow (Pecuária, Rastreabilidade & Vacinação)        │
├──────────────────────────────────────────────────────────────────────────────────┤
│ 🏢 SETOR 5: FINANCEIRO E IMOBILIÁRIO                                             │
│    🟢 Nível 1: PI 09 — FinLite (Contas a Pagar/Receber & Fluxo de Caixa)         │
│    🔴 Nível 2: PI 10 — ImobiFlow (Gestão Imobiliária, Contratos & Locação)       │
└──────────────────────────────────────────────────────────────────────────────────┘

[!TIP] Como Escolher:

• Grupos em Consolidação de Base: Escolham projetos de Nível 1 (🟢 Essencial / 3 a 4 Tabelas). Vocês entregarão um sistema 100% funcional com relacionamentos 1:N diretos.
• Grupos Avançados / Desafiadores: Escolham projetos de Nível 2 (🔴 Intermediário / 5 a 7 Tabelas), implementando relacionamentos N:N, transações ACID e relatórios analíticos.

⚡ 4. Setup do Ambiente em 3 Minutos no VS Code

O curso disponibiliza um template oficial pronto para clonar na pasta:
📂 examples/template_projeto_integrador/

Passo a Passo de Execução:

1. Instale as Extensões Recomendadas no VS Code: Abra o projeto e aceite a instalação do pacote .vscode/extensions.json (Python, Jinja, SQLTools, Docker, Draw.io).

2. Crie e Ative seu Ambiente Virtual:

   python -m venv venv
   # No Windows (PowerShell):
   .\venv\Scripts\Activate.ps1
   # No Linux/Mac:
   source venv/bin/activate
   

3. Instale as Dependências:

   pip install -r requirements.txt
   

4. Execute o Sistema com SQLite (Zero Configuração no Dia 1):

   python main.py
   

   • 🌐 Aplicação Web & API: http://localhost:5000

5. Execute a Suíte de Testes Automatizados:

   pytest
   

📅 5. Cronograma de Entregas e Rubricas de Avaliação

timeline
    title Linha do Tempo do Projeto Integrador (20 Semanas)
    Semana 04 : Entrega 1 - Concepção e Escopo : Documento de Visão, Personas e User Stories no Trello
    Semana 08 : Entrega 2 - Modelagem de Engenharia : Casos de Uso, Diagrama de Classes e DER 3FN no Draw.io
    Semana 14 : Entrega 3 - Backend e Persistência : API Flask, Modelos SQLAlchemy e Banco Dual
    Semana 20 : Entrega 4 - Entrega Final : Aplicação Web Jinja2, Testes Pytest, Docker e Apresentação

Rubrica Oficial de Pontuação:

🛡️ 6. Regras de Ouro para o Sucesso da Equipe

1. A "Regra dos Três Mundos": Certifique-se de que cada tabela SQL tenha sua classe correspondente em Python e seu bloco no Diagrama de Classes UML.
2. Commits Frequentes: Não deixem para subir código no último dia. Usem Git e branches de funcionalidade (feature/nova-tela).
3. Qualidade desde o Dia 1: Escrevam testes simples com pytest para garantir que o que funciona hoje continue funcionando amanhã.
4. Comunicação Clara: O software profissional é aquele que qualquer desenvolvedor consegue clonar, rodar e entender em menos de 5 minutos! 🚀🛡️

🗺️ 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!

🎯 ATIVIDADE 01: ESCOPO E PERSONAS

Bem-vindo a mais uma etapa da sua jornada no curso de Gestão de TI / Desenvolvimento de Sistemas. Hoje vamos mergulhar em conceitos que conectam a teoria técnica diretamente com o padrão de excelência da indústria, definindo as bases de um projeto real de Engenharia de Software. 🛡️🧩

🎯 Objetivos de Aprendizagem do Laboratório

Ao final deste laboratório prático (estimativa: 4 horas presenciais / autoguiadas), você será capaz de:

• Definir um Escopo claro de projeto, diferenciando o que o sistema fará (In) do que não fará (Out).
• Criar Personas que representem usuários reais, mapeando suas dores e necessidades.
• Documentar a ideia central de um software profissional de ponta a ponta.

🏢 O Cenário Prático (Seu Desafio)

Imagine que você é o Líder de Produto (Product Owner) da TecProExpress. A diretoria identificou que os motoristas terceirizados estão com dificuldades para encontrar as entregas do dia, e o SAC está lotado de clientes perguntando "Onde está meu pacote?". O desafio desta semana é:

"Você precisa documentar a proposta de um novo App de Rastreamento. Sua primeira missão é definir o Escopo do projeto (para não estourar o orçamento da empresa) e descrever exatamente quem são as Personas (O Motorista e O Cliente) que vão usar a ferramenta."

🧠 Fundamentos: A Teoria Traduzida

Na Engenharia de Software, não saímos programando no primeiro dia. Precisamos alinhar as expectativas com os stakeholders (pessoas interessadas).

Escopo e Personas

• Escopo (Scope): É o limite do projeto. Se o cliente pede um carro, o escopo é o carro; um avião está fora do escopo.
• Persona: É uma representação semi-fictícia do seu cliente ideal baseada em dados reais e suposições educadas. Ela tem nome, dores e objetivos.

📊 Visualizando a Lógica

📖 Exemplo Guiado

Abaixo, veja como aplicar a teoria passo a passo no cenário da TecProExpress.

📊 Delimitação Visual do MVP (Escopo In/Out)

flowchart TD
    subgraph IN [Escopo Ativo - MVP]
        direction TB
        F1["Chave de Ignição: Login Seguro"]
        F2["Painel do Motorista: Lista de Entregas"]
        F3["Status da Carga (Pendente / Trânsito / Entregue)"]
    end
    subgraph OUT [Escopo Futuro - Fora]
        direction TB
        NF1["Gestão Financeira & Comissões"]
        NF2["Algoritmo Avançado de Inteligência Artificial para Rotas"]
    end
    IN -.-> OUT
    style IN fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style OUT fill:#ffebee,stroke:#c62828,stroke-width:2px

🛠️ Exemplo de Documentação

# Projeto: Rastreio Express

**Escopo (In):**
- Login do Motorista.
- Atualização de status da entrega (Pendente, Em Trânsito, Entregue).

**Escopo (Out):**
- Pagamento de comissão do motorista (Fora do escopo atual).

**Persona:**
*Nome:* Roberto "Beto", 45 anos.
*Ocupação:* Motorista Terceirizado.
*Dor:* "O aplicativo antigo trava muito e eu perco tempo ligando pro cliente."
*Objetivo:* Um botão gigante de "Cheguei no local".

🔍 Detalhamento da Documentação:

• Escopo (In): É o MVP (Mínimo Produto Viável).
• Escopo (Out): Protege a equipe de desenvolvimento contra pedidos abusivos que atrasam a entrega.
• Persona: Vai muito além de "homens de 40 a 50 anos". O Beto tem uma Dor e a nossa interface tem que curar essa dor.

🛠️ Prática Obrigatória 1: Definição do Escopo

Cenário: O projeto semestral que você vai desenvolver. Você pode escolher um sistema de Delivery, Gestão Escolar, PetShop ou criar o seu próprio.

1. Dê um Título para o seu sistema.
2. Escreva 1 parágrafo descrevendo "O Problema" que ele resolve.
3. Liste 3 funcionalidades que estão Dentro (In) do escopo.
4. Liste 2 funcionalidades que estão Fora (Out) do escopo.

🏁 Resultado Esperado (Para sua Referência)

Você deverá gerar um documento (Markdown ou PDF) contendo essas definições claras, sem jargões excessivos, provando que você sabe limitar o tamanho do seu projeto.

💻 Validação Prática & Resultado Esperado no Terminal

Para apoiar a análise automatizada do seu escopo, utilize o script de validação de requisitos e personas em Python:

# validar_escopo.py
import json

projeto = {
    "nome": "TecProExpress - App de Rastreamento",
    "mvp_in": ["Autenticação de Motorista", "Lista de Entregas do Dia", "Atualização de Status"],
    "mvp_out": ["Módulo Financeiro de Comissões", "Algoritmo de Roteirização por IA"],
    "personas": [
        {"nome": "Roberto 'Beto'", "papel": "Motorista Terceirizado", "dor": "App antigo trava e exige ligações"},
        {"nome": "Mariana Lima", "papel": "Cliente Destinatária", "dor": "Incerteza sobre horário de entrega"}
    ]
}

print("=" * 60)
print(f"🚀 VALIDADOR DE ESCOPO: {projeto['nome']}")
print("=" * 60)
print(f"✅ Itens no Escopo (IN): {len(projeto['mvp_in'])} funcionalidades")
for item in projeto["mvp_in"]:
    print(f"   • [IN]  {item}")

print(f"\n⛔ Itens Fora do Escopo (OUT): {len(projeto['mvp_out'])} funcionalidades")
for item in projeto["mvp_out"]:
    print(f"   • [OUT] {item}")

print(f"\n👥 Personas Mapeadas: {len(projeto['personas'])}")
for p in projeto["personas"]:
    print(f"   • {p['nome']} ({p['papel']}) -> Dor: \"{p['dor']}\"")
print("=" * 60)

🖥️ Saída Esperada no Terminal:

============================================================
🚀 VALIDADOR DE ESCOPO: TecProExpress - App de Rastreamento
============================================================
✅ Itens no Escopo (IN): 3 funcionalidades
   • [IN]  Autenticação de Motorista
   • [IN]  Lista de Entregas do Dia
   • [IN]  Atualização de Status

⛔ Itens Fora do Escopo (OUT): 2 funcionalidades
   • [OUT] Módulo Financeiro de Comissões
   • [OUT] Algoritmo de Roteirização por IA

👥 Personas Mapeadas: 2
   • Roberto 'Beto' (Motorista Terceirizado) -> Dor: "App antigo trava e exige ligações"
   • Mariana Lima (Cliente Destinatária) -> Dor: "Incerteza sobre horário de entrega"
============================================================

🌐 Exemplo de Payload JSON para Cadastro de Personas (Swagger /docs)

{
  "nome": "Roberto 'Beto'",
  "idade": 45,
  "ocupacao": "Motorista Terceirizado",
  "dores": [
    "Aplicativo antigo trava com frequência",
    "Perda de tempo ligando para o cliente para confirmar endereço"
  ],
  "objetivos": [
    "Confirmar entrega com apenas 1 toque na tela",
    "Visualizar rota consolidada do dia"
  ]
}

📤 Instruções de Entrega (Microsoft Teams)

Após validar as suas definições de engenharia:

1. Salve o arquivo de documentação com o nome Atividade_01.md na pasta es-atv-01-escopo/ do seu repositório GitHub.
2. Certifique-se de fazer o commit e push para o repositório público.
3. Submeta o link do seu repositório no Microsoft Teams para avaliação do professor.

💡 Checkpoint de Lógica

🔥 Desafio de Fixação (Opcional)

Nível: Expert 🏆

Se você terminou rápido, expanda o seu escopo criando a "Matriz de Priorização (MoSCoW)":

• Must have (Deve ter)
• Should have (Deveria ter)
• Could have (Poderia ter)
• Won't have (Não vai ter nesta versão)

Classifique as funcionalidades do seu projeto nessas 4 categorias e anexe ao documento final.

📊 Rubrica Formativa de Avaliação

🎯 ATIVIDADE 02: MODELOS DE PROCESSO DE SOFTWARE

Bem-vindo a mais uma etapa da sua jornada no curso de Gestão de TI / Desenvolvimento de Sistemas. Hoje vamos mergulhar em conceitos que conectam a teoria técnica diretamente com o padrão de excelência da indústria, definindo as engrenagens de como a sua equipe vai trabalhar. 🛡️🧩

🎯 Objetivos de Aprendizagem do Laboratório

Ao final deste laboratório prático (estimativa: 4 horas presenciais / autoguiadas), você será capaz de:

• Diferenciar modelos Preditivos (Cascata/Waterfall) de modelos Adaptativos (Ágeis, Scrum, Kanban).
• Justificar tecnicamente a escolha de um processo de software com base no nível de incerteza do escopo.
• Definir papéis gerenciais e operacionais (ex: Product Owner, Scrum Master, Dev Team).

🏢 O Cenário Prático (Seu Desafio)

A diretoria da TecProExpress aprovou o escopo do seu "App de Rastreamento" (Atividade 01). Agora, o Gerente de Projetos quer saber: "Como vocês vão construir isso?"

Um diretor mais antigo sugeriu o uso do Modelo Cascata, exigindo que a equipe entregue o software completo apenas daqui a 6 meses. O seu time de desenvolvimento, no entanto, acredita que o mercado é muito volátil e prefere o Scrum para fazer entregas mensais.

"Seu desafio é vestir a camisa de Scrum Master / Agile Coach, escolher oficialmente qual modelo o projeto da sua equipe (criado na Atividade 01) vai seguir, e apresentar uma justificativa técnica blindada contra argumentos antigos."

🧠 Fundamentos: A Teoria Traduzida

Não existe um "melhor" modelo de processo de software. Existe o modelo que melhor lida com o nível de risco do seu projeto.

Preditivo vs Adaptativo

• Cascata (Preditivo): Você tem que saber 100% do que o cliente quer no dia 1. Se o cliente mudar de ideia no meio, o projeto falha. Ideal para: Softwares de aviões ou satélites.
• Ágil/Scrum (Adaptativo): Você assume que o cliente não sabe o que quer e vai mudar de ideia. O software é feito em "fatias" (Sprints) e o cliente testa mensalmente. Ideal para: Apps, Sistemas Web, Startups.

📊 Visualizando a Lógica

subgraph Scrum
A2(("Sprint 1")) --> B2(("Sprint 2")) --> C2(("Sprint 3"))
end

---

## 📖 Exemplo Guiado
Abaixo, veja como estruturar a escolha de um processo.

| Passo | Ação de Engenharia | Resultado Esperado |
| :--- | :--- | :--- |
| 01 | Analisar a Incerteza | Alta incerteza (O motorista do App não sabe bem o que quer). |
| 02 | Escolher o Modelo | Scrum. |
| 03 | Definir Papéis | Quem é o Dono do Produto (PO)? Quem programa? |

#### 📊 Jornada de uma Tarefa no Kanban Ágil
```mermaid
flowchart LR
    B["Backlog (Ideias)"] --> TD["To Do (Sprint)"]
    TD --> IP["In Progress"]
    IP --> CR["Code Review"]
    CR --> QA["Testing/QA"]
    QA --> DN["Done (Produção)"]

    style B fill:#eceff1,stroke:#607d8b
    style TD fill:#e1f5fe,stroke:#0288d1
    style IP fill:#fffde7,stroke:#fbc02d
    style CR fill:#f3e5f5,stroke:#8e24aa
    style QA fill:#e8f5e9,stroke:#2e7d32
    style DN fill:#e0f2f1,stroke:#004d40,stroke-width:2px

🛠️ Exemplo de Documentação

# Processo Escolhido: Scrum

**Justificativa:** 
Optamos pelo Scrum porque o aplicativo de rastreio tem alta incerteza. Como não sabemos se os motoristas terceirizados vão se adaptar à interface, precisamos de feedback constante (Sprints de 2 semanas) para corrigir a rota antes do orçamento acabar, coisa que o Cascata não permitiria.

**Papéis no Scrum:**
* **Product Owner (PO):** O Gerente de Logística (Dono do processo).
* **Scrum Master:** O Líder Técnico do projeto.
* **Dev Team:** Os programadores e designers.

🔍 Detalhamento da Documentação:

• A Justificativa não é "porque é mais moderno". É uma defesa baseada na Incerteza e no Custo do Erro.
• O PO (Product Owner) não é um programador. É a pessoa que entende de logística e sabe o que dá dinheiro para a empresa.

🛠️ Prática Obrigatória 1: Escolha e Justificativa

Cenário: O projeto semestral da sua equipe.

1. Declare qual modelo seu projeto vai seguir: Scrum, Kanban ou Cascata.
2. Escreva um parágrafo de no mínimo 4 linhas justificando tecnicamente sua escolha, usando as palavras "Incerteza" e "Feedback".

🏁 Resultado Esperado (Para sua Referência)

Texto argumentativo profissional validando o modelo de trabalho escolhido.

💻 Simulador de Sprint & Burndown em Python

Para vivenciar a cadência de uma Sprint ágil, execute o simulador em Python abaixo:

# simulador_sprint.py
class SprintScrum:
    def __init__(self, nome_sprint: str, duracao_dias: int, total_story_points: int) -> None:
        self.nome_sprint = nome_sprint
        self.duracao_dias = duracao_dias
        self.pontos_restantes = total_story_points
        self.historico = [total_story_points]

    def queimar_pontos_dia(self, dia: int, pontos_entregues: int) -> None:
        self.pontos_restantes = max(0, self.pontos_restantes - pontos_entregues)
        self.historico.append(self.pontos_restantes)
        print(f"📅 Dia {dia:02d}: Entregues {pontos_entregues:02d} pts | Restam: {self.pontos_restantes:02d} pts")

if __name__ == "__main__":
    print("=" * 60)
    print("🏃 SIMULADOR DE BURNDOWN DE SPRINT (SCRUM) - TECPROEXPRESS")
    print("=" * 60)

    sprint = SprintScrum(nome_sprint="Sprint 01 - Autenticação & MVP", duracao_dias=10, total_story_points=34)
    print(f"Meta: {sprint.nome_sprint} | Duração: {sprint.duracao_dias} dias | Backlog: 34 pts\n")

    sprint.queimar_pontos_dia(dia=2, pontos_entregues=5)
    sprint.queimar_pontos_dia(dia=4, pontos_entregues=8)
    sprint.queimar_pontos_dia(dia=7, pontos_entregues=13)
    sprint.queimar_pontos_dia(dia=10, pontos_entregues=8)

    print("-" * 60)
    if sprint.pontos_restantes == 0:
        print("🎉 SPRINT CONCLUÍDA COM 100% DOS PONTOS ENTREGUES!")
    print("=" * 60)

🖥️ Saída Esperada no Terminal:

============================================================
🏃 SIMULADOR DE BURNDOWN DE SPRINT (SCRUM) - TECPROEXPRESS
============================================================
Meta: Sprint 01 - Autenticação & MVP | Duração: 10 dias | Backlog: 34 pts

📅 Dia 02: Entregues 05 pts | Restam: 29 pts
📅 Dia 04: Entregues 08 pts | Restam: 21 pts
📅 Dia 07: Entregues 13 pts | Restam: 08 pts
📅 Dia 10: Entregues 08 pts | Restam: 00 pts
------------------------------------------------------------
🎉 SPRINT CONCLUÍDA COM 100% DOS PONTOS ENTREGUES!
============================================================

🌐 Exemplo de Payload JSON para Criação de Sprint (Swagger /docs)

{
  "nome": "Sprint 01 - Autenticação e Gestão de Entregas",
  "data_inicio": "2026-03-01",
  "data_fim": "2026-03-14",
  "story_points_alvo": 34,
  "product_owner": "Carlos Eduardo (Gerente de Logística)",
  "scrum_master": "Mariana Silva (Líder Técnica)",
  "itens_backlog": [
    {"id": "US-01", "titulo": "Login do Motorista via Token JWT", "pontos": 5},
    {"id": "US-02", "titulo": "Lista de Pacotes Atribuídos", "pontos": 8},
    {"id": "US-03", "titulo": "Atualização de Status de Entrega", "pontos": 13}
  ]
}

📤 Instruções de Entrega (Microsoft Teams)

Após validar suas documentações técnicas:

1. Salve o arquivo de documentação com o nome Atividade_02.md na pasta es-atv-02-processos/ do seu repositório GitHub.
2. Certifique-se de fazer o commit e push para o repositório público.
3. Submeta o link do seu repositório no Microsoft Teams para avaliação do professor.

💡 Checkpoint de Lógica

📊 Rubrica Formativa de Avaliação

🎯 ATIVIDADE 03: ENGENHARIA DE REQUISITOS (FR E NFR)

Bem-vindo a mais uma etapa da sua jornada no curso de Gestão de TI / Desenvolvimento de Sistemas. Hoje vamos mergulhar em conceitos que conectam a teoria técnica diretamente com o padrão de excelência da indústria, aprendendo a redigir o contrato técnico que guiará todos os programadores. 🛡️🧩

🎯 Objetivos de Aprendizagem do Laboratório

Ao final deste laboratório prático (estimativa: 4 horas presenciais / autoguiadas), você será capaz de:

• Diferenciar Requisitos Funcionais (RF) (O que o sistema faz) de Requisitos Não-Funcionais (RNF) (Como o sistema se comporta).
• Redigir requisitos com alto rigor técnico utilizando o padrão de escrita: "O sistema deve...".
• Aplicar uma matriz de priorização de requisitos (Essencial, Importante, Desejável).

🏢 O Cenário Prático (Seu Desafio)

Na TecProExpress, após o seu time decidir utilizar a metodologia ágil (Atividade 02), a diretoria começou a bombardear a equipe com ideias para o novo App de Rastreamento. O diretor de Vendas quer que o App tenha "um mapa bem bonito e rápido". O diretor de Logística quer "um botão de pânico para o motorista".

Ouvindo essas demandas soltas, os desenvolvedores não sabem o que programar primeiro, nem como medir se o mapa é "bonito e rápido" o suficiente.

"Seu desafio é atuar como Engenheiro de Requisitos. Você deve traduzir as falas confusas e abstratas da diretoria em Requisitos Funcionais e Não-Funcionais matemáticos, testáveis e priorizados, criando a lista mestra que o time de desenvolvimento vai usar para trabalhar."

🧠 Fundamentos: A Teoria Traduzida

A Engenharia de Requisitos é a arte de extrair a verdade. Se o requisito for mal escrito, o programador criará o código errado.

Funcional vs Não-Funcional

• Funcional (RF): É uma ação. É um botão que você clica, uma tela que abre, um cálculo que é feito. (Ex: "O sistema deve calcular o frete").
• Não-Funcional (RNF): É a infraestrutura, a performance, a segurança. Você não clica num RNF, você o sente. (Ex: "O cálculo do frete deve ser respondido em menos de 2 segundos").

📊 Visualizando a Lógica

📖 Exemplo Guiado

Abaixo, veja como categorizar e escrever requisitos de forma profissional.

📊 Priorização MoSCoW dos Requisitos da TecProExpress

flowchart TD
    subgraph MUST [Must Have - Essencial]
        M1["RF01: Login do Motorista"]
        M2["RF02: Listar Entregas do Dia"]
    end
    subgraph SHOULD [Should Have - Importante]
        S1["RF03: Roteirização Automática"]
    end
    subgraph COULD [Could Have - Desejável]
        C1["RF04: Som ao atribuir carga"]
    end
    MUST --> SHOULD --> COULD

    style MUST fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style SHOULD fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
    style COULD fill:#fffde7,stroke:#fbc02d,stroke-width:2px

🛠️ Estrutura de Documentação de Requisitos

# Lista de Requisitos (App Rastreio Express)

## Requisitos Funcionais (RF)
| ID | Descrição | Prioridade |
| :--- | :--- | :--- |
| RF01 | O sistema deve permitir que o motorista faça login via CPF e Senha. | Essencial |
| RF02 | O sistema deve listar as entregas do dia em ordem de distância. | Importante |
| RF03 | O sistema deve emitir um som quando um novo pacote for atribuído. | Desejável |

## Requisitos Não-Funcionais (RNF)
| ID | Categoria | Descrição |
| :--- | :--- | :--- |
| RNF01 | Performance | A listagem de entregas deve carregar em < 2 segundos. |
| RNF02 | Segurança | As senhas devem ser criptografadas em BCrypt no banco. |

🔍 Detalhamento da Documentação:

• A Prioridade salva projetos. Se o prazo apertar, o time corta os requisitos "Desejáveis" para garantir que o "Essencial" suba para produção.
• Categorias de RNF: Podem ser de Performance, Segurança, Usabilidade ou Tecnológicas.

💻 Matriz de Rastreabilidade & Validador de Requisitos em Python

Para auditar se seus requisitos possuem métricas verificáveis e priorização definida, execute o validador:

# validador_requisitos.py
requisitos_funcionais = [
    {"id": "RF01", "desc": "Autenticação do motorista via CPF e Senha", "prioridade": "Essencial"},
    {"id": "RF02", "desc": "Listagem de entregas ordenadas por distância", "prioridade": "Importante"},
    {"id": "RF03", "desc": "Notificação sonoro-visual ao atribuir nova entrega", "prioridade": "Desejável"}
]

requisitos_nao_funcionais = [
    {"id": "RNF01", "categoria": "Performance", "criterio": "Tempo de resposta < 2.0s sob 500 req/s"},
    {"id": "RNF02", "categoria": "Segurança", "criterio": "Criptografia de senhas com algoritmo BCrypt (salt >= 12)"}
]

print("=" * 65)
print("📋 MATRIZ DE RASTREABILIDADE DE REQUISITOS - TECPROEXPRESS")
print("=" * 65)

print(f"🔹 Requisitos Funcionais ({len(requisitos_funcionais)} catalogados):")
for rf in requisitos_funcionais:
    print(f"   • [{rf['id']}] [{rf['prioridade']:<10}] {rf['desc']}")

print(f"\n🔸 Requisitos Não-Funcionais ({len(requisitos_nao_funcionais)} catalogados):")
for rnf in requisitos_nao_funcionais:
    print(f"   • [{rnf['id']}] [{rnf['categoria']:<11}] Critério: {rnf['criterio']}")

print("=" * 65)

🖥️ Saída Esperada no Terminal:

=================================================================
📋 MATRIZ DE RASTREABILIDADE DE REQUISITOS - TECPROEXPRESS
=================================================================
🔹 Requisitos Funcionais (3 catalogados):
   • [RF01] [Essencial ] Autenticação do motorista via CPF e Senha
   • [RF02] [Importante] Listagem de entregas ordenadas por distância
   • [RF03] [Desejável ] Notificação sonoro-visual ao atribuir nova entrega

🔸 Requisitos Não-Funcionais (2 catalogados):
   • [RNF01] [Performance] Critério: Tempo de resposta < 2.0s sob 500 req/s
   • [RNF02] [Segurança  ] Critério: Criptografia de senhas com algoritmo BCrypt (salt >= 12)
=================================================================

🌐 Exemplo de Payload JSON para Catálogo de Requisitos (Swagger /docs)

{
  "codigo": "RF01",
  "modulo": "Autenticação",
  "descricao": "O sistema deve permitir que o motorista faça login via CPF e Senha",
  "prioridade": "Essencial",
  "criterios_aceite": [
    "Retornar token JWT válido por 8 horas",
    "Bloquear conta temporariamente após 5 tentativas inválidas"
  ],
  "rastreabilidade_testes": [
    "tests/test_auth.py::test_login_sucesso",
    "tests/test_auth.py::test_login_bloqueio"
  ]
}

📤 Instruções de Entrega (Microsoft Teams)

Após validar suas documentações técnicas:

1. Salve o arquivo de documentação com o nome Atividade_03.md na pasta es-atv-03-requisitos/ do seu repositório GitHub.
2. Certifique-se de fazer o commit e push para o repositório público.
3. Submeta o link do seu repositório no Microsoft Teams para avaliação do professor.

💡 Checkpoint de Lógica

📊 Rubrica Formativa de Avaliação

📝 ATIVIDADE 04: USER STORIES E BACKLOG

Bem-vindo a mais uma etapa da sua jornada no curso de Gestão de TI / Desenvolvimento de Sistemas. Hoje vamos mergulhar em conceitos que conectam a teoria técnica diretamente com o padrão de excelência da indústria ágil, mudando o foco do "O Quê" para o "Por Quê". 🛡️🧩

🎯 Objetivos de Aprendizagem do Laboratório

Ao final deste laboratório prático (estimativa: 4 horas presenciais / autoguiadas), você será capaz de:

• Converter Requisitos Funcionais tradicionais em User Stories (Histórias de Usuário).
• Redigir histórias no padrão internacional da agilidade: "Como [Persona], Eu quero [Ação], Para que [Valor]".
• Criar Critérios de Aceite testáveis para definir o que significa uma tarefa "Pronta" (DoD).
• Priorizar e organizar um Product Backlog.

🏢 O Cenário Prático (Seu Desafio)

Na TecProExpress, você entregou a lista de Requisitos Funcionais (Atividade 03) para a equipe de programadores. Um dos requisitos era: "RF01: O sistema deve ter uma barra de busca na tela inicial".

Os programadores criaram uma barra de busca linda, mas ela só buscava clientes pelo CPF. Quando os motoristas tentaram usar, ficaram furiosos, pois eles queriam buscar o endereço do cliente, não o CPF! O requisito foi cumprido tecnicamente, mas falhou comercialmente por falta de empatia e contexto.

"Seu desafio como Product Owner / Analista é impedir que isso aconteça novamente. Você deve pegar seus requisitos frios e reescrevê-los como User Stories, colocando o desenvolvedor na 'pele' da Persona, e escrevendo Critérios de Aceite que não deixem margem para dúvidas sobre como a funcionalidade deve se comportar."

🧠 Fundamentos: A Teoria Traduzida

Na agilidade, nós não escrevemos ordens genéricas, escrevemos "histórias" curtas que justificam o esforço do programador.

O Padrão da User Story

Uma boa história deve caber em um post-it. Ela tem 3 partes:

1. Como [Papel/Persona]: Quem precisa disso?
2. Eu quero [Ação]: O que o sistema tem que fazer?
3. Para que [Valor/Benefício]: Por que isso é importante? Qual a dor que resolve?

📊 Visualizando a Lógica

📖 Exemplo Guiado

Abaixo, veja como aplicar a técnica de User Stories e Critérios de Aceite no contexto da TecProExpress.

📊 Decomposição Ágil: Do Épico aos Critérios de Aceite

flowchart TD
    EP["Épico: Logística Last-Mile"] --> F1["Feature: Rastreamento em Tempo Real"]
    EP --> F2["Feature: Painel de Gestão Comercial"]
    F1 --> US1["US01: Atualização de Status da Carga"]
    F1 --> US2["US02: Geolocalização de Motoristas"]
    US1 --> CA1["Critério 1: Status 'Entregue' exige comprovante"]
    US1 --> CA2["Critério 2: Notificar cliente em < 5s"]

    style EP fill:#eceff1,stroke:#607d8b,stroke-width:2px
    style F1 fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
    style F2 fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
    style US1 fill:#fffde7,stroke:#fbc02d,stroke-width:2px
    style US2 fill:#fffde7,stroke:#fbc02d,stroke-width:2px

🛠️ Estrutura do Backlog

# Product Backlog (Priorizado)

## US01: Destaque de Pedidos Atrasados
**Como** Dona Silvana,
**Quero** ver os pedidos com prazo vencido destacados na cor vermelha,
**Para que** eu possa focar nas cobranças mais urgentes assim que abrir o sistema.

**Critérios de Aceite:**
1. Pedidos com data de vencimento < Data de Hoje devem ter a cor de fundo #FF0000.
2. A tela deve apresentar um botão no topo "Filtrar apenas atrasados".
3. Se não houver pedidos atrasados, exibir mensagem: "Tudo em dia!".

## US02: ...

🔍 Detalhamento da Documentação:

• Ao ler a US01, o programador entende a dor da Dona Silvana. Ele não fará apenas um "IF", ele entenderá o valor do negócio.
• Os Critérios de Aceite são o roteiro que o testador de QA (Quality Assurance) usará para aprovar ou reprovar a entrega da equipe.
• O documento completo forma o Product Backlog, que deve sempre estar organizado de cima para baixo (do mais importante para o menos importante).

💻 Parser e Validador de User Stories (INVEST) em Python

Para auditar se suas histórias de usuário seguem as boas práticas ágeis (modelo INVEST), execute o analisador:

# validador_backlog.py
user_stories = [
    {
        "id": "US01",
        "persona": "Dona Silvana (Gerente Financeira)",
        "acao": "ver os pedidos com prazo vencido destacados em vermelho",
        "beneficio": "focar nas cobranças mais urgentes logo ao abrir o painel",
        "criterios": [
            "Pedidos com vencimento < Hoje exibem badge vermelho #FF0000",
            "Filtro rápido 'Apenas Atrasados' no topo da listagem"
        ],
        "story_points": 5
    },
    {
        "id": "US02",
        "persona": "Roberto Beto (Motorista)",
        "acao": "confirmar entrega com leitura de QR Code",
        "beneficio": "evitar preenchimento manual de formulários durante a rota",
        "criterios": [
            "Validação criptográfica do QR Code da nota fiscal",
            "Registro offline caso não haja conexão 4G imediata"
        ],
        "story_points": 8
    }
]

print("=" * 65)
print("📝 BACKLOG ÁGIL & AUDITORIA DE USER STORIES - TECPROEXPRESS")
print("=" * 65)

for us in user_stories:
    print(f"\n🏷️  [{us['id']}] - Estimativa: {us['story_points']} Story Points")
    print(f"   • Como: {us['persona']}")
    print(f"   • Quero: {us['acao']}")
    print(f"   • Para que: {us['beneficio']}")
    print("   • Critérios de Aceite (DoD):")
    for crit in us["criterios"]:
        print(f"     [✓] {crit}")

print("=" * 65)

🖥️ Saída Esperada no Terminal:

=================================================================
📝 BACKLOG ÁGIL & AUDITORIA DE USER STORIES - TECPROEXPRESS
=================================================================

🏷️  [US01] - Estimativa: 5 Story Points
   • Como: Dona Silvana (Gerente Financeira)
   • Quero: ver os pedidos com prazo vencido destacados em vermelho
   • Para que: focar nas cobranças mais urgentes logo ao abrir o painel
   • Critérios de Aceite (DoD):
     [✓] Pedidos com vencimento < Hoje exibem badge vermelho #FF0000
     [✓] Filtro rápido 'Apenas Atrasados' no topo da listagem

🏷️  [US02] - Estimativa: 8 Story Points
   • Como: Roberto Beto (Motorista)
   • Quero: confirmar entrega com leitura de QR Code
   • Para que: evitar preenchimento manual de formulários durante a rota
   • Critérios de Aceite (DoD):
     [✓] Validação criptográfica do QR Code da nota fiscal
     [✓] Registro offline caso não haja conexão 4G imediata
=================================================================

🌐 Exemplo de Payload JSON para Item do Backlog (Swagger /docs)

{
  "id_historia": "US01",
  "titulo": "Destaque Visual de Pedidos Vencidos",
  "persona": "Dona Silvana (Financeiro)",
  "quero": "visualizar pedidos atrasados com badge vermelho",
  "para_que": "priorizar cobranças e renegociações críticas",
  "story_points": 5,
  "sprint_alvo": 1,
  "criterios_aceite": [
    "Badge #FF0000 visível quando data_vencimento < data_atual",
    "Mensagem 'Tudo em dia!' quando lista atrasada estiver vazia"
  ]
}

📤 Instruções de Entrega (Microsoft Teams)

Após validar seu Backlog Ágil:

1. Salve o arquivo de documentação com o nome Atividade_04.md na pasta es-atv-04-backlog/ do seu repositório GitHub.
2. Certifique-se de fazer o commit e push para o repositório público.
3. Submeta o link do seu repositório no Microsoft Teams para avaliação do professor.

💡 Checkpoint de Lógica

📊 Rubrica Formativa de Avaliação

🎭 ATIVIDADE 05: CASOS DE USO (UML)

Bem-vindo a mais uma etapa da sua jornada no curso de Gestão de TI / Desenvolvimento de Sistemas. Hoje vamos mergulhar em conceitos que conectam a teoria técnica diretamente com o padrão de excelência da indústria visual, transformando requisitos em diagramas universais. 🛡️🧩

🎯 Objetivos de Aprendizagem do Laboratório

Ao final deste laboratório prático (estimativa: 4 horas presenciais / autoguiadas), você será capaz de:

• Identificar Atores (pessoas ou sistemas externos que interagem com o seu software).
• Mapear Casos de Uso (funcionalidades entregues ao ator).
• Aplicar os relacionamentos de dependência <<include>> e <<extend>> corretamente, segundo as normas UML.
• Descrever textualmente o "Caminho Feliz" de um Caso de Uso.

🏢 O Cenário Prático (Seu Desafio)

Na TecProExpress, você escreveu um Backlog incrível (Atividade 04). Mas quando levou os Post-its para a diretoria, o CEO disse: "Não consigo ler isso, são muitos textos soltos. Quero um desenho que me mostre de forma macro o que o Motorista pode fazer e o que o Administrador pode fazer".

"Seu desafio é desenhar o primeiro diagrama oficial da Engenharia de Software: O Diagrama de Casos de Uso. Ele será a 'Planta Baixa' do seu aplicativo, estabelecendo a Fronteira do Sistema (o que está dentro e o que está fora)."

🧠 Fundamentos: A Teoria Traduzida

A UML (Linguagem de Modelagem Unificada) é o idioma mundial da engenharia. Um desenvolvedor japonês que não fala português consegue entender seu projeto se você desenhar em UML.

Elementos Chaves

• Ator (Boneco de Palito): É quem provoca o sistema. (Ex: O Cliente, O Motorista, ou até a API do Banco Central).
• Caso de Uso (Oval): Sempre no infinitivo (Ex: Atualizar Rastreio, Realizar Login).
• Fronteira (Retângulo): A caixa do seu software. Atores ficam de fora, Casos de Uso ficam dentro.

📊 Visualizando a Lógica

📖 Exemplo Guiado

Abaixo, veja como estruturar o cenário do aplicativo de logística da TecProExpress.

📊 Relações de Include e Extend da TecProExpress

flowchart LR
    M(("Motorista")) --> UC1(["Finalizar Entrega"])
    UC1 -. "<< include >>" .-> UC2(["Registrar Geolocalização"])
    UC3(["Registrar Foto do Comprovante"]) -. "<< extend >> (Se falhar GPS)" .-> UC1

    style M fill:#eceff1,stroke:#607d8b,stroke-width:2px
    style UC1 fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
    style UC2 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style UC3 fill:#fffde7,stroke:#fbc02d,stroke-width:2px

🛠️ Especificação Textual do Caso de Uso

Todo oval desenhado precisa de um "Manual de Instruções" por trás dele. Exemplo do Caso "Reportar Atraso":

• Ator Principal: Motorista.
• Pré-condição: O motorista deve estar logado no aplicativo.
• Fluxo Principal (Caminho Feliz):
  1. O motorista seleciona a entrega em andamento.
  2. Clica no botão "Reportar Atraso".
  3. O sistema pede o motivo (Trânsito, Veículo Quebrado, etc).
  4. O motorista seleciona o motivo e confirma.
  5. O sistema atualiza o status e notifica o SAC.
• Pós-condição: O status da entrega muda para "Atrasado".

🔍 Detalhamento da Documentação:

• O Caminho Feliz é a rota perfeita, sem erros. É essencial escrever isso para que o testador de software saiba o que esperar quando tudo dá certo.

🛠️ Prática Obrigatória 1: O Diagrama

Cenário: O projeto semestral da sua equipe.

1. Acesse o draw.io (ou Lucidchart, Astah) e crie um Diagrama de Casos de Uso.
2. Desenhe a Fronteira do Sistema (O retângulo com o nome do App no topo).
3. Insira pelo menos 2 Atores diferentes (do lado de fora).
4. Insira pelo menos 6 Casos de Uso (dentro da fronteira), derivados das suas User Stories.
5. Crie pelo menos uma relação de <<include>> e uma de <<extend>>.

🏁 Resultado Esperado (Para sua Referência)

Um arquivo de imagem (PNG/JPG) com o diagrama organizado, onde as linhas não se cruzam loucamente, provando que você sabe abstrair o macro do sistema.

💻 Simulador de Casos de Uso (Fluxo Principal & Exceções) em Python

Para validar a execução programática do caso de uso "Atualizar Status de Entrega" (incluindo a extensão de atraso), execute o script:

# simulador_caso_uso.py
from datetime import datetime, timezone

class EntregaService:
    def __init__(self, id_entrega: str) -> None:
        self.id_entrega = id_entrega
        self.status = "EM_TRANSITO"
        self.historico = []

    def executar_fluxo_principal_concluir(self) -> None:
        """UC01 - Fluxo Principal: Confirmar Entrega."""
        self.status = "ENTREGUE"
        self.historico.append({"evento": "CONFIRMACAO_ENTREGA", "data": datetime.now(timezone.utc).isoformat()})
        print(f"✅ [UC01 - Fluxo Principal] Entrega {self.id_entrega} concluída com sucesso!")

    def executar_extensao_reportar_atraso(self, motivo: str) -> None:
        """UC01 <<extend>> UC02: Reportar Atraso na Rota."""
        self.status = "ATRASADO"
        self.historico.append({"evento": "REPORTE_ATRASO", "motivo": motivo, "data": datetime.now(timezone.utc).isoformat()})
        print(f"⚠️  [UC02 - Extend] Entrega {self.id_entrega} marcada como ATRASADA. Motivo: '{motivo}'. SAC notificado!")

if __name__ == "__main__":
    print("=" * 65)
    print("🎭 SIMULADOR DE CASOS DE USO & FLUXOS UML - TECPROEXPRESS")
    print("=" * 65)

    entrega1 = EntregaService("PKG-9901")
    entrega2 = EntregaService("PKG-9902")

    # 1. Executando Caminho Feliz (Fluxo Principal)
    entrega1.executar_fluxo_principal_concluir()

    # 2. Executando Fluxo Alternativo/Extensão
    entrega2.executar_extensao_reportar_atraso("Pneu furado na Rodovia Anhanguera")

    print("-" * 65)
    print(f"Status Final PKG-9901: {entrega1.status}")
    print(f"Status Final PKG-9902: {entrega2.status}")
    print("=" * 65)

🖥️ Saída Esperada no Terminal:

=================================================================
🎭 SIMULADOR DE CASOS DE USO & FLUXOS UML - TECPROEXPRESS
=================================================================
✅ [UC01 - Fluxo Principal] Entrega PKG-9901 concluída com sucesso!
⚠️  [UC02 - Extend] Entrega PKG-9902 marcada como ATRASADA. Motivo: 'Pneu furado na Rodovia Anhanguera'. SAC notificado!
-----------------------------------------------------------------
Status Final PKG-9901: ENTREGUE
Status Final PKG-9902: ATRASADO
=================================================================

🌐 Exemplo de Payload JSON para Extensão de Caso de Uso (Swagger /docs)

{
  "id_entrega": "PKG-9902",
  "acao": "REPORTAR_ATRASO",
  "motivo": "Pneu furado na Rodovia Anhanguera",
  "geolocalizacao": {
    "latitude": -23.55052,
    "longitude": -46.633308
  },
  "notificar_cliente_sms": true
}

📤 Instruções de Entrega (Microsoft Teams)

Após validar suas documentações técnicas:

1. Salve o arquivo de documentação com o nome Atividade_05.md e a imagem do seu diagrama com o nome Atividade_05.png na pasta es-atv-05-casos-uso/ do seu repositório GitHub.
2. Certifique-se de fazer o commit e push para o repositório público.
3. Submeta o link do seu repositório no Microsoft Teams para avaliação do professor.

💡 Checkpoint de Lógica

📊 Rubrica Formativa de Avaliação

🖼️ ATIVIDADE 06: PROTOTIPAGEM E WIREFRAMES

Bem-vindo a mais uma etapa da sua jornada no curso de Gestão de TI / Desenvolvimento de Sistemas. Hoje vamos mergulhar em conceitos que conectam a teoria técnica diretamente com o padrão de excelência visual, trazendo a interface do software para o "mundo real" antes mesmo de escrever a primeira linha de código. 🛡️🧩

🎯 Objetivos de Aprendizagem do Laboratório

Ao final deste laboratório prático (estimativa: 4 horas presenciais / autoguiadas), você será capaz de:

• Criar Wireframes (protótipos de baixa fidelidade) focados na funcionalidade, não na estética.
• Projetar a Jornada do Usuário (o fluxo lógico de cliques entre as telas).
• Validar se os requisitos e casos de uso das aulas anteriores estão visíveis e acessíveis na interface (Usabilidade).

🏢 O Cenário Prático (Seu Desafio)

Na TecProExpress, você apresentou o Diagrama de Casos de Uso (Atividade 05). O Diretor de Marketing gostou, mas comentou: "Legal, mas como isso vai aparecer na mão do motorista? Vai ser fácil dele clicar com a mão suja ou usando luvas? Onde fica o botão de emergência?".

"Seu desafio como Designer de Interface (UI/UX) é desenhar o 'esqueleto' (Wireframe) das telas principais. Você não precisa de cores bonitas agora, você precisa provar que o fluxo de navegação é intuitivo o suficiente para que um motorista com pressa consiga usar o App sem treinamento."

🧠 Fundamentos: A Teoria Traduzida

A prototipagem é a ferramenta mais barata da engenharia. É muito mais fácil apagar um desenho do que refazer um banco de dados.

Wireframe vs Protótipo de Alta Fidelidade

• Wireframe (Esqueleto): Preto e branco, focado no lugar dos botões e campos de texto. Resolve a Usabilidade.
• Alta Fidelidade: Cores, logos e imagens reais. Resolve a Estética.

Jornada do Usuário

É o mapa de cliques. Se para fazer um rastreio o motorista precisa clicar em 10 telas diferentes, a sua jornada está ruim. O objetivo é o "Menor Caminho Crítico".

📊 Visualizando a Lógica

📖 Exemplo Guiado

Abaixo, veja como planejar as telas para o aplicativo da TecProExpress.

📊 Fluxo de Transição e Navegação de Telas (TecProExpress)

flowchart TD
    L["Tela de Login (Entrada de Credenciais)"] -->|Autenticação bem-sucedida| D["Dashboard: Lista de Pedidos"]
    L -->|Falha de Login| E["Alerta: Credenciais Inválidas"]
    E -->|Tentar Novamente| L
    D -->|Selecionar Entrega| DET["Detalhes da Carga"]
    DET -->|Voltar| D
    DET -->|Iniciar Rota| MAP["Navegação no Mapa (GPS)"]
    MAP -->|Chegar ao Destino| CONF["Confirmar Recebimento (Câmera)"]
    CONF -->|Upload de Foto| SUC["Mensagem de Sucesso"]
    SUC --> D

    style L fill:#e1f5fe,stroke:#0288d1
    style D fill:#e8f5e9,stroke:#2e7d32
    style CONF fill:#fffde7,stroke:#fbc02d
    style E fill:#ffebee,stroke:#c62828

🛠️ Estrutura de Validação da Tela

Para cada tela desenhada, responda:

1. Qual o objetivo desta tela? (Ex: "Fazer o login").
2. Qual o elemento principal (Call to Action)? (Ex: "Botão Entrar").
3. Quais requisitos da Atividade 03 estão aqui? (Ex: "RF01 - Login").

🔍 Detalhamento do Processo:

• Note que a prototipagem expõe falhas nos requisitos. Se você desenhou um botão de "Esqueci minha senha", mas não escreveu esse requisito na Atividade 03, você acaba de descobrir uma Lacuna de Requisitos. Parabéns, você está fazendo engenharia de verdade!

🛠️ Prática Obrigatória 1: Os Wireframes

Cenário: O projeto semestral da sua equipe.

1. Defina as 3 telas principais do seu sistema.
2. Utilizando uma ferramenta (Figma, Balsamiq, Draw.io ou papel e caneta), desenhe os wireframes (esqueletos) dessas 3 telas.
   • Foque na disposição dos elementos.
   • Use retângulos para botões, "X" em caixas para imagens.
   • Proibido usar cores ou fotos nesta etapa.

🏁 Resultado Esperado (Para sua Referência)

Imagens dos 3 esqueletos (PNG/JPG) mostrando a estrutura lógica da interface.

💻 API Mockup para Validação de Telas (Backend UI) em Python (Flask)

Para validar a integridade dos dados consumidos pelos seus protótipos de interface, instale o Flask e utilize o servidor de mockup abaixo:

pip install flask

# mock_ui_server.py
import sys
from flask import Flask, jsonify

app = Flask(__name__)

DADOS_ENTREGAS = [
    {"id": "ENT-01", "destinatario": "Farmácia Central", "endereco": "Av. Paulista, 1000", "status": "PENDENTE"},
    {"id": "ENT-02", "destinatario": "Mercado Modelo", "endereco": "Rua Augusta, 450", "status": "EM_TRANSITO"}
]

@app.get("/api/v1/entregas/painel")
def obter_dados_tela_entregas():
    """Fornece dados mockados para o Wireframe da Tela 02 (Lista de Entregas)."""
    return jsonify(DADOS_ENTREGAS), 200

if __name__ == "__main__":
    if "--server" in sys.argv:
        print("🚀 Servidor de Mockup de UI rodando em http://127.0.0.1:5000/api/v1/entregas/painel")
        app.run(port=5000, debug=True)
    else:
        print("--- Teste Automatizado do Endpoint de Mockup UI (Flask test_client) ---")
        with app.test_client() as client:
            resposta = client.get("/api/v1/entregas/painel")
            print(f"Status HTTP: {resposta.status_code}")
            print(f"Dados retornados: {resposta.get_json()}")

🚀 Como Executar

Para validar os dados instantaneamente via terminal:

python mock_ui_server.py

Para subir o servidor HTTP local na porta 5000:

python mock_ui_server.py --server

🖥️ Saída Esperada no Terminal:

--- Teste Automatizado do Endpoint de Mockup UI (Flask test_client) ---
Status HTTP: 200
Dados retornados: [{'destinatario': 'Farmácia Central', 'endereco': 'Av. Paulista, 1000', 'id': 'ENT-01', 'status': 'PENDENTE'}, {'destinatario': 'Mercado Modelo', 'endereco': 'Rua Augusta, 450', 'id': 'ENT-02', 'status': 'EM_TRANSITO'}]

🌐 Requisições cURL e Payloads JSON para Prototipagem (Swagger /docs)

🔹 1. Requisição cURL de Teste da Tela:

curl -X GET "http://127.0.0.1:5000/api/v1/entregas/painel" \
     -H "Accept: application/json"

🔹 2. Resposta JSON Recebida pela Interface:

[
  {
    "id": "ENT-01",
    "destinatario": "Farmácia Central",
    "endereco": "Av. Paulista, 1000",
    "status": "PENDENTE"
  },
  {
    "id": "ENT-02",
    "destinatario": "Mercado Modelo",
    "endereco": "Rua Augusta, 450",
    "status": "EM_TRANSITO"
  }
]

📤 Instruções de Entrega (Microsoft Teams)

Após validar seus desenhos:

1. Salve o arquivo de documentação com o nome Atividade_06.md e as imagens dos seus wireframes na pasta es-atv-06-prototipagem/ do seu repositório GitHub.
2. Certifique-se de fazer o commit e push para o repositório público.
3. Submeta o link do seu repositório no Microsoft Teams para avaliação do professor.

💡 Checkpoint de Lógica

📊 Rubrica Formativa de Avaliação

📐 ATIVIDADE 07: DIAGRAMA DE CLASSES (UML)

Bem-vindo a mais uma etapa da sua jornada no curso de Gestão de TI / Desenvolvimento de Sistemas. Hoje vamos mergulhar em conceitos que conectam a teoria técnica diretamente com o padrão de excelência da arquitetura de software, criando o guia mestre para a implementação do código. 🛡️🧩

🎯 Objetivos de Aprendizagem do Laboratório

Ao final deste laboratório prático (estimativa: 4 horas presenciais / autoguiadas), você será capaz de:

• Definir Atributos (o que o objeto guarda) e Métodos (o que o objeto faz).
• Aplicar modificadores de Visibilidade (Público +, Privado -, Protegido #) baseados no princípio do Encapsulamento.
• Modelar Associações e multiplicidade (1:1, 1:N, N:N).
• Identificar oportunidades de Herança para otimização de código.

🏢 O Cenário Prático (Seu Desafio)

Na TecProExpress, os protótipos (Atividade 06) foram aprovados! Agora, o time de desenvolvimento backend (Java/C#/Python) precisa saber: "Como os dados serão organizados no código? Quais são as classes e como elas se conectam?".

Se você apenas disser "Cria uma tabela de motorista", o programador pode esquecer de validar se o motorista tem uma CNH válida ou se ele pode ter vários veículos associados a ele.

"Seu desafio é atuar como Arquiteto de Software. Você deve desenhar o Diagrama de Classes, que é o mapa estrutural que diz ao programador exatamente quais variáveis e funções ele deve criar para que o sistema suporte toda a lógica de logística da TecProExpress."

🧠 Fundamentos: A Teoria Traduzida

O Diagrama de Classes mostra a "foto" parada do sistema. Se o software fosse um prédio, o Diagrama de Classes seria a planta estrutural das paredes e colunas.

Anatomia da Classe

1. Nome: Sempre substantivo e no singular (Ex: Motorista).
2. Atributos (Dados): O que ele sabe? (Ex: - cnh: String).
3. Métodos (Ações): O que ele faz? (Ex: + validarDocumento()).

📊 Visualizando a Lógica

📖 Exemplo Guiado

Abaixo, veja como mapear as entidades da TecProExpress para classes UML.

📊 Graus de Acoplamento e Relacionamentos entre Classes

flowchart LR
    A["Associação Simples<br/>(Uso comum - Acoplamento fraco)"] -->|Motorista - Veiculo| B["Ex: Um motorista dirige um veículo"]
    C["Agregação<br/>(Todo/Parte - Partes vivem sem o todo)"] -->|Pedido - Cliente| D["Ex: Cliente possui pedidos, mas cliente existe sem o pedido"]
    E["Composição<br/>(Todo/Parte rígido - Partes morrem com o todo)"] -->|Pedido - ItemPedido| F["Ex: Pedido possui itens de pedido, se o pedido morre, itens morrem"]

    style A fill:#eceff1,stroke:#607d8b
    style C fill:#e1f5fe,stroke:#0288d1
    style E fill:#ffebee,stroke:#c62828

🛠️ Estrutura de Atributo e Método

• Atributo: - salario: Double = 1412.00
  • -: Privado.
  • salario: Nome.
  • Double: Tipo do dado.
  • = 1412.00: Valor padrão.
• Método: + calcularIdade(dataNasc: Date): Int
  • +: Público.
  • dataNasc: Date: Parâmetro de entrada.
  • : Int: O que o método devolve (Tipo de retorno).

🔍 Detalhamento do Processo:

• Note que no Diagrama de Classes não colocamos "clicar no botão". Colocamos a lógica do objeto. Se o botão na tela chama uma função de salvar, o método salvar() deve estar na Classe.

🛠️ Prática Obrigatória 1: O Diagrama de Classes

Cenário: O projeto semestral da sua equipe.

1. Identifique as 5 principais entidades do seu sistema (ex: Usuário, Produto, Pedido, Categoria, Endereço).
2. Utilizando uma ferramenta UML (Astah, Lucidchart ou Draw.io), desenhe o diagrama.
3. Cada classe deve conter pelo menos 3 atributos e 2 métodos.
4. Defina as multiplicidades corretamente (ex: Um cliente tem 0 ou N pedidos).

🏁 Resultado Esperado (Para sua Referência)

Uma imagem (PNG/JPG) do diagrama contendo as 5 classes conectadas, com tipos de dados e visibilidade (+ e -) aplicados.

💻 Implementação Orientada a Objetos em Python

Para materializar o seu Diagrama de Classes UML em código fonte executável com encapsulamento, execute a classe de domínio:

# modelo_classes.py
from datetime import datetime, timezone
from typing import Any

class EntregaPacote:
    def __init__(self, id_pacote: str, destinatario: str, peso_kg: float) -> None:
        self._id_pacote: str = id_pacote # Atributo Privado (-)
        self._destinatario: str = destinatario
        self._peso_kg: float = peso_kg
        self._status: str = "PENDENTE"
        self._data_criacao: datetime = datetime.now(timezone.utc)

    # Métodos Públicos (+)
    @property
    def status(self) -> str:
        return self._status

    def despachar_entrega(self) -> None:
        if self._status != "PENDENTE":
            raise ValueError("Apenas pacotes pendentes podem ser despachados.")
        self._status = "EM_TRANSITO"
        print(f"📦 Pacote {self._id_pacote} para '{self._destinatario}' despachado com sucesso!")

    def __repr__(self) -> str:
        return f"EntregaPacote(id={self._id_pacote}, dest='{self._destinatario}', status='{self._status}')"

if __name__ == "__main__":
    print("=" * 65)
    print("🏛️ DOMÍNIO ORIENTADO A OBJETOS (UML -> PYTHON) - TECPROEXPRESS")
    print("=" * 65)

    pkg = EntregaPacote("BR778899", "Hospital São Lucas", peso_kg=4.5)
    print(f"Instância Criada: {pkg}")
    print(f"Status Inicial Encapsulado: {pkg.status}")

    # Executando transição de método
    pkg.despachar_entrega()
    print(f"Status Atualizado: {pkg.status}")
    print("=" * 65)

🖥️ Saída Esperada no Terminal:

=================================================================
🏛️ DOMÍNIO ORIENTADO A OBJETOS (UML -> PYTHON) - TECPROEXPRESS
=================================================================
Instância Criada: EntregaPacote(id=BR778899, dest='Hospital São Lucas', status='PENDENTE')
Status Inicial Encapsulado: PENDENTE
📦 Pacote BR778899 para 'Hospital São Lucas' despachado com sucesso!
Status Atualizado: EM_TRANSITO
=================================================================

🌐 Exemplo de Payload JSON para Instanciação de Entidade (Swagger /docs)

{
  "id_pacote": "BR778899",
  "destinatario": "Hospital São Lucas",
  "peso_kg": 4.5,
  "endereco_entrega": {
    "rua": "Av. Brasil",
    "numero": 1500,
    "cidade": "São Paulo",
    "cep": "01430-000"
  },
  "prioridade_urgente": true
}

📤 Instruções de Entrega (Microsoft Teams)

Após validar suas documentações técnicas:

1. Salve o arquivo de documentação com o nome Atividade_07.md e a imagem do seu diagrama de classes com o nome Atividade_07.png na pasta es-atv-07-classes/ do seu repositório GitHub.
2. Certifique-se de fazer o commit e push para o repositório público.
3. Submeta o link do seu repositório no Microsoft Teams para avaliação do professor.

💡 Checkpoint de Lógica

📊 Rubrica Formativa de Avaliação

🎬 ATIVIDADE 08: DIAGRAMA DE SEQUÊNCIA (UML)

Bem-vindo a mais uma etapa da sua jornada no curso de Gestão de TI / Desenvolvimento de Sistemas. Hoje vamos mergulhar em conceitos que conectam a teoria técnica diretamente com o padrão de excelência da dinâmica de software, entendendo como o sistema "conversa" internamente. 🛡️🧩

🎯 Objetivos de Aprendizagem do Laboratório

Ao final deste laboratório prático (estimativa: 4 horas presenciais / autoguiadas), você será capaz de:

• Modelar o fluxo temporal de uma funcionalidade específica (Diferente da Classes, que é estático).
• Identificar Linhas de Vida (Lifelines) de objetos e atores.
• Representar Mensagens Síncronas, Assíncronas e Respostas.
• Visualizar a interação entre as camadas do sistema (Interface, Lógica e Banco de Dados).

🏢 O Cenário Prático (Seu Desafio)

Na TecProExpress, você definiu as Classes (Atividade 07). Agora, os desenvolvedores de Frontend e Backend precisam sentar para combinar como as mensagens serão trocadas. O programador da tela pergunta: "Quando eu clicar em 'Confirmar Entrega', para quem eu mando o sinal? Quem valida se o motorista está no local certo? Quem avisa o banco de dados para salvar?".

"Seu desafio como Analista de Sistemas é desenhar o 'filme' dessa ação. Você deve criar o Diagrama de Sequência que mostra o passo a passo temporal: da tela para o servidor, do servidor para o banco, e a resposta voltando para o celular do motorista."

🧠 Fundamentos: A Teoria Traduzida

Se o Diagrama de Classes é a foto das peças de um tabuleiro de xadrez, o Diagrama de Sequência é a descrição de uma jogada específica.

Elementos Chaves

• Atores e Objetos: Ficam no topo. De cada um desce uma Linha de Vida (tracejada).
• Foco de Controle (Retângulo na linha): Indica que o objeto está "trabalhando" naquele momento.
• Seta Contínua: Chamada de método (pergunta/ordem).
• Seta Tracejada: Retorno (resposta).

📊 Visualizando a Lógica

M->>T: Clica em "Finalizar"
T->>S: validarLocalizacao(gps)
S->>B: salvarStatus("Entregue")
B-->>S: OK (Sucesso)
S-->>T: Exibir Mensagem Sucesso
T-->>M: Notificação na Tela

![Diagrama de Sequência TecProExpress (UML)](img/es_atv_08_sequencia.svg)

---

## 📖 Exemplo Guiado
Abaixo, veja como planejar a sequência do "Login" no sistema da TecProExpress.

| Ordem | Quem fala com quem? | O que é dito? |
| :--- | :--- | :--- |
| 1 | Usuário -> Tela | Digita usuário/senha e clica em Entrar. |
| 2 | Tela -> Servidor | `autenticar(user, pass)` |
| 3 | Servidor -> Banco | `SELECT * FROM usuarios...` |
| 4 | Banco -> Servidor | Retorna os dados do usuário. |
| 5 | Servidor -> Tela | Login Autorizado. |

#### 📊 Dinâmica de Chamadas e Foco de Controle
```mermaid
sequenceDiagram
    autonumber
    actor U as Usuário
    participant T as Tela Login
    participant S as Servidor Auth
    
    U->>T: Digita credenciais e clica em Entrar
    activate T
    T->>S: POST /login (payload JSON)
    activate S
    Note over S: Autentica credenciais e gera JWT
    S-->>T: 200 OK (Token JWT)
    deactivate S
    T-->>U: Redireciona para o Dashboard
    deactivate T

🛠️ Regras de Ouro do Diagrama

1. Objetos nunca falam sozinhos: Uma mensagem sempre sai de uma linha de vida e vai para outra.
2. Use verbos de ação: As setas representam chamadas de funções que você definiu lá na Atividade 07.
3. Mantenha o foco: Não tente colocar 50 telas no mesmo diagrama. Escolha um fluxo (ex: Realizar Compra) e desenhe apenas ele.

🔍 Detalhamento do Processo:

• O Diagrama de Sequência é o melhor lugar para descobrir bugs de lógica. Se você desenhou que a "Tela" fala direto com o "Banco de Dados", você descobriu uma falha de segurança! Na engenharia profissional, a Tela sempre fala com o Servidor, e o Servidor fala com o Banco.

💻 Simulação de Sequência de Chamadas (Trace Middleware) em Python

Para inspecionar na prática a troca temporal de mensagens entre Usuário, Frontend, API e Banco de Dados:

# simulador_sequencia.py
import time

class BancoDadosMock:
    def consultar_usuario(self, email: str) -> dict:
        time.sleep(0.05) # Simula latência de rede/disco
        print("      [DB] 💾 SELECT * FROM usuarios WHERE email = :email -> Encontrado!")
        return {"id": 1, "nome": "Carlos Silva", "senha_hash": "$2b$12$e8f..."}

class ServidorAPIMock:
    def __init__(self, db: BancoDadosMock) -> None:
        self.db = db

    def autenticar(self, email: str, senha: str) -> dict:
        print("   [API] ⚙️ Recebida requisição POST /api/v1/auth/login")
        user = self.db.consultar_usuario(email)
        print("   [API] 🔐 Validando hash de senha e gerando Token JWT...")
        return {"status": 200, "token": "eyJhbGciOiJIUzI1NiIsIn...", "nome": user["nome"]}

class FrontendAppMock:
    def __init__(self, api: ServidorAPIMock) -> None:
        self.api = api

    def clicar_botao_entrar(self, email: str, senha: str) -> None:
        print("[UI] 📱 Usuário clicou em 'Entrar'. Disparando requisição HTTP...")
        resposta = self.api.autenticar(email, senha)
        print(f"[UI] 🟢 200 OK recebido! Redirecionando para Dashboard. Bem-vindo(a), {resposta['nome']}!")

if __name__ == "__main__":
    print("=" * 65)
    print("⏱️  SIMULADOR DE TRACE TEMPORAL (DIAGRAMA DE SEQUÊNCIA UML)")
    print("=" * 65)

    db = BancoDadosMock()
    api = ServidorAPIMock(db)
    app = FrontendAppMock(api)

    app.clicar_botao_entrar("carlos@tecproexpress.com", "SenhaForte123")
    print("=" * 65)

🖥️ Saída Esperada no Terminal:

=================================================================
⏱️  SIMULADOR DE TRACE TEMPORAL (DIAGRAMA DE SEQUÊNCIA UML)
=================================================================
[UI] 📱 Usuário clicou em 'Entrar'. Disparando requisição HTTP...
   [API] ⚙️ Recebida requisição POST /api/v1/auth/login
      [DB] 💾 SELECT * FROM usuarios WHERE email = :email -> Encontrado!
   [API] 🔐 Validando hash de senha e gerando Token JWT...
[UI] 🟢 200 OK recebido! Redirecionando para Dashboard. Bem-vindo(a), Carlos Silva!
=================================================================