# LLM_CONTEXT.md - Nexos (Exent)

> Este documento e o ponto de entrada para qualquer LLM que for trabalhar neste projeto.
> Leia este arquivo PRIMEIRO. Ele contem o contexto necessario para entender o sistema
> sem precisar analisar todo o codigo-fonte.
>
> Ultima atualizacao: 2026-06-18

---

## 1. O que e o Nexos

Nexos e um sistema de gestao financeira e operacional multi-tenant para a empresa Exent (agencia de marketing digital). Ele gerencia:

- **Colaboradores** (RH): cadastro, contratos, contas bancarias, documentos
- **Clientes e Projetos**: clientes institucionais, clientes faturaveis, projetos com contratos
- **Cobrancas**: emissao de boletos/PIX, notas fiscais de servico (NFS-e), controle de pagamentos
- **Pagamentos a colaboradores**: folha de pagamento mensal (recorrencia) e premios semestrais
- **Pagamentos operacionais**: boletos, TED, PIX, PIX QR Code para fornecedores
- **Conta corrente**: extratos consolidados de multiplos bancos
- **Wiki**: base de conhecimento interna com artigos e trilhas de aprendizado

---

## 2. Stack Tecnica

| Camada | Tecnologia |
|--------|-----------|
| Backend | Laravel 12, PHP 8.2+ |
| Multi-tenancy | stancl/tenancy v3 — banco de dados separado por tenant |
| Banco de dados | MySQL (producao) |
| Autenticacao | Google OAuth via laravel/socialite, dominio restrito (@exent.com.br, @vendrix.com.br) |
| API Auth | Laravel Sanctum (tokens), middlewares customizados para webhooks |
| Frontend | Blade + Inspinia Theme + Tailwind CSS 4 |
| Build | Vite 7 + laravel-vite-plugin |
| DataTables | yajra/laravel-datatables (server-side) |
| Fila | Database driver, worker com tries=1 |
| CI/CD | GitHub Actions → deploy via SSH (porta 1097) |
| Servidor | Ubuntu, www-data, nginx |

---

## 3. Arquitetura Multi-Tenant

```
BANCO CENTRAL (landlord)
  ├── users (autenticacao global)
  ├── tenants (empresas)
  ├── tenant_user (N:N)
  ├── integration_providers + integration_tokens + company_token (credenciais)
  ├── email_configs (SMTP por tenant/modulo)
  ├── jobs + failed_jobs (fila unica)
  └── sessions, cache, personal_access_tokens

BANCO POR TENANT (isolado)
  ├── core_* (9 tabelas: collaborators, clients, projects, contracts, etc)
  ├── finance_* (27 tabelas: charges, transactions, invoices, etc)
  └── wiki_* (8 tabelas: articles, categories, trails, etc)
```

**Como funciona:**
- Usuario faz login via Google → seleciona tenant → sessao guarda tenant_id
- Middleware `InitializeTenancyBySession` troca o banco de dados automaticamente
- APIs externas usam header `X-Tenant-ID` + middleware `InitializeTenancyByHeader`
- Webhooks Asaas identificam o tenant pelo token no header (busca em todos os tenants)
- Cron jobs usam macro `tenantJob` que itera `Tenant::cursor()` e dispatcha no contexto de cada banco

---

## 4. Modulos

### 4.1 Sistema (Landlord)
- Login Google OAuth, selecao de tenant, painel Master (CRUD de empresas e credenciais)
- Arquivos: `SystemController`, `MasterController`, `TenantSelectionController`, `GoogleController`

### 4.2 Core
- CRUD de colaboradores (com documentos no Google Cloud Storage)
- CRUD de clientes institucionais (compartilhado Core/Finance via prefixo {module}/)
- CRUD de projetos (compartilhado Core/Finance)
- Alteracoes pendentes do Exent Space (aprovacao/rejeicao com diff)
- Arquivos-chave: `CollaboratorController`, `InstitutionalClientController`, `ProjectController`

