# Documentação e Padronização — Fluxo Jurídico API

## 1. Objetivo

Este documento é a referência obrigatória para manutenção e evolução da API. O projeto usa padrões internacionais de desenvolvimento, mas mantém documentação funcional em português para facilitar a comunicação com a equipe.

## 2. Stack oficial

| Item | Padrão |
|---|---|
| Framework | Laravel 13 |
| PHP | 8.3 ou superior |
| Banco | MySQL 8 |
| API | REST, JSON e versionamento por URL |
| Autenticação | JWT Bearer |
| Autorização | Spatie Laravel Permission |
| Documentação | OpenAPI 3 com L5-Swagger |
| Testes | PHPUnit |
| Estilo | Laravel Pint / PSR-12 |
| Arquivos privados | AWS S3 com URL temporária |

## 3. Idioma e nomenclatura

- Classes, métodos, variáveis, tabelas técnicas e comentários de código: **inglês simples**.
- Mensagens de interface podem ser traduzidas no frontend.
- Documentação de negócio: português.
- Classes usam `PascalCase`.
- Métodos e variáveis usam `camelCase`.
- Tabelas e colunas usam `snake_case`.
- Permissões usam `resource.action`, por exemplo `clients.view`.
- Roles usam slug em minúsculas, por exemplo `advogado-senior`.

## 4. Estrutura de cada módulo

Cada recurso deve seguir esta separação:

```text
app/
├── Http/
│   ├── Controllers/Api/V1/
│   ├── Requests/Api/V1/
│   └── Resources/
├── Models/
├── Rules/
├── Services/
└── OpenApi/
```

Regras:

1. Controller coordena a requisição; não concentra regra de negócio complexa.
2. Form Request valida e normaliza entrada.
3. Resource controla o JSON de saída.
4. Rule concentra validações reutilizáveis, como CPF e CNPJ.
5. Service concentra operações de negócio reutilizáveis.
6. Model define estado, casts, relacionamentos e scopes.
7. Operações com várias gravações usam transação.
8. Toda consulta deve respeitar o escritório do usuário autenticado.

## 5. Versionamento da API

A versão atual é `/api/v1`.

Mudança incompatível exige nova versão, por exemplo `/api/v2`. Novos campos opcionais e novos endpoints podem permanecer na versão atual.

## 6. Envelope JSON

Sucesso:

```json
{
  "success": true,
  "message": "User created successfully.",
  "data": {},
  "errors": null
}
```

Erro:

```json
{
  "success": false,
  "message": "Validation failed.",
  "data": null,
  "errors": {}
}
```

Listagens paginadas incluem `meta`:

```json
{
  "success": true,
  "message": "Request completed successfully.",
  "data": [],
  "errors": null,
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 15,
    "total": 0
  }
}
```

## 7. Multi-tenancy por escritório

- `office_id` é obrigatório nas entidades pertencentes a um escritório.
- O `office_id` nunca deve ser aceito diretamente do payload do frontend.
- O valor deve vir do usuário autenticado.
- Consultas devem usar um scope ou filtro explícito por escritório.
- Acesso a um registro de outro escritório responde `404`, não `403`, para não revelar sua existência.
- Testes de isolamento são obrigatórios em cada módulo multi-tenant.

## 8. Autenticação JWT

- O token é enviado em `Authorization: Bearer <token>`.
- Senhas nunca são retornadas pela API.
- Permissões não são gravadas dentro do token; alterações de role devem valer imediatamente.
- O endpoint de refresh deve aceitar token expirado dentro da janela configurada.
- Logout invalida o token atual.
- `JWT_SECRET` nunca é versionado.

## 9. Roles e permissions

- Toda rota protegida recebe uma permissão explícita.
- Novas permissões entram em `RolePermissionSeeder`.
- O guard oficial é `api`.
- Controllers não devem substituir a proteção da rota; verificações internas são apenas complementares.

## 10. OpenAPI e L5-Swagger

- Todo endpoint deve possuir atributo OpenAPI.
- Cada `operationId` deve ser único.
- Schemas reutilizáveis devem ficar em `app/OpenApi`.
- O JSON gerado em `storage/api-docs` não deve ser versionado.
- Antes de publicar:

```bash
php artisan l5-swagger:generate
```

- A geração do Swagger deve passar no CI sem avisos ou conflitos de schema.

## 11. Banco de dados

- Migrations são imutáveis depois de publicadas em produção.
- Chaves estrangeiras devem declarar comportamento de atualização e exclusão.
- Registros jurídicos e administrativos usam soft delete quando o histórico precisa ser preservado.
- Documentos e telefones usados em busca devem ser armazenados normalizados.
- Datas são armazenadas no banco e retornadas em ISO 8601.
- Operações que alteram entidade principal e relações usam `DB::transaction`.

