📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados em Módulo 01: Fundamentos da Computação. Recomendado revisar antes de começar.

💻 Simulador de ULA & Conversor de Bases Numéricas

v1.0 — Portas Lógicas, Circuitos Aritméticos e Aritmética Binária

Trilha de Especialização Pedagógica — Projeto 1 de 4

• ➡️ v1 (este): Fundamentos de Hardware · Simulação de ULA 8-bit · Flags de Status · Conversor de Bases
• v2: Máquina de Turing · Autômatos Finitos Determinísticos (DFA)
• v3: Pipeline RISC-V · Decodificação de Instruções
• v4: Emulador de CPU 8-bit Completo com Memória RAM e Barramento

🎓 Nível Profissional Simulado: Estagiário de Engenharia de Software. Todo programador de alto nível precisa entender o que acontece quando o código vira zeros e uns. Saber como a ULA calcula somas em complemento de dois e lida com Overflow e Carry evita bugs clássicos de estouro de memória em produção.

🎯 Objetivo & Escopo do Projeto

Construir um Simulador de Unidade Lógica e Aritmética (ULA) de 8 bits e um conversor de bases numéricas (Binário, Octal, Decimal e Hexadecimal), implementando operações booleanas elementares (AND, OR, XOR, NOT), soma em complemento de dois e cálculo atômico de flags de status (Zero, Negative, Carry e Overflow).

🧑‍💼 Fase 1 — Levantamento de Requisitos

O Briefing do Cliente (Professor Coordenador de Arquitetura)

“Preciso de um simulador didático para o laboratório de hardware. Os alunos precisam inserir dois operandos em formato decimal, binário ou hexadecimal, selecionar a operação da ULA (ADD, SUB, AND, OR, XOR) e visualizar tanto o resultado em todas as bases quanto o estado exato das 4 flags de registradores (Zero, Negative, Carry, Overflow). O sistema não pode usar operadores prontos de alto nível sem controle de 8 bits.”

Requisitos Funcionais (RF) e Não-Funcionais (RNF)

📋 Fase 2 — Backlog & User Stories

Quadro Kanban da Sprint

🌿 Fase 3 — Engenharia em Equipe (Git Flow & Setup)

# Criar branch da funcionalidade
git checkout -b feature/US02-ula-bitwise-flags

# Executar o simulador
python src/ula_simulator.py

Template de Pull Request

• O que foi feito: Implementação da classe ULA8Bit com soma em complemento de dois e cálculo de flags Z/N/C/V.
• Como testar: python -m unittest discover tests/

• Checklist: [x] Sem dependências externas

  [x] Máscara 0xFF aplicada

  [x] ADR 001 documentada

🛠️ Fase 4 — Implementação Guiada do Código

1. Núcleo da ULA de 8 Bits (src/ula_simulator.py)

class ULA8Bit:
    def __init__(self):
        self.flag_zero = False
        self.flag_negative = False
        self.flag_carry = False
        self.flag_overflow = False

    def somar(self, a, b):
        raw = a + b
        res = raw & 0xFF
        self.flag_zero = (res == 0)
        self.flag_negative = bool(res & 0x80)
        self.flag_carry = (raw > 0xFF)
        self.flag_overflow = bool(~(a ^ b) & (a ^ res) & 0x80)
        return res

🚀 Como Executar no Laboratório

1. Abra o terminal na pasta deste projeto

No seu editor/IDE, abra a pasta deste projeto (File > Open Folder) ou navegue via terminal:

cd fundamentos_01_ula_conversor

2. Execute a aplicação ou testes

# Executar comandos específicos da tecnologia:
python main.py # ou npm run dev / ./gradlew build

[!TIP] Dica para execução a partir da raiz do repositório: Se você abriu o repositório completo no VS Code, basta navegar até a pasta antes de executar: cd catalogo_projetos/fundamentos_01_ula_conversor`

🧭 Decisões de Arquitetura (ADRs)

• ADR 001: Adoção de simulação bitwise pura com registradores de 8 bits para fidelidade didática ao hardware real.

🧪 Testes de Validação & Troubleshooting

# Teste de Overflow e Carry
assert ula.somar(255, 1) == 0      # Carry = True, Zero = True
assert ula.somar(127, 1) == 128    # Overflow = True (positivo virou negativo em 2's complement)

💡 Troubleshooting (Erros Clássicos)

• Problema: Inteiros em Python possuem precisão arbitrária e não estouram em 255.
• Causa-Raiz: Python não usa tipos primitivos de 8 bits nativamente.
• Solução: Aplicar a máscara & 0xFF em todas as saídas de registradores.

🏛️ Arquitetura Visual & Engenharia do Sistema

A visualização arquitetural abaixo detalha a separação de responsabilidades e o fluxo de dados implementado na subpasta cli-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