# DeepScan: Arquitetura Avançada de Servidor (Banco de Dados, Entidades e ORM)

O Banco de Dados transacional da LogiSplit deve ser relacional (`PostgreSQL`) usando uma camada de abstração Typescript com o **Prisma ORM**. Esta escolha garante escalabilidade, coerência de relacionamentos complexos cross-entities em operações de split assíncrono. Abaixo, o design base para o SCHEMA exigido.

## 1. Módulo Core Identity 

### Tabela `Role` / `Tenant`
Sustenta os subdomínios isolados. O Lojista nunca navega nas rotas de Transporte ou vice-versa protegendo o isolamento dos recursos de API Restful.

### Tabela `Users`
- `id`: UUID Primary Key.
- `email`: String Unique, index.
- `password_hash`: String (Argon2 / Bcrypt)
- `role`: Enum `[SELLER_ROLE, LOGISTIC_ROLE, ADMIN_ROLE]`
- `created_at`: DateTime Default Now.

### Módulo de Ledger de Saldo Pessoal / Contas Digitais
- **`FinancialProfiles`** (1-1 relations com o usuário).
- Mantém campos críticos: `gateway_sub_account_id` (Crucial pra Split Connect Stripe/Pagarme), `pix_key`, `available_balance_cents` (Int), `escrow_balance_cents` (Int - Saldo Retido).

## 2. A Alma: Estrutura Transacional e Payment Links

Todo ato no Software desdobra-se da `PaymentLink`.
### Tabela `PaymentLinks`
- `id` (PK UUID), `seller_id` (FK referenciando logado Lojista).
- `link_hash`: UUID legível curto pra URLs encurtadas na public URL ex `pay.logisplit.io/{hash}`.
- `title_reference`: String opcional (Ex: Tênis Nike Preto).
- `product_amount_cents`: Int. (Valor comercial puro).
- `freight_type`: Enum `[NULL_MODE, FIXED_MODE, CEP_DYNAMIC]`.
- `freight_fixed_cents`: Int (Opcional - null se não for FIXED type).
- `origin_cep`: String (null caso null mode).

### Tabela Crítica de Dinheiro Envolvido `Transactions`
Gerada e guardada como snapshot não destruitivo a cada vez que a página de Checkout no link exito uma intenção efetivada e aprovada pelo banco do Cliente Cartão.
- `id`: PK, UUID.
- `link_fk`: FK que deu a semente genética à venda.
- `internal_gateway_tx_id`: String (O código longo originado de IDs da Stripe/Outros).
- `total_payer_charged`: Int. (Valor 100% que bateu na fatura do cliente sacado).
- `status`: Enum (PENDING, PAID, DISPUTED, REFUNDED). Index massivo aqui para relatórios.
- **Divisões Congeladas Intocáveis na Venda:** Guardar o contrato base do ato `platform_fee_cents`, `seller_net_cents`, `logistics_freight_cents`. Isso garante históricos passados que nunca quebram se você alterar as Rules Defaults Administrativas de Taxa da API meses depois!

## 3. Estrutura Operacional de Entregas (Service Orders Ecosystem)

Vínculo vivo conectando os nós de Logística que o Frontend mapeia no seu Grid UI componentizado.

### Tabela `DeliveryTask` (Ordem da Fila)
Uma Trigger/Event ouvinte do Backend só gera essa Tabela quando o `Transaction` emite Success (PAID) para seu próprio Id Link cujos parametros `freight_type` tenham materialidade provada (Diferente de MODO NONE de Frete).
- `id`: PK
- `transaction_id`: FK.
- `origin_company_id`/ `seller_id`: FK de onde coletar.
- `origin_pickup_address` / `cep`: String Json data location.
- `delivery_customer_address`: Json location recebido no Checkout page por Customer.
- `task_bounty_amount_cents`: Int. Exatamente igual a `logistics_freight_cents`. Mas nomeado como Bounty (ofertado).
- `pickup_status`: Enum: `[AVAILABLE_ON_BOARD, CLAIMED, IN_TRANSIT, COMPLETED_PROOVED, FAILED]`.
- `logistics_hero_id`: FK null, com Constraint (UNIQUE com index partial status CLAIMED). Permite UPDATE atômico por meio do Motorista assumindo a tarefa correndo o risco via Race Conditions API Endpoint, setando-se à posse exclusiva de tasker.

## 4. Auditoria Base e Regras de Engine DB
- Os registros financeiros como "Withdrawals" (Saques de usuários de seus balances virtuais para Bancos reais) devem ser mapeados em Enitdade própria `WithdrawRequest` (Int valor, fk_user, status PENDING / EFFECTIVATED).
- A API God mode`/admin` apenas fará Queries agregadas massivas tipo `Prisma.transaction.aggregate({ _sum: { platform_fee_cents: true }})` e guardará em redis cache a vida global da startup.