### 4.3 Finance
- **Cobrancas**: criacao manual, recorrencia automatica, campanhas Monday, segunda via
- **Resumo de cobranca**: agrupamento de projetos com send_mail=false
- **Transacoes**: boletos (OCR+AI), transferencias TED/PIX, PIX QR Code
- **Pagamentos colaboradores**: snapshots mensais/semestrais, prioridade 1-3
- **Conta corrente**: extratos Asaas/Iugu (API) + BTG/Itau/C6 (manual)
- **NFs colaboradores**: upload + validacao por IA (OpenAI)
- **Sincronizacao**: 5 steps (clientes→NFS-e→recorrencias→emissao→verificacao)
- **50+ cron jobs** e **41 queue jobs**

### 4.4 Wiki
- Artigos com dois tipos: article (por categoria) e trail (por trilha hierarquica)
- Trilha: Trail → Module → Submodule → Topic → Article
- Editor rich-text, upload de imagens, draft/published
- API JSON interna (CRUD via AJAX)

---

## 5. Convencoes do Codigo

### 5.1 Estrutura de Arquivos

```
Controllers/  → Logica de request/response, validacao, orquestracao
Services/     → Logica de negocio, chamadas a APIs externas
Jobs/         → Processamento assincrono (todos ShouldQueue)
Models/       → Eloquent com relacionamentos, casts, scopes
Helpers/      → Funcoes puras de formatacao (FormatHelper, BoletoHelper, etc)
```

### 5.2 Padroes Aplicados

- **Nao ha Repositories** — controllers chamam services que consultam models diretamente
- **Nao ha Form Requests** — validacao feita com `Validator::make()` dentro dos controllers
- **Nao ha Events/Listeners** — jobs sao dispatchados diretamente
- **Nao ha API Resources** — JSON formatado manualmente nos controllers
- **Services sao instanciados via `app()` ou `new`** — sem interface binding no container (exceto PaymentServiceFactory)
- **Controllers chamam outros controllers** como services (ex: `AsaasApiController::asaasCreatePayment()` — metodos estaticos ou instanciados)
- **Todos os jobs usam a queue default** — sem filas separadas
- **Transacoes DB com `DB::beginTransaction()`** — nao usa closures

### 5.3 Nomenclatura

- Models: `FinanceCharge`, `CoreCollaborator` (prefixo do modulo)
- Tabelas: `finance_charges`, `core_collaborators` (snake_case com prefixo)
- Controllers: `ChargesController`, `CollaboratorController` (sem prefixo)
- Services: `ChargesSyncService`, `EmailChargeService` (descritivo)
- Jobs: `SendChargeGeneratedNotifications`, `CheckAsaasPaymentsJob` (acao no nome)
- Rotas: `finance.charges.store`, `core.collaborator.update` (dot notation)

### 5.4 Formatacao e Moeda

- Valores monetarios: `decimal(13,2)` ou `decimal(15,2)` no banco, `FormatHelper::currencyToDecimal()` na entrada, `FormatHelper::decimalToCurrency()` na saida
- Datas: `d/m/Y` na interface, `Y-m-d` no banco, `FormatHelper::dateToDatabase()` / `dateToDisplay()`
- CPF/CNPJ: armazenado sem formatacao, formatado na exibicao com `FormatHelper::formatCpfOrCnpj()`

---

## 6. Integracoes Externas

| Servico | Para que | Credencial | Arquivos-chave |
|---------|----------|------------|----------------|
| **Asaas** | Pagamentos (boleto/PIX), NFS-e, extratos, webhooks | asaas_token, asaas_url | `AsaasApiController`, `AsaasPaymentService`, `AsaasCheckPaymentsService`, `AsaasStatementService` |
| **Iugu** | Boletos, transferencias, extratos | iugu_token_base64 | `IuguChargesController`, `IuguPaymentService`, `IuguStatementService` |
| **Spedy** | Emissao NFS-e | spedy_token, spedy_url | `SpedyApiController`, `Spedy/InvoiceSyncService` |
| **Google Cloud Storage** | Armazenamento de documentos, NFs, comprovantes | JSON service account | `BucketGoogleApiController`, `GoogleCSService` |
| **Google Cloud Vision** | OCR de PDFs (boletos, NFs) | JSON service account | `BucketGoogleApiController::read_pdf()` |
| **OpenAI** | Extracao de dados de NFs e boletos (GPT-4) | openai_api_key | `OpenaiApiController`, `OpenAIService` |
| **Gemini** | Fallback de extracao de dados | gemini_api_key | `GeminiApiController` |
| **Slack** | Alertas de erro, notificacoes, DMs para colaboradores | webhook_url, bot_token | `SlackAlertService`, `SlackApiController` |
| **Monday.com** | Sync de projetos/campanhas Incorp | monday_api_key (GraphQL) | `MondayApiController`, `FormulaService` |
| **Ntfy.sh** | Push notifications | server, token, topic | `NtfyApiController` |
| **N8N** | Automacao (webhook de email) | api_token | `N8NWebhookController` |

