# Cadastro de Comissão + Aplicação no Contrato — Design

Card Trello #105 (branch `cereuslote-105-cadastro-comissao`). Referência: módulo
`comissao/cadastroComissao` do ACADE VENDAS (telas/código citados no card original,
análise somente leitura). Pedido do cliente: montar a comissão num cadastro próprio
e escolher essa comissão na hora de fazer o contrato (Administração → Contrato).

## Achados que mudaram o escopo em relação ao card original

- A estrutura de tabelas (`COMISSAO_LANCAMENTO`/`COMISSAO_PAGAMENTO`) já existe e
  tem CRUD, mas é **crua**: `vendas/comissaoFormulario.blade.php` (135 linhas) expõe
  os campos do banco como inputs soltos — nenhuma parte do motor de cálculo do
  ACADE VENDAS (4 modalidades, conversão bidirecional %↔R$, rateio por parcela,
  modal "Adicionar parceiro") foi portada. O trabalho real está em construir esse
  motor, não só "ligar o que já existe".
- Tanto o ACADE VENDAS quanto o CRUD já portado exigem **contrato já existente**
  pra criar uma comissão — o oposto do que o cliente pediu ("montar antes, escolher
  depois"). Confirmado com o programador: seguimos o pedido do cliente, não o
  comportamento literal da referência.
- `PARAMETRO_COMISSAO` (tabela já existente, pensada como "plano de comissão por
  empreendimento") está **100% órfã** — nenhum código além do próprio CRUD morto a
  lê (confirmado por grep). Zero risco de reaproveitá-la.
- `CONTRATO.id_parametro_comissao` já existe no banco e no `$fillable` do model,
  mas está morta (não validada, não lida/gravada em lugar nenhum) — é o gancho
  original pensado pra isso, mas **não serve mais** depois da decisão de permitir
  múltiplos parceiros por contrato (ver abaixo) — fica morta, documentar o motivo.
- `ComissaoPagamento::parcela()` tem relação Eloquent quebrada
  (`belongsTo(Parcela::class, 'id_parcela', 'id_parcela_contrato')` — a coluna
  `id_parcela_contrato` não existe em `receivables`/`Parcela`). Precisa de correção
  como parte desta entrega, já que o algoritmo de rateio depende de consultar
  comissão já comprometida por parcela.

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

1. **Fluxo desacoplado do contrato** — a comissão é montada livremente (sem exigir
   contrato, e sem exigir empreendimento — ver item 2) e só depois vinculada a um
   ou mais contratos.
2. **Empreendimento é opcional no cadastro de comissão** — não trava a criação, e
   **não filtra** o combo de comissões disponíveis no Contrato. Qualquer comissão
   cadastrada no tenant pode ser escolhida em qualquer contrato, independente do
   empreendimento do contrato. (Decisão corrigida depois da primeira proposta, que
   exigia empreendimento — o cliente apontou que isso geraria duplicação de
   comissões iguais por empreendimento.)
3. **Todas as 4 modalidades de cálculo entram**: Total Venda (%), Valor Fixo (R$),
   Tipo Parcela (%), Tabela de Preço (%).
4. **Das 2 formas de pagamento, só "sobre parcelas" (rateio automático) entra**
   nesta entrega. "Específicas" (marcar parcelas e valor manualmente) fica de fora
   — só faz sentido com o contrato já existente, e o fluxo aqui é desacoplado.
5. **Múltiplos parceiros de comissão por contrato** (decisão corrigida depois da
   proposta original, que previa só 1). Implica tabela pivot nova, não dá mais pra
   usar `CONTRATO.id_parametro_comissao` (FK simples).
6. **Sem calculadora bidirecional %↔R$ com valor real** no cadastro da comissão
   (não existe contrato/valor real nesse momento). Em troca, um campo de
   "simulação" — valor hipotético digitado à mão, só client-side, nunca
   persistido — que alimenta a mesma lógica de conversão %↔R$ só pra conferência.
7. **Aviso informativo (não bloqueia)** quando o limite de comissão por parcela
   configurado não é suficiente pra fechar o valor total da comissão dentro das
   parcelas geradas do contrato. Sobra sem distribuir, sistema só avisa.
8. **Sem geração automática de Contas a Pagar pro parceiro** — diferente do padrão
   usado no IVA do Paraguai. O cliente não pediu isso aqui; a comissão fica só
   registrada (`COMISSAO_LANCAMENTO`/`COMISSAO_PAGAMENTO}`), pagar o parceiro de
   fato continua manual, fora deste fluxo.
9. **Moeda segue o padrão já estabelecido** (`CurrencyConfig`/`formatarMoeda()`,
   dinâmico por país do tenant) — mesmo mecanismo já usado no IVA.
10. **Divergência aritmética nos prints de referência do card original** (soma
    visível R$176 vs rodapé R$500) — não se aplica, não estamos clonando a tela
    de referência pixel a pixel.

## Modelo de dados

### `PARAMETRO_COMISSAO` — colunas novas (migration `ALTER`)

As colunas antigas (`tp_comissao`, `tp_local_insidencia`, `vl_corretor` etc.) são
de um conceito diferente (split fixo por papel) e continuam existindo — a tabela
é órfã, não vou apagar nada nela, só adicionar. **Correção pós-implementação
(Task 1, 20/10/2026):** quatro delas (`id_empreendimento`, `tp_comissao`,
`tp_local_insidencia`, `qt_parcela_comissao`) são `NOT NULL` sem default no
schema original (`create_PARAMETRO_COMISSAO_table`) e o form novo não as
preenche — "intocadas" valia pro dado, não pro `NULL`/`NOT NULL`: a mesma
migration as torna nullable via `DB::statement('ALTER TABLE ... MODIFY ...')`
(sem `->change()`, `doctrine/dbal` não instalado), sem precisar de migration à
parte — ver nota sobre `id_empreendimento` logo abaixo, também desatualizada.

- `id_parceiro` (`PESSOA.id`, nullable) — o parceiro/imobiliária.
- `id_pessoa_parceiro` (`PESSOA.id`, nullable) — pessoa de contato do parceiro.
  Mesma semântica (e mesmo padrão de busca) já usada em
  `vendas/comissaoFormulario.blade.php` (`buscaPessoa()`), não a semântica descrita
  no card original (que tratava `id_parceiro` como "tipo" — confirmado que a versão
  já portada no Cereus Lote usa os dois como pessoa real).
- `tp_modalidade` (string: `venda`|`fixo`|`parcela`|`tabela`).
- `porc_venda`, `vl_fixo`, `porc_parcela`, `tp_parcela` (`N`/`S`/`I`/`C`,
  mesmo domínio de `installment_category`), `id_tabela_preco` — um preenchido por
  vez, conforme `tp_modalidade`.
- `parcela_paga` (`'0'` à vista / `'1'` sobre parcelas).
- `pc_limite_parcela` (decimal, nullable) — só relevante quando `parcela_paga='1'`;
  é o "% limite por parcela" do algoritmo de rateio.

`id_empreendimento` (coluna já existente): confirmado `NOT NULL` no schema
físico — a mesma migration de Task 1 a torna `NULL` (não precisou de migration
à parte, ver correção acima).

### Tabela nova — `CONTRATO_PARAMETRO_COMISSAO` (pivot N:N)

- `id` (PK, auto-incremento)
- `id_contrato` (`CONTRATO.id`)
- `id_parametro_comissao` (`PARAMETRO_COMISSAO.id_parametro_comissao`)
- Sem FK real (schema legado, mesmo padrão do resto do projeto)
- **Índice único** em `(id_contrato, id_parametro_comissao)`, nome explícito
  curto (`ux_contrato_parametro_comissao` — o nome gerado por convenção do
  Laravel estoura o limite de 64 caracteres do MySQL). Substitui o índice
  simples cogitado inicialmente: além de cobrir a mesma busca por
  `id_contrato` (prefixo à esquerda), impede o mesmo modelo de comissão ser
  vinculado duas vezes ao mesmo contrato — sem essa garantia, um payload com
  o mesmo id repetido geraria `COMISSAO_LANCAMENTO` em dobro (achado do task
  review da Task 2, 20/10/2026).
- Sem coluna de ordem explícita — a ordem "em que foi adicionado" (usada no
  algoritmo de rateio, seção D) é a ordem de inserção, lida por `id` ascendente
  (auto-incremento já preserva isso, mesmo padrão implícito de outras listas desse
  controller, ex. `CONTRATO_PESSOA`).

### `CONTRATO.id_parametro_comissao`

Continua **morta** — decisão 5 (múltiplos parceiros) inviabiliza usar uma FK
simples. Não validar, não exibir, não gravar. Documentar o motivo em
`rules/backend.md` ou comentário na migration, pra não confundir sessão futura que
veja essa coluna e ache que é só "terminar de ligar".

### `COMISSAO_LANCAMENTO` / `COMISSAO_PAGAMENTO`

Sem mudança de schema — já têm os campos certos pro que esta entrega precisa.
Corrigir `ComissaoPagamento::parcela()` (relação quebrada, ver achados acima) antes
de depender dela no cálculo de comprometimento.

## Fluxo

### A) Cadastro de Comissão (tela nova, Administração)

- Rotas web: `administracao/comissao`, `.../comissao/add`, `.../comissao/{id?}`
  (mesmo padrão de `administracao/contrato`).
- Form: Nome do modelo (`nm_parametro_comissao`), Empreendimento (opcional),
  Parceiro + Pessoa de contato (busca, reaproveitando `buscaPessoa()` de
  `comissaoFormulario.blade.php`), seletor de modalidade (toggle dos 4 blocos de
  campo, mesmo padrão de toggle já usado em `account-plans/form.blade.php`), forma
  de pagamento (+ campo "% limite por parcela" quando "sobre parcelas"), campo de
  simulação (client-side, nunca enviado no payload).
- API CRUD nova (molde de `ParametroComissaoController`), validando os campos
  novos.
- Permissão nova — **não reaproveitar** "Comissão"/"Listar Comissão" (já são do
  módulo Vendas, roles distintas). Seed em `database/migrations/geral`.
- Menu novo no bloco Administração da sidebar + traduções pt/es/en.

### B) Aplicar no Contrato

- Nova seção "Parceiros de Comissão" em `contratoFormulario.blade.php` — mesmo
  padrão de UI já usado pra Co-compradores nesse arquivo (busca → adiciona numa
  lista → remove). Avaliar na implementação se fica na aba Informações Básicas ou
  numa aba própria.
- Endpoint novo `GET administracao/contrato/comissoesDisponiveis` — lista **todas**
  as comissões do tenant (`PARAMETRO_COMISSAO.tp_modalidade IS NOT NULL` — não há
  coluna de status/ativo nesta tabela, "todas" significa isso mesmo, sem filtro
  de empreendimento (decisão 2). Correção de terminologia (task review da Task 7,
  20/10/2026): "ativas" sugeria um campo de status que não existe.
- `store()`/`update()`: salva a lista em `CONTRATO_PARAMETRO_COMISSAO`, mesmo
  padrão "apaga tudo e recria" de `salvarCoCompradores()`/
  `salvarTiposParcelaPersonalizados()`/`salvarSinais()` já usados nesse controller.
- `show()`: devolve a lista de comissões já vinculadas (id + nome) pra tela reabrir
  preenchida.

### C) Instanciação no `gerarParcelas()`

Mesmo hook já usado pro cálculo do IVA (`ContratoController::gerarParcelas()`).
Para cada `PARAMETRO_COMISSAO` vinculado ao contrato, na ordem em que foi
adicionado:

1. Calcula a base conforme `tp_modalidade`:
   - `venda` → `Contrato::calcularValorTotal()` (valor total do contrato).
   - `fixo` → `vl_fixo` é o próprio total, sem cálculo.
   - `parcela` → soma das parcelas reais geradas do `tp_parcela` escolhido.
   - `tabela` → valor da tabela de preço do lote (confirmar tabela/coluna exata na
     implementação — não deve mudar o desenho).
2. Cria 1 `COMISSAO_LANCAMENTO` (`vl_comissao_total` calculado, parceiro/pessoa
   copiados do modelo).
3. Se `parcela_paga='1'`: roda o algoritmo de rateio (seção D) contra as parcelas
   reais já geradas.

### D) Algoritmo de rateio ("Todas até completar", com comprometimento real)

Precisa considerar que múltiplas comissões do mesmo contrato podem disputar a
mesma parcela (decisão 5). Para cada `PARAMETRO_COMISSAO` com `parcela_paga='1'`,
na ordem em que foi vinculado ao contrato, e para cada parcela em ordem de
vencimento:

1. `comprometido_na_parcela` = soma de `COMISSAO_PAGAMENTO.vl_comissao_parcela` já
   gravado pra aquela parcela (de outras comissões do mesmo contrato, já
   processadas antes nesta mesma chamada).
2. Teto disponível = `vl_parcela − comprometido_na_parcela`.
3. Valor a alocar = `min(vl_parcela × pc_limite_parcela / 100, teto_disponível,
   saldo_restante_da_comissao_atual)`.
4. Grava `COMISSAO_PAGAMENTO`, abate do saldo restante da comissão atual.
5. Para quando o saldo da comissão atual chegar a zero.
6. Se todas as parcelas acabarem e sobrar saldo não alocado: inclui aviso
   informativo na resposta de `gerarParcelas()` (mesmo JSON que já devolve
   `total_parcelas`) — não bloqueia a geração.

A ordem de adição das comissões no contrato afeta quem "pega primeiro" o espaço de
cada parcela — comportamento esperado, consistente com a lógica de "comprometido"
do próprio ACADE VENDAS (sempre relativo ao que já foi lançado antes).

## Fora do escopo desta entrega (confirmado)

- Modalidade de pagamento "Específicas" (ajuste manual por parcela).
- Conversão %↔R$ com valor real na tela de cadastro (só a simulação manual).
- Geração automática de Contas a Pagar pro parceiro.
- Edição manual pós-geração do rateio (ajustar uma parcela específica depois de já
  gerada) — fica pra entrega futura se pedido.
- Mais de 1 "modelo de comissão" reutilizado em paralelo por vários contratos ao
  mesmo tempo com valores diferentes por contrato — cada vínculo
  `CONTRATO_PARAMETRO_COMISSAO` aponta pro mesmo modelo, que é recalculado contra
  os dados reais de cada contrato (não há "cópia" do modelo, é sempre o mesmo
  registro-fonte sendo lido).

## Arquivos que devem mudar (mapa inicial — confirmar file:line na implementação)

- `database/migrations/clientes/` — 2 migrations novas: colunas em
  `PARAMETRO_COMISSAO`, tabela `CONTRATO_PARAMETRO_COMISSAO`.
- `app/Models/Vendas/ParametroComissao.php` — `$fillable` novo.
- `app/Models/Vendas/ComissaoPagamento.php` — corrigir `parcela()`.
- `app/Http/Controllers/Api/Vendas/ParametroComissaoController.php` (ou controller
  novo em Administração, a decidir na implementação) — CRUD da comissão.
- `app/Http/Controllers/Api/Administracao/ContratoController.php` — endpoint
  `comissoesDisponiveis`, `salvarComissoes()` (padrão `salvarCoCompradores()`),
  wiring em `store()`/`update()`/`show()`/`gerarParcelas()`.
- `resources/views/administracao/comissao.blade.php` /
  `comissaoFormulario.blade.php` (novos).
- `resources/views/administracao/contratoFormulario.blade.php` — seção "Parceiros
  de Comissão".
- `routes/web.php`, `routes/api.php` — rotas novas.
- `resources/views/partials/sidebar.blade.php` + `resources/lang/{pt,es,en}/menu.php`
  — menu novo.
- `database/migrations/geral/` — seed de permissão nova.
- `resources/lang/{pt,es,en}/administracao.php` (ou arquivo de tradução próprio) —
  rótulos da tela nova.

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

- Cada uma das 4 modalidades calcula `vl_comissao_total` corretamente contra um
  contrato real.
- Rateio "sobre parcelas" com 1 comissão fecha exatamente o total dentro das
  parcelas (ou avisa quando não fecha).
- Rateio com 2+ comissões no mesmo contrato respeita o comprometimento já gravado
  pela comissão processada antes.
- Comissão sem empreendimento aparece no combo de qualquer contrato, de qualquer
  empreendimento.
