Módulo 4 - Faturamento & Inteligência Financeira (billing)

Módulo 4: Faturamento & Inteligência Financeira (`billing`)

O módulo Billing gerencia o faturamento fiscal dos serviços executados, calcula a rentabilidade líquida por limpeza, controla a quitação das faturas dos clientes e provê exportação e integração direta via REST API com o QuickBooks Online UK.

O envio de fatura por e-mail mantém separação entre diagnóstico e experiência: falhas do Resend ou do Worker são sanitizadas no log interno, enquanto PWA, Android, iOS e desktop recebem somente uma mensagem estável para tentar novamente. O objeto do provedor, stack e possíveis credenciais nunca integram a resposta 500. O composer usa AdaptiveBottomSheet, CFInput, Button e IconBadge; valida e normaliza destinatário, assunto e corpo antes do envio, mantém lock síncrono, bloqueia fechamento durante a entrega e preserva o rascunho em falha. O link de pagamento usa sempre a origem atual ou o fallback oficial app.primecrowncleaning.co.uk. O envio do mesmo documento por WhatsApp captura o PDF montado, usa mutação limitada a 15 segundos e associa um AbortController à fatura visível. Fechar, desmontar ou trocar a fatura cancela a rede; uma conclusão sem ownership não produz háptico ou toast, e falha preserva a prévia para retry.

Persistência atômica de faturas e entidades fiscais segue o mesmo limite: erros inesperados são classificados no log administrativo e retornam o contrato compartilhado de retry, enquanto validações fiscais e permissões continuam específicas.

Void, dispatch e remoção de uma visita usam um owner síncrono por fatura e snapshots atuais do store, sem rede, log ou atualização cruzada dentro de updaters React/Zustand. /api/billing/invoice-operation valida papel, estado e vínculos esperados e grava service_requests, invoices e itens normalizados em um único D1Database.batch, com guards repetidos contra concorrência. Void e remoção publicam estado otimista, mas só anunciam conclusão depois da transação; falha restaura os dois domínios, e teardown descarta resposta/toast tardio em desktop, PWA, Android e iOS.

Confirmação de pagamento e recebimento direto observam sempre o snapshot atual de serviços, inclusive quando a agenda mudou sem alterar a lista de faturas. As visitas retornadas pela regra financeira são mescladas por um índice de ID compartilhado, preservando ordem, referências não alteradas e a precedência histórica da primeira atualização duplicada. Isso evita tanto closures antigas quanto buscas quadráticas durante a reconciliação local nas quatro experiências.

💰 1. Cálculo de Rentabilidade (`ProfitLogic`)

Para cada serviço executado, o ProfitLogic apura a margem financeira real:

$$\text{Lucro Líquido} = \text{Valor Pago pelo Cliente} - \text{Custo da Funcionária} - \text{Imposto (VAT)} - \text{Taxa de Material/Logística}$$

Margem de Lucro (%): $(\text{Lucro Líquido} / \text{Valor Total}) \times 100$.
Alerta de Margem Baixa: Se a margem de lucro de um cliente ficar abaixo de 35%, o sistema gera um alerta visual no painel financeiro para revisão de tarifa.

📑 2. Ciclo de Vida da Fatura (`InvoiceStateLogic`)

stateDiagram-v2
    [*] --> DRAFT: Limpeza concluída
    DRAFT --> ISSUED: Fatura emitida pelo sistema/gerente
    ISSUED --> SENT: Fatura enviada via E-mail / WhatsApp
    SENT --> PAID: Pagamento confirmado (BACS / Cartão / Wallet)
    SENT --> OVERDUE: Vencimento sem pagamento
    OVERDUE --> PAID: Quitação com juros/multa
    ISSUED --> CANCELLED: Fatura cancelada / Estornada

🇬🇧 3. Integração Contábil QuickBooks UK (CSV & REST API)

O sistema oferece integração oficial com o QuickBooks Online UK para conformidade com a HMRC:

Exportação CSV Oficial HMRC:
- Geração de arquivos padronizados com cabeçalhos *InvoiceNo, *Customer, *InvoiceDate, *DueDate, *ItemTaxCode (20.0% S ou Exempt), *ItemTaxAmount e Currency (GBP).
- Download ou compartilhamento direto via QuickBooksExportService.exportToQuickBooks().
Integração Direta via REST API & OAuth 2.0:
- Endpoint backend functions/api/billing/quickbooks.ts:
  - GET ?action=auth-url: Gera URL de autorização OAuth Intuit.
  - GET ?action=status: Retorna o estado da conexão e data da última sincronização.
  - POST { action: 'sync', invoiceIds: string[] }: Dispara o payload JSON padronizado para a API do QuickBooks Online (/v3/company/{realmId}/invoice).
  - POST { action: 'save-config' } e POST { action: 'disconnect' }: Gestão segura das credenciais e Company ID (realmId).
