Sumário

1. Introdução
2. Fundamentação Teórica
   • 2.1. O Problema do Controle de Estoque Manual
   • 2.2. Acurácia de Inventário e Automação
   • 2.3. Transações ACID em Sistemas de Gestão
   • 2.4. Prevenção de Anomalias de Concorrência
3. Engenharia de Software
   • 3.1. Requisitos Funcionais (RF)
   • 3.2. Requisitos Não Funcionais (RNF)
   • 3.3. Orientação a Objetos na Arquitetura do Sistema
   • 3.4. Caso de Uso Principal (UC-01)
4. Banco de Dados (MySQL)
   • 4.1. Modelagem e Script DDL
   • 4.2. Consultas Complexas e Curva ABC (DML)
5. Gestão, Segurança e LGPD
   • 5.1. Backlog e Histórias de Usuário (Padrão INVEST)
   • 5.2. Conformidade com a LGPD e Privacy by Design
   • 5.3. Cronograma do Projeto
6. Diagramas de Visualização
   • 6.1. Diagrama de Casos de Uso
   • 6.2. Diagrama de Classes
   • 6.3. Diagrama de Entidade-Relacionamento (DER)

1. Introdução

No dinâmico mercado de pequenas e médias empresas (PMEs), a gestão eficiente do almoxarifado é um fator determinante para a lucratividade. O excesso de produtos imobiliza capital de giro, enquanto a ruptura de estoque (falta de produto) causa perda imediata de vendas e desgasta a confiança do consumidor. O Projeto Integrador Sistema de Gerenciamento de Estoque Digital, desenvolvido como projeto acadêmico (2026), endereça essa problemática ao transformar processos baseados em planilhas não estruturadas em uma solução de software coesa, rastreável e automatizada.

O projeto tem como objetivo arquitetar um sistema que registre, com alta disponibilidade e consistência, a movimentação de mercadorias (Entradas e Saídas), permitindo que os gestores de armazém mantenham uma visão perfeitamente sincronizada de seus inventários. Este documento compila de forma exaustiva o planejamento arquitetural do sistema, explorando desde o paradigma orientado a objetos utilizado no código até a otimização de instruções relacionais em banco de dados, balizando o desenvolvimento em rigorosas normas de qualidade de software.

2. Fundamentação Teórica

2.1. O Problema do Controle de Estoque Manual

O controle manual de estoques, comumente realizado através de fichas de prateleira (Kardex físico) ou planilhas locais não integradas, é altamente suscetível ao erro humano. O lapso em registrar uma saída no exato momento da expedição resulta em divergência entre o estoque físico e o estoque sistêmico. Essa falta de Acurácia de Inventário compromete o planejamento de compras e a promessa de prazos de entrega. A automação proporcionada por este software visa mitigar esse atraso informacional, integrando a tela do operador diretamente à base de dados central, garantindo que o saldo consultado por qualquer departamento (Vendas, Logística, Diretoria) seja a fonte única da verdade.

2.2. Acurácia de Inventário e Automação

Em logística, a Acurácia de Inventário é a métrica que mede a exatidão entre o sistema e o mundo real. Para maximizar esse indicador, o sistema projetado não permite modificações arbitrárias do "Saldo" de um produto. Em vez disso, o saldo é estritamente derivado da somatória aritmética do histórico de transações de Entrada (positivo) e Saída (negativo). Esse design pattern arquitetural de registro contábil (Double-entry bookkeeping) garante auditoria contínua, sendo impossível alterar o saldo final sem deixar um rastro transacional do motivo.

2.3. Transações ACID em Sistemas de Gestão

O núcleo deste sistema de estoque repousa sobre as propriedades ACID (Atomicidade, Consistência, Isolamento e Durabilidade) dos Sistemas de Gerenciamento de Bancos de Dados Relacionais (SGBDR). A atomicidade é crítica: se uma operação de transferência de produtos entre duas filiais falhar no meio da execução (ex: o produto sai da Filial A, mas a rede cai antes de entrar na Filial B), a transação inteira sofre um Rollback, impedindo que o banco de dados fique em um estado inconsistente e produtos "desapareçam" no limbo cibernético.

2.4. Prevenção de Anomalias de Concorrência

