# SISTEMA DE COMPRAS E FROTA – GRUPO 1AMS
## Manual Oficial do Sistema

> Documento em linguagem simples. Cada item traz o **status real**:
> ✅ implementado · 🟡 parcial · ⏳ pendente · 🧱 preparado (arquitetura pronta, sem tela).

---

## 1. Visão Geral do Projeto

**Objetivo:** centralizar e controlar as **compras** e a **frota** do Grupo 1AMS
(A Moderna Sany, ISANQUI, 1AMS LOG), com aprovação por alçada, rastreabilidade e
relatórios — substituindo o controle por planilha.

**Problemas que resolve:**
- Falta de controle de quem pediu, quem aprovou e quanto se gastou.
- Aprovações informais (sem alçada por valor).
- Fornecedores e veículos digitados “à mão”, sem padronização.
- Ausência de histórico e auditoria.
- Dificuldade de enxergar gastos por empresa, centro de custo, categoria e veículo.

**Escopo do MVP entregue:** login com perfis e permissões, cadastro de fornecedores
e veículos, requisição de compra, aprovação por alçada (com dupla aprovação),
dashboard gerencial e exportação em Excel — tudo com histórico e auditoria, e
telas que funcionam no celular.

---

## 2. O que foi Construído no MVP

| Módulo / Tela | O que faz | Status |
|---|---|---|
| **Login** | Acesso por e-mail e senha; troca obrigatória no 1º acesso; bloqueio após 5 tentativas; expiração por inatividade | ✅ |
| **Usuários e permissões** | Perfis (Administrador, Gestão, Comprador, Pátio/Operação, Motorista, Supervisor); cada um só vê o que sua função permite | ✅ |
| **Fornecedores** | Cadastrar, editar, buscar e inativar; usado nas requisições | ✅ |
| **Veículos** | Cadastrar, editar, buscar, inativar; placa única; histórico de status | ✅ |
| **Requisições** | Número automático, empresa/centro/categoria, solicitante automático, prioridade, justificativa, anexos, veículo/fornecedor; status Rascunho→Pendente→Aprovada/Rejeitada→Comprada | ✅ |
| **Aprovações por alçada** | Roteia para o aprovador certo pela faixa de valor; dupla aprovação acima de R$ 10.000; recusa exige motivo; fila do aprovador | ✅ |
| **Dashboard** | Total/aprovado/reprovado/emergenciais, 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 histórico de aprovações, por período/empresa/centro/status | ✅ |
| **Histórico e auditoria** | Toda mudança de status vira histórico; toda ação vira registro de auditoria (quem/quando/IP) | ✅ |
| **Responsividade (celular)** | Telas adaptam ao celular; fila de aprovações é mobile-first (PWA-ready) | ✅ |
| **Cadastros administráveis** | Empresas, **Filiais**, Usuários (perfil + empresas/centros permitidos), Centros de Custo (responsável principal + corresponsáveis, ligados a filial), Categorias, Unidades de Medida, Destinos, Veículos, Matriz de Alçada — tudo só para Administrador, com auditoria | ✅ |
| **Fornecedor completo** | ~30 campos (dados Receita, endereço, vendedor, classificação, status Ativo/Inativo/Bloqueado, preferencial, obs comerciais); **consulta automática de CNPJ** (preenche o form, alerta se não-ATIVA, link Receita); **painel de histórico automático** (compras, valor total, ranking, categorias/produtos) | ✅ |
| **Fluxo de requisição em 3 papéis** | Solicitante (itens/destino/prazo) → Compras (cotação) → Aprovação (alçada por valor cotado); solicitante = usuário logado; centros restritos ao permitido | ✅ |
| **Gerar/imprimir etiquetas QR; notificações push/WhatsApp** | — | ⏳ Fase 2/3 |

---

## 3. Stack Utilizada

