# Aba "Comissão" no Contrato + Modo "Específicas" — Design

Entrega B do esforço maior "ROTINA: Administração - Contrato" (card externo, 9
itens — ver `.claude/rules/comissao.md` pro rastreador completo). Decompomos o
card em 3 entregas sequenciais (A: limpeza mecânica, já concluída; B: este
documento; C: geração automática de Conta a Pagar na baixa da parcela, ainda
não desenhada). Referência visual: tela "Tipo Parcela: Todas/Específicas" do
ACADE VENDAS (`modulo/comissao/cadastroComissao`), análise somente leitura —
não é port 1:1 (arquitetura diferente, ver achados abaixo).

## Pedido original (2 pontos do card)

1. Nova aba "Comissão" no formulário de Contrato, posicionada logo depois de
   "Parcela", com o seletor de modelo de comissão (hoje dentro da aba Pessoa).
2. Quando o modelo selecionado tiver modalidade "Tipo de Parcela (%)", um
   sub-seletor "Todas" (comportamento automático já existente) vs
   "Específicas" (marcar parcelas e %/valor manualmente, com coluna "Comissão
   Comprometida" ao vivo) — modo "Específicas" era explicitamente fora de
   escopo na entrega anterior (20/10/2026).

## Achados que moldaram o desenho (não estavam previstos ao abrir o card)

- **A aba "Parcela" só existe em modo edição** (`@if($id)`,
  `contratoFormulario.blade.php:476`) — contrato precisa já ter sido salvo
  (tem `id`) pra ela aparecer. Decisão do programador (22/10/2026): a aba
  "Comissão" segue a mesma regra, posicionada depois de "Parcela". Isso muda
  comportamento atual: hoje o seletor de Modelo de Comissão vive na aba
  "Pessoa" (`:458-472`), disponível **desde a criação** do contrato — depois
  desta entrega, só dá pra configurar comissão depois do primeiro save.
- **"Específicas" exige parcela real já gerada** (número/data/valor de
  verdade pra marcar linha a linha, igual à tela de referência) — não dá pra
  operar sobre um conceito abstrato de "tipo de parcela" antes de
  `gerarParcelas()` rodar.
- **Vincular um modelo de comissão a um contrato que já tem parcela gerada
  não faz nada hoje** (achado real, confirmado lendo `gerarParcelas()`/
  `instanciarComissoesDoContrato()`) — `instanciarComissoesDoContrato()` só
  roda *dentro* de `gerarParcelas()` (`ContratoController.php:598-721`), que
  é bloqueado de rodar duas vezes (`abort_if($contrato->fl_gerado === '1', ...)`,
  `:601`). Um modelo vinculado depois disso fica como link morto em
  `CONTRATO_PARAMETRO_COMISSAO`, sem nunca gerar `COMISSAO_LANCAMENTO`. Como a
  aba "Comissão" agora é alcançável tanto antes quanto depois de gerar
  parcela, essa lacuna preexistente passa a aparecer de verdade. **Decisão do
  programador (22/10/2026): fechar a lacuna** — depois de `fl_gerado='1'`,
  adicionar um modelo de comissão novo processa na hora (o usuário escolhe
  ali mesmo "Todas" ou "Específicas"), em vez de ficar como vínculo morto.
- **`COMISSAO_LANCAMENTO` não guarda `id_parametro_comissao`** (confirmado
  lendo a migration de criação) — é uma cópia/snapshot dos campos do modelo
  no momento da geração, sem rastro de qual `PARAMETRO_COMISSAO` a originou.
  Sem isso, não dá pra checar "este modelo já foi processado pra este
  contrato?" de forma confiável — precisa de coluna nova (ver modelo de
  dados).
- **Parcela paga não entra no modo Específicas** (decisão do programador,
  22/10/2026) — só parcela em aberto (`payment_date IS NULL`, e não
  cancelada) é elegível pra marcar/editar comissão manual.
- **Sub-seletor "Todas"/"Específicas" só aparece quando `tp_modalidade='parcela'`
  E `parcela_paga='1'`**, como o card pediu literalmente — não generalizado
  pras outras 3 modalidades (`venda`/`fixo`/`tabela`), mesmo elas também
  podendo ter `parcela_paga='1'` (rateio por parcela é ortogonal à
  modalidade no motor atual, `ComissaoCalculoService::ratear()`). Um modelo
  `parcela` com `parcela_paga='0'` (à vista) não tem rateio nenhum — é lançado
  como valor único, igual qualquer outra modalidade à vista, sem pergunta.
  Fora desses dois critérios (`venda`/`fixo`/`tabela`, ou `parcela_paga='0'`),
  o fechamento da lacuna de "vínculo morto pós-geração" (achado acima)
  processa sempre via "Todas", sem oferecer escolha.