**Credenciais sao centralizadas** em `IntegrationCredentialService` — busca por slug do provider no banco central, vinculadas ao tenant.

---

## 7. Fluxos Criticos

### 7.1 Ciclo de Cobranca
```
Recorrencia ativa (cron 2x/dia)
  → RecurrenceSyncService gera FinanceCharge (Programado, stage=1)
  → PendingChargesGenerationService emite boleto Asaas + NFS-e (Pendente, stage=2)
  → SendChargeGeneratedNotifications envia email ao cliente (5min)
  → CheckAsaasPaymentsJob verifica status (2min)
  → Asaas Webhook confirma pagamento
  → Se vencida: SendChargeOverdueNotifications (D+1, D+2, D+5, cada 2 dias uteis)
  → ChargesSyncService atualiza status final (Pago, stage=3)
```

### 7.2 Ciclo de Pagamento a Colaborador
```
Dia 25: GenerateRecurrenceSnapshot (draft)
  → Email + push lembrete para enviar NF
Dia 1: DispatchSnapshotInvoices cria FinanceInvoice (expected)
  → DispatchSnapshotTransfers cria FinanceTransaction PIX (scheduled)
  → DispatchScheduledPaymentsJob processa no dia (pending → ProcessPaymentJob)
Dias 4-5: Slack DM cobrando NF (3x/dia)
Dias 1-5: CloseCompletedSnapshotsJob fecha snapshot se tudo finalizado
```

### 7.3 Pagamento Operacional
```
Upload PDF → OCR (Vision) → AI extrai codigo (OpenAI/Gemini) → Asaas simula
  → Transacao draft criada
Revisao → validateBatch → status pending/scheduled
  → ProcessPaymentJob → AsaasPaymentService/IuguPaymentService
  → Webhook Asaas retorna status final
  → Comprovante baixado e salvo no GCS
```

---

## 8. Regras de Negocio Essenciais

### Cobrancas
- **bill_stage**: 1=programada, 2=emitida, 3=finalizada. So edita em stage 1. So cancela NFS+pagamento em stage 2+.
- **mail_stage**: 0-9, controla cadencia de emails. Stage 9 = nenhuma notificacao mais.
- **Status "Vencido"** e calculado (Pendente + due_date < hoje), NAO armazenado.
- **Segunda via** reusa a NFS-e original e cancela a cobranca anterior.
- **Multa**: percentual configuravel + juros fixo 1% a.m.

### Projetos e Resumo
- Projeto so entra no resumo se `FinanceProject.send_mail = false`.
- Remover projeto do resumo automaticamente reativa `send_mail = true`.
- Desativar projeto cascateia para contratos e configs financeiras.

### Snapshots
- Recorrencia: dia 25 (gera) → dia 1 (NFs + transferencias) → dias 1-5 (fecha).
- Premios: dia 15 abr/out (gera) → dia 25 (NFs + transferencias) → dias 25-30 (fecha).
- Prioridade 1/2/3 = dia base + 0/1/2 dias uteis.
- Edicao bloqueada apos lock_date.

### Dias Uteis
- 10 feriados fixos + 5 moveis (baseados na Pascoa).
- Se vencimento cai em feriado/fim de semana, avanca para proximo dia util.
- Dia 29/30/31 ajusta para ultimo dia do mes.

### NFs de Colaborador
- Upload PDF → OCR → OpenAI valida valor → se confere: received, senao: rejected.
- Rejeicao manual exige motivo e envia email.

### Sincronizacao
- 5 steps sequenciais, falha individual nao para os proximos.
- Janela de lock: 07:55-08:05 e 19:55-20:05 (protege cron).
- Timeout: 30 minutos.

---

## 9. Banco de Dados

**60 tabelas** distribuidas entre landlord (16) e tenant (44).

