EstoqueMultimidia

🎓 UniFAP — Sistema Integrado de Gestão de Estoque, Patrimônio, Eventos & Biometria Facial

Next.js 15 TypeScript FastAPI PostgreSQL Prisma ORM Cloudflare Tunnel Vitest LGPD

Sistema institucional oficial desenvolvido para o setor de Suporte de Tecnologia da Informação & Multimídia do Centro Universitário Paraíso (UniFAP - Juazeiro do Norte/CE) • unifapce.edu.br.

Uma plataforma corporativa completa que unifica o controle de materiais a granel, rastreabilidade individual de equipamentos patrimoniais, fluxo de empréstimos com termos A4 e notificações no WhatsApp, ordens de serviço com horímetro para projetores, scanner mobile de QR Code, mapeamento físico do armário de TI, microsserviço de Reconhecimento Facial Biométrico com busca vetorial (pgvector), módulo de Eventos Acadêmicos com Check-in por Totem e Sorteios Interativos em Telão, além de API REST para integrações externas com n8n e agentes de IA.

📑 Sumário

🎯 Visão Geral e Objetivos

O setor de Suporte de TI & Multimídia da UniFAP atende centenas de professores, colaboradores e discentes em dezenas de salas de aula, laboratórios, auditórios e eventos acadêmicos institucionais. Este sistema foi desenvolvido para solucionar gargalos operacionais e introduzir inovação tecnológica:

  1. Rastreabilidade Físico-Espacial: Mapeamento digital exato das 3 portas do armário de TI e suas 18 caixas organizadoras.
  2. Ciclo de Vida Perpétuo de Patrimônios: Trilha de auditoria inalterável (AssetHistory) para projetores, notebooks, caixas de som e microfones.
  3. Formalização de Empréstimos & WhatsApp: Emissão imediata do Termo Oficial de Cautela UniFAP em A4 e envio de lembretes automáticos com link direto no WhatsApp.
  4. Horímetro de Lâmpadas & Manutenção Preventiva: Controle de horas de uso de lâmpadas de projetores e histórico financeiro de ordens de serviço.
  5. Reconhecimento Facial Biométrico de Alta Precisão: Identificação de alunos e servidores em frações de segundo através de embeddings de 128 dimensões com pgvector e FastAPI.
  6. Gestão de Eventos Acadêmicos & Sorteios Gamificados: Totem de check-in facial expresso, controle de elegibilidade de presença e sorteador interativo em telão com efeitos sonoros e confetes.
  7. Segurança Corporativa & Zero Trust: Exposição segura via Cloudflare Tunnel, autenticação NextAuth.js com RBAC em 4 níveis, proteção estrita anti-SSRF e conformidade com a LGPD.

🏗️ Arquitetura do Ecossistema

O sistema adota uma arquitetura modular em microsserviços integrados, operando em rede isolada de containers Docker:

flowchart TB
    subgraph Internet["Rede Externa / Usuários"]
        UserBrowser["Navegador Web / Mobile (PWA)"]
        TotemClient["Totem de Presença Facial"]
        WhatsAppBot["n8n / WhatsApp Bots"]
    end

    subgraph Edge["Camada de Borda & Segurança"]
        Cloudflare["Cloudflare Edge (WAF, SSL, DDoS)"]
        Tunnel["Cloudflare Tunnel (cloudflared container)"]
    end

    subgraph DockerNetwork["Rede Interna Docker (unifap-network)"]
        subgraph WebApp["Next.js 14 App (Porta 3000)"]
            UI["Interface React & Tailwind CSS"]
            Middleware["Edge Security Middleware (RBAC)"]
            APIRoutes["Next.js Route Handlers (API v1)"]
            PrismaClient["Prisma ORM Client"]
        end

        subgraph BioService["Microsserviço Python (Porta 8000)"]
            FastAPI["FastAPI 0.111"]
            FaceRecognition["InsightFace / Dlib (128D Embeddings)"]
        end

        subgraph Database["PostgreSQL 16 (Porta 5432)"]
            PGVector["Extensão pgvector (Busca Vetorial L2)"]
            RelationalData["Tabelas Relacionais (17 Modelos)"]
        end
    end

    UserBrowser & TotemClient & WhatsAppBot --> Cloudflare
    Cloudflare --> Tunnel
    Tunnel --> WebApp
    WebApp <--> BioService
    WebApp <--> Database
    BioService <--> Database