- **Frontend:** TypeScript + **React 19** + **Vite** + **Tailwind CSS v4**; roteamento `react-router-dom`; HTTP `axios`. Funciona como **PWA** (instalável no celular).
- **Backend:** TypeScript + **NestJS 11** (Node.js). Autenticação **JWT** (`@nestjs/jwt` + `passport-jwt`), senha com **bcrypt**, validação com `class-validator`. Exportação Excel com **ExcelJS**. Upload com **Multer**.
- **Banco de dados:** **PostgreSQL 17**, acesso via **Prisma 6** (ORM) com migrações versionadas.
- **Infra/operação:** scripts de backup (`pg_dump`); túnel de teste com **cloudflared** (Cloudflare).

---

## 4. Estrutura de Pastas

```
Sistema Moderna Sany/
├── backend/                 # API (NestJS)
│   ├── src/
│   │   ├── auth/            # login, JWT, bloqueio, logout, troca de senha
│   │   ├── common/          # decorators e guards (permissões)
│   │   ├── prisma/          # serviço de acesso ao banco
│   │   ├── audit/           # auditoria (quem fez o quê)
│   │   ├── notificacoes/    # serviço de notificação (preparado p/ push/WhatsApp)
│   │   ├── referencias/     # listas auxiliares (empresas, centros, categorias…)
│   │   ├── fornecedores/    # cadastro de fornecedores
│   │   ├── veiculos/        # cadastro de veículos
│   │   ├── requisicoes/     # requisição + alçada + aprovação
│   │   └── dashboard/       # indicadores + exportação Excel
│   ├── prisma/
│   │   ├── schema.prisma    # modelo do banco (todas as tabelas)
│   │   ├── migrations/      # histórico de alterações do banco
│   │   ├── seed.ts          # carga inicial
│   │   └── criar-admin-master.ts
│   ├── uploads/             # anexos enviados (fora da pasta pública)
│   └── .env                 # segredos (NÃO versionar)
├── frontend/                # aplicação React (PWA)
│   ├── src/ (api, auth, components, pages)
│   └── public/logo.png      # logomarca oficial (a fornecer)
├── infra/backup/            # script e instruções de backup
└── docs/                    # esta e as demais documentações
```

---

## 5. Estrutura do Banco de Dados

**Diagrama textual (relacionamentos principais):**

```
Empresa ──< Filial ──< CentroCusto
   │                        │
   └──< Veiculo >── DespesaVeiculo (Diesel/Sem Parar… — preparado)
   └──< Fornecedor

Usuario >──< Perfil >──< Permissao        (perfis e permissões)
Usuario ──< UsuarioAcessoHierarquia (empresa/filial/centro que enxerga)

Requisicao ──< RequisicaoAnexo
Requisicao ──< RequisicaoAprovacao   (etapas de decisão; perfil/usuário esperado)
Requisicao >── Empresa, CentroCusto, Categoria, Solicitante, Comprador, Veiculo, Fornecedor

AlcadaRegra ──< AlcadaAprovador      (matriz de alçada configurável)

(qualquer entidade) ──> AuditLog / StatusHistorico   (rastreabilidade)
```

**Tabelas (37):**

- **Hierarquia:** `empresa`, `filial`, `centro_custo`, `centro_custo_responsavel`.
- **Acesso:** `usuario`, `perfil`, `permissao`, `perfil_permissao`, `usuario_perfil`, `usuario_permissao`, `usuario_acesso_hierarquia` (empresas/centros permitidos), `ip_permitido`.
- **Alçada:** `alcada_regra`, `alcada_aprovador`.
- **Compras:** `requisicao`, `requisicao_item`, `requisicao_anexo`, `requisicao_aprovacao`, `motivo_recusa`, `categoria`, `unidade_medida`, `destino`.
- **Cadastros/Frota:** `veiculo`, `fornecedor` (cadastro completo + dados Receita), `despesa_veiculo` 🧱.
- **Preparadas (Fase 2/3):** `orcamento`, `item_estoque`, `movimento_estoque`, `ativo_qr`, `cabine`, `componente`, `composicao`, `ordem_locacao`, `entrega`, `integracao_outbox` — todas 🧱.
- **Rastreabilidade:** `audit_log`, `status_historico`.

*(Finalidade campo a campo em [RELATORIO-FINAL-MVP.md](RELATORIO-FINAL-MVP.md), seção 1, e em `backend/prisma/schema.prisma`.)*

---