- **Existe endpoint reaproveitável pra listar parcelas reais do contrato**:
  `GET api/administracao/contrato/{id}/parcelas`
  (`contratoFormulario.blade.php:1442-1477`) já devolve
  `{resumo, parcelas: [{id, installment_number, categoria_label, due_date,
  payment_date, original_amount, total_amount, status}, ...]}` — mesma fonte
  de dado da aba "Parcela". O picker de "Específicas" precisa de uma visão
  derivada dessa (filtrada por elegibilidade + comissão já comprometida), não
  de uma fonte nova do zero.

## Decisões de negócio (confirmadas com o programador, 22/10/2026)

1. Aba "Comissão" só em modo edição (`@if($id)`), posicionada depois de
   "Parcela".
2. Antes de `fl_gerado='1'`: comportamento idêntico ao de hoje, só
   realocado — tabela de modelos vinculados + combo + "Adicionar", payload
   `comissoes` (array de ids) continua indo junto do save geral do contrato
   (`store()`/`update()` → `salvarComissoesContrato()`, sem mudança nesse
   código). Só "Todas" é possível aqui (sem parcela real pra picker de
   Específicas).
3. Depois de `fl_gerado='1'`: adicionar um modelo novo é uma ação própria,
   com salvamento imediato (endpoint novo, não o save geral do contrato):
   - Se `tp_modalidade='parcela'`: pergunta "Todas" ou "Específicas" na hora.
   - Senão: processa direto via "Todas" (sem pergunta), fechando o vínculo
     morto.
   - Um modelo já processado (tem `COMISSAO_LANCAMENTO` gerado) fica
     **travado** nessa lista — não editável/removível por aqui (mesmo
     espírito da regra já existente "atualizar contrato com parcelas já
     geradas ignora mudança de comissão").
4. Modo "Específicas": lista só parcelas em aberto (não pagas, não
   canceladas) do contrato, com número/tipo/data/valor/**comissão
   comprometida** (soma do que outros modelos já linkados ao mesmo contrato
   já reservaram daquela parcela). Usuário marca checkbox + digita %
   **ou** valor (conversão bidirecional, mesmo padrão do ACADE VENDAS)
   por linha.
5. **Trava dura, não só aviso visual**: o backend rejeita (422) se a soma de
   comissão comprometida + nova alocação ultrapassar o valor da parcela —
   mesma garantia que o modo "Todas" já tem via `ratear()` (dois tetos,
   `min()`). Diferente do ACADE VENDAS, que só mostra aviso em vermelho sem
   bloquear o submit.
6. Reabrir "Específicas" de um modelo já processado permite editar a seleção
   — salvar substitui (apaga e recria) as linhas de `COMISSAO_PAGAMENTO`
   daquele `COMISSAO_LANCAMENTO`.
7. Fora de escopo (entrega C): nenhuma Conta a Pagar é gerada aqui.

## Modelo de dados

### `COMISSAO_LANCAMENTO` — 2 colunas novas (migration `ALTER`)

- `id_parametro_comissao` (integer, nullable, sem FK real — mesmo padrão do
  resto do projeto) — rastreia qual modelo originou este lançamento. Sem FK
  porque `PARAMETRO_COMISSAO.id_parametro_comissao` não tem constraint
  declarada nas migrations legadas. **Também passa a ser gravado pelo fluxo
  já existente** (`instanciarComissoesDoContrato()`, hoje não grava nada
  nessa coluna porque ela não existia) — mudança retrocompatível, não altera
  comportamento, só adiciona rastreabilidade.
- `tp_parcela_comissao` (string, nullable, `'todas'`\|`'especificas'`) — só
  relevante quando `parcela_paga='1'`. Sempre `'todas'` quando gravado pelo
  fluxo de `gerarParcelas()` (pré-geração) ou pelo fechamento do vínculo
  morto fora de `tp_modalidade='parcela'`.

### `CONTRATO_PARAMETRO_COMISSAO` — sem mudança de schema

Continua só o vínculo (`id_contrato`, `id_parametro_comissao`). A decisão de
modo/processamento vive em `COMISSAO_LANCAMENTO` (acima), não aqui — esta
tabela segue sendo gerenciada pelo fluxo "apaga tudo e recria"
(`salvarComissoesContrato()`) **só enquanto `fl_gerado='0'`**. Depois disso,
o endpoint novo (ver Fluxo) faz upsert pontual de UM vínculo por vez, sem
apagar os demais.

### `COMISSAO_PAGAMENTO` — sem mudança de schema

Já tem a forma certa (`id_comissao_lanc`, `porc_parcela`, `id_parcela`,
`tp_parcela`, `vl_parcela`, `vl_comissao_parcela`) pra guardar tanto o
resultado do rateio automático (`ratear()`) quanto a seleção manual
("Específicas") — grava-se igual nos dois casos, só muda quem decide os
valores (algoritmo vs. usuário).

## Fluxo

### A) Aba "Comissão" — HTML (`contratoFormulario.blade.php`)

- Novo `<button>`/`<div class="tab-pane">` `tab-comissao`, inserido logo
  depois do bloco `tab-parcelas` (`:477-525`), dentro do mesmo `@if($id)`.
- A seção hoje em `:458-472` (h6 + tabela + combo + botão "Adicionar") sai da
  aba Pessoa e entra aqui, **sem mudança de HTML/IDs** — só de localização
  (o JS que já existe, `:680-705`, continua funcionando igual).
- Abaixo dessa seção (já existente, realocada), nova seção "Adicionar modelo
  pós-geração" — só visível quando `fl_gerado==='1'`, lido do campo
  `fl_gerado` que `GET api/administracao/contrato/{id}` (`show()`) já
  devolve hoje (já carregado pelo form ao abrir, sem requisição extra):
  combo de modelos ainda não vinculados + botão. Ao escolher um
  modelo com `tp_modalidade==='parcela'` e `parcela_paga==='1'`, mostra
  radio "Todas"/"Específicas" antes do botão confirmar.
- Tabela de modelos **já processados** (têm `COMISSAO_LANCAMENTO`) — somente
  leitura, sem botão remover (trava da decisão 3).
- Modo "Específicas" escolhido → abre uma tabela (mesmas colunas da tela do
  ACADE VENDAS: checkbox, número, tipo, vencimento, valor da parcela, %
  comissão, valor comissão, comissão comprometida), carregada via o endpoint
  novo (ver C). Conversão %↔valor bidirecional por linha, mesmo padrão já
  usado em `comissaoFormulario.blade.php` pro campo de simulação
  (`desfazerMascaraMoeda()`/`mascaraMoeda()`).

### B) `ContratoController` — endpoints novos

- `GET administracao/contrato/{id}/comissao/{idParametroComissao}/parcelas`
  — devolve: dados do modelo (nome, modalidade, base calculada, valor total
  da comissão via `ComissaoCalculoService::calcularValorComissao()`) +
  parcelas elegíveis (`payment_date IS NULL`, status ≠ `cancelled`) com
  `comissao_comprometida` por linha (soma de `COMISSAO_PAGAMENTO.vl_comissao_parcela`
  de **outros** `COMISSAO_LANCAMENTO` do mesmo contrato — exclui o
  lançamento deste mesmo `id_parametro_comissao`, se já existir, pra permitir
  reedição sem contar a própria seleção anterior como "comprometida contra
  si mesma"). Se já existe `COMISSAO_LANCAMENTO` com esse
  `id_parametro_comissao`, devolve também a seleção já salva (pra UI reabrir
  preenchida).
- `POST administracao/contrato/{id}/comissao/{idParametroComissao}/processar`
  — body `{ tp_parcela_comissao: 'todas'|'especificas', parcelas?: [{id_parcela, valor}] }`.
  Servidor:
  1. `abort_if` contrato não tem `fl_gerado='1'` (esta rota só existe pro
     caso pós-geração — pré-geração continua pelo fluxo velho).
  2. Upsert do vínculo em `CONTRATO_PARAMETRO_COMISSAO` (não apaga os
     demais).
  3. Se já existe `COMISSAO_LANCAMENTO` pra esse `id_parametro_comissao`
     neste contrato → é reedição: apaga as `COMISSAO_PAGAMENTO` antigas
     desse lançamento antes de recriar (não cria um segundo lançamento).
  4. Calcula `vl_comissao_total` (mesma lógica de `instanciarComissoesDoContrato()`,
     extraída pra método privado reaproveitável pelos dois fluxos).
  5. Se `tp_parcela_comissao==='todas'`: roda `ComissaoCalculoService::ratear()`
     igual já faz hoje.
  6. Se `'especificas'`: valida cada linha do payload — `id_parcela`
     pertence a este contrato, está elegível (aberta), e
     `comissao_comprometida + valor_desta_linha ≤ valor_da_parcela`
     (422 se estourar, mensagem nomeando a parcela). Grava uma
     `COMISSAO_PAGAMENTO` por linha com o valor exato informado.
  7. Tudo dentro de uma `DB::connection('cliente')->transaction()`.
- `instanciarComissoesDoContrato()` (já existente) ganha a gravação de
  `id_parametro_comissao` no insert de `COMISSAO_LANCAMENTO` (linha `:774-785`) —
  único ajuste no código já existente, sem mudar comportamento.

### C) Pré-geração — sem mudança

`salvarComissoesContrato()`, `comissoesDisponiveis()`, `store()`/`update()`/`show()`
continuam exatamente como estão. A aba só reposiciona o HTML; o
comportamento pré-`fl_gerado` é o de hoje.

## Fora do escopo desta entrega

- Geração automática de Conta a Pagar (entrega C).
- Editar/remover um modelo **antes** de `fl_gerado` via a nova rotina
  pós-geração (continua pelo fluxo velho, "apaga tudo e recria").
- Reverter/desfazer processamento de um modelo já processado (trava
  permanente, decisão 3) — se precisar desfazer, é ajuste manual direto no
  banco por enquanto.
- Qualquer tratamento especial pra parcela com status `agreed` (negociada
  via Acordo) no picker de Específicas — tratada como não-elegível por ora
  (mesmo critério de "não é parcela aberta normal"); revisitar se um caso
  real aparecer.
- Mudar o relatório "Vendas > Relatórios > Comissão" ou a cláusula de
  corretagem do contrato "lotear-urb" — pendência documentada à parte em
  `.claude/rules/comissao.md`, não faz parte desta entrega.

## Arquivos que devem mudar (mapa inicial)

- `database/migrations/clientes/` — 1 migration nova: `id_parametro_comissao`
  + `tp_parcela_comissao` em `COMISSAO_LANCAMENTO`.
- `app/Services/Comissao/ComissaoCalculoService.php` — sem mudança de
  assinatura; reaproveitado como está.
- `app/Http/Controllers/Api/Administracao/ContratoController.php` —
  extrair cálculo de base/valor pra método privado reaproveitável; adicionar
  `parcelasComissaoEspecifica()`/`processarComissaoPosGeracao()` (nomes a
  confirmar na implementação); gravar `id_parametro_comissao` em
  `instanciarComissoesDoContrato()`.
- `resources/views/administracao/contratoFormulario.blade.php` — nova aba
  `tab-comissao` (HTML + JS), realocando a seção hoje em `tab-pessoa`.
- `routes/api.php` — 2 rotas novas sob `cliente.auth` (mesmo grupo de
  permissão de Contrato, sem role nova — é uma ação dentro do Contrato, não
  uma tela própria).
- `resources/lang/{pt,es,en}/administracao.php` — rótulos novos (aba,
  radio Todas/Específicas, colunas da tabela, mensagens de erro de
  validação).

## Testes (mínimo, a expandir na implementação)

- Vincular modelo novo (modalidade `venda`/`fixo`/`tabela`) com
  `fl_gerado='1'` processa imediatamente via "Todas" (fecha o vínculo morto).
- Vincular modelo `parcela` com `fl_gerado='1'` e `tp_parcela_comissao='todas'`
  produz o mesmo resultado que `ratear()` já produziria em `gerarParcelas()`.
- "Específicas": marcar 2 parcelas com valores manuais grava exatamente
  esses valores em `COMISSAO_PAGAMENTO`, nem mais nem menos.
- "Específicas" rejeita (422) quando a soma ultrapassa o valor de uma
  parcela individual, considerando comissão já comprometida por outro
  modelo.
- Reeditar uma seleção "Específicas" já salva substitui as linhas antigas,
  não duplica.
- Parcela paga não aparece na lista de elegíveis do picker.
- Modelo já processado não aparece mais como editável/removível na lista
  simples (trava da decisão 3).