🚀 Tecnologias Utilizadas

Frontend & Interface

Backend, Banco & Inteligência Artificial

Scanner, Mídia & Áudio

Testes & Qualidade de Software

✨ Módulos e Funcionalidades

1. 🏷️ Gestão de Patrimônio & Linha do Tempo Vitalícia

2. 🗄️ Estoque Físico, Armário & Caixas Organizadoras

3. 🤝 Empréstimos, Devoluções & Cautelas A4

4. 🔧 Ordens de Serviço, Manutenção & Horímetro de Projetores

5. 👤 Biometria Facial & Embeddings Vetoriais (pgvector)

6. 🎟️ Eventos Acadêmicos, Presença Facial & Sorteios ao Vivo

7. 📺 Totem de Autoatendimento & Modo Telão (Presentation Mode)

8. 📱 Scanner Mobile de QR Code e Código de Barras (/scanner)

9. 📅 Central de Agendamentos & Gestão de Salas

10. 📊 Relatórios Gerenciais, Checklist & Exportação

11. 🤖 API REST Externa, Webhooks & Integração n8n/WhatsApp

12. 🔒 Segurança, Auditoria, RBAC & LGPD

🚪 Estrutura do Armário Físico

O armário principal de TI e Multimídia está organizado fisicamente em 3 portas e 18 caixas padronizadas:

┌─────────────────────────┬─────────────────────────┬─────────────────────────┐
│         PORTA 1         │         PORTA 2         │         PORTA 3         │
│     (Lado Esquerdo)     │        (Centro)         │     (Lado Direito)      │
├─────────────────────────┼─────────────────────────┼─────────────────────────┤
│ [C001] Cabos HDMI 2m/3m │ [C007] Cabos HDMI 10m   │ [C013] Projetores Epson │
│ [C002] Cabos VGA & DVI  │ [C008] Cabos HDMI 15m   │ [C014] Projetores BenQ  │
│ [C003] Cabos Rede CAT6  │ [C009] Adaptadores Mac  │ [C015] Caixas de Som    │
│ [C004] Mouses USB/Sem F │ [C010] Microfones Lapela│ [C016] Microfones S/ Fio│
│ [C005] Teclados ABNT2   │ [C011] Microfones Pedest│ [C017] Extensões & Filt │
│ [C006] Cabos de Força   │ [C012] Passadores Slides│ [C018] Pilhas & Baterias│
└─────────────────────────┴─────────────────────────┴─────────────────────────┘

📁 Estrutura de Pastas do Projeto

unifap-estoque/
├── docker-compose.yml              # Orquestração: PostgreSQL + Biometric API + Next.js App + Cloudflared
├── package.json                    # Dependências e scripts do ecossistema Next.js
├── start-db.ps1                    # Script PowerShell para inicialização rápida
├── biometric-api/                  # Microsserviço Python FastAPI de Biometria Facial
│   ├── Dockerfile                  # Container do microsserviço biométrico
│   ├── requirements.txt            # Dependências Python (FastAPI, OpenCV, InsightFace, pgvector)
│   └── app/                        # Código-fonte da API biométrica (config, rotas, modelos)
├── docs/                           # Documentação técnica e relatórios institucionais
│   └── RELATORIO_AUDITORIA_SEGURANCA.md # Relatório completo de auditoria de segurança & LGPD
├── prisma/
│   ├── schema.prisma               # Modelagem completa do banco de dados (17 tabelas relacionais)
│   └── seed.ts                     # Script de população idempotente e criação de usuários padrão
├── public/                         # Arquivos públicos e estáticos
└── src/
    ├── middleware.ts               # Edge Middleware de autenticação e proteção RBAC
    ├── app/                        # Rotas e páginas do Next.js App Router (76 rotas)
    │   ├── (auth)/login/           # Autenticação institucional com rate limiter
    │   ├── (dashboard)/            # Shell autenticado do sistema
    │   │   ├── dashboard/          # Métricas, KPIs e gráficos em tempo real
    │   │   ├── armario/ & caixas/  # Mapeamento do armário físico e caixas organizadoras
    │   │   ├── estoque/            # Gestão de materiais e movimentações atômicas
    │   │   ├── patrimonio/         # Tombamento e linha do tempo de equipamentos
    │   │   ├── emprestimos/        # Checkout de empréstimo e cautelas A4
    │   │   ├── manutencao/         # Ordens de serviço e horímetro de projetores
    │   │   ├── eventos/            # Gestão de eventos, credenciamento e sorteador
    │   │   ├── biometria/          # Cadastro biométrico e gerenciamento de pessoas
    │   │   ├── scanner/            # Scanner mobile de QR Code via câmera
    │   │   ├── relatorios/         # 5 relatórios analíticos e checklist
    │   │   ├── agenda/ & salas/    # Agendamento de salas e equipamentos
    │   │   └── usuarios/           # Gestão de operadores e perfis de acesso
    │   ├── totem/[eventId]/        # Totem de check-in facial em tela cheia
    │   ├── presentation/[eventId]/ # Telão ao vivo para auditórios
    │   └── api/v1/                 # Endpoints REST internos e externos
    ├── components/                 # Componentes React reutilizáveis (UI, modais, formulários)
    ├── lib/                        # Utilitários (Prisma, Auth, Anti-SSRF, Mascaramento LGPD, Áudio)
    ├── schemas/                    # Esquemas de validação com Zod
    ├── services/                   # Camada de serviços e regras de negócio
    └── __tests__/                  # Suíte de 135 testes automatizados com Vitest

