# Módulo Técnicos

O módulo Técnicos provê cadastro e gestão de técnicos, cálculo de comissões e integração com Vendas, Serviços e PDV.

## Tabelas
- `technicians`: dados pessoais, contato, bancários, comissão (%), status e `pdv_code`.
- `technician_service_history`: histórico de serviços com `amount` e `commission_amount` calculado.

## Campos principais (technicians)
- `nome` (string, obrigatório)
- `cpf` (string, 11 dígitos, obrigatório e único)
- `rg` (string, obrigatório)
- `email` (string, opcional, formato válido)
- `telefone` (string, obrigatório)
- `bank_name`, `bank_agencia`, `bank_conta`, `pix_key` (opcionais)
- `comissao_percent` (number, 0–100)
- `enabled` (boolean/int, 1 ativo, 0 inativo)
- `pdv_code` (string, opcional, único)

## Autenticação e Permissões
- Todas as rotas exigem autenticação (`Bearer JWT`) e permissões RBAC:
  - `tecnicos.read`, `tecnicos.create`, `tecnicos.update`, `tecnicos.delete`, `tecnicos.reports`.

## Endpoints

### Listar técnicos
- `GET /api/cadastros/tecnicos?q=<texto>&page=<n>&per_page=<n>`
- Resposta: `{ data: [ { id, nome, ... } ], page, per_page }`

### Obter técnico
- `GET /api/cadastros/tecnicos/{id}`
- Resposta: `{ data: { id, nome, cpf, ... } }`

### Criar técnico
- `POST /api/cadastros/tecnicos`
- Body JSON: campos principais acima.
- Resposta: `{ data: { id, ... } }`

### Atualizar técnico
- `PUT /api/cadastros/tecnicos/{id}`
- Body JSON: campos a atualizar.
- Resposta: `{ data: { id } }`

### Excluir técnico
- `DELETE /api/cadastros/tecnicos/{id}`
- Resposta: status `204`.

### Histórico de serviços
- `POST /api/cadastros/tecnicos/{id}/service-history`
- Body JSON: `{ description, amount, executed_at, service_id?, source?, reference_id? }`
- Calcula `commission_amount = amount * (comissao_percent / 100)` e salva.
- Resposta: status `201`, `{ data: { commission_amount } }`

### Comissões por período
- `GET /api/cadastros/tecnicos/{id}/comissoes?from=YYYY-MM-DD&to=YYYY-MM-DD`
- Resposta: `{ data: { services, total_amount, total_commission }, from, to }`

### Relatório de produtividade
- `GET /api/cadastros/tecnicos/relatorios/produtividade?from=YYYY-MM-DD&to=YYYY-MM-DD`
- Resposta: `{ data: [ { technician_id, nome, services, total_amount, total_commission } ], from, to }`

### Exportação de pagamentos (CSV)
- `GET /api/cadastros/tecnicos/export/payments?from=YYYY-MM-DD&to=YYYY-MM-DD`
- Resposta: CSV com cabeçalho `nome,bank_name,bank_agencia,bank_conta,pix_key,commission_total`.

-### Identificação por código PDV
- `GET /api/cadastros/tecnicos/identify?code=<PDV_CODE>` ou `GET /api/cadastros/tecnicos/identify/<PDV_CODE>`
- Resposta: `{ data: { id, nome, enabled } }`

## UI
- `GET /cadastros/tecnicos`: interface responsiva para CRUD, busca, relatórios e exportação.

## Testes
- `tests/TecnicosEndpointsTest.php`: valida o CRUD, identificação PDV, histórico e relatórios.