julian
17c08e6392
- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
153 lines
7.1 KiB
Markdown
153 lines
7.1 KiB
Markdown
# 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*
|