# Relatório Final do MVP — Sistema de Compras, Estoque e Locação (Grupo 1AMS)

Stack: **React (PWA)** · **NestJS (Node)** · **PostgreSQL + Prisma**. Tudo open source.
Data de encerramento do MVP: 2026-06-09.

---

## 1. Estrutura final do banco de dados (33 tabelas)

### Hierarquia organizacional
| Tabela | Propósito | Campos-chave |
|---|---|---|
| `empresa` | Empresas do grupo | razao_social, nome_fantasia, cnpj, ativo |
| `filial` | Filiais de cada empresa | empresa_id, nome, cnpj, endereco |
| `centro_custo` | Centros de custo por filial | empresa_id, filial_id, codigo, nome |

### Usuários e permissões
| Tabela | Propósito | Campos-chave |
|---|---|---|
| `usuario` | Pessoas que acessam | nome, email, senha_hash, trocar_senha, acesso_remoto, two_factor_* |
| `perfil` | Funções (Administrador, Gestão…) | nome, is_sistema |
| `permissao` | Capacidades liberáveis | codigo, descricao |
| `perfil_permissao` | Permissões padrão por perfil | perfil_id, permissao_id |
| `usuario_perfil` | Perfis de cada usuário | usuario_id, perfil_id |
| `usuario_permissao` | Ajuste fino por pessoa (concede/revoga) | usuario_id, permissao_id, concedida |
| `usuario_acesso_hierarquia` | Quais empresas/filiais/centros o usuário enxerga | usuario_id, empresa_id, filial_id, centro_custo_id |
| `ip_permitido` | Lista de IPs liberados (trava por rede) | empresa_id, filial_id, cidr, ativo |

### Alçada de aprovação
| Tabela | Propósito | Campos-chave |
|---|---|---|
| `alcada_regra` | Faixas de valor | valor_min, valor_max, requer_dupla_aprovacao, ordem |
| `alcada_aprovador` | Quem aprova cada faixa (perfil ou pessoa) | regra_id, tipo, perfil_id, usuario_id, ordem |

### Compras (Módulo 1)
| Tabela | Propósito | Campos-chave |
|---|---|---|
| `requisicao` | Requisição de compra | numero, empresa/filial/centro_custo, categoria, solicitante, comprador, veiculo, fornecedor, preco_solicitado, motivo, urgencia, status |
| `requisicao_anexo` | Anexos (foto, orçamento, documento) | requisicao_id, tipo, arquivo |
| `requisicao_aprovacao` | Etapas de decisão (alçada/dupla) | requisicao_id, aprovador_id, perfil_esperado_id, decisao, motivo |
| `motivo_recusa` | Catálogo de motivos de recusa | codigo, descricao |
| `categoria` | Categorias de compra | nome |

### Cadastros e Frota
| Tabela | Propósito | Campos-chave |
|---|---|---|
| `veiculo` | Frota | placa, modelo, ano, km_atual, centro_custo, status |
| `fornecedor` | Fornecedores | razao_social, cnpj, telefone, contato, categoria |
| `despesa_veiculo` | **(preparada)** despesas de frota (Diesel, Sem Parar…) | veiculo_id, tipo, valor, data, km, litros, origem |

### Preparadas para a Fase 2/3
| Tabela | Módulo | Propósito |
|---|---|---|
| `orcamento` | 1.5 | Orçamento mensal/anual por centro/empresa |
| `item_estoque` | 2A | Itens de consumo (saldo) |
| `movimento_estoque` | 2A | Entradas/saídas (baixa por QR) |
| `ativo_qr` | 2B | Ativos com QR (cabine/componente) |
| `cabine` | 2B | Banheiro químico (modelo calculado) |
| `componente` | 2B | Peças serializadas da cabine |
| `composicao` | 2B | Histórico de qual peça em qual cabine |
| `ordem_locacao` | 3 | Ordem de locação (cliente, qtd, tipo) |
| `entrega` | 3 | Entrega/devolução (foto, GPS) |
| `integracao_outbox` | ADMServ | Fila de espelhamento (TXT/API futura) |

### Rastreabilidade (atravessa tudo)
| Tabela | Propósito |
|---|---|
| `audit_log` | Quem fez, o quê, quando, de qual IP |
| `status_historico` | Toda mudança de status, rastreável |

---

## 2. Módulos concluídos (MVP)

1. **Controle de acesso** — login individual, perfis, permissões (menor privilégio),
   troca de senha no 1º acesso, auditoria de login.
