# Arquitetura do Sistema de Ótica

## 1. Princípio central

O Laravel é a fonte oficial dos dados e das regras de negócio. O Node.js atua apenas como camada de tempo real, consumo de filas, webhooks, eventos e mensageria.

Nenhuma regra financeira crítica deve existir somente no Node.js.

## 2. Limites dos serviços

### Laravel

Responsável por:

- autenticação e autorização;
- isolamento por empresa;
- clientes;
- receitas ópticas;
- produtos e estoque;
- vendas e ordens;
- crediário;
- parcelas, juros, multas e pagamentos;
- geração de cobranças;
- auditoria e trilha de eventos;
- APIs internas para o Node.js.

### Node.js

Responsável por:

- WebSocket/tempo real;
- consumo de filas;
- entrega de notificações;
- processamento assíncrono de webhooks;
- ponte com canais de mensageria quando necessário.

Node.js recebe comandos/eventos do Laravel e devolve status. Não mantém um segundo saldo financeiro.

## 3. Multiempresa

As tabelas de domínio usam `company_id`. O tenant deve ser obtido da identidade autenticada, nunca confiado diretamente em `company_id` enviado pelo navegador.

Policies, scopes e serviços devem bloquear acesso entre empresas.

## 4. Histórico completo do cliente

O cadastro do cliente deve exibir uma timeline cronológica desde o primeiro registro, incluindo:

- criação e alterações cadastrais relevantes;
- todas as receitas ópticas, sem sobrescrever as antigas;
- compras e ordens;
- produtos/lentes/armações adquiridos;
- parcelas do crediário;
- pagamentos, atrasos, renegociações e quitações;
- cobranças enviadas;
- observações e atendimentos.

`customer_events` funciona como trilha de eventos e referência de timeline, mas os registros financeiros continuam tendo suas próprias tabelas como fonte oficial.

## 5. Crediário

O saldo deve ser derivado das parcelas e pagamentos alocados. O sistema não deve confiar em saldo calculado no frontend.

Pagamento parcial é permitido e fica registrado em `credit_payment_allocations`.

Integrações Sicoob e Mercado Pago devem usar referências idempotentes e webhooks validados.

## 6. WhatsApp

A integração será feita pela API oficial da Meta. O Laravel decide quando uma cobrança deve ser enviada. O Node pode processar a fila e entregar a mensagem, mas não decide sozinho se o cliente está inadimplente.

## 7. Credenciais de integrações por empresa

Credenciais externas de Meta/WhatsApp, Mercado Pago e Sicoob são propriedade de cada tenant e não pertencem à configuração global da aplicação.

Regras obrigatórias:

- `company_integrations` é sempre filtrada por `company_id` derivado do usuário autenticado;
- tokens, app secrets, client secrets e demais credenciais são armazenados em campo criptografado pelo Laravel;
- certificados e chaves privadas bancárias ficam em `storage/app/private`;
- nunca expor tokens salvos de volta no HTML, API, logs ou mensagens de erro;
- somente administrador da empresa pode configurar integrações;
- serviços de cobrança e mensageria devem obter credenciais via `CompanyIntegrationService`, nunca diretamente de `env()`;
- webhook recebido deve resolver de forma segura a empresa destinatária antes de qualquer baixa financeira ou alteração de estado.

O `.env` continua reservado a segredos da própria aplicação e infraestrutura, como `APP_KEY`, banco e autenticação interna entre serviços.

## 8. Segurança

- LGPD por padrão;
- soft delete para cadastros quando adequado;
- dados financeiros nunca apagados fisicamente em operação normal;
- auditoria de ações sensíveis;
- idempotência para cobranças e pagamentos;
- validação server-side;
- rate limit em APIs e webhooks;
- segredos de cada tenant criptografados e isolados;
- segredos globais da aplicação somente em configuração de infraestrutura segura.