Trading Platform - Sistema de Comércio Exterior

Sistema completo de gestão de operações de comércio internacional (exportação) com CRM integrado, KYC/Compliance, e dashboards analíticos.

🏗️ Arquitetura

Monólito Modular em .NET 8 com PostgreSQL, estruturado para velocidade de desenvolvimento e fácil evolução.

Módulos

• Identity/RBAC - Autenticação, autorização e auditoria
• Master Data - Cadastros base (Produtos, Buyers, Suppliers)
• CRM - Gestão de Deals, Stages e Activities
• Analytics - Dashboards e métricas em tempo real

🚀 Quick Start

Pré-requisitos

• .NET 8 SDK
• PostgreSQL 14+
• Docker (opcional)

Setup Local

1. Clone o repositório

git clone https://github.com/avilainc/exportacao.git
cd exportacao

2. Configure o banco de dados

Crie um banco PostgreSQL:

CREATE DATABASE tradingplatform;

Ou use Docker:

docker run --name postgres-trading -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=tradingplatform -p 5432:5432 -d postgres:14

3. Atualize a connection string

Edite src/TradingPlatform.Api/appsettings.json:

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=tradingplatform;Username=postgres;Password=SUA_SENHA"
  }
}

4. Rode as migrations e seed

dotnet restore
dotnet ef database update --project src/TradingPlatform.Infrastructure --startup-project src/TradingPlatform.Api

5. Execute a API

cd src/TradingPlatform.Api
dotnet run

API rodando em: https://localhost:7000 (ou confira o terminal)

6. Acesse o Swagger

https://localhost:7000/swagger

📊 Funcionalidades

PR1 - MVP Base ✅

• CRUD completo de Produtos
• CRUD completo de Buyers (compradores)
• CRUD completo de Suppliers (fornecedores)
• Deals com pipeline (Lead → Qualified → Quote → Negotiation → Closed/Lost)
• Activities por Deal (Email, Call, Meeting, Task, Note)
• Dashboard Comercial (pipeline + follow-ups vencidos)
• Auditoria automática

PR2 - KYC + Event Log + Worker ✅

• KYC Checklist completo por Buyer
• Items de checklist (Document, Financial, Reference, Legal)
• Aprovação/Rejeição de KYC com score A/B/C
• Bloqueio automático de Deals sem KYC aprovado
• Event Log (append-only) para rastreabilidade
• Background Worker para processamento assíncrono
• Dashboard KYC (pendências por idade + deals bloqueados)
• Endpoint de override de bloqueio

🛣️ Roadmap

PR1 - Core + CRM + Master Data ✅

PR2 - KYC + Bloqueios + Event Log ✅

PR3 - Quotes/Proforma + Contracts

• Quote versionada
• Geração de PDF
• Contract management
• Snapshots diários (snap_pipeline_daily, snap_kpi_daily)
• Dashboard conversão, ciclo, motivos de perda

PR4 - Ops + Docs + Finance

• Shipment tracking
• Custos logísticos
• Document checklist + uploads
• Recebíveis/Pagamentos/Comissões
• Dashboards Ops/Finance/Executivo

🗂️ Estrutura do Projeto

src/
├── TradingPlatform.Api/                # API REST (Controllers, Swagger)
├── TradingPlatform.Core/               # Entidades de domínio
│   ├── Common/                         # BaseEntity, AuditLog
│   ├── MasterData/                     # Product, Buyer, Supplier
│   └── CRM/                            # Deal, Activity
├── TradingPlatform.Infrastructure/     # DbContext, Migrations, Services
│   ├── Data/                           # TradingDbContext, SeedData
│   └── Services/                       # AuditService
├── TradingPlatform.Modules.Identity/   # User, Role, Permissions
├── TradingPlatform.Modules.MasterData/ # DTOs e lógica Master Data
├── TradingPlatform.Modules.CRM/        # DTOs e lógica CRM
└── TradingPlatform.Modules.Analytics/  # DTOs Dashboard

🔐 Roles e Permissões

Roles Padrão (Seed)

• Admin - Acesso total ao sistema
• Sales - CRM, produtos, buyers, dashboards
• Compliance - KYC, audit log, buyers

Permissões Disponíveis

// Master Data
products.view, products.manage
buyers.view, buyers.manage
suppliers.view, suppliers.manage

// CRM
deals.view, deals.manage, deals.view_all

// KYC
kyc.view, kyc.manage, kyc.override_block

// Admin
users.manage, audit.view, dashboards.view

🧪 Dados de Exemplo (Seed)

Após rodar o seed, você terá:

• 5 produtos (Soja, Café, Açúcar, Milho, Algodão)
• 3 buyers (USA, China, Netherlands)
• 2 suppliers brasileiros
• 3 roles (Admin, Sales, Compliance)

📡 Endpoints Principais

Products

GET    /api/products
GET    /api/products/{id}
POST   /api/products
PUT    /api/products/{id}
DELETE /api/products/{id}

Buyers

GET    /api/buyers?kycStatus=Approved
GET    /api/buyers/{id}
POST   /api/buyers
PUT    /api/buyers/{id}

Deals

GET    /api/deals?stage=Quote
GET    /api/deals/{id}
POST   /api/deals
PUT    /api/deals/{id}
GET    /api/deals/{dealId}/activities
POST   /api/deals/{dealId}/activities

Dashboards

GET    /api/dashboards/commercial
GET    /api/dashboards/pipeline-by-stage
GET    /api/dashboards/overdue-activities?days=7
GET    /api/dashboards/kyc
GET    /api/dashboards/kyc/pending-by-age
GET    /api/dashboards/kyc/blocked-deals

KYC

POST   /api/kyc/checklists
GET    /api/kyc/checklists/buyer/{buyerId}
POST   /api/kyc/checklists/{checklistId}/items
PUT    /api/kyc/items/{itemId}/complete
POST   /api/kyc/checklists/{checklistId}/approve
POST   /api/kyc/checklists/{checklistId}/reject
GET    /api/kyc/checklists/pending
GET    /api/kyc/checklists/by-age

Deals (Adicionais)

POST   /api/deals/{id}/unblock?reason=...

🛠️ Stack Tecnológico

• .NET 8 - Framework principal
• ASP.NET Core Web API - REST API
• Entity Framework Core 10 - ORM
• PostgreSQL - Database
• Npgsql - PostgreSQL provider
• Swashbuckle - Swagger/OpenAPI

📝 Convenções

Naming

• Entidades: PascalCase singular (Deal, Product)
• DTOs: Sufixo Dto (DealDto, CreateDealDto)
• Controllers: Sufixo Controller (DealsController)

API Response

• 200 OK - Success
• 201 Created - Resource created (com location header)
• 204 No Content - Success sem retorno
• 400 Bad Request - Validação falhou
• 404 Not Found - Resource não encontrado

🤝 Contribuindo

1. Fork o projeto
2. Crie uma feature branch (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

📄 Licença

Este projeto é proprietário de Avila Inc.

📧 Contato

Avila Inc - exportacao@avila.inc

Project Link: https://github.com/avilainc/exportacao