# SAR — Força de Vendas
**JCS Sistemas · Produto SaaS B2B**

---

## O que é o SAR

O SAR é um sistema web de força de vendas desenvolvido pela JCS Sistemas para representantes comerciais e empresas do setor B2B.

Ele substitui e expande um aplicativo Android/Desktop legado, centralizando em uma única plataforma moderna tudo que o representante precisa para trabalhar: pedidos, clientes, financeiro, comissões e CRM.

---

## A ideia

Representantes comerciais perdem tempo com ferramentas fragmentadas — um app para pedido, outro para financeiro, outro para agenda. O SAR resolve isso com uma plataforma única que o representante acessa do celular ou do computador, com os dados sempre sincronizados com o ERP da empresa.

**Para o representante:** visão 360° do cliente, lançamento rápido de pedido, acompanhamento de comissão e FLEX, funil de vendas e agenda integrados.

**Para a empresa:** controle de limite de crédito, bloqueios automáticos, configurações por empresa/filial, relatórios e dashboards em tempo real.

---

## Público-alvo

| Perfil | Uso principal |
|---|---|
| Representante externo | Pedidos, CRM, agenda, comissão |
| Supervisor de vendas | Acompanhamento de equipe, liberação de descontos |
| Administrador | Configurações, pautas, relatórios |

---

## Módulos

| Módulo | O que faz |
|---|---|
| **Vendas** | Pedidos (Orçamento → Faturado), catálogo, pautas de preço |
| **Fiscal** | ICMS-ST, IPI, grupos tributários por UF |
| **Financeiro** | Títulos, recebimentos, limite de crédito |
| **Comissão / FLEX** | Cálculo por representante e produto, rateio com supervisor, saldo FLEX |
| **CRM** | Funil Kanban, agenda, check-in GPS, timeline 360° do cliente |
| **Administrativo** | Multi-empresa, configurações, gestão de representantes |

---

## Identidade Visual

### Paleta de cores

| Papel | Nome | Hex |
|---|---|---|
| Primária | JCS Blue | `#004a99` |
| Primária hover | JCS Blue Hover | `#003a7a` |
| Fundo ativo (menu) | JCS Blue Light | `#e6eff8` |
| Background app | Body | `#f4f7fa` |
| Texto principal | Text Main | `#2d3748` |
| Texto secundário | Text Muted | `#718096` |
| Sucesso / Faturado | Green | `#38a169` |
| Alerta / Em aberto | Orange | `#ed8936` |
| Erro / Bloqueado | Red | `#e53e3e` |
| WhatsApp | WA Green | `#25d366` |

### Tipografia

**Plus Jakarta Sans** · Google Fonts  
Pesos utilizados: 400 · 500 · 600 · 700 · 800

### Ícones e gráficos

- Ícones: **Font Awesome 6.4.0**
- Gráficos: **Chart.js**

### Bordas e sombras

| Token | Valor |
|---|---|
| Radius grande (cards, modais) | `20px` |
| Radius médio (inputs, botões) | `12px` |
| Sombra padrão | `0 4px 25px rgba(0,0,0,0.05)` |

### Tom visual

Clean e minimalista — muito branco, azul `#004a99` como único destaque cromático, bordas suaves, sem zebra agressiva em tabelas. Inspiração Apple: espaço em branco generoso, hierarquia clara, sem ruído visual.

---

## Layout padrão

```
┌─────────────────────────────────────────────────────┐
│  TOPBAR (80px)                                      │
├──────────────┬──────────────────────────────────────┤
│              │                                      │
│  SIDEBAR     │  CONTEÚDO (scrollável)               │
│  (260px)     │                                      │
│  fixa        │                                      │
│              │                                      │
└──────────────┴──────────────────────────────────────┘
```

**Login:** tela cheia com card centralizado, gradiente sutil `#f0f4f8 → #d9e2ec`.

---

## Stack técnica

