# CLAUDE.md — Guia de continuidade do projeto

> Leia este arquivo primeiro. Ele permite a uma nova sessão continuar de onde
> paramos. Detalhes em `docs/` (ARQUITETURA, DOCUMENTACAO, RELATORIO-FINAL-MVP,
> PLANO, PROXIMA-FASE, BACKLOG).

## O que é
Sistema web de **Compras, Estoque e Locação** do Grupo 1AMS (A Moderna Sany,
ISANQUI, 1AMS LOG). Usuário/dono: **Bruno** (não-programador, PT-BR, valida
testando cada parte). Fale simples e mostre rodando.

## Stack
- **Frontend** `frontend/`: React 19 + Vite + TypeScript + Tailwind v4 (PWA). axios, react-router-dom.
- **Backend** `backend/`: NestJS 11 (Node 24) + **Prisma 6** (NÃO usar 7) + PostgreSQL 17. JWT+bcrypt, exceljs, multer.
- Tudo open source. Local: Windows.

## Ambiente local (IMPORTANTE)
- Projeto: `C:\Users\bruno.silva\Desktop\Sistema Moderna Sany`.
- **Node não está no PATH do Bash.** No PowerShell, prefixe comandos com:
  `$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User");`
- **Banco:** PostgreSQL 17. DB `moderna_sany`, app user `moderna` / senha `moderna_dev_2026`, superuser `postgres` / `postgres`. `DATABASE_URL` no `backend/.env`. `psql` em `C:\Program Files\PostgreSQL\17\bin\psql.exe`.
- **Rodar (preview MCP é o jeito mais estável):** `.claude/launch.json` define `frontend` (vite) e `backend` (`node --use-system-ca dist/src/main.js`). **O backend roda do `dist/` — rode `npm run build` no backend antes de (re)iniciar.** Para regenerar o Prisma client, **pare o backend antes** (a DLL fica travada).
- **Quirks do preview:** servidores às vezes são encerrados entre turnos (basta `preview_start` de novo). Screenshots **travam depois de navegar via `location.href`** ou após muitos cliques — recupere com `preview_stop`+`preview_start`, injete o token no `localStorage` (`moderna.token`), `location.reload()`, e navegue clicando nos links do menu (SPA). O login pela UI dispara o diálogo "salvar senha" do navegador que **trava screenshots** — prefira injetar o token.
- **Rede do backend:** a consulta de CNPJ (BrasilAPI) só funciona com `node --use-system-ca` (a rede do Bruno faz interceptação de TLS) **e** com header `User-Agent` (Cloudflare bloqueia o UA padrão do Node com 403). Já está assim no código e no launch.json.
- **Túnel de teste no celular:** `cloudflared` instalado (winget). Rodar `cloudflared tunnel --url http://localhost:5173` → URL `*.trycloudflare.com` (muda a cada execução; exige PC ligado).

## Credenciais (DEV — trocar em produção)
Todos: senha **`Moderna@2026`**. `trocar_senha` está **desligado** na fase de build
(rode `npm run db:reset-senhas` para rearmar). Usuários seed:
- `bruno@1ams.com.br` (Administrador), `nataly@`/`cristiano@` (Gestão),
  `supervisor@` (Supervisor), `comprador@` (Comprador), `danilo@`/`andrei@`/`bianca@` (Solicitante),
  `admin.master@1ams.com.br` (Administrador Master, senha `Master@2026`).

