# Arquitetura do Sistema — Grupo 1AMS

Visão técnica da arquitetura. Para o manual de uso, ver [DOCUMENTACAO.md](DOCUMENTACAO.md).

## Camadas

```
[Navegador / Celular]  →  Frontend React (PWA)  →  /api  →  Backend NestJS  →  PostgreSQL
       (UI)                  Vite + Tailwind          (REST)     (Prisma ORM)      (dados)
```

- **Frontend** (`frontend/`): React 19 + TypeScript + Vite + Tailwind. Rotas por
  permissão; o que o usuário não pode nem aparece no menu. Estado de autenticação
  em `AuthContext` (token JWT + expiração por inatividade).
- **Backend** (`backend/src/`): NestJS por módulos. Guards globais de autenticação
  (JWT) e de permissão. Auditoria e histórico transversais.
- **Banco**: PostgreSQL via Prisma, com migrações versionadas em
  `backend/prisma/migrations/`.

## Módulos do backend

| Módulo | Responsabilidade |
|---|---|
| `auth` | Login JWT, bcrypt, bloqueio por tentativas, logout, troca de senha |
| `common` | Decorators e guards de permissão (`@RequirePermissions`, `@RequireAnyPermissions`) |
| `audit` | Registro de auditoria (quem/o quê/quando/IP, antes/depois) |
| `referencias` | Listas auxiliares (empresas, **meus-centros**, categorias, unidades, destinos, perfis, usuários) |
| `cadastros` | **CRUD administrável**: empresas, usuários, centros de custo (+responsáveis), categorias, unidades, destinos |
| `requisicoes` | Fluxo Solicitação → Cotação → Aprovação (alçada), itens, anexos |
| `dashboard` | Indicadores + exportação Excel |
| `notificacoes` | Ponto de extensão para push/WhatsApp (futuro) |

## Fluxo da requisição (papéis)

```
SOLICITANTE          COMPRAS                APROVADOR (alçada)        COMPRAS
   │ cria itens         │ cota                  │ aprova/rejeita          │ compra
   ▼                    ▼                       ▼                         ▼
RASCUNHO → SOLICITADA → EM_COTACAO → AGUARDANDO_APROVACAO → APROVADA → COMPRADA
                                              └→ REJEITADA
```
- Solicitante = usuário logado (Admin/Compras podem abrir em nome de outro).
- Centros de custo restritos ao que o usuário pode (validado no backend + auditado).
- Dados comerciais (fornecedor/valores) só visíveis com `ver_preco`.
- Alçada definida pelo **valor total cotado**.

## Cadastros administráveis (sem código)

Tudo que cresce é cadastro, não programação: **empresas, filiais, usuários
(perfil + empresas/centros permitidos), centros de custo (responsáveis
principal/corresponsáveis, ligados a filial), categorias, unidades de medida,
destinos, fornecedores (completo), veículos e a matriz de alçada**. Todos exigem
a permissão `configurar` (Administrador) e geram auditoria.

## Fornecedor — consulta de CNPJ e histórico

- **Consulta CNPJ:** `GET /fornecedores/consultar-cnpj?cnpj=` → BrasilAPI
  (servidor faz a chamada). Requer `node --use-system-ca` (TLS) + header
  `User-Agent` (evita 403 do Cloudflare). Nunca bloqueia o cadastro; preenche o
  formulário e alerta se a situação não for ATIVA.
- **Histórico (automático):** `GET /fornecedores/:id/historico` — calculado das
  requisições COMPRADAS (última compra, qtd, valor total, categorias/produtos
  mais comprados, tempo médio, ranking). Base para a cotação inteligente (Fase 2).

## Banco de dados (37 tabelas)

Núcleo: hierarquia `empresa → filial → centro_custo` (+ `centro_custo_responsavel`);
`usuario`/`perfil`/`permissao` (+ `usuario_acesso_hierarquia` para empresas/centros
permitidos); `alcada_regra`/`alcada_aprovador`; `requisicao`/`requisicao_item`/
`requisicao_anexo`/`requisicao_aprovacao`; cadastros `categoria`,
`unidade_medida`, `destino`, `fornecedor` (completo), `veiculo`, `despesa_veiculo`;
rastreabilidade `audit_log`/`status_historico`; preparadas para Fase 2/3
(`orcamento`, estoque/QR, locação, `integracao_outbox`).

Detalhe tabela a tabela em [RELATORIO-FINAL-MVP.md](RELATORIO-FINAL-MVP.md) e no
schema em `backend/prisma/schema.prisma` (fonte da verdade).