- Serviço Frontend src/features/billing/services/QuickBooksApiService.ts.
- Status e URL OAuth usam leitura limitada; sincronização e desconexão encerram em 15 segundos e aceitam cancelamento da superfície chamadora. O modal mantém um único trabalho por vez, congela filtros/seleção durante exportação ou sync e aborta a API ao fechar/desmontar. Falha ou cancelamento mantém o modal aberto e nunca produz háptico, fechamento ou mensagem de sucesso; somente success: true confirmado pelo servidor conclui a operação.
Conciliação de Extrato Bancário:
- O lote de liquidação também usa timeout de 15 segundos e AbortSignal. Fechar ou desmontar o bottom sheet cancela o transporte; a resposta aceita continua sendo espelhada no store e no TanStack Query antes do sucesso. Timeout/falha preserva relatório e seleção para retry, enquanto linhas já pagas permanecem uma resposta informativa, sem reenvio de recibo.

🏛️ 4. Ecossistema de Pagamento Open Banking UK (`Pay by Bank`)

O Prime Crown dispõe de um ecossistema de pagamento integrado via Faster Payments / Open Banking UK:

Página Pública de Pagamento (/pay/:invoiceId):
- Acesso público e seguro para clientes sem exigência de login via src/pages/PublicInvoicePay.tsx.
- Botão 1-Click Pay by Bank com suporte aos principais bancos britânicos (Monzo, Revolut, Barclays, HSBC, Lloyds, NatWest, Santander, Starling).
- Dados manuais BACS (Sort Code + Account Number + Referência) com botões de cópia rápida.
- Endpoint backend seguro: functions/api/public/invoice.ts.
- A leitura possui limite de 12 segundos, é cancelada ao sair da tela e diferencia link inexistente de falha de conexão; esta última preserva um botão Try again.
Botão e QR Code no PDF Oficial:
- O componente InvoiceDocument.tsx estampa o botão interativo “Pay by Bank” e o QR Code vetorial gerado por OpenBankingService.ts.
Emissão Automática de Recibos (Payment Receipts):
- Endpoint functions/api/billing/payment-receipt.ts: Despacho de recibo formal com valor liquidado, data e agradecimento no WhatsApp e por e-mail via Resend.
Cobrança & Lembretes Inteligentes (Smart Dunning):
- Serviço InvoiceDunningService.ts e endpoint functions/api/billing/dunning-reminder.ts para disparo de lembretes preventivos (24h antes do vencimento) e avisos de pendência com link de pagamento direto anexado.

📑 5. Extrato Financeiro Consolidado do Cliente (`/statement/:clientId`)

Para clientes recorrentes ou corporativos que solicitam histórico financeiro consolidado:

Página Pública de Extrato (src/pages/PublicClientStatement.tsx):
- Resumo de faturamento: Total Faturado, Total Pago e Total em Aberto.
- Tabela completa de faturas emitidas com datas e links individuais de pagamento.
- Botão “Pay All Outstanding via Open Banking”: Permite a liquidação de todas as pendências em lote com 1 clique no app do banco.
Endpoint Backend (functions/api/public/statement.ts): Retorna os dados agregados e status em tempo real.
A leitura usa o mesmo transporte público limitado e abortável da fatura; erro de rede nunca é apresentado como extrato inexistente e pode ser tentado novamente.

🛠️ 6. Arquivos Principais do Módulo

Lógica de Lucro: src/features/billing/services/ProfitLogic.ts
Máquina de Estados da Fatura: src/features/billing/services/InvoiceStateLogic.ts
Serviço Open Banking UK: src/features/billing/services/OpenBankingService.ts
Página Pública de Pagamento: src/pages/PublicInvoicePay.tsx
Página Pública de Extrato Consolidado: src/pages/PublicClientStatement.tsx
Serviço de Cobrança / Dunning: src/features/billing/services/InvoiceDunningService.ts
Serviço de Exportação QuickBooks: src/features/billing/services/QuickBooksExportService.ts
Serviço da API QuickBooks: src/features/billing/services/QuickBooksApiService.ts
Endpoints Backend: functions/api/billing/, functions/api/public/invoice.ts, functions/api/public/statement.ts
Painel Financeiro & Hub Contábil: src/pages/BillingHub.tsx / src/pages/AccountingHub.tsx

Módulo 4 - Faturamento & Inteligência Financeira (billing)

Módulo 4: Faturamento & Inteligência Financeira (billing)

💰 1. Cálculo de Rentabilidade (ProfitLogic)

📑 2. Ciclo de Vida da Fatura (InvoiceStateLogic)