2. **Cadastro de Fornecedores** — CRUD, busca, inativação lógica.
3. **Cadastro de Veículos** — CRUD, placa única, histórico de status.
4. **Requisição de Compra** — número automático, empresa/centro/categoria,
   solicitante automático, prioridade, justificativa, anexos, veículo/fornecedor,
   status (Rascunho→Pendente→Aprovada/Rejeitada→Comprada), histórico e auditoria.
5. **Aprovação por Alçada** — matriz configurável, roteamento por faixa,
   múltiplos níveis, **dupla aprovação**, motivo obrigatório na recusa, fila de
   aprovações mobile-first, decisões com histórico e auditoria, estrutura de
   notificação (pronta para push/WhatsApp).
6. **Dashboard Gerencial** — total/aprovado/reprovado/emergenciais, ticket médio,
   indicadores executivos, compras por empresa/centro/categoria/veículo (com %),
   Top 10 fornecedores, evolução mensal (gráfico de linha), filtros.
7. **Exportação Excel** — requisições e histórico de aprovações, por período,
   empresa, centro de custo e status.
8. **Operação/Produção** — backup automático do PostgreSQL (diário, 30 dias),
   Administrador Master, documentação de instalação e `.env.example`.

---

## 3. Fase 2 (próxima — arquitetura já preparada)

- **Módulo 1.5 — Controle Orçamentário:** orçamento por centro/empresa, consumo
  na aprovação, alertas 80%/100%/120% (trava + aprovação especial).
- **Módulo 2A — Estoque de Consumo (QR):** entrada/saída por leitura, alimenta o
  "tem em estoque" e o "retirar do estoque?" da requisição.
- **Frota avançada:** Diesel, Sem Parar, **custo total por veículo**, custo/km,
  importação de planilha Excel da frota (tabela `despesa_veiculo` já criada).
- **Inteligência de preço / desperdício:** alerta de desvio vs. última compra,
  checklist de decisão na aprovação, diagnóstico de recusas.
- **Notificações:** push (PWA) e/ou WhatsApp para aprovadores e solicitante.

## 4. Fase 3 (posterior)

- **Módulo 2B — Banheiros Químicos (QR):** cabine + componentes por leitura,
  modelo calculado (Simples/Luxo/Super Luxo), rastreabilidade por peça,
  manutenção e limpeza.
- **Módulo 3 — Logística/Locação:** entrega via celular do motorista (QR, foto,
  GPS), vínculo cabine↔ordem, devolução, ocupação da frota, modo offline.
- **Integração ADM Server:** geração de arquivo **TXT** (sem API) e, quando a API
  for fornecida, espelhamento via `integracao_outbox`.
- **Reforços de segurança:** 2FA nas contas remotas, trava por IP fixo, escopo de
  hierarquia aplicado nas telas.

---

## 5. Publicação na Hostinger (VPS) — passo a passo

