# CLAUDE.md

Este arquivo fornece orientações para o Claude Code (claude.ai/code) ao trabalhar com código neste repositório.

## Stack Tecnológico

- **Backend**: Laravel 12, PHP 8.2+
- **Frontend**: React 19, TypeScript, Inertia.js v2, Vite 6, Tailwind CSS 4
- **Testes**: Pest v3 (PHP)
- **Pacotes principais**: Spatie Permission/Activitylog, Maatwebsite Excel, cloud-dfe/sdk-php (API fiscal), Asaas (pagamentos), TipTap (texto rico), TanStack Table, React Hook Form + Zod

## Comandos

```bash
# Instalar dependências
composer install && npm install

# Desenvolvimento (inicia Laravel + queue + Vite + visualizador de logs simultaneamente)
composer run dev

# Fazer build do frontend
npm run build

# Rodar testes
./vendor/bin/pest

# Rodar um único arquivo de teste ou filtro
./vendor/bin/pest tests/Feature/InvoiceTest.php
./vendor/bin/pest --filter=NomeDoTeste

# Estilo de código PHP
./vendor/bin/pint

# Lint + formatação do frontend
npm run lint
npm run format

# Verificação de tipos TypeScript
npm run types
```

## Arquitetura

### Ciclo de Requisição

Controladores recebem requisições HTTP → delegam para classes de Serviço (`Service`) → retornam respostas Inertia com props de componentes React. Operações pesadas são despachadas para a fila (`queue`).

### Camada de Serviços (`app/Services/`)

A lógica de negócios vive aqui, não em controladores ou modelos:

- `InvoiceService` – criação de faturas, transições de status, lógica de recorrência
- `IntegraNotasService` – emissão de nota fiscal (NFSe) via API IntegraNotas (provedor atual)
- `AsaasApiService` / `AsaasSubaccountService` – integração com gateway de pagamento
- `TicketService` – gerenciamento de tickets de suporte
- `CustomerProductService` – ciclo de vida de assinaturas e ciclos de faturamento

### Padrões Orientados a Eventos

- Observadores de Modelo (`app/Observers/`) lidam com efeitos colaterais no ciclo de vida do modelo (ex., `InvoiceObserver` aciona a emissão de NFSe com base na configuração `EmitNfseOn`: MANUAL, CREATION ou PAYMENT)
- Eventos de Domínio (`app/Events/`) + Ouvintes (`app/Listeners/`) para efeitos colaterais assíncronos (e-mails, webhooks, WhatsApp)
- Jobs de Fila (`app/Jobs/`): `EmitNfseJob`, `SendSystemEmailJob`, `SendWebhookJob`, `ProcessEmailToTicketJob`

### Estrutura do Frontend (`resources/js/`)

As páginas em `pages/` são componentes de página do Inertia que recebem props tipadas dos controladores. Componentes reutilizáveis compartilhados ficam em `components/`. Os formulários usam React Hook Form + validação Zod. As rotas são acessadas por meio do helper tipado `route()` do Ziggy.

### Integrações Principais

- **Asaas**: Gateway de pagamento brasileiro (PIX, cartão de crédito, boleto)
- **IntegraNotas**: API de emissão de nota fiscal (NFSe) (substituiu o antigo NotaFacil)
- **IMAP**: Recebimento de e-mail → conversão em ticket de suporte
- **Helena**: Mensagens CRM/SMS/WhatsApp

### Autorização

Spatie `laravel-permission` fornece RBAC. O modelo User usa `HasRoles`. Verificações de permissão em controladores/policies protegem todas as operações sensíveis.

### Rotas

As rotas são divididas em vários arquivos: `routes/web.php` (principal), `routes/settings.php`, `routes/auth.php`, `routes/customer.php` (portal do cliente), `routes/webhooks.php`.

## Contexto do Mercado Brasileiro

Este é um ERP focado em empresas brasileiras. Principais conceitos do domínio:

- **NFSe** (Nota Fiscal de Serviços Eletrônica) – notas fiscais eletrônicas de serviço, exigidas legalmente para faturamento
- **Asaas** – Gateway de pagamento brasileiro suportando PIX, boleto, cartão de crédito
- **CNPJ/CPF** – Identificações fiscais brasileiras (empresarial/pessoal) usadas em todos os registros de clientes

## Contexto da aplicação

Esse é um sistema ERP, que será utilizado por empresas para gestão de serviços prioritariamente recorrentes, lidando com tickets, faturas, pagamentos, notas fiscais, produtos, clientes, etc. 

É um sistema single tenant, onde cada empresa terá sua instalação própria, banco de dados, servidor, etc. Porém para cada funcionalidade, temos que pensar em como abranger o máximo de cenários possíveis, pois cada empresa pode ter suas próprias necessidades e particularidades, e o sistema deve ser flexível o suficiente para atender a essas necessidades.

Sempre que alterar uma rota, execute o comando para atualizar as rotas do frontend: `php artisan ziggy:generate --types`