# CRM e Clientes

## Objetivo

O módulo mantém os clientes pessoa física e jurídica de cada escritório, seus meios de contato, endereços e histórico de atendimento.

## Entidades

### `clients`

Registro principal do cliente.

- `office_id`: escritório proprietário do dado;
- `person_type`: `individual` ou `company`;
- `status`: `prospect`, `active` ou `inactive`;
- `document`: CPF ou CNPJ armazenado somente com números;
- `created_by_user_id` e `updated_by_user_id`: auditoria básica;
- soft delete para preservar o histórico.

CPF ou CNPJ é único dentro do mesmo escritório.

### `client_contacts`

Lista de telefones, celulares, WhatsApp, e-mails ou outros contatos. Apenas um item da lista pode ser marcado como principal.

### `client_addresses`

Lista de endereços residenciais, profissionais, de cobrança ou outros. Apenas um endereço pode ser marcado como principal.

### `client_interactions`

Histórico cronológico de notas, chamadas, e-mails, mensagens, reuniões e outros atendimentos. Cada interação registra o usuário responsável e a data em que ocorreu.

## Endpoints

```http
GET    /api/v1/clients
POST   /api/v1/clients
GET    /api/v1/clients/{client}
PUT    /api/v1/clients/{client}
DELETE /api/v1/clients/{client}

GET    /api/v1/clients/{client}/interactions
POST   /api/v1/clients/{client}/interactions
```

## Listagem

Parâmetros aceitos:

- `search`: nome, nome fantasia, e-mail, telefone, contato, CPF ou CNPJ;
- `status`: `prospect`, `active` ou `inactive`;
- `person_type`: `individual` ou `company`;
- `per_page`: de 1 a 100 registros.

## Contatos e endereços

Contatos e endereços são enviados dentro do payload do cliente. Em uma atualização:

- campo ausente: mantém a coleção atual;
- campo enviado: substitui a coleção completa;
- array vazio: remove todos os itens da coleção.

Essa regra evita estados parciais e mantém o fluxo simples para o frontend.

## Permissões

```text
clients.view
clients.create
clients.update
clients.delete
clients.interactions.view
clients.interactions.create
```

## Segurança multi-tenant

Toda consulta usa o `office_id` do usuário autenticado. Ao tentar consultar ou alterar um cliente de outro escritório, a API responde `404`, evitando confirmar a existência do registro.

## Validação de documentos

- pontuação de CPF e CNPJ é removida antes da validação;
- sequências repetidas são inválidas;
- dígitos verificadores são calculados pela API;
- pessoa física exige CPF válido;
- pessoa jurídica exige CNPJ válido.

## Exclusão

A exclusão do cliente usa soft delete. O registro deixa de aparecer na API, mas permanece no banco para histórico, auditoria e futura recuperação administrativa.