📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados em Especialização em Sistemas com Python. Recomendado revisar antes de começar.

🐍 Projeto 04: Automação Comercial Executável

Guia de Engenharia de Software: Ponto de Venda (PDV), Segurança Criptográfica, Transações ACID, Logging e Deploy .exe com PyInstaller

Trilha de Especialização Pedagógica — Nível Intermediário (Curso 25: Sistemas Desktop com Python & POO)

• Visão Geral da Trilha: 📚 Módulo Sistemas com Python
• Trilha Evolutiva Completa: 🚀 Especificação das 4 Fases
• Catálogo de Projetos: 🏗️ Catálogo de Projetos
• ➡️ Projeto 4 de 4: Automação Comercial Executável (sistemas_python_04_automacao_executavel)

🎯 Objetivo & Escopo do Projeto

Este é o projeto culminante da trilha intermediária de Sistemas com Python. Ele consolida todo o conhecimento de engenharia de software em um produto de software de mercado pronto para distribuição em clientes reais:

1. Segurança & Controle de Acesso Criptográfico:
   • Hashing de senhas com SHA-256 e Salt (security.py), garantindo que nenhuma senha trafegue ou seja gravada em texto plano.
   • Controle de privilégios de acesso com base no papel do usuário (PapelUsuario.ADMIN vs. PapelUsuario.OPERADOR).
2. Transações Relacionais com ACID Estrito:
   • Gravação atômica da venda e dos itens (vendas e itens_venda), garantindo que se ocorrer qualquer falha durante a persistência, o rollback preserve a integridade contábil.
3. Auditoria & Logging Corporativo (logging):
   • Registro detalhado de logins, emissão de cupons fiscais e exceções em pdv_operacoes.log.
4. Configuração Externa Desacoplada (config_pdv.ini):
   • Parametrização dinâmica de dados da empresa, CNPJ, número de caixa e teto de descontos.
5. Pipeline de Empacotamento Nativo (.exe) com PyInstaller:
   • Script automatizado build_exe.py que gera o executável binário autônomo para Windows sem exigir que o cliente final tenha o Python instalado.

🏛️ Diagrama de Arquitetura do Sistema PDV

flowchart TD
    subgraph Sec ["🔐 Camada de Segurança & Sessão"]
        AUTH["security.py (SHA-256 + Salt)\nValidação de Usuários e Perfis"]
        LOG["logging (pdv_operacoes.log)\nTrilha de Auditoria Contábil"]
    end

    subgraph UI ["🖥️ Camada de Apresentação (Desktop Tkinter)"]
        LOGIN["TelaLoginModal\nAutenticação Obrigatória"]
        PDV["AppPDVComercial\n• Carrinho Reativo (Treeview)\n• Emissão de Cupom Não-Fiscal\n• Fechamento de Caixa"]
    end

    subgraph Core ["📦 Camada de Negócio & DAO"]
        CFG["config.py (config_pdv.ini)\nEmpresa, CNPJ, Descontos"]
        MODELS["models.py (Dataclasses)\nUsuario, ItemVenda, VendaPDV"]
        DAO["database.py (DatabasePDV)\nTransações ACID SQLite3"]
    end

    subgraph Deploy ["🚀 Camada de Distribuição"]
        BUILD["build_exe.py (PyInstaller)\nCompilação em dist/PDV_Comercial.exe"]
    end

    LOGIN --> AUTH
    LOGIN --> PDV
    PDV --> CFG
    PDV --> MODELS
    PDV --> DAO
    PDV --> LOG
    PDV -.-> BUILD

    style Sec fill:#ffebee,stroke:#c62828,stroke-width:2px
    style UI fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Core fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
    style Deploy fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px

📂 Estrutura de Pastas e Arquivos

sistemas_python_04_automacao_executavel/
├── models.py                # Entidades Dataclass (Usuario, ItemVenda, VendaPDV) e Enums
├── security.py              # Hashing criptográfico SHA-256 e validação de senhas
├── database.py              # DAO relacional SQLite3 com transações ACID atômicas
├── config.py                # Leitura e gravação de parâmetros em config_pdv.ini
├── app.py                   # Interface Desktop completa com Login Modal e PDV
├── cli.py                   # Terminal PDV para vendas rápidas
├── build_exe.py             # Script de compilação PyInstaller (.exe standalone)
├── main.py                  # Hub Launcher central (Desktop, CLI, Build ou Testes)
├── tests/
│   └── test_pdv.py          # Suíte de testes unitários automatizados
└── index.md                 # Guia técnico e documentação pedagógica