## 12. Padrões do CRM

- CPF e CNPJ são armazenados somente com números.
- CPF/CNPJ é único por escritório.
- Contatos e endereços enviados no update representam a coleção completa.
- Array ausente mantém a coleção; array vazio remove todos os itens.
- Apenas um contato e um endereço podem ser principais.
- Interações registram usuário, tipo e `occurred_at`.
- Exclusão do cliente usa soft delete.
- Consulte `docs/CRM_CLIENTS.md` antes de alterar o módulo.

## 13. Segurança e arquivos

- Validar tamanho, tipo e extensão de uploads.
- Bucket S3 deve permanecer privado.
- Download usa URL temporária.
- Nunca salvar segredos ou URLs temporárias em logs.
- Produção usa HTTPS e `APP_DEBUG=false`.
- Executar `composer audit` em todo pipeline.

## 14. Testes obrigatórios

Cada módulo deve cobrir, no mínimo:

1. fluxo principal de criação;
2. validação de entrada;
3. autenticação;
4. permissão;
5. isolamento por escritório;
6. listagem e filtros importantes;
7. atualização e exclusão quando aplicáveis.

Banco de teste: SQLite em memória. Testes usam JWT real quando a rota depende do guard `api`.

## 15. Qualidade e publicação

Antes de abrir ou atualizar uma Pull Request:

```bash
composer validate --strict
vendor/bin/pint --test
php artisan l5-swagger:generate
php artisan test
composer audit
```

O CI deve passar integralmente antes do merge.

## 16. Comentários no código

Comentários explicam decisões de negócio ou comportamento não óbvio. Não devem repetir literalmente o código.

Bom exemplo:

```php
// Numeric searches also cover normalized CPF, CNPJ and phone fields.
```

Evitar comentários como:

```php
// Creates the client.
$client = Client::create($data);
```

## 17. Commits e Pull Requests

- Commits em inglês e no imperativo/convenção do projeto.
- Uma Pull Request deve explicar escopo, impacto, migrations e validações executadas.
- Alteração incompatível deve indicar estratégia de migração.
- Nenhuma credencial deve aparecer em diff, teste ou documentação.

## 18. Padrões do GED

- Todo documento pertence a um `office_id` e a um `client_id`.
- O escritório vem do usuário autenticado; nunca do payload.
- Rotas públicas do GED usam UUID, não ID sequencial.
- O nome original é metadado; o caminho físico usa nome aleatório.
- O caminho segue `offices/{office_id}/clients/{client_id}/documents/{uuid}.{extension}`.
- `disk` e `path` não são retornados pelo Resource.
- O bucket ou disco permanece privado.
- Download é feito somente por URL temporária com expiração máxima de 60 minutos.
- Upload registra MIME type, extensão, tamanho e checksum SHA-256.
- Formatos e limite de tamanho ficam centralizados em `config/documents.php`.
- Atualização modifica apenas metadados; substituição de arquivo exige uma operação versionada futura.
- Exclusão usa soft delete e preserva o objeto até existir política formal de retenção e expurgo.
- Toda mudança no GED deve testar upload, formato inválido, permissão, isolamento, filtros, download e exclusão.
- Consulte `docs/GED_DOCUMENTS.md` antes de alterar o módulo.

## 19. Padrões do Financeiro

- Valores monetários são armazenados em centavos inteiros (`*_cents`).
- `float`, `double` e cálculos monetários em ponto flutuante são proibidos.
- Todo lançamento pertence a um escritório, cliente e categoria compatível.
- O status é derivado de parcelas, pagamentos, vencimento e cancelamento; não é aceito livremente do frontend.
- Cada lançamento possui pelo menos uma parcela e o total das parcelas deve ser igual ao total do lançamento.
- Pagamentos nunca são sobrescritos ou apagados; exclusão de pagamento gera estorno com usuário, data e motivo.
- O registro de pagamento usa transação e `lockForUpdate` para impedir pagamento concorrente acima do saldo.
- Agenda de parcelas e valores financeiros não podem ser alterados depois do primeiro pagamento ativo.
- Categoria com histórico financeiro não pode ser removida; deve ser desativada.
- Lançamento cancelado usa soft delete, mantendo parcelas e pagamentos para auditoria.
- Documentos financeiros continuam sob controle do GED e só podem ser vinculados ao mesmo cliente e escritório.
- Rotas de lançamentos, parcelas e pagamentos usam UUID público.
- Consultas devem recalcular ou materializar o estado de vencimento antes de devolver resultados.
- Toda alteração financeira deve testar pagamento parcial, pagamento total, excesso de pagamento, estorno, vencimento, permissão, isolamento e preservação histórica.
- Consulte `docs/FINANCIAL.md` antes de alterar o módulo.