Controle de Estoque TI — WAP
Sistema interno para substituir o controle de ativos de TI feito hoje em três planilhas desconectadas (inventário, saída e devolução) + revisão por Gmail + relatório semanal manual por filial.
Ideia central: registra-se só a movimentação (saída, devolução, compra, transferência…) uma única vez; o estado do ativo, o estoque e os relatórios por filial derivam automaticamente por trigger no banco. O relatório deixa de ser enviado por e-mail — vira um link sempre atualizado, protegido por senha.
O sistema está em produção desde o go-live de 15/07/2026 (1.596 ativos, 5 filiais). A entrada de dados do dia a dia é 100% manual pelo sistema — não há sincronização com planilhas.
Começar em 5 minutos
Pré-requisitos: Node 24+ e npm (o CI roda no 24, que é o LTS ativo; o desenvolvimento, no 26). Banco, Auth e Storage rodam num projeto Supabase de desenvolvimento — nunca produção.
npm install
cp .env.example .env.local # preencha com os valores do Supabase de DEV
npm run db:seed # popula o banco de DEV com dados ficticios
npm run dev # app em http://localhost:3000
Variáveis de ambiente (todas descritas em .env.example):
| Variável | Para quê |
|---|
NEXT_PUBLIC_SUPABASE_URL · NEXT_PUBLIC_SUPABASE_ANON_KEY | Cliente do navegador |
SUPABASE_SERVICE_ROLE_KEY | Só server-side e scripts — jamais em Client Component ou NEXT_PUBLIC_* |
VIEW_SESSION_SECRET | Assina o cookie da sessão de visualização por senha |
SEED_CONFIRM · SEED_PROJECT_REF | Guardas que impedem os scripts de dados fictícios de rodarem fora do DEV |
Nunca aponte .env.local para produção. scripts/env-guard.ts mantém a lista REFS_DE_PRODUCAO e faz db:seed/db:reset recusarem qualquer ref de produção — mas a guarda é a segunda linha, não a primeira.
Comandos
| Comando | O quê faz |
|---|
npm run dev · npm run build · npm run lint | Desenvolvimento · build de produção · lint (obrigatório ao fim de cada ordem) |
npm run test · npm run test:watch | Vitest — testes de funções puras (normalização de patrimônio, De→Para, datas, motor do import…) |
npm run db:seed | Popula o banco de DEV com dados fictícios determinísticos (jamais aponta para produção) |
npm run db:reset | Zera as tabelas de dados (exige as guardas do .env.local) |
npm run db:types | Regenera src/lib/types/database.ts a partir do schema |
npm run contraste | Confere o contraste das cores do sistema de design (F40) |
npm run db:test · npm run db:test:um <arquivo> | Roda os roteiros SQL de supabase/tests/ — o MESMO script que o CI roda (scripts/db/rodar-roteiros.sh). Precisa de um Postgres: DATABASE_URL=…, ou o local do supabase start (porta 54322). Nunca aponte para produção |
npm run verificar:actions | Gate de artefato: procura Server Action registrada sem binding no build. Rode depois de npm run build — ele lê .next/server |
npm run carga | Carga única do go-live (scripts/import/; guardas CARGA_*) — ferramenta, não feature |
O CI (.github/workflows/ci.yml) roda em todo push na main e em qualquer PR, com dois jobs: verificar (lint → test → contraste → build → verificar:actions) e banco-sem-docker, que sobe um Postgres 17 pelo services do runner, aplica todas as migrations em ordem por psql e roda os roteiros de supabase/tests/ pelo mesmo script que npm run db:test chama. Desde a F45 o cancelamento de execução em andamento vale só em PR: em push na main cada commit tem o CI dele do começo ao fim. O job de banco saiu do Docker do Supabase na F46 (3m52s → 57s) e o job banco antigo foi removido na v1.51.1, depois de os dois chegarem ao mesmo veredito em cinco runs seguidos — o que o supabase start dava de graça está declarado em supabase/ci/, e a receita para rodar o mesmo banco na mesa está em docs/RUNBOOK-BANCO.md. Desde a F47 o job de banco faz mais duas coisas: um gate de deriva compara o catálogo do Postgres com src/lib/types/database.ts e reprova quando o banco tem tabela, coluna ou função que o arquivo não conhece; e o injetor de mutações (npm run db:test:mutations) quebra o banco de propósito, 55 vezes, exigindo que o roteiro correspondente acuse o cenário nomeado — é a prova de que os roteiros sabem ficar vermelhos.
O portão da main está LIGADO desde 05/09/2026 (F45) — decisão do Johnny, ata em docs/DECISOES.md. verificar e banco-sem-docker são required status checks (o segundo era banco até a v1.51.1), com require pull request (0 aprovações) e bypass na conta do Johnny (enforce_admins: false). Provado de ponta a ponta: um PR com um roteiro SQL deliberadamente vermelho teve o merge recusado com "the base branch policy prohibits the merge" — docs/RELATORIO-F45.md §8.5.
Consequência aceita: da F46 em diante o caminho normal é PR, com espera do job banco (~3 a 6 min). O push direto continua passando para o Johnny — é o bypass —, e o GitHub avisa (2 of 2 required status checks are expected): usá-lo virou ato consciente.
O RISCO, dito por escrito: a proteção é configuração fora do repositório, e nenhuma trava interna impede que alguém a desligue no painel — src/lib/ci-passos.test.ts defende os passos do CI, não a proteção da branch. Ligar não é defender. Para conferir: gh api repos/vmatusita/ti-wap-inventory-control/branches/main/protection --jq '.required_status_checks.contexts'.
Stack (decidida em 09/07/2026)
- Next.js 16 (App Router, Turbopack) + React 19 + TypeScript strict
- Tailwind CSS v4 + shadcn/ui + Recharts v3 (análise de alternativas em
docs/PLANEJAMENTO.md §2.1)
- Supabase (plano Free) — Postgres, Auth (login por convite), RLS, Realtime, Storage
- Deploy: Vercel (conta Pro já paga — custo novo R$ 0 para a empresa)
A lista é fechada: dependência nova exige aprovação do Johnny. O inventário completo está no CLAUDE.md.
Duas regras que explicam metade do sistema
Patrimônio repete. O patrimônio identifica o equipamento, mas repete em casos raros — quem é único é o par patrimônio + service tag (spec §5, regra 1). Toda busca por patrimônio trata o caso de múltiplos resultados. Desde a F24 a identidade é por filial: o mesmo par pode coexistir em duas filiais, e o par vira a pendência "conflito entre filiais", resolvida na mesa de /pendencias.
Acesso são duas portas. Operar = login com conta corporativa (@wap.ind.br, @stefanini.com, @latam.stefanini.com), com quatro cargos em hierarquia estrita — Desenvolvedor ⊃ Administrador ⊃ Operador ⊃ Consulta. Todo perfil ativo lê tudo; o que se restringe é a escrita (operador escreve só nas filiais vinculadas; consulta não escreve nada). Visualizar relatórios = senha de acesso, sem conta — é outra porta, não um cargo. A regra mora no Postgres, não na tela: spec §3, docs/ADR-002-papeis-e-permissoes.md e docs/ADR-001-rls-por-filial.md.
Onde fica o quê
| Caminho | Conteúdo |
|---|
docs/README.md | Índice da documentação — comece por aqui para achar qualquer documento |
docs/ONBOARDING.md | Primeiro dia — do clone à primeira mudança em produção |
docs/ARQUITETURA.md | Como o sistema está construído; o mapa "quero mudar X → mexo em Y" |
docs/ESPECIFICACAO.md | O quê construir — modelo de dados, máquina de estados, telas, regras |
CLAUDE.md | Regras permanentes do agente (lido em toda sessão) |
CHANGELOG.md | Histórico fase a fase, da mais recente para a mais antiga |
src/ · supabase/migrations/ · scripts/ | Código · fonte da verdade do banco · ferramentas (seed, carga, perf, termos) |
mockups/dashboard-relatorio.html | Mockup navegável do relatório por filial |
A documentação do operador não está aqui: ela vive dentro do sistema, em /ajuda (28 páginas + manual imprimível), e o fonte é src/lib/ajuda/.
Status
Versão no ar: 1.57.0. A fonte única é src/lib/versoes/registry.ts — VERSOES[0] é a versão publicada, e um teste trava a divergência com o package.json. O operador vê o mesmo histórico em /versoes.
Entregue da F0 à F47: operação completa de ativos e movimentações, itens por quantidade, relatórios ao vivo e snapshots semanais com acesso por senha, termos gerados em .docx, import de startup por filial, cargos e permissões no Postgres, área /dev com zona destrutiva, e o sistema de design com /ativos e as três telas de /itens dentro do casco — a lista de itens mostrando, na própria linha, quanto tem em cada filial, e dizendo por extenso de qual filial são os números quando há filtro.
- O que mudou, fase a fase:
CHANGELOG.md — toda entrada tem uma versão correspondente
- O que falta: seção Pendências (roadmap) no fim do
CHANGELOG.md
- Por que cada escolha foi feita:
docs/DECISOES.md (append-only)
Definições que valem como referência permanente: as filiais oficiais (15/07/2026) são Matriz, CD-Afonso Pena, Linhares, Eusébio e Serra (Serra Park é filial própria; Filial-CE = Eusébio). Seguem em aberto, sem bloquear nada, as perguntas 4 a 7 da spec §13, mais A8 (compra com patrimônio pendente) e T11 (as duas definições de "semana") do backlog de UX — as três dependem de decisão do Johnny.
Como as fases funcionam
As ordens rodam em modo autônomo com acesso total (decisão de 09/07/2026, regras no CLAUDE.md): o Claude executa tudo — decisões, merge, deploy e produção — sem pedir autorização, compensando com autoproteções (backup/dry-run em operação destrutiva) e rastro auditável em docs/DECISOES.md. Cada fase é uma ordem de serviço em docs/prompts/; só se executa a ordem que o Johnny colar na conversa.
O sistema não nasce com os dados reais. O desenvolvimento roda com dados fictícios; os dados reais entram por carga de go-live: a carga global inicial pelos scripts da F4 (autônoma, na janela do go-live) e, desde a F7, o import de startup por filial pela tela admin/importar (só Substituir tudo — spec §10.2). A entrada do dia a dia continua 100% manual — ser mais prático que o Excel é o requisito central.