### Tabelas mais criticas (maior volume de leitura/escrita):
- `finance_charges` — tabela central, acessada por 25+ arquivos, 7 indices
- `finance_transactions` — pagamentos operacionais e de colaboradores
- `finance_payment_collab_snapshot_items` — itens de lote de pagamento
- `finance_ca_statement` — extrato consolidado
- `finance_logs` — log de erros (polling a cada 1 minuto)

### Campos com criptografia:
- `integration_tokens.payload` — credenciais de API
- `email_configs.payload` — credenciais SMTP

### Modelo com SoftDeletes:
- Apenas `FinanceRecurrence`

### Tabelas que foram removidas via migration:
- `finance_payment_transfer` e `finance_payment_cost_expense` — substituidas por `finance_transactions` + subtabelas

---

## 10. Cron Jobs Criticos

| Job | Freq | Impacto |
|-----|------|---------|
| SendFinanceLogAlerts | 1 min | Alertas Slack para erros |
| CheckAsaasPaymentsJob | 2 min | Status de pagamentos em tempo real |
| CheckIuguPaymentsJob | 2 min | Status de pagamentos Iugu |
| SyncInvoiceStatus | 2 min | Status de NFS-e |
| SendChargeGeneratedNotifications | 5 min | Emails de cobranca |
| RunFinanceSync | 08:00/20:00 | Sync completo (maior job do sistema) |
| DispatchScheduledPaymentsJob | 09:00 | Processa pagamentos do dia |
| GenerateRecurrenceSnapshot | Dia 25 | Inicia ciclo de pagamento mensal |

---

## 11. Webhooks

| Endpoint | Origem | Middleware | Impacto |
|----------|--------|-----------|---------|
| `POST /api/asaas/transaction_status` | Asaas | AsaasWebhookMiddleware | Atualiza status de transacoes em tempo real |
| `POST /api/n8n/mailNotification` | N8N | N8nTokenMiddleware | Push notification de emails |
| `POST /api/finance/refunds/add` | Exent Space | google.domain + tenancy.header | Cria reembolsos |
| `POST /api/finance/invoices/add` | Exent Space | google.domain + tenancy.header | Upload de NFs |
| `POST /api/integration/collaborators/sync` | Exent Space | IntegrationApiTokenMiddleware | Sync de dados de colaboradores |

---

## 12. Arquivos Criticos

**Se voce precisa mudar algo, estes sao os arquivos que mais impactam o sistema:**

| Arquivo | Por que e critico |
|---------|-------------------|
| `routes/console.php` | TODOS os 50+ cron jobs definidos aqui |
| `routes/web.php` | Todas as rotas web (~200 rotas) |
| `routes/api.php` | Webhooks e API de integracao |
| `app/Services/Finance/Payment/PaymentServiceFactory.php` | Decide qual provider processa pagamentos |
| `app/Jobs/Finance/ProcessPaymentJob.php` | Executa pagamento real (dinheiro sai da conta). tries=1. |
| `app/Jobs/Finance/RunManualFinanceSync.php` | Orquestra sync completo. timeout=30min. |
| `app/Http/Controllers/Finance/TransactionsController.php` | 3.349 linhas, controller mais complexo |
| `app/Http/Controllers/Finance/ChargesController.php` | Toda logica de cobrancas |
| `app/Services/IntegrationCredentialService.php` | Resolve credenciais de API — quebra tudo se falhar |
| `app/Services/GuzzleService.php` | Cliente HTTP centralizado — usado por todas as APIs |
| `app/Http/Middleware/AsaasWebhookMiddleware.php` | Autentica webhooks Asaas e identifica tenant |
| `app/Providers/TenancyServiceProvider.php` | Ciclo de vida do tenant (create/delete database) |
| `app/Services/Finance/GeneralService.php` | Dias uteis, feriados — afeta todos os calculos de data |

---

## 13. Cuidados ao Implementar Novas Funcionalidades

### Multi-tenancy
- **SEMPRE** verifique se o codigo roda no contexto do tenant correto. Models sem `$connection` explicita usam o tenant atual.
- Models de integracao (`IntegrationProvider`, `IntegrationToken`, `CompanyToken`) estao no banco central — cuidado ao fazer queries.
- Ao criar um novo Job, use a macro `tenantJob` no `console.php` se for rodar para todos os tenants.