🗄️ Modelo de Dados Relacional & Vetorial (Prisma ORM)

erDiagram
    User ||--o{ StockMovement : "realiza"
    User ||--o{ Loan : "cria/recebe"
    User ||--o{ Maintenance : "abre/encerra"
    User ||--o{ AuditLog : "gera"
    User ||--o{ ApiKey : "possui"

    Door ||--o{ Box : "contém"
    Box ||--o{ Inventory : "armazena"
    Box ||--o{ Asset : "guarda"

    Category ||--o{ Item : "classifica"
    Item ||--o{ Inventory : "saldo"
    Item ||--o{ Asset : "tombamentos"
    Item ||--o{ StockMovement : "movimenta"

    Asset ||--o{ AssetHistory : "trilha"
    Asset ||--o{ Loan : "emprestado"
    Asset ||--o{ Maintenance : "manutenções"

    Person ||--o{ FaceEmbedding : "vetores 128D"
    Person ||--o{ Presence : "presenças"
    Person ||--o{ EventParticipant : "inscrições"

    Event ||--o{ EventParticipant : "participantes"
    Event ||--o{ Presence : "presenças"
    Event ||--o{ Prize : "prêmios"
    Event ||--o{ Draw : "sorteios"
    Draw ||--o{ Winner : "ganhadores"

🛠️ Guia de Instalação e Execução

Opção A: Implantação Completa com Docker Compose (Produção / Cloudflare Tunnel)

Esta é a opção recomendada para produção. Todos os serviços (Next.js, FastAPI, PostgreSQL com pgvector e Cloudflared Tunnel) sobem de forma orquestrada e com as portas do host restritas à interface local (127.0.0.1).

  1. Clonar o Repositório: 
    git clone https://github.com/RivaldoMascarenhas/EstoqueMultimidia.git
cd EstoqueMultimidia
  2. Configurar o Arquivo .env: 
    cp .env.example .env

    Edite o .env e preencha com senhas fortes geradas aleatoriamente e o seu token do Cloudflare Tunnel:

    # Gerar segredos fortes no terminal:
openssl rand -base64 32
  3. Subir os Containers com Build: 
    docker compose up -d --build
  4. Sincronizar o Banco e Executar o Seed Inicial: 
    # Executa o seed dentro do ambiente da aplicação
docker compose exec app npm run prisma:push
docker compose exec app npm run prisma:seed
  5. Pronto! O sistema estará disponível com HTTPS no seu subdomínio configurado no Cloudflare Tunnel e localmente em http://localhost:3000.

Opção B: Execução Local para Desenvolvimento

  1. Instalar Dependências: 
    npm install
  2. Iniciar o Banco de Dados PostgreSQL: 
    # Via Docker Compose (apenas o banco):
docker compose up postgres -d
  3. Sincronizar o Esquema e Rodar o Seed: 
    npm run prisma:push
npm run prisma:seed
  4. Iniciar o Servidor Next.js em Modo Dev: 
    npm run dev

    Acesse: http://localhost:3000

🔐 Variáveis de Ambiente (.env)

Variável Descrição Exemplo / Padrão
DATABASE_URL URL de conexão com o PostgreSQL postgresql://postgres:senha@localhost:5432/estoque_multimidia
POSTGRES_USER Usuário do banco de dados postgres
POSTGRES_PASSWORD Senha segura do banco de dados gere_com_openssl_rand
POSTGRES_DB Nome da base de dados estoque_multimidia
NEXTAUTH_URL URL pública da aplicação http://localhost:3000 ou https://estoque.fapce.edu.br
NEXTAUTH_SECRET Chave mestra de assinatura JWT gere_com_openssl_rand_-base64_32
BIOMETRIC_API_URL URL do microsserviço FastAPI http://localhost:8000 (dev) / http://biometric-api:8000 (docker)
BIOMETRIC_INTERNAL_TOKEN Token interno de comunicação Next.js ↔ FastAPI token_secreto_interno
RECOGNITION_TOLERANCE Limiar de distância Euclidiana L2 para reconhecimento 0.60
CLOUDFLARE_TUNNEL_TOKEN Token de autenticação do Cloudflare Tunnel eyJhIjoi...

🔑 Contas de Demonstração & Seed Local

O script de inicialização (prisma/seed.ts) permite popular o banco local com perfis de teste para validação de fluxos e permissões.

[!IMPORTANT] Segurança de Produção: Em ambientes de produção, o seed não utiliza credenciais pré-fixadas e exige a definição da variável SEED_DEFAULT_PASSWORD (ou gera senhas seguras pseudo-aleatórias descartáveis), ativando troca obrigatória de senha (mustChangePassword: true) para todas as contas criadas.

Perfil de Teste E-mail de Exemplo Role RBAC Escopo de Permissões
Administrador admin@exemplo.local ADMIN Acesso total a configurações, usuários, auditoria e chaves de API.
Gestor Multimídia gestor@exemplo.local GESTOR Gestão de patrimônio, estoque, OS, eventos, relatórios e auditoria.
Operador de TI operador@exemplo.local OPERADOR Empréstimos, devoluções, baixas/entradas, presenças e scanner.
Apoio Acadêmico docente@exemplo.local ACADEMIC_SUPPORT Requisição de equipamentos pedagógicos e agendamento de salas.

🛡️ Perfis de Acesso (RBAC)

Módulo / Funcionalidade ADMIN GESTOR OPERADOR ACADEMIC_SUPPORT
Dashboard & Indicadores Gerais ✅ ✅ ✅ ✅ (Resumido)
Agendamento & Requisição de Salas ✅ ✅ ✅ ✅
Scanner Mobile de QR Code ✅ ✅ ✅ ❌
Consultar Armário & Caixas Físicas ✅ ✅ ✅ ❌
Empréstimos, Devoluções & Cautelas A4 ✅ ✅ ✅ ❌
Movimentações de Estoque (Entrada/Baixa) ✅ ✅ ✅ ❌
Ordens de Serviço & Manutenção ✅ ✅ ✅ ❌
Eventos Acadêmicos, Presença & Sorteios ✅ ✅ ✅ ❌
Cadastro Biométrico Facial ✅ ✅ ✅ ❌
Exportação de Relatórios & Checklist ✅ ✅ ❌ ❌
Gestão de Usuários & Redefinição de Senhas ✅ ❌ ❌ ❌
Trilha de Auditoria & Chaves de API ✅ ❌ ❌ ❌

🧪 Suíte de Testes Automatizados (Vitest)

O sistema possui uma suíte abrangente de testes automatizados cobrindo segurança, integridade referencial, concorrência, ciclos de vida de empréstimos, validação LGPD e prevenção de vulnerabilidades:

# Executar todos os testes automatizados:
npm test

Resultados da Suíte de Testes

✓ src/__tests__/security-edge.test.ts (8 tests)
✓ src/__tests__/events/exhaustive-events.test.ts (21 tests)
✓ src/__tests__/request-e2e-workflow.test.ts (21 tests)
✓ src/__tests__/users-api.test.ts (9 tests)
✓ src/__tests__/shift.service.test.ts (7 tests)
✓ src/__tests__/multimidia-platform.test.ts (7 tests)
✓ src/__tests__/loan-lifecycle.test.ts (6 tests)
✓ src/__tests__/room-projector.test.ts (6 tests)
✓ src/__tests__/lgpd-compliance.test.ts (5 tests)
✓ src/__tests__/maintenance-lifecycle.test.ts (5 tests)
✓ src/__tests__/api-auth.test.ts (5 tests)
✓ src/__tests__/asset-availability-scheduling.test.ts (5 tests)
✓ src/__tests__/api-guard.test.ts (4 tests)
✓ src/__tests__/concurrency.test.ts (3 tests)
✓ src/__tests__/security-hardening.test.ts (3 tests)
...

Test Files: 25 passed (25)
Tests:      135 passed (135)
Duration:   3.05s

🔌 Documentação da API Externa (n8n / WhatsApp / Bots)

A API REST externa permite integrar o sistema com automações no n8n, chatbots do WhatsApp e agentes de IA.

Autenticação

Envie o token no cabeçalho HTTP:

Authorization: Bearer <sua_chave_ou_token_de_api>

ou

x-api-key: <sua_chave_ou_token_de_api>

Endpoints Principais

1. Consulta em Linguagem Natural (NLP para WhatsApp)

2. Checkout de Empréstimo via Bot

3. Devolução de Equipamento via Bot

4. Abertura de Ordem de Serviço (Chamado Técnico)

🔒 Segurança da Informação e Conformidade LGPD

O sistema foi rigorosamente auditado contra os padrões do OWASP Top 10 e a Lei Geral de Proteção de Dados (Lei nº 13.709/2018). Para conferir a análise detalhada de cada vulnerabilidade remediada, consulte:

📄 Relatório Técnico de Auditoria de Segurança & LGPD

Principais Salvaguardas Implementadas:

  1. Proteção Anti-SSRF: Validação centralizada (src/lib/ssrf.ts) com bloqueio a redes internas e metadados de nuvem.
  2. Defesa em Profundidade: Cobertura estrita do Edge Middleware em 100% das páginas autenticadas.
  3. Rate Limiting Inteligente: Proteção dupla contra força bruta (por conta e por IP real extraído do Cloudflare).
  4. Mascaramento de Dados Sensíveis: CPFs e contatos são ofuscados na camada de apresentação e em respostas de feeds públicos.
  5. Zero Trust & Cloudflare Tunnel: Nenhuma porta do banco ou da aplicação precisa ser exposta publicamente no firewall do servidor.

🖨️ Impressão Oficial de Documentos (A4)

O sistema conta com folhas de estilo @media print otimizadas para gerar documentos em folha A4 com identidade visual institucional:

  1. Termo Oficial de Cautela e Responsabilidade: Gerado na tela de empréstimos, com dados do solicitante, equipamento tombado, prazo de devolução, termos legais de uso, QR Code de validação e campo de assinaturas.
  2. Ordem de Serviço Institucional: Ficha completa da OS com número de protocolo, sintomas relatados, laudo técnico, peças substituídas e assinaturas.
  3. Etiquetas Adesivas com QR Code: Emissão de etiquetas para caixas físicas do armário e selos adesivos de patrimônio.
  4. Relatórios Gerenciais de Inventário: Impressão de relatórios analíticos para auditorias institucionais e prestações de contas.

⌨️ Atalhos Rápidos de Teclado

Atalho Ação
Ctrl + K / ⌘ + K Abre a Busca Global Instantânea (Spotlight) em qualquer tela do sistema.
Esc Fecha modais, janelas de diálogo e a busca global.
Enter Confirma seleção no Spotlight ou executa a busca rápida.

📜 Scripts NPM Disponíveis

Comando Descrição
npm run dev Inicia o servidor de desenvolvimento Next.js.
npm run build Compila o projeto e gera o bundle de produção otimizado.
npm run start Inicia o servidor em modo de produção.
npm test Executa a suíte de 135 testes automatizados com Vitest.
npm run lint Executa a verificação estática do código com ESLint.
npm run prisma:push Sincroniza o schema do Prisma com o PostgreSQL sem gerar migrações.
npm run prisma:migrate Cria e aplica migrações versionadas no Prisma.
npm run prisma:seed Popula o banco com os dados iniciais institucionais da UniFAP.
npm run prisma:studio Abre a interface web visual do Prisma Studio para inspeção do banco.
npm run docker:up Sobe o ecossistema de containers via Docker Compose.
npm run docker:down Encerra os containers do Docker.
npm run docker:logs Exibe os logs em tempo real dos containers.

📚 Documentação de Produção & Deploy Contínuo

🏢 Instituição & Equipe

UniFAP — Tecnologia, Inovação e Excelência a Serviço da Educação