## Estado atual — ✅ IMPLEMENTADO e validado
1. **Login/segurança:** JWT, bcrypt, troca de senha 1º acesso, **bloqueio após 5 falhas/15min**, **expiração por inatividade (30min)**, logout auditado.
2. **Permissões (menor privilégio):** perfis (Administrador, Gestão, Comprador, Solicitante, Pátio/Operação, Motorista, Supervisor); 9 permissões (`ver_preco, ver_relatorios, criar_requisicao, aprovar, estoque_2a, ativos_2b, locacao_m3, cotar, configurar`); o que não pode nem aparece. Guards globais.
3. **Requisição (fluxo em 3 papéis):** SOLICITANTE (itens até 10 c/ unidade e foto, destino, prazo) → COMPRAS (cotação: fornecedor + valores) → APROVAÇÃO (alçada pelo **valor total cotado**, dupla aprovação). Status: `RASCUNHO → SOLICITADA → EM_COTACAO → AGUARDANDO_APROVACAO → APROVADA/REJEITADA → COMPRADA`. Solicitante = usuário logado (Admin/Compras abrem em nome de outro). Centros restritos aos permitidos (validado + auditado). Dados comerciais ocultos sem `ver_preco`. Anexos, histórico, auditoria.
4. **Aprovação por alçada:** matriz configurável por valor/aprovador, fila mobile-first, motivo obrigatório na recusa.
5. **Dashboard:** KPIs, ticket médio, indicadores executivos, compras por empresa/centro/categoria/**veículo**, Top 10 fornecedores, evolução mensal (linha), filtros. **Exportação Excel** (requisições e aprovações).
6. **Cadastros administráveis (menu Cadastros, só `configurar`/Admin):** Empresas, **Filiais**, Usuários (perfil + empresas/centros permitidos), Centros de Custo (responsável **principal★** + corresponsáveis, ligados a filial), Categorias, Unidades de Medida, Destinos, **Fornecedores (completo)**, Veículos, Matriz de Alçada. Auditoria em tudo.
7. **Fornecedor completo:** ~30 campos (dados Receita, endereço, vendedor, classificação, status ATIVO/INATIVO/BLOQUEADO, preferencial, obs comerciais). **Consulta CNPJ** (BrasilAPI, preenche o form, não bloqueia em falha, alerta se não-ATIVA, link Receita). **Histórico automático** (`/fornecedores/:id/historico`): última compra, qtd, valor total, categorias/produtos top, tempo médio, ranking.
8. **Operação:** backup `pg_dump` diário/30d (`infra/backup/`, testado), Admin Master (`npm run criar-admin-master`), `criar requisição→aprovar no celular→dashboard→Excel` (critério de aceite do MVP) ✅.
9. **Empresas com CNPJ real** (cartões CNPJ): Moderna `13.604.140/0001-10`, ISANQUI `45.844.284/0001-30`.

## Em andamento / sugerido a seguir
- **Cotação inteligente (✅):** na cotação já mostra o **histórico do fornecedor** (nº de compras, última compra, ranking) + **alertas** (BLOQUEADO/INATIVO/Receita irregular); **último preço pago por item** (`GET /requisicoes/ultimo-preco?descricao=` → último `valorUnitario` em requisições COMPRADAS) com **variação %** (▲ vermelho aumentou / ▼ verde baixou); e **subtotais + total cotado ao vivo**. **Falta (opcional):** sugerir fornecedor automaticamente; tornar o "último preço" também ciente do veículo (hoje casa só pela descrição da peça).
- Carregar os **dados reais** do Bruno: fornecedores (da planilha "Controle de Gastos"), usuários de verdade, centros/categorias reais.

## O que ainda FALTA (Fase 2 / Fase 3 — preparado, não desenvolvido)
- **Pagamento na requisição:** forma de pagamento (PIX/boleto/cartão/30-60-90/DDL), **parcelas**, nº da NF, controle financeiro/baixa. (A planilha do Bruno tem essas colunas — combinado para Fase 2.)
- **Módulo 1.5** orçamento (alertas 80/100/120%); **Módulo 2A** estoque QR; **Módulo 2B** banheiros químicos QR; **Módulo 3** locação (entrega por celular, foto/GPS); **integração ADMServ via TXT**.
- **Notificações** push (PWA)/WhatsApp (estrutura `NotificacoesService` pronta, só loga).
- **2FA**, **trava por IP fixo**, **escopo de hierarquia nas listagens** (Admin ainda vê tudo) — reforços de produção.
- **Hospedagem definitiva** (Hostinger VPS — passo a passo em `docs/RELATORIO-FINAL-MVP.md`).
> As tabelas desses módulos **já existem** no banco. Entram como atualização, sem reconstruir.

## Banco de dados (37 tabelas)
Schema em `backend/prisma/schema.prisma` (fonte da verdade). Convenções: modelos em
português, `@@map` snake_case, `id/criadoEm/atualizadoEm`, exclusão lógica (`ativo`/status).
Para **alterar o banco:** editar schema → criar migration em `prisma/migrations/`
(o ambiente é não-interativo: **escrever o `migration.sql` à mão** e rodar
`npx prisma migrate deploy`; `migrate dev` falha por ser interativo) → `npx prisma generate`
(pare o backend antes). Para mudança de enum, recrie o tipo via SQL (ver migrações existentes).

## Convenções e decisões-chave
- **Banco nasce completo** (todos os módulos) — regra #1 do Bruno: não simplificar o schema.
- Hierarquia **Empresa → Filial → Centro de Custo** como base; tudo se amarra a ela.
- **Prisma 6** (estável), não 7 (que exige driver adapters).
- **Auditoria (`audit_log`) em toda escrita** e **`status_historico` em toda mudança de status** (regras #5/#6). Sanitiza senha/token.
- **Permissão `configurar`** = cadastros mestres (Admin). **`cotar`** = só Compras/Admin preenchem fornecedor/valores. Visibilidade comercial = `ver_preco`.
- Cadastros admin usam `@Body() any` (sem DTO) — são só-Admin. Endpoints de escrita auditam.
- Senhas via `.env`/segredos nunca no Git (`.gitignore` cobre `.env`, `uploads/`, backups).
- Idioma do produto: PT-BR. Identidade visual: verde `#2E7D32`, grafite `#263238`, branco. Logo em `frontend/public/logo.png` (Bruno vai enviar; hoje selo provisório "AM").

## Como retomar rapidamente
1. PowerShell com PATH (acima). `cd backend; npm run build`.
2. `preview_start` backend e frontend (launch.json). Conferir `GET /api/health`.
3. Login `bruno@1ams.com.br` / `Moderna@2026`. Testar o fluxo de requisição.
4. Memória do projeto: `~/.claude/projects/.../memory/` (MEMORY.md + notas).