testes/docs/PADROES_ROTAS_APRESENTACAO.md

# Padrões de Rotas de Apresentação (Back–Front)

**Objetivo**: Contrato único por rota de listagem: endpoint, resposta esperada e colunas sugeridas para o front.  
**Uso**: Ao inserir ou alterar uma rota "apresentar", atualizar este documento; as views devem usar as colunas sugeridas aqui (ver comentário no código: "Ver docs/PADROES_ROTAS_APRESENTACAO.md § NomeDaRota").

---

## Ambiente: Prafrot (Prafrota)

### GET /cadastro_frota/apresentar

- **Descrição**: Lista veículos cadastrados na frota.
- **Service**: `prafrotService.getVehicles()`.
- **View**: Veículos / Status Frota.

**Resposta esperada**: array de objetos com campos, por exemplo:
`idveiculo_frota`, `placa`, `modelo`, `base`, `motorista`, `status`, `manutencao`, `atuacao`, `proprietario`, `vecfleet`, `obs`, `combustivel`, `tipo`, `marca`, `ano`, `cidade`, etc.

**Colunas sugeridas** (copiar para a view que usa ExcelTable):
```js
[
  { field: 'placa', header: 'Placa', width: '100px', className: 'font-mono font-bold text-emerald-600 dark:text-emerald-500' },
  { field: 'modelo', header: 'Modelo', width: '150px' },
  { field: 'base', header: 'Unidade', width: '120px' },
  { field: 'motorista', header: 'Motorista', width: '180px' },
  { field: 'status', header: 'Status', width: '140px' },
  { field: 'manutencao', header: 'Manutenção', width: '120px' },
  { field: 'atuacao', header: 'Atuação', width: '140px' },
  { field: 'proprietario', header: 'Proprietário', width: '140px' },
  { field: 'vecfleet', header: 'VecFleet', width: '140px' },
  { field: 'obs', header: 'OBS', width: '250px' }
]
```

**filterDefs sugeridos**: `[{ field: 'placa', label: 'Placa', type: 'text' }, { field: 'motorista', label: 'Motorista', type: 'text' }, { field: 'base', label: 'Unidade', type: 'select' }]`

---

### GET /manutencao_frota/apresentar

- **Descrição**: Lista todas as manutenções (total).
- **Service**: `prafrotService.getMaintenance()`.
- **View**: MaintenanceView (Manutenção).

**Resposta esperada**: array de objetos com campos:
`idmanutencao_frota`, `atendimento`, `placa`, `placa_reserva`, `modelo`, `oficina`, `base_frota`, `cidade`, `uf`, `proprietario`, `responsavel`, `motivo_atendimento`, `status`, `manutencao`, `status_frota_veiculo`, `data_solicitacao`, `data_agendamento`, `data_parada_veiculo`, `previcao_entrega`, `data_finalizacao`, `data_retirada`, `orcamento_inicial`, `orcamento_final`, `dif_orcamento`, `condicao_pagamento`, `validacao_financeiro`, `resp_aprovacao`, `sla_oficina`, `sla_pos_oficina`, `obs`, `endereco_prestador`, `pdf_orcamento`.

**Colunas sugeridas** (ver MaintenanceView.jsx – já alinhado):
```js
[
  { field: 'idmanutencao_frota', header: 'ID', width: '80px' },
  { field: 'atendimento', header: 'ATENDIMENTO', width: '100px' },
  { field: 'placa', header: 'PLACA', width: '100px', className: 'font-mono font-bold text-emerald-600 dark:text-emerald-500' },
  { field: 'placa_reserva', header: 'PLACA RESERVA', width: '100px' },
  { field: 'modelo', header: 'MODELO', width: '110px' },
  { field: 'oficina', header: 'OFICINA', width: '160px' },
  { field: 'base_frota', header: 'BASE FROTA', width: '100px' },
  { field: 'cidade', header: 'CIDADE', width: '120px' },
  { field: 'uf', header: 'UF', width: '60px' },
  { field: 'proprietario', header: 'PROPRIETÁRIO', width: '110px' },
  { field: 'responsavel', header: 'RESPONSÁVEL', width: '120px' },
  { field: 'motivo_atendimento', header: 'MOTIVO ATEND.', width: '120px' },
  { field: 'status', header: 'STATUS', width: '140px' },
  { field: 'manutencao', header: 'MANUTENÇÃO', width: '90px' },
  { field: 'status_frota_veiculo', header: 'STATUS FROTA', width: '120px' },
  { field: 'data_solicitacao', header: 'DATA SOLIC.', width: '100px' },
  { field: 'data_agendamento', header: 'DATA AGEND.', width: '100px' },
  { field: 'data_parada_veiculo', header: 'DATA PARADA', width: '100px' },
  { field: 'previcao_entrega', header: 'PREV. ENTREGA', width: '100px' },
  { field: 'data_finalizacao', header: 'DATA FINAL.', width: '100px' },
  { field: 'data_retirada', header: 'DATA RETIRADA', width: '100px' },
  { field: 'orcamento_inicial', header: 'ORÇ. INICIAL', width: '110px' },
  { field: 'orcamento_final', header: 'ORÇ. FINAL', width: '110px' },
  { field: 'dif_orcamento', header: 'DIF. ORÇ.', width: '100px' },
  { field: 'condicao_pagamento', header: 'COND. PAG.', width: '100px' },
  { field: 'validacao_financeiro', header: 'VALID. FINANC.', width: '110px' },
  { field: 'resp_aprovacao', header: 'RESP. APROV.', width: '110px' },
  { field: 'sla_oficina', header: 'SLA OFICINA', width: '100px' },
  { field: 'sla_pos_oficina', header: 'SLA PÓS-OF.', width: '100px' },
  { field: 'obs', header: 'OBS', width: '180px' },
  { field: 'endereco_prestador', header: 'END. PRESTADOR', width: '180px' },
  { field: 'pdf_orcamento', header: 'PDF ORÇAMENTO', width: '100px' }
]
```