🚀 Como Executar no Laboratório

1. Abra o terminal na pasta deste projeto

No VS Code / PyCharm, abra a pasta deste projeto (File > Open Folder) ou navegue via terminal:

cd sistemas_python_04_automacao_executavel

2. Execute o Hub Launcher ou Modos Específicos

# Executar o Hub Launcher (Menu interativo):
python main.py

# Ou executar diretamente o PDV Desktop:
python app.py

# Executar o PDV no Terminal (CLI):
python cli.py

# Compilar o Executável .exe com PyInstaller:
python build_exe.py

# Executar os Testes Unitários:
python -m unittest discover -s tests

[!TIP] Dica para execução a partir da raiz do repositório: Se você abriu o repositório completo no VS Code, basta executar: python catalogo_projetos/sistemas_python_04_automacao_executavel/main.py

📖 Destaques Técnicos do Código

1. Hashing Seguro com SHA-256 e Salt (security.py)

import hashlib

SALT_PADRAO = "PDV_AGY_2026_SECURE_SALT"

def gerar_hash_senha(senha_plana: str, salt: str = SALT_PADRAO) -> str:
    texto_combinado = f"{salt}:{senha_plana}"
    return hashlib.sha256(texto_combinado.encode("utf-8")).hexdigest()

def verificar_senha(senha_plana: str, hash_esperado: str, salt: str = SALT_PADRAO) -> bool:
    return gerar_hash_senha(senha_plana, salt) == hash_esperado

2. Transação Atômica ACID (database.py)

def registrar_venda_transacional(self, venda: VendaPDV) -> int:
    conn = self.conectar()
    cursor = conn.cursor()
    try:
        cursor.execute("""
            INSERT INTO vendas (codigo_cupom, operador_login, cliente_nome, forma_pagamento, desconto, valor_bruto, valor_liquido, status, timestamp)
            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
        """, (venda.codigo_cupom, venda.operador_login, venda.cliente_nome, venda.forma_pagamento.value, venda.desconto, venda.valor_bruto, venda.valor_liquido, venda.status.value, venda.timestamp))
        venda_id = cursor.lastrowid
        
        for item in venda.itens:
            cursor.execute("""
                INSERT INTO itens_venda (venda_id, descricao, quantidade, preco_unitario, subtotal)
                VALUES (?, ?, ?, ?, ?)
            """, (venda_id, item.descricao, item.quantidade, item.preco_unitario, item.subtotal))
            
        conn.commit()
        return venda_id
    except Exception as e:
        conn.rollback()
        raise RuntimeError(f"Falha na venda: {e}")
    finally:
        conn.close()

🧪 Validação dos Testes Unitários

Ran 2 tests in 0.071s — OK

Os testes automatizados cobrem:

• Hashing criptográfico de senhas e autenticação segura de usuários.
• Recálculo automático de itens do carrinho com descontos.
• Gravação atômica transacional no SQLite e fechamento consolidado de caixa.

🏛️ Arquitetura Visual & Engenharia do Sistema

A visualização arquitetural abaixo detalha a separação de responsabilidades e o fluxo de dados implementado na subpasta app-python/:

flowchart TD
    subgraph Entrada["Camada de Entrada & CLI"]
        IN1["Interface de Comando / API"] --> IN2["Parser & Sanitização"]
    end
    subgraph Dominio["Camada de Domínio & Regras"]
        DM1["Modelos de Domínio"] --> DM2["Processamento Algorítmico"]
    end
    subgraph Armazenamento["Persistência & Recursos"]
        ST1["Banco de Dados / Arquivo"] --> ST2["Transações ACID & Logs"]
    end
    subgraph Qualidade["Validação & Qualidade"]
        QA1["Testes Automatizados"] --> QA2["Checkpoints CP-01..05 PASS"]
    end

    Entrada --> Dominio
    Dominio --> Armazenamento
    Armazenamento --> Qualidade

    style Entrada fill:#e3f2fd,stroke:#1976d2,stroke-width:1.5px
    style Dominio fill:#fffde7,stroke:#fbc02d,stroke-width:1.5px
    style Armazenamento fill:#e8f5e9,stroke:#388e3c,stroke-width:1.5px
    style Qualidade fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1.5px

🎯 Engenharia de Requisitos & Modelagem Formal

👤 User Stories (Histórias de Usuário)

⚙️ Requisitos Funcionais (RF)

🛡️ Requisitos Não-Funcionais (RNF)

🔗 Matriz de Rastreabilidade (RTM)

🏁 Checkpoints de Qualidade & Homologação