# Arquitetura SaveInMed

## Visão geral

```
┌─────────────────────────────────────────────────────┐
│                   Clientes HTTP                      │
│  Browser (frontend)        Browser (admin panel)     │
└──────────────┬──────────────────────┬───────────────┘
               │                      │
               ▼                      ▼
     ┌─────────────────┐   ┌─────────────────────┐
     │  backend (Go)   │   │  backoffice (NestJS) │
     │  :8214          │   │  :3001              │
     └────────┬────────┘   └──────────┬──────────┘
              │                        │
              └───────────┬────────────┘
                          ▼
              ┌─────────────────────┐
              │  PostgreSQL         │
              └─────────────────────┘
```

## Decisões de design

### Backend Go — Clean Architecture

A separação de camadas segue **Uncle Bob's Clean Architecture**:

```
cmd/api/
  └── main.go            → DI e wiring de dependências

internal/
  ├── domain/            → Entidades, value objects, interfaces de repositório
  ├── usecase/           → Regras de negócio (independentes de framework)
  │     ├── usecase.go            → Service struct + interfaces centrais
  │     ├── auth_usecase.go       → Autenticação, JWT, reset de senha
  │     ├── company_usecase.go    → Empresas e KYC
  │     ├── product_usecase.go    → Catálogo e inventário
  │     ├── order_usecase.go      → Ciclo de vida de pedidos (state machine)
  │     ├── shipping_usecase.go   → Cálculo de frete e configurações
  │     ├── cart_usecase.go       → Carrinho com descontos B2B
  │     ├── payment_usecase.go    → Pagamentos e webhooks
  │     ├── review_usecase.go     → Avaliações de vendedores
  │     ├── user_usecase.go       → CRUD de usuários
  │     ├── address_usecase.go    → Endereços
  │     └── dashboard_usecase.go  → KPIs de vendedor e admin
  ├── http/
  │     ├── handler/     → Um arquivo por recurso REST
  │     └── middleware/  → Auth JWT, CORS, rate-limit, logging
  ├── repository/postgres/ → Implementações de Repository + migrações
  └── infrastructure/
        ├── mapbox/      → Cliente Mapbox (cálculo de distância de rota)
        ├── payments/    → Mercado Pago, Asaas, Stripe
        └── notifications/ → Firebase Cloud Messaging (FCM)
```

**Regra de dependência:** camadas externas (HTTP, banco, infra) dependem das camadas internas (use case, domain). Nunca o contrário.

### Frontend React — Organização por perfil

Páginas agrupadas em `src/pages/<contexto>/<perfil>/`, com alias `@/` para importações absolutas:

```
pages/
  auth/           → Login, registro (público)
  marketplace/    → Search, Cart, Checkout, Orders (compradores)
  dashboard/
    admin/        → Painel admin (consome backoffice API)
    seller/       → Seller Dashboard, Inventory, Products
    employee/     → Colaborador
    delivery/     → Entregador
    Company.tsx   → Perfil da empresa (compartilhado)
    MyProfile.tsx → Perfil do usuário (compartilhado)
```

### Backoffice NestJS — API para operações internas

O `backoffice/` é uma **API separada** (não é front-end), organizada em módulos NestJS:

| Módulo | Responsabilidade |
|--------|-----------------|
| `auth` | Autenticação de operadores internos |
| `users` | Gestão de usuários da plataforma |
| `kyc` | Aprovação de empresas (KYC) |
| `inventory` | Gestão de estoque e compras (B2B interno) |
| `dashboard` | Métricas agregadas da plataforma |
| `reports` | Exportação de relatórios |
| `fraud` | Detecção de padrões suspeitos |
| `disputes` | Gestão de disputas entre partes |
| `audit` | Log de ações administrativas |
| `webhooks` | Recebimento de eventos externos |
| `performance` | Monitoramento de performance de sellers |
| `settings` | Configurações da plataforma |

> **Importante:** `backoffice` e as páginas admin do `frontend` formam um par API+UI. Não há duplicidade — um é o servidor, o outro é o cliente.

## Integrações externas

| Serviço | Uso | Pacote |
|---------|-----|--------|
| Mapbox API | Distância de rota para cálculo de frete | `infrastructure/mapbox/` |
| Mercado Pago | Pagamentos B2C e B2B com split | `infrastructure/payments/` |
| Asaas | Gateway alternativo / boleto | `infrastructure/payments/` |
| Firebase FCM | Push notifications (mobile/PWA) | `infrastructure/notifications/` |

## State machine de pedidos

```
Pending → Paid → Invoiced → Shipped → Delivered → Completed
   ↓         ↓       ↓
Cancelled  Cancelled Cancelled
```

Transições são validadas em `order_usecase.go#UpdateOrderStatus`. Cancelamentos restituem estoque automaticamente.

## Segurança

- JWT HS256 com pepper no hash de senha (bcrypt)
- Rate limiting por IP no middleware
- CORS configurável por ambiente
- Company verification (KYC) antes de pedidos de produção
- Uploads validados por tipo MIME e tamanho