**filterDefs sugeridos**: `[{ field: 'placa', label: 'Placa', type: 'text' }, { field: 'oficina', label: 'Oficina', type: 'select' }, { field: 'status', label: 'Status', type: 'select' }, { field: 'motivo_atendimento', label: 'Motivo Atendimento', type: 'select' }, { field: 'responsavel', label: 'Responsável', type: 'select' }, { field: 'cidade', label: 'Cidade', type: 'select' }]`

---

### GET /manutencao_frota/aberto_fechado/apresentar

- **Descrição**: Lista manutenções agrupadas em aberto/fechado.
- **Service**: `prafrotService.getAbertoFechado()`.
- **Uso**: Filtro na MaintenanceView (statusFilter: total | aberta | fechada).

**Resposta esperada**: estrutura com listas ou grupos `aberta` e `fechada` (ou array com campo de status). Formato exato depende do backend; a view filtra localmente se receber array único.

---

### GET /disponibilidade_frota/apresentar

- **Descrição**: Lista disponibilidade de veículos.
- **Service**: `prafrotService.getAvailability()`.

**Resposta esperada**: array de objetos; campos típicos a confirmar com o backend. Colunas sugeridas: espelhar campos retornados (ex.: `placa`, `disponivel`, `periodo`, etc.).

---

### GET /moki_frota/apresentar

- **Descrição**: Lista checklists Moki.
- **Service**: `prafrotService.getMoki()`.

---

### GET /status_frota/apresentar

- **Descrição**: Lista status da frota.
- **Service**: `prafrotService.getStatus()`.

---

### GET /monitoramento_frota/apresentar

- **Descrição**: Lista monitoramento.
- **Service**: `prafrotService.getMonitoring()`.

---

### GET /sinistro_devolucao_venda_frota/apresentar

- **Descrição**: Lista sinistros/devoluções/vendas.
- **Service**: `prafrotService.getClaims()`.

---

### GET /oficinas_frota/apresentar

- **Descrição**: Lista oficinas.
- **Service**: `prafrotService.getWorkshops()`.

---

## Ambiente: Workspace / Financeiro-v2

### GET /extrato/apresentar

- **Descrição**: Extrato bancário; filtrar por `tipoOperacao`: "C" = receitas, "D" = despesas.
- **Service**: `extratoService.fetchExtrato()`.

**Resposta esperada**: array de objetos com campos, por exemplo:
`idextrato`, `dataEntrada` (ou `data`), `descricao`, `valor`, `tipoOperacao`, `categoria`, `beneficiario_pagador` (ou `beneficiario`), `caixinha`, etc.

**Colunas sugeridas** (transações):
```js
[
  { field: 'data', header: 'Data', width: '120px' },
  { field: 'descricao', header: 'Descrição', width: '400px' },
  { field: 'valor', header: 'Valor', width: '150px' },
  { field: 'tipo', header: 'Tipo', width: '120px' },
  { field: 'status', header: 'Status', width: '120px' }
]
```

---

### GET /categorias/apresentar

- **Descrição**: Lista categorias para conciliação/labels.
- **Service**: `extratoService.fetchCategorias()` ou `workspaceConciliacaoService`.

**Resposta esperada**: array de objetos (ex.: `id`, `nome`, `descricao`, `tipoMovimento`, `cor`).

---

### GET /caixinhas/apresentar

- **Descrição**: Lista caixinhas.
- **Service**: `extratoService.fetchCaixinhas()` ou `workspaceConciliacaoService`.

**Resposta esperada**: array de objetos (ex.: `id`, `nome`, `banco`, `agencia`, `conta`).

---

### GET /contas_a_pagar/apresentar

- **Descrição**: Contas a pagar planejadas.
- **Service**: `workspaceDespesasService` (ou equivalente).

**Resposta esperada**: array com campos do planejado (categoria, valor, data, etc.). Colunas sugeridas: espelhar campos retornados.

---

### GET /saldo/armazenado/apresentar

- **Descrição**: Saldos armazenados (histórico); usado para último saldo do mês anterior no fluxo de caixa.
- **Service**: `extratoService.fetchSaldoArmazenado()`.

**Resposta esperada**: array (ou objeto único) com `data_saldo`, `saldo_disponivel`, `mes`, `ano`, `idsaldos_mensais`, etc.

---

## Ambiente: GR

### GET /cadastro/drivers/apresentar

- **Descrição**: Lista motoristas (cadastro).
- **Service**: `grService` (getRegistrations ou equivalente).

### GET /contrato/drivers/apresentar

- **Descrição**: Lista motoristas em contrato ativo.
- **Service**: `grService`.

---

## Como usar este documento

1. **Nova rota de apresentação**: adicione um bloco acima com endpoint, resposta esperada e colunas sugeridas; na view, use as colunas do doc e comente: `// Ver docs/PADROES_ROTAS_APRESENTACAO.md § NomeDaRota`.
2. **Backend mudou**: atualize a "Resposta esperada" e as "Colunas sugeridas" aqui; depois ajuste a view para manter alinhamento.
3. **Playground**: a seção "Rotas e Ambientes" pode exibir este documento por ambiente para gerenciamento visual.