📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados em Módulo 09: Estruturas de Dados. Recomendado revisar antes de começar.

📦 Biblioteca de Estruturas de Dados Avançadas & Big-O

v1.0 — Pilhas, Filas, Listas Duplamente Encadeadas e Hash Tables

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

• ➡️ v1 (este): Estruturas Lineares · Pilhas (LIFO) · Filas (FIFO) · Listas Encadeadas · Hash Table
• v2: Árvores AVL Auto-Balanceadas & B-Trees
• v3: Grafos Ponderados & Algoritmo de Dijkstra
• v4: Programação Dinâmica & Algoritmos Gulosos

🎓 Nível Profissional Simulado: Engenheiro de Software Júnior. Saber escolher entre um Array e uma LinkedList ou entender como uma HashTable lida com colisões em $O(1)$ é o teste técnico padrão das principais empresas de tecnologia do mundo (FAANG / Big Techs).

🎯 Objetivo & Escopo do Projeto

Construir do zero uma biblioteca de Estruturas de Dados Fundamentais contendo Pilhas (LIFO), Filas (FIFO), Listas Duplamente Encadeadas com ponteiros anterior/próximo e uma Tabela Hash com resolução de colisões por encadeamento separado, acompanhada da análise assintótica de complexidade Big-O de cada método.

🧑‍💼 Fase 1 — Levantamento de Requisitos

O Briefing do Cliente (Arquiteto de Sistemas de Alta Performance)

“Nossa aplicação de processamento de logs sofre com travamentos porque o time usa listas simples para fazer buscas com contains(), o que gera custo $O(n)$ em 2 milhões de registros. Precisamos de uma biblioteca de estruturas de dados padrão da empresa, com Listas Duplamente Encadeadas para inserção $O(1)$ e uma Tabela Hash customizada para indexação rápida $O(1)$ com tratamento rigoroso de colisões.”

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

📋 Fase 2 — Backlog & User Stories

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

# Branch da funcionalidade
git checkout -b feature/US02-tabela-hash-encadeada

# Executar a biblioteca e testes
python src/estruturas_core.py

🛠️ Fase 4 — Implementação Guiada (src/estruturas_core.py)

class TabelaHashEncadeada:
    def __init__(self, capacidade=16):
        self.capacidade = capacidade
        self.baldes = [[] for _ in range(capacidade)]

    def _hash(self, chave):
        return hash(chave) % self.capacidade

    def inserir(self, chave, valor):
        indice = self._hash(chave)
        for i, (k, v) in enumerate(self.baldes[indice]):
            if k == chave:
                self.baldes[indice][i] = (chave, valor)
                return
        self.baldes[indice].append((chave, valor))

🚀 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 algoritmos_01_estruturas_dados

2. Execute a aplicação ou testes

go run main.go
# ou python main.py

[!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/algoritmos_01_estruturas_dados`

🧭 Decisões de Arquitetura (ADRs)

• ADR 001: Adoção de encadeamento separado para tratamento resiliente de colisões na Tabela Hash.

🧪 Testes de Validação & Asserções

th = TabelaHashEncadeada(capacidade=4)
th.inserir("id:1", "Valor A")
th.inserir("id:5", "Valor B") # Força colisão no mesmo balde
assert th.buscar("id:1") == "Valor A"
assert th.buscar("id:5") == "Valor B"

🏛️ 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