### Cobrancas e Pagamentos
- **NUNCA** altere `bill_stage` ou `bill_status` sem seguir as transicoes documentadas (1→2→3).
- **NUNCA** altere `mail_stage` para um valor menor que o atual (so avanca).
- `ProcessPaymentJob` tem tries=1 — se voce criar um novo job de pagamento, considere a mesma restricao.
- Webhook Asaas SEMPRE retorna 200 — se mudar isso, Asaas vai reenviar indefinidamente.

### Datas e Valores
- Use `FormatHelper::currencyToDecimal()` para converter valores da interface.
- Use `GeneralService::ensureWorkday()` para ajustar datas de vencimento.
- Feriados estao hardcoded em `GeneralService::getHolidays()` — adicione novos la.

### Notificacoes
- Cada tipo de notificacao tem cadencia especifica (ver `business-rules.md` secao 9).
- Emails usam SMTP dinamico por tenant/modulo — `SmtpCredentialService` resolve as credenciais.
- Slack usa webhook para alertas gerais e Bot API para DMs a colaboradores.

### APIs Externas
- Todas passam pelo `GuzzleService` (timeout 30s, auto JSON parse).
- Credenciais via `IntegrationCredentialService::getToken('slug')`.
- Se adicionar novo provider: crie `IntegrationProvider` com slug unico, adicione no `MasterController`.

### Banco de Dados
- Novas tabelas de tenant: migrations em `database/migrations/tenant/`.
- Novas tabelas centrais: migrations em `database/migrations/`.
- `finance_charges` tem 7 indices — cuidado com queries sem indice nesta tabela.
- `finance_transactions` e polimorfica (bill, transfer, pix_qrcode via hasOne).

### Testes
- Projeto nao tem testes automatizados significativos. Valide manualmente.
- Use `finance_invoice_test` para testar NFS-e sem afetar producao.
- Use `TransactionsController::testTransfer()` para testar transferencia de R$ 1,00.

---

## 14. Documentacao Complementar

Todos os documentos estao em `docs-llm/`:

| Documento | Conteudo | Quando consultar |
|-----------|----------|-----------------|
| `system-map.md` | Estrutura de diretorios, modulos, dependencias, stack | Visao geral do projeto |
| `dependency-map.md` | Route → Controller → Service → Model → DB para cada modulo | Antes de alterar qualquer fluxo |
| `business-rules.md` | Regras de negocio implicitas (17 secoes) | Antes de alterar logica de negocio |
| `automatic-flows.md` | Cron jobs, queue jobs, webhooks com timing e dependencias | Ao trabalhar com jobs ou crons |
| `database-documentation.md` | 60 tabelas com campos, FKs, indices, onde sao usadas | Ao criar/alterar migrations ou queries |
| `flows/01-20` | 20 documentos de fluxos de usuario com diagramas | Ao implementar ou alterar funcionalidades |

### Ordem de leitura recomendada para uma LLM nova:
1. **Este arquivo** (LLM_CONTEXT.md) — contexto geral
2. **system-map.md** — estrutura e modulos
3. **business-rules.md** — regras que o codigo deve respeitar
4. O documento especifico da area que vai trabalhar (flows/, dependency-map, database, automatic-flows)

---

## 15. Glossario

| Termo | Significado |
|-------|-------------|
| Cobranca (Charge) | Boleto ou PIX emitido para um cliente |
| NFS-e | Nota Fiscal de Servico Eletronica |
| Recorrencia | Regra automatica que gera cobrancas mensalmente |
| Snapshot | Lote de pagamentos a colaboradores (mensal ou semestral) |
| Snapshot Item | Item individual do snapshot (1 por colaborador) |
| Bill Stage | Estagio da cobranca: 1=draft, 2=emitida, 3=finalizada |
| Mail Stage | Estagio de notificacao: 0-9 (9=final) |
| Resumo de Cobranca | Agrupamento de cobrancas de projetos com send_mail=false |
| Transacao | Pagamento operacional (boleto/TED/PIX/PIX QR Code) |
| Transfer Account | Conta bancaria de terceiro cadastrada para transferencias |
| Provider | Gateway de pagamento (Asaas ou Iugu) |
| Tenant | Empresa no sistema multi-tenant |
| Exent Space | App externo que envia dados de colaboradores via API |
| Incorp | Submodulo de campanhas importadas do Monday.com |
| MEI | Micro Empreendedor Individual (limite anual monitorado) |