> Requer **VPS** (Node + PostgreSQL). Estimativa: **VPS KVM 2** (2 vCPU, 8 GB) ≈
> R$ 45–60/mês + domínio (~R$ 40/ano). SSL grátis (Let's Encrypt).

1. **Contratar** a VPS (Ubuntu 22.04/24.04) no hPanel da Hostinger e apontar o
   **domínio** para o IP da VPS (registro A).
2. **Acessar por SSH** e atualizar: `sudo apt update && sudo apt upgrade -y`.
3. **Instalar Node 20+**: 
   `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`
4. **Instalar PostgreSQL**: `sudo apt install -y postgresql` e criar o banco:
   ```sql
   sudo -u postgres psql
   CREATE ROLE moderna LOGIN PASSWORD 'senha_forte' CREATEDB;
   CREATE DATABASE moderna_sany OWNER moderna;
   \c moderna_sany
   ALTER SCHEMA public OWNER TO moderna;
   ```
5. **Clonar o projeto** (ou enviar via Git/SFTP) para `/var/www/moderna`.
6. **Backend**:
   ```bash
   cd backend
   cp .env.example .env      # editar DATABASE_URL, JWT_SECRET, FRONTEND_ORIGIN, ADMIN_MASTER_*
   npm install
   npm run prisma:deploy
   npm run db:seed
   npm run criar-admin-master
   npm run build
   ```
7. **Subir o backend como serviço** com PM2:
   `sudo npm i -g pm2 && pm2 start "npm run start:prod" --name moderna-api && pm2 save && pm2 startup`
8. **Frontend**: `cd ../frontend && npm install && npm run build` (gera `dist/`).
9. **Nginx** (servir o `dist/` e fazer proxy do `/api` para a porta 3000):
   ```nginx
   server {
     server_name seu-dominio.com.br;
     root /var/www/moderna/frontend/dist;
     index index.html;
     location / { try_files $uri /index.html; }
     location /api/ { proxy_pass http://localhost:3000; proxy_set_header Host $host;
                      proxy_set_header X-Forwarded-For $remote_addr; }
   }
   ```
   `sudo apt install -y nginx && sudo nginx -t && sudo systemctl reload nginx`
10. **HTTPS** com Certbot:
    `sudo apt install -y certbot python3-certbot-nginx && sudo certbot --nginx -d seu-dominio.com.br`
11. **Backup automático** (cron diário às 02:00) — ver seção 6.
12. **Testar**: acessar `https://seu-dominio.com.br`, logar e validar o fluxo.

---

## 6. Backup e restauração do banco

**Backup (diário, retenção 30 dias).** No Windows, o script já existe em
`infra/backup/backup-postgres.ps1` (agende no Agendador de Tarefas — ver
`infra/backup/README.md`). No Linux/VPS, equivalente com cron:

```bash
# /etc/cron.d/moderna-backup  (roda 02:00 todo dia)
0 2 * * * postgres pg_dump -Fc moderna_sany > /var/backups/moderna_$(date +\%F).dump && \
          find /var/backups -name 'moderna_*.dump' -mtime +30 -delete
```

**Restauração** (a partir de um arquivo `.dump`):

```bash
pg_restore -U moderna -h localhost -d moderna_sany --clean /var/backups/moderna_AAAA-MM-DD.dump
```

> No Windows: `& "C:\Program Files\PostgreSQL\17\bin\pg_restore.exe" -U moderna -h localhost -d moderna_sany --clean caminho\arquivo.dump`

---

## 7. Credenciais padrão do Administrador Master

| Campo | Valor |
|---|---|
| E-mail | `admin.master@1ams.com.br` |
| Senha inicial | `Master@2026` |
| Observação | **Troca obrigatória no 1º acesso.** Perfil Administrador, acesso de qualquer lugar, visão de todas as empresas. |

> Em produção, defina `ADMIN_MASTER_EMAIL` e `ADMIN_MASTER_SENHA` no `.env` antes
> de rodar `npm run criar-admin-master`, e **troque a senha** no primeiro acesso.
> Usuários do seed (Bruno, Nataly, Cristiano, Supervisor, Comprador) usam a senha
> `Moderna@2026` — devem ser revisados/desativados em produção.

---

## 8. Arquivos a preservar em backup antes de futuras atualizações

| Item | Caminho | Por quê |
|---|---|---|
| Banco de dados | dump do PostgreSQL (seção 6) | todos os dados reais |
| Variáveis/segredos | `backend/.env` | conexão, JWT_SECRET, senhas (**fora do Git**) |
| Anexos enviados | `backend/uploads/` | fotos, orçamentos, documentos (**fora do Git**) |
| Backups gerados | `infra/backup/backups/` | histórico de cópias |
| Logomarca | `frontend/public/logo.png` | identidade visual |
| Migrações | `backend/prisma/migrations/` | histórico do schema (versionado no Git) |

> Regra de ouro antes de atualizar: **(1)** fazer um `pg_dump` novo, **(2)** copiar
> `backend/.env` e `backend/uploads/`, **(3)** então atualizar o código e rodar
> `npm run prisma:deploy`.

---

## 9. Checklist de implantação em produção

- [ ] VPS contratada (Ubuntu) e **domínio** apontado para o IP.
- [ ] PostgreSQL instalado; banco `moderna_sany` e usuário `moderna` criados.
- [ ] `backend/.env` com **JWT_SECRET novo e aleatório** e `DATABASE_URL` de produção.
- [ ] `FRONTEND_ORIGIN` com o domínio real (CORS).
- [ ] `npm run prisma:deploy` (tabelas) + `npm run db:seed` (dados base).
- [ ] **Administrador Master** criado e senha trocada no 1º acesso.
- [ ] Usuários de exemplo (seed) revisados/desativados; senhas trocadas.
- [ ] Backend rodando via **PM2** (reinício automático).
- [ ] Frontend `dist/` servido pelo **Nginx**.
- [ ] **HTTPS** ativo (Certbot) e redirecionando HTTP→HTTPS.
- [ ] **Backup automático** diário configurado e testado (gerar + restaurar 1 vez).
- [ ] **Logomarca** oficial em `frontend/public/logo.png`.
- [ ] (Quando disponível) **IP fixo** da empresa cadastrado e **2FA** ativado nas
      contas de acesso remoto (Bruno/Nataly/Admin Master).
- [ ] Teste de aceite final: criar requisição → aprovar (celular) → dashboard → exportar Excel.

---

**MVP oficialmente encerrado e pronto para implantação.**