Um desafio comum em estoques digitalizados é o problema da "Leitura Fantasma" ou atualizações perdidas (Lost Updates). Se dois operadores tentarem dar saída na última unidade de um produto simultaneamente, o sistema deve garantir que apenas o primeiro consiga concluir a transação, enquanto o segundo receba um aviso de "Estoque Insuficiente". Para isso, o banco de dados implementa estratégias de bloqueio pessimista (Pessimistic Locking) como o SELECT ... FOR UPDATE nas consultas de disponibilidade, garantindo a integridade (RNF-001) contra concorrência pesada.

3. Engenharia de Software

3.1. Requisitos Funcionais (RF)

1. RF-001 | Cadastro e Entrada de Produto: O sistema deve permitir o cadastro de um novo item de inventário e registrar as entradas oriundas de compras, associando data, quantidade e número de lote.
2. RF-002 | Baixa e Saída de Produto: O sistema deve registrar a expedição/saída de produtos, subtraindo o montante do saldo global.
3. RF-003 | Consulta Rápida (Busca): O sistema deve fornecer um campo de busca inteligente (por código de barras ou descrição parcial) para apresentar a disponibilidade e a localização física do item no galpão.
4. RF-004 | Recálculo de Saldo Automático: O sistema não deve exigir o cálculo manual de saldo; a atualização do inventário deve ser disparada automaticamente por gatilhos de software a cada transação computada.
5. RF-005 | Histórico de Movimentações (Kardex): O sistema deve gerar um extrato (log) individualizado por produto detalhando o tipo, operador, quantidade e o saldo pós-operação.

3.2. Requisitos Não Funcionais (RNF)

1. RNF-001 (Integridade de Dados): É expressamente proibido pelo sistema que qualquer registro resulte em saldo (quantidade em estoque) menor que zero. A persistência deve ser validada na camada de negócio e na Constraint do Banco de Dados.
2. RNF-002 (Usabilidade e Desempenho): O módulo de consulta (RF-003) deve responder à requisição em menos de 200 milissegundos para não atrasar operações de balcão ou despacho.
3. RNF-003 (Auditoria Criptográfica): Os preços de custo (informação comercial sensível da empresa) devem transitar encriptados ou restritos em tabelas protegidas, garantindo acesso apenas à gerência.

3.3. Orientação a Objetos na Arquitetura do Sistema

A construção do Back-end explora intensamente a Programação Orientada a Objetos para conferir escalabilidade ao projeto:

• Abstração: Uma classe TransacaoEstoque abstrai o conceito de movimentação. Independentemente se é uma "Devolução de Cliente", "Avaria", "Venda" ou "Compra", a abstração central lida com a data, produto e quantidade absoluta.
• Encapsulamento: A propriedade saldo_atual na classe Produto é protegida. Nenhuma outra classe pode atribuir valor direto (produto.saldo = 50). Para modificar o saldo, as classes externas invocam os métodos encapsulados produto.acrescentar(qtd) e produto.deduzir(qtd), as quais detêm toda a lógica de validação do RNF-001 (checar saldo negativo).
• Polimorfismo: Ao despachar um produto, o comportamento da transação pode variar de acordo com o Tipo de Movimentação. Uma hierarquia de herança permite que as classes derivadas TransacaoEntrada e TransacaoSaida estendam a base e apliquem o método polimórfico executarEfeitoContabil(), que numa entrada multiplica a quantidade por +1 e na saída por -1.

3.4. Caso de Uso Principal (UC-01)

Identificador: UC-01
Nome: Registrar Saída de Mercadoria (Despacho)
Ator Principal: Operador de Logística
Pré-condição: Operador logado no sistema e mercadoria previamente cadastrada no catálogo.

Fluxo Principal:

1. O Operador acessa o módulo de "Saída de Materiais".
2. O sistema requer a digitação do Código do Produto (ou uso de leitor laser).
3. O sistema recupera e exibe os detalhes do produto e o Saldo Atual.
4. O Operador insere a quantidade a ser baixada e a justificativa (ex: Ordem de Serviço #123).
5. O Operador clica em "Processar Saída".
6. A camada de negócios (Encapsulamento) verifica se Quantidade Solicitada <= Saldo Atual.
7. O sistema executa a transação no banco de dados (INSERT na tabela de movimentação e UPDATE no saldo do produto).
8. O sistema confirma visualmente que o despacho foi processado com sucesso.

Fluxo de Exceção 1 (Ruptura de Estoque / Saldo Negativo): No passo 6, se o saldo disponível for menor do que a quantidade solicitada (ex: pediu 10, tem 8), a operação é bloqueada imediatamente. O sistema alerta: "Erro de Integridade: Quantidade indisponível. Saldo atual: 8 unidades. Ajuste a requisição."

4. Banco de Dados (MySQL)

Para gerir a criticidade de um inventário dinâmico, o design lógico do Banco de Dados precisa antecipar os trade-offs entre armazenamento e velocidade de leitura.

4.1. Modelagem e Script DDL

A modelagem utiliza redundância controlada: O saldo total do produto é armazenado na tabela do produto (para buscas em O(1)) e também é calculado transacionalmente na tabela de movimentações (para fins de log rigoroso). Para a segurança dos preços de custo contra acessos não autorizados de DBAs juniores, utiliza-se a cifração na coluna preco_custo_cifrado (VARBINARY).

-- Criação do Schema do Almoxarifado
CREATE DATABASE IF NOT EXISTS db_gestao_estoque
CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

USE db_gestao_estoque;

-- Tabela de Operadores (Usuários do Sistema)
CREATE TABLE IF NOT EXISTS tbl_operadores (
    id_operador INT AUTO_INCREMENT PRIMARY KEY,
    nome_operador VARCHAR(100) NOT NULL,
    nivel_acesso ENUM('ESTOQUISTA', 'GERENTE', 'AUDITOR') NOT NULL,
    status_ativo BOOLEAN DEFAULT TRUE
);

-- Tabela Central do Catálogo de Produtos
CREATE TABLE IF NOT EXISTS tbl_produtos (
    id_produto INT AUTO_INCREMENT PRIMARY KEY,
    codigo_barras VARCHAR(50) UNIQUE NOT NULL,
    descricao_produto VARCHAR(150) NOT NULL,
    unidade_medida ENUM('UN', 'KG', 'L', 'CX', 'M') NOT NULL,
    saldo_atual DECIMAL(10,3) NOT NULL DEFAULT 0.000,
    estoque_minimo DECIMAL(10,3) NOT NULL DEFAULT 0.000,
    preco_custo_cifrado VARBINARY(500) COMMENT 'Dado sensível encriptado (AES)',
    localizacao_prateleira VARCHAR(20),
    -- Proteção nativa no BD contra Saldo Negativo (RF-001)
    CONSTRAINT ck_saldo_positivo CHECK (saldo_atual >= 0)
);

-- Tabela Kardex (Histórico Transacional Imutável)
CREATE TABLE IF NOT EXISTS tbl_movimentacoes_kardex (
    id_movimentacao BIGINT AUTO_INCREMENT PRIMARY KEY,
    id_produto INT NOT NULL,
    id_operador INT NOT NULL,
    tipo_operacao ENUM('ENTRADA_COMPRA', 'ENTRADA_DEVOLUCAO', 'SAIDA_VENDA', 'SAIDA_AVARIA', 'AJUSTE_BALANCO') NOT NULL,
    quantidade DECIMAL(10,3) NOT NULL,
    data_hora_movimentacao DATETIME DEFAULT CURRENT_TIMESTAMP,
    numero_documento VARCHAR(50) COMMENT 'Nota fiscal ou Ordem de serviço',
    FOREIGN KEY (id_produto) REFERENCES tbl_produtos(id_produto) ON DELETE RESTRICT,
    FOREIGN KEY (id_operador) REFERENCES tbl_operadores(id_operador) ON DELETE RESTRICT
);

4.2. Consultas Complexas e Curva ABC (DML)

Para prover inteligência ao negócio, o Gestor de Estoque precisa identificar quais produtos exigem mais atenção. A instrução SQL abaixo constrói uma Curva ABC de movimentação, utilizando funções analíticas e agrupamentos complexos para identificar os 20% dos produtos que representam a maior volumetria de saídas nos últimos 6 meses, além de reportar o saldo residual que ameaça romper o estoque mínimo.

-- Relatório Estratégico: Produtos com Maior Volumetria de Saída (Últimos 6 meses)
SELECT 
    P.codigo_barras AS 'Código',
    P.descricao_produto AS 'Produto',
    P.unidade_medida AS 'UM',
    COUNT(M.id_movimentacao) AS 'Qtd_Despachos',
    SUM(M.quantidade) AS 'Volume_Total_Movido',
    P.saldo_atual AS 'Saldo_Físico',
    IF(P.saldo_atual <= P.estoque_minimo, 'CRÍTICO', 'NORMAL') AS 'Alerta_Abastecimento'
FROM 
    tbl_produtos P
INNER JOIN 
    tbl_movimentacoes_kardex M ON P.id_produto = M.id_produto
WHERE 
    M.tipo_operacao IN ('SAIDA_VENDA', 'SAIDA_AVARIA')
    AND M.data_hora_movimentacao >= DATE_SUB(CURRENT_DATE(), INTERVAL 6 MONTH)
GROUP BY 
    P.id_produto, P.codigo_barras, P.descricao_produto, P.unidade_medida, P.saldo_atual, P.estoque_minimo
HAVING 
    'Volume_Total_Movido' > 50
ORDER BY 
    'Volume_Total_Movido' DESC
LIMIT 50;

Justificativa Técnica: A mescla do INNER JOIN com a condicional dinâmica IF na projeção e os agregadores transacionais no filtro temporal garantem que o gestor atue antes que a ruptura ocorra no estoque, aplicando o conceito proativo da tecnologia da informação.

5. Gestão, Segurança e LGPD

5.1. Backlog e Histórias de Usuário (Padrão INVEST)

Na cadência das Sprints de desenvolvimento, os épicos foram decompostos em histórias enxutas e de valor (INVEST):

História de Usuário 01 - Proteção Criptográfica do Custo de Mercadorias

Como um Gerente de Compras,
Eu quero que os preços de custo de entrada (CMV) sejam armazenados em formato encriptado no banco de dados,
Para que operadores de logística comuns e ataques cibernéticos não tenham acesso à margem de lucro da empresa.
Critérios de Aceite: Ao cadastrar a Nota Fiscal de compra, a aplicação (via Python/Secrets/Fernet) cifra o valor; o SELECT puro no banco deve exibir apenas o VARBINARY; o front-end do estoquista não deve ter a chave de decriptação, apenas a tela da Diretoria.

História de Usuário 02 - Alerta de Ruptura (Reposição)

Como um Analista de Compras,
Eu quero que o Dashboard exiba uma notificação em vermelho toda vez que o "Saldo Atual" for menor ou igual ao "Estoque Mínimo",
Para que eu inicie imediatamente a requisição de novos suprimentos aos fornecedores.
Critérios de Aceite: A verificação deve ocorrer após qualquer operação de "Saída"; o painel deve listar os produtos críticos organizados por ordem de criticidade.

5.2. Conformidade com a LGPD e Privacy by Design

Ainda que o núcleo do sistema transacione "coisas" (produtos), o sistema identifica os operadores que realizam as movimentações (para fins de auditoria de furtos internos).

• Adequação: A tabela tbl_operadores trata os dados pessoais como confidenciais. A conformidade (Compliance) requer a adoção do Privacy by Design: A exclusão de um colaborador não apaga as movimentações históricas que ele executou (para não ferir a consistência da empresa). Realiza-se a Anonimização do Dado (pseudonimização), substituindo o nome na base histórica por uma hash irreversível, respeitando o direito legal do titular (LGPD) sem violar as obrigações fiscais corporativas.

5.3. Cronograma do Projeto

A estimativa para finalização do MVP (Minimum Viable Product) foi dividida em um fluxo de 6 semanas:

6. Diagramas de Visualização

A estrutura sistêmica é cristalizada por meio dos diagramas modelados via sintaxe Mermaid.

6.1. Diagrama de Casos de Uso

Mapeia a restrição de privilégios e os fluxos primordiais do estoque.

Versão em SVG (Diagrama de Casos de Uso):

6.2. Diagrama de Classes (Contabilidade de Estoque)

Descreve a correlação orientada a objetos (OO) responsável por efetivar as transações lógicas antes da persistência.

6.3. Diagrama de Entidade-Relacionamento (DER)

A espinha dorsal dos dados lógicos transacionados no MySQL (Tabelas do Script DDL).

Fim da Documentação do Projeto Integrador (2026). A concepção deste sistema transcende a simples computação, oferecendo uma arquitetura tática que provê segurança criptográfica dos ativos financeiros da empresa e integridade concorrencial nas esteiras de despacho de mercadorias.