## 6. Como Rodar Localmente

```bash
# 1) Dependências
cd backend  && npm install
cd ../frontend && npm install

# 2) Configurar o .env do backend
cd ../backend
copy .env.example .env      # (Windows)   |  cp .env.example .env (Linux)
# editar DATABASE_URL e JWT_SECRET

# 3) Criar o banco (uma vez), no PostgreSQL:
#   CREATE ROLE moderna LOGIN PASSWORD 'senha' CREATEDB;
#   CREATE DATABASE moderna_sany OWNER moderna;
#   (conectado em moderna_sany) ALTER SCHEMA public OWNER TO moderna;

# 4) Migrações (cria as tabelas)
npm run prisma:deploy

# 5) Carga inicial + Administrador Master
npm run db:seed
npm run criar-admin-master

# 6) Backend
npm run start:dev           # http://localhost:3000/api

# 7) Frontend (em outro terminal)
cd ../frontend && npm run dev   # http://localhost:5173
```

---

## 7. Variáveis de Ambiente (`backend/.env`)

| Variável | Para que serve |
|---|---|
| `DATABASE_URL` | Endereço/credenciais do PostgreSQL |
| `JWT_SECRET` | Segredo que assina o token de login (use valor longo e aleatório) |
| `JWT_EXPIRES_IN` | Validade do token (padrão `8h`) |
| `PORT` | Porta da API (padrão `3000`) |
| `FRONTEND_ORIGIN` | Endereço do frontend liberado no CORS |
| `SEED_SENHA_PADRAO` | Senha inicial dos usuários do seed |
| `ADMIN_MASTER_NOME/EMAIL/SENHA` | Dados do Administrador Master |

> Estas variáveis **nunca** vão para o repositório — ficam só no `.env` (já no `.gitignore`).

---

## 8. Usuários de Exemplo

| Perfil | E-mail | Senha |
|---|---|---|
| Administrador | `bruno@1ams.com.br` | `Moderna@2026` |
| Gestão | `nataly@1ams.com.br` / `cristiano@1ams.com.br` | `Moderna@2026` |
| Comprador | `comprador@1ams.com.br` | `Moderna@2026` |
| Supervisor | `supervisor@1ams.com.br` | `Moderna@2026` |
| **Administrador Master** | `admin.master@1ams.com.br` | `Master@2026` |

> ⚠️ **AVISO OBRIGATÓRIO: trocar TODAS as senhas antes da implantação em produção**
> e desativar/remover os usuários de teste.

---

## 9. Como Publicar em Produção (resumo)

VPS (Ubuntu) → instalar **Node** e **PostgreSQL** → criar banco → enviar projeto →
`.env` de produção → `prisma:deploy` + `db:seed` + `criar-admin-master` →
`build` → backend via **PM2** → frontend (`dist/`) via **Nginx** → **HTTPS** com
Certbot → **backup** diário (cron) → testar. Passo a passo detalhado em
[RELATORIO-FINAL-MVP.md](RELATORIO-FINAL-MVP.md), seção 5.

---

## 10. Como Atualizar o Sistema Futuramente

1. **Antes de tudo:** fazer `pg_dump` novo e copiar `backend/.env` e `backend/uploads/`.
2. Subir a nova versão do código (git pull / envio dos arquivos).
3. Backend: `npm install` → `npm run prisma:deploy` (migrações) → `npm run build` → `pm2 restart moderna-api`.
4. Frontend: `npm install` → `npm run build` (atualiza a pasta `dist/`).
5. **Rollback:** voltar para a versão anterior do código e `pm2 restart`.
6. **Em caso de falha de dados:** restaurar o último backup (ver seção 11/RELATORIO).

---

## 11. O que Ficou Preparado para o Futuro (🧱 arquitetura pronta)