| Camada | Tecnologia |
- **Runtime:** Node 24 LTS · pnpm 11.1 · TypeScript 5.9 → [§01](docs/01-runtime-tooling.md)
- **Monorepo:** Nx 22.7 → [§02](docs/02-monorepo-nx.md)
- **Backend:** NestJS 11.1 (Express 5) · Prisma 7 · PostgreSQL 18 · `nestjs-cls` · `@nestjs/terminus` · `@nestjs/throttler` + `@nest-lab/throttler-storage-redis` → [§03](docs/03-backend.md), [§20](docs/20-praticas-nest-universais.md)
- **Frontend:** React 19.2 + Compiler · Vite 8 (Rolldown) · Ant Design 6.4 · TanStack Query 5.100 · TanStack Router · Zustand 5.0.13+ → [§04](docs/04-frontend.md)
- **API:** REST + OpenAPI 3.1 + RFC 9457 Problem Details · Zod 4 (pnpm catalog) + nestjs-zod + react-hook-form (`zodResolver`) → [§05](docs/05-api-design.md), [§06](docs/06-validacao.md)
- **Auth:** Guards NestJS + `jose` + **master-login** (IdP OAuth2/OIDC próprio em VM Proxmox; HS256 hoje → RS256 roadmap) · argon2id centralizado no IdP → [§07](docs/07-autenticacao.md), [ADR 0005](docs/adr/0005-auth-master-login.md)
- **Segredos:** **HashiCorp Vault** (KV v2) self-host · Vault Agent injeta env vars no container → [§08](docs/08-secrets-config.md)
- **Observabilidade:** Pino + nestjs-pino 10.3 · OpenTelemetry (Traces+Metrics GA; Logs Beta) · Grafana Cloud LGTM · Sentry → [§09](docs/09-observabilidade.md)
- **Flags:** OpenFeature SDK + GrowthBook self-host → [§10](docs/10-feature-flags.md)
- **Filas:** BullMQ 5.77 + `@nestjs/bullmq` 11 · Bull Board · **Valkey em VM/LXC** Proxmox → [§11](docs/11-filas-jobs.md)
- **Cache:** `@nestjs/cache-manager` v3 + cache-manager 6 + `@keyv/redis` + `cacheable` (L1) — TTL em **ms** → [§12](docs/12-cache.md)
- **Real-time:** Socket.IO 4 + `@socket.io/redis-adapter` · SSE via `@Sse()` nativo NestJS → [§13](docs/13-realtime.md)
- **Uploads:** **MinIO** (S3-compat) presigned **POST policy** + AWS SDK v3 · Uppy + `@uppy/aws-s3` · **ClamAV** em worker BullMQ · sharp 0.34 → [§14](docs/14-uploads.md)
- **Email:** **Resend** (SaaS — não self-host) + React Email via BullMQ → [§15](docs/15-email-notificacoes.md)
- **Testes:** Vitest 4.1 · Testcontainers 12 · Supertest 7.2.2 (encapsulado) · Playwright 1.60 → [§16](docs/16-testes.md)
- **Qualidade:** ESLint 10.4 flat · typescript-eslint 8.59 · Prettier 3.8.3 · eslint-plugin-import-**x** 4.16.2 · Husky 9 + lint-staged 17 · **gitleaks** → [§17](docs/17-qualidade-codigo.md)
- **CI/Deploy:** GitHub Actions + Nx Cloud · Trivy gate · pin actions por SHA · Docker multi-stage `node:24-alpine` · **Ansible/SSH para VMs Proxmox** com docker-compose rolling (backend) · **Cloudflare + Nginx** servindo SPA estática (frontend, **não containerizar**) → [§18](docs/18-cicd-containers.md)


---

## Variáveis CSS — referência rápida

```css
:root {
  --jcs-blue:        #004a99;
  --jcs-blue-hover:  #003a7a;
  --jcs-blue-light:  #e6eff8;
  --bg-body:         #f4f7fa;
  --text-main:       #2d3748;
  --text-muted:      #718096;
  --green:           #38a169;
  --whatsapp-green:  #25d366;
  --red:             #e53e3e;
  --orange:          #ed8936;
  --radius-lg:       20px;
  --radius-md:       12px;
  --shadow:          0 4px 25px rgba(0, 0, 0, 0.05);
}
```

---

*Powered JCS. sistemas SAR - Força de Vendas · v1.0*