bf85072bff
- remove backend-old (Medusa), saveinmed-frontend (Next.js/Appwrite) and marketplace dirs - split Go usecases by domain and move notifications/payments to infrastructure - reorganize frontend pages into auth, dashboard and marketplace modules - add Makefile, docker-compose.yml and architecture docs
124 lines
5.6 KiB
Markdown
124 lines
5.6 KiB
Markdown
# 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
|