| Tema | No banco hoje | Falta desenvolver |
|---|---|---|
| Diesel / Sem Parar / Pedágio | tabela `despesa_veiculo` (com `tipo`, `litros`, `km`, `origem`) | telas e importação |
| Custos da frota / custo por km | base (compras por veículo + `despesa_veiculo`) | card de custo total |
| Importação Excel da frota | (ExcelJS já usado na exportação) | rotina de import |
| QR Code / Banheiros químicos (2B) | `ativo_qr`, `cabine`, `componente`, `composicao` | leitura por câmera, receitas, telas |
| Estoque (2A) | `item_estoque`, `movimento_estoque` | baixa por QR, telas |
| Locação (Módulo 3) | `ordem_locacao`, `entrega` (foto/GPS) | app do motorista |
| Orçamento (1.5) | `orcamento` | alertas 80/100/120% |
| ADM Server (TXT) | `integracao_outbox` | gerador do arquivo TXT |

> Nada disso tem tela/funcionalidade final no MVP — apenas a **estrutura**.

---

## 12. O que Ficou para a Fase 2

Inteligência de preço · comparação com a última compra · comparação entre
fornecedores · alertas de aumento de preço · controle orçamentário (1.5) ·
workflow avançado de recusa (diagnóstico) · estoque (2A) · QR Code · locação (3) ·
integrações (ADM Server, ZUQ) · notificações push/WhatsApp.

---

## 13. O que o Proprietário Precisa Providenciar

- **Logomarca** oficial (arquivo) → `frontend/public/logo.png`.
- **Domínio** (ex.: `.com.br`).
- **Hospedagem** na Hostinger (VPS).
- **API do ADM Server** (se optar por integração via API em vez de TXT).
- **Dados do ZUQ** (export CSV/API) para custo por carro e KM.
- **IP fixo** da empresa (se quiser a trava por IP).
- **Certificado SSL** (grátis via Let’s Encrypt no servidor).
- **Contas de e-mail/SMTP** (para notificações futuras).

---

## 14. Riscos Conhecidos

- **Aprovação parcial:** quem tem permissão “aprovar” mas não está na faixa é
  bloqueado; o escopo por **hierarquia nas telas** (ver só a sua empresa) ainda
  não filtra a listagem — Administrador vê tudo. 🟡
- **Notificações** ainda não disparam no celular (estrutura pronta). ⏳
- **CNPJs das empresas** estão provisórios no seed — ajustar no cadastro.
- **Hospedagem/segurança de servidor** (HTTPS, firewall, banco não exposto,
  automação de backup) depende da configuração de produção. ⏳ (servidor)
- **Túnel de teste** (Cloudflare) é temporário e exige o PC ligado.

---

## 15. Checklist Final de Implantação

- [ ] VPS criada
- [ ] Banco criado
- [ ] HTTPS ativo
- [ ] Backup testado
- [ ] Usuários revisados
- [ ] Logomarca instalada
- [ ] Produção liberada
- [ ] Senhas trocadas
- [ ] Firewall configurado
- [ ] Auditoria validada

---

## 16. Histórico do Projeto

- **Início:** 08/06/2026.
- **Conclusão do MVP:** 09/06/2026.
- **Entregas (etapas validadas):** Fundação (banco completo + login + layout) →
  Cadastros → Requisição → Alçada/Aprovação → Dashboard/Excel/Produção.
- **Decisões arquiteturais principais:**
  - Banco **nasce completo** (todos os módulos), para crescer sem refatorar.
  - Hierarquia **Empresa → Filial → Centro de Custo** como base de tudo.
  - **Prisma 6** (estável) em vez do 7 (recém-lançado).
  - **Permissões de menor privilégio** com guards no backend.
  - Auditoria e histórico **transversais** a todas as funcionalidades.
  - PWA + telas mobile-first para o uso em campo.

---

## 17. Segurança da Informação e Boas Práticas de Produção

### Segurança de Acesso
- Senhas com **criptografia bcrypt**. ✅
- **Troca obrigatória** das senhas no 1º acesso (seed cria com essa marca). ✅
- Proibir senha padrão em produção — **política documentada** (sem bloqueio
  técnico de “senha fraca”; recomenda-se trocar todas). 🟡
- **Sessão expira por inatividade** (logout automático após 30 min) + token JWT
  válido por 8h. ✅
- **Bloqueio temporário** após **5 tentativas** incorretas (15 min). ✅

### Controle de Permissões ✅
- Cada usuário vê apenas o que a função permite (o que não pode **nem aparece**).
- Comprador não acessa configurações; Pátio/Motorista não veem preço/relatórios;
  Administrador Master tem acesso total.

### Auditoria ✅
Registra **login, logout, criação, alteração, aprovação, reprovação, exclusão
lógica e exportação Excel**, salvando **usuário, data/hora, IP e ação**.
*(Verificado: ações LOGIN, LOGOUT, LOGIN_FALHA, LOGIN_BLOQUEIO, CRIAR, EDITAR,
INATIVAR, APROVAR, REJEITAR, COMPRAR, EXPORTAR no `audit_log`.)*

### Banco de Dados
- **Backup diário** (script pronto e testado). ✅ — **automação** (cron/agendador)
  é configuração do servidor. ⏳ (servidor)
- **Procedimento de restauração documentado.** ✅
- **Não exposto na internet** / acesso só pela aplicação. ⏳ (servidor)

### Arquivos e Uploads ✅
- **Valida extensões** (só JPG, PNG, WEBP, GIF, PDF) — **bloqueia executáveis**.
- **Limite de 10 MB** por arquivo.
- Anexos **fora da pasta pública** (acesso só por download autenticado).

### Variáveis de Ambiente ✅
- `DATABASE_URL`, `JWT_SECRET` e credenciais ficam **apenas no `.env`** (no
  `.gitignore`); nunca no repositório.

### Infraestrutura ⏳ (servidor)
- HTTPS obrigatório + redirecionamento HTTP→HTTPS; firewall ativo; atualizações
  de segurança; **PM2** com reinício automático. *(O código já lê o IP real atrás
  de proxy — `trust proxy` ativo.)*

### Backup ⏳ (servidor)
- Diário do banco (script pronto) · semanal dos anexos · teste periódico de
  restauração.

### Produção (antes da liberação definitiva)
- [ ] HTTPS ativo · [ ] senhas trocadas · [ ] usuários de teste removidos ·
  [ ] backup validado · [ ] banco protegido · [ ] firewall ativo ·
  [ ] auditoria funcionando · [ ] logomarca oficial instalada

### Risco Residual
- Trava por **IP** e **2FA** existem como campos/estrutura, mas **não estão
  ativos** — recomendados antes da liberação. O escopo por hierarquia ainda não
  filtra as listagens (Administrador vê todas as empresas).

---

## 18. Resumo Executivo Final

**O que existe hoje (operacional):** controle de acesso com perfis/permissões,
bloqueio de login e sessão por inatividade; cadastros de fornecedores e veículos;
requisição completa; aprovação por alçada com dupla aprovação e fila mobile;
dashboard gerencial completo; exportação Excel; histórico e auditoria.

**O que está preparado (sem tela final):** Diesel/Sem Parar/custo de frota,
importação Excel da frota, estoque (2A), banheiros químicos/QR (2B), locação (3),
orçamento (1.5) e integração ADM Server (TXT) — **tabelas já no banco**.

**O que falta desenvolver:** as telas e regras dos módulos acima (Fase 2 e 3).

**Percentual de conclusão (honesto):**
- **MVP (escopo travado):** **100% concluído.**
- **Visão completa do briefing** (Módulos 1 + 1.5 + 2 + 3 + ADMServ): **~35% concluído**
  — porém a **fundação** (banco completo, autenticação, arquitetura, auditoria) está
  **100% pronta**, o que reduz muito o esforço do restante.
- **Pendente:** ~65% do escopo total (módulos 1.5, 2, 3, integrações e inteligências do Módulo 1).

**Estimativa de esforço para as próximas fases (aproximada):**
- **Fase 2** (resto do Módulo 1 + 1.5 + Estoque 2A + Frota avançada): ~4 a 7 semanas.
- **Fase 3** (Banheiros 2B + Locação 3 + ADM Server TXT): ~5 a 8 semanas.
- *(Estimativas dependem de validações, dados do ZUQ e do layout do ADM Server.)*

---

> **MVP concluído e pronto para implantação. As próximas funcionalidades deverão
> ser desenvolvidas na Fase 2 sem necessidade de reconstrução da base atual.**