# Documentação Master: Visão Geral e Ecossistema LogiSplit

## 1. O Paradigma e a Proposta de Valor
Historicamente, as plataformas de e-commerce e vendas em link de pagamento isolam o fluxo de frete e o fluxo financeiro. O lojista recebe a venda, e depois transfere o valor do frete manualmente para o serviço de logística ou motorista particular. O **LogiSplit** nasce para destruir essa barreira. 

O LogiSplit é um **ecossistema de pagamentos tripártite**. Ele unifica:
- A geração da cobrança (Checkout).
- O cálculo e repasse do frete.
- A liquidação financeira automática, dividindo instantaneamente o fundo para a Empresa e para a Logística na camada bancária via tecnologia "Split de Pagamentos".

## 2. A Tríade de Usuários
O sistema opera estruturadamente com três atores em um balé financeiro sincronizado. 

### 2.1 Empresa / Vendedor (O Motor Comercial)
- O Lojista é a raiz de todas as transações da plataforma. 
- **Objetivo Prático:** Vender pelas redes sociais, sem precisar de site, gerando apenas um "Link" contendo suas régras de produto e de frete (Fixo ou baseado em distância - CEP).
- O lojista compartilha este link no WhatsApp/Instagram.

### 2.2 Parceiro Logístico (O Braço Físico)
- Profissionais independentes ou Transportadoras cadastradas que usam um painel dedicado (`/logistica`).
- **Objetivo Prático:** Analisar o "banco de pedidos disponíveis", acatar (aceitar) ordens de serviço pendentes criadas pelos Links de pagamento de Lojistas da sua região, retirar a mercadoria e entregar ao cliente.
- **Vantagem Master:** O frete é creditado em suas contas isoladamente via gateway de pagamento, protegendo-os do risco de calote por parte da empresa.

### 2.3 Administrador Plataforma (Deus do Ecossistema)
- Donos do LogiSplit. Ficam com uma margem, uma Taxa (`Take Rate`) deduzida da parcela da EMpresa sobre o Volume Total Transacionado (TPV). 
- Possui painel analítico (`/admin`) focado no uptime (funcionamento) das APIs, observando volumes astronômicos de requisições de pagamentos concorrentes, e provendo painéis de moderação (Suspensão de Entes por fraude).

## 3. Jornada End-to-End de uma Transação
A vida útil de uma venda obedece um ciclo estrito inviolável em nossa futura arquitetura:
1. Lojista acessa `vendedor`, preenche um link "Mentorias R$ 100, Frete Fixo R$ 20".
2. O sistema do Backend devolve um UUID "logisplit.com/pay/uuid".
3. O Pagante final preenche o cartão ou PIX. O Backend monta um Payload pro Gateway (Stripe/Pagar.me), e atríbui na raiz as rules de `Split`.
4. Transação `AUTHORIZED` -> Gateway retém comissão do Logisplit para o Master Account -> Despacha o Frete pra Sub-Account ID da Logística -> Devolve o Troco/Liquido para Sub-Account ID do Vendedor.
5. Transação passa para `PAID` via Webhook. O Backend imediatamente dispara o job assíncrono para a "Fila de Corridas Logísticas" como `"Aguardando Coleta"`.
6. A Transportadora (Hub), vendo as notificações pipocarem no painel, adota essa Ordem de Serviço, executa-a no mundo real e marca no painel como `ENTREGUE`.

## 4. Diferenciais Tecnológicos & Scalability B2B
O FrontEnd já foi concebido com uma SPA React Vite usando classes modulares utilitárias (Tailwind) e animações ultra leves (`lucide-react`, `tailwindcss-animate`). Isso aliviou o DOM.
Para o desenvolvedor e o Backend que assumirem esta documentação, deve-se prever **Alta Disponibilidade (HA)** e **Computação Assíncrona**. A API de criação de Link de pagamentos baterá em concorrência alta. 

## 5. Riscos do Modelo e Mitigação Algoritmica
- **Fraude e Lavagem de Dinheiro:** Lojistas forjarem links vazios apenas para lavar o dinheiro como frete para parceiros comparsas ficticios.
  - Mitigação: Painéis God Mode no Frontend projetados (`Admin Lojista` e `Admin Logistica`). A plataforma vai requerer integração de KYC e bloqueio manual no state `active -> suspended`.
- **Double-Spending Logístico:** Vários motoboys engatarem o botão "Aceitar Corrida" ao mesmo tempo num Link que acabou de ser pago.
  - Mitigação: Banco robusto Relacional `PostgreSQL` usando Transaction Locks (`SELECT FOR UPDATE NOWAIT`) acoplado no contrato da API, disparando erro amigável na tela da UI caso outro parceiro já tenha pego o item.