# Geração Automática de Conta a Pagar na Baixa de Comissão — Design

Entrega C do esforço maior "ROTINA: Administração - Contrato" (card externo,
9 itens — ver `.claude/rules/comissao.md` pro rastreador completo). Entregas
A (limpeza mecânica) e B (aba "Comissão" no Contrato + modo "Específicas")
já estão implementadas e commitadas (branch `cereuslote-124-comissao-ajustes`).
Este documento fecha o desenho da C: "gerar Conta a Pagar automaticamente
quando uma parcela com comissão associada for paga" — item explicitamente
deixado fora de escopo em B (`docs/superpowers/specs/2026-10-22-aba-comissao-contrato-especificas-design.md:107,212`).

## Pedido original

Quando uma parcela de contrato com comissão vinculada for recebida, o sistema
deve gerar automaticamente o lançamento correspondente em Contas a Pagar, pro
parceiro (corretor/imobiliária/indicador) — sem exigir lançamento manual do
operador.

## Referência consultada — ACADE VENDAS

Verificado a pedido do programador antes de desenhar (regra do projeto:
checar referência de implementação similar antes de construir algo novo).
`modulo/relatorio/controller/ParcelasComissaoPagarController.php` do
ACADE VENDAS **não gera Conta a Pagar nenhuma** — é um relatório (PDF/Excel)
que lista parcelas de comissão já pagas, agrupado por parceiro, pra alguém
processar o pagamento manualmente fora do sistema (`getParcelas()` +
`getParcelasHistorico()`, leitura pura). Não existe lá nenhum conceito de
"Contas a Pagar" automatizado — o card pede exatamente a automação que o
legado nunca teve.

Achado útil, mesmo sem ser um padrão de código a portar: o relatório agrupa
por `id_pessoa_parceiro`/`tipoParceiro` (mesmo campo que `COMISSAO_LANCAMENTO`
já usa) e tem uma opção de recalcular a comissão com base no valor
**efetivamente recebido** (`vl_comissao_parcela = porc_parcela * vl_total_pago
/ 100`) em vez do valor nominal da parcela — decisão explicitamente descartada
aqui (ver "Decisões de negócio" abaixo), em favor de reaproveitar o valor já
fixado pela entrega B.

O precedente técnico real usado neste desenho é interno ao próprio
cereusLote: `App\Services\Receivable\ReceivableService::gerarPayableIva()`
(card #12 de `rules/multi-pais.md`, já em produção) — mesmo choke point,
mesma filosofia de não bloquear a baixa da parcela por falta de configuração.

## Achados que moldaram o desenho

- **`COMISSAO_PAGAMENTO.id_parcela` aponta pra `receivables.id`** (confirmado
  lendo `ContratoController::instanciarComissoesDoContrato()` — `$parcela =
  $parcelasGeradas->firstWhere('id', $alocacao['id_parcela'])`, onde
  `$parcelasGeradas` vem de `receivables`). O valor da comissão por parcela
  (`vl_comissao_parcela`) já está fixado desde que a entrega B processou a
  alocação ("Todas" automático ou "Específicas" manual) — não precisa
  recalcular nada no momento do pagamento.
- **`parcela_paga='0'` (comissão "à vista") não gera nenhuma linha em
  `COMISSAO_PAGAMENTO`** — só `COMISSAO_LANCAMENTO.vl_comissao_total`, sem
  vínculo com parcela nenhuma. Isso exige um segundo caminho de geração,
  diferente do caso "paga por parcela".
- **`CONTRATO.fl_fm_pagamento` ("PC"/"AV"/"PM") é só um campo informativo**
  (confirmado por grep — gravado, exibido, importado, mas nunca lido por
  `gerarParcelas()`/`GeracaoParcelasService`) — "à vista" como forma de
  pagamento do contrato **não é o mesmo conceito** que `parcela_paga='0'` da
  comissão (são campos independentes, em tabelas diferentes). O que garante
  que todo contrato com comissão tem pelo menos 1 parcela real é outra coisa:
  `instanciarComissoesDoContrato()` só roda quando `$total > 0` (pelo menos 1
  segmento configurado — Normal/Sinal/Intercalada/Chave/Personalizada), e um
  contrato "à vista" de verdade é só um contrato com 1 segmento Normal
  (`nr_parcela=1`). Ou seja: **todo** contrato com comissão processada tem no
  mínimo 1 `receivable` real — confirmado lendo `ContratoController::gerarParcelas()`
  linha a linha, não por suposição.
- **`account_plans.code` tem constraint única** (`2026_08_04_100000_drop_client_id_from_financeiro_tables.php:106`,
  `$table->unique('code')`, aplicada depois que o drop de `client_id`
  confirmou não haver duplicata nos dados). O código `2.3.1` ("Comissões de
  Corretores e Imobiliárias") escolhido pro lançamento só existe depois que o
  tenant clica "Criar Plano Padrão" (`AccountPlanService::createDefaultAccountPlans()`)
  — **diferente** do padrão do IVA (`App\Support\IvaPayable`, código `9001`),
  que é semeado direto por migration, standalone, com um código reservado que
  nunca colide com a árvore opcional de ~180 contas. Semear `2.3.1` por
  migration do mesmo jeito colidiria com essa constraint única na primeira
  vez que o tenant clicasse "Criar Plano Padrão" — travando a criação do
  plano padrão inteiro com erro de duplicidade. Por isso `2.3.1` é resolvido
  só em runtime (consulta simples), nunca semeado.
- **`payables.receivable_id` já existe** (migration do card #12) — reaproveitado
  aqui como "qual parcela disparou a geração" (auditoria), mas **não é
  suficiente sozinho como chave de idempotência**: ao contrário do IVA (1
  parcela → no máximo 1 Payable de IVA), uma mesma parcela pode carregar
  comissão de **múltiplos** modelos/parceiros simultâneos
  (`CONTRATO_PARAMETRO_COMISSAO` é N:N) — por isso a chave de idempotência
  real precisa incluir também qual `COMISSAO_LANCAMENTO` gerou aquele Payable.

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

1. **Escopo do gatilho — os 2 casos de `parcela_paga`, ambos dentro do
   escopo desta entrega** (não só `='1'` como cogitado inicialmente):
   - `parcela_paga='1'`: 1 Payable por linha de `COMISSAO_PAGAMENTO`,
     disparado quando **aquela parcela específica** (`id_parcela =
     receivable.id`) é recebida.
   - `parcela_paga='0'` ("à vista", sem rateio): 1 Payable pelo valor
     total (`COMISSAO_LANCAMENTO.vl_comissao_total`), disparado na
     **primeira** parcela do contrato a ser recebida (qualquer uma — não
     precisa ser a cronologicamente mais cedo por vencimento, só a primeira
     que acontecer de verdade). Idempotente por `COMISSAO_LANCAMENTO.id`
     sozinho, pra não gerar de novo quando a 2ª parcela também for paga.
2. **Valor usado**: o já fixado em `COMISSAO_PAGAMENTO.vl_comissao_parcela`/
   `COMISSAO_LANCAMENTO.vl_comissao_total` — **sem recalcular** com base no
   valor efetivamente recebido na baixa (descarta a opção do ACADE VENDAS).
   Consistente com o que a entrega B já gravou e exibe na tela.
3. **Sem backfill retroativo** — mesma decisão já tomada pro IVA (card #12).
   Contrato com parcela já paga ANTES desta feature existir não gera Conta a
   Pagar retroativamente; se precisar do que ficou pra trás, é caso a caso.
4. **Plano de contas**: reaproveita o código `2.3.1` já semeado na estrutura
   padrão opcional — resolvido em runtime, **sem semear nada por migration**
   (ver achado acima sobre a constraint única). Se o tenant ainda não clicou
   "Criar Plano Padrão", a geração não acontece — só loga, mesmo tratamento
   do item 5 abaixo — até o plano existir.
5. **Credor ausente** (`COMISSAO_LANCAMENTO.id_pessoa_parceiro` é nullable):
   mesmo padrão do IVA — não bloqueia a baixa, só loga (`Log::warning`) — mais
   aviso visual na tela (ver "Fluxo" abaixo).
6. **Estorno de recebimento**: **não desfaz** o Payable de comissão já
   gerado — mesmo comportamento (e mesmo gap já documentado/aceito) do IVA
   hoje. Não implementar lógica de cancelamento automático nesta entrega.
7. **Datas do Payable** (`due_date`/`issue_date`/`competence_date`): data do
   recebimento da parcela que disparou — mesmo padrão do IVA, sem regra de
   prazo própria de repasse de comissão.
8. **Avisos visuais**: dois, ambos na aba "Comissão" do Contrato (ver
   "Fluxo"), não um endpoint global como `ivaStatus()` — a granularidade aqui
   é por modelo/lançamento (parceiro configurado ou não) e por tenant (plano
   de contas existe ou não), não uma condição global só.

## Modelo de dados

### `payables` — 1 coluna nova (migration `ALTER`)

```php
Schema::connection('cliente')->table('payables', function (Blueprint $table) {
    $table->unsignedBigInteger('comissao_lancamento_id')->nullable()->index()->after('receivable_id');
});
```

Sem FK (mesmo padrão de `receivable_id`/`contract_id` — schema legado sem FK
real nas tabelas que `payables` referencia). Guarda `COMISSAO_LANCAMENTO.id`
que originou o lançamento. Combinado com `receivable_id` (já existente, do
IVA) para a chave de idempotência do caso 1; sozinho, para o caso 2.

`App\Models\Payable::$fillable` ganha `'comissao_lancamento_id'`.
`PayableService::create()` precisa ler essa chave **no array explícito do
insert**, não só confiar no `$fillable` — repetir esse erro seria reproduzir
o bug real já corrigido no card #12 (`receivable_id` estava em `$fillable`
mas ausente do array de `create()`, quebrando a idempotência em silêncio até
ser pego testando de ponta a ponta).

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

Os dois casos já leem dados que a entrega B deixou prontos
(`id_pessoa_parceiro`, `vl_comissao_parcela`, `vl_comissao_total`,
`parcela_paga`).

## Fluxo

### A) `App\Support\ComissaoPayable` (novo — espelha `IvaPayable`)

```php
class ComissaoPayable
{
    private const ACCOUNT_PLAN_CODE = '2.3.1';

    public static function accountPlanId(): ?int
    {
        return DB::connection('cliente')->table('account_plans')
            ->where('code', self::ACCOUNT_PLAN_CODE)
            ->value('id');
    }
}
```

Sem `credorPersonId()` (diferente do IVA) — o credor aqui varia por
lançamento (`id_pessoa_parceiro`), não é um valor único por tenant.

### B) `ReceivableService` — novo método privado, chamado de `registrarMovimento()`

```php
private function registrarMovimento(Receivable $receivable, string $type): void
{
    if ($this->financialMovementService->createFromReceivable($receivable, $type)) {
        if ($type === 'receita') {
            $this->gerarPayableIva($receivable);
            $this->gerarPayableComissao($receivable);
        }
        return;
    }
    // ...
}

private function gerarPayableComissao(Receivable $receivable): void
{
    if ($receivable->type !== ParcelaReceivable::TYPE) {
        return;
    }

    $accountPlanId = ComissaoPayable::accountPlanId();
    if (!$accountPlanId) {
        Log::warning('Payable de comissão não gerado: plano de contas 2.3.1 ainda não existe (Criar Plano Padrão pendente).', [
            'receivable_id' => $receivable->id,
            'database' => DB::connection('cliente')->getDatabaseName(),
        ]);
        return;
    }

    // Caso 1: comissão paga por parcela — alocações desta parcela específica.
    $alocacoes = DB::connection('cliente')->table('COMISSAO_PAGAMENTO')
        ->join('COMISSAO_LANCAMENTO', 'COMISSAO_LANCAMENTO.id', '=', 'COMISSAO_PAGAMENTO.id_comissao_lanc')
        ->where('COMISSAO_PAGAMENTO.id_parcela', $receivable->id)
        ->get([
            'COMISSAO_LANCAMENTO.id as id_comissao_lanc',
            'COMISSAO_LANCAMENTO.id_pessoa_parceiro',
            'COMISSAO_PAGAMENTO.vl_comissao_parcela as valor',
        ]);

    foreach ($alocacoes as $alocacao) {
        $this->criarPayableComissao(
            $receivable, $accountPlanId, $alocacao->id_comissao_lanc,
            $alocacao->id_pessoa_parceiro, (float) $alocacao->valor,
            exigirMesmaParcela: true
        );
    }

    // Caso 2: comissão "à vista" — dispara na 1ª parcela paga do contrato.
    $lancamentosAVista = DB::connection('cliente')->table('COMISSAO_LANCAMENTO')
        ->where('id_contrato', $receivable->contract_id)
        ->where('parcela_paga', '0')
        ->get(['id', 'id_pessoa_parceiro', 'vl_comissao_total']);

    foreach ($lancamentosAVista as $lancamento) {
        $this->criarPayableComissao(
            $receivable, $accountPlanId, $lancamento->id,
            $lancamento->id_pessoa_parceiro, (float) $lancamento->vl_comissao_total,
            exigirMesmaParcela: false
        );
    }
}

private function criarPayableComissao(
    Receivable $receivable, int $accountPlanId, int $idLancamento,
    ?int $personId, float $valor, bool $exigirMesmaParcela
): void {
    if ($valor <= 0) {
        return;
    }

    // Idempotência: caso 1 é por (lançamento, parcela) — o mesmo lançamento
    // pode gerar um Payable por parcela que recebeu alocação. Caso 2 é só
    // por lançamento — só pode existir 1 Payable no total, não importa qual
    // parcela do contrato disparou.
    $existeQuery = Payable::where('comissao_lancamento_id', $idLancamento);
    if ($exigirMesmaParcela) {
        $existeQuery->where('receivable_id', $receivable->id);
    }
    if ($existeQuery->exists()) {
        return;
    }

    if (!$personId) {
        Log::warning('Payable de comissão não gerado: parceiro não configurado.', [
            'id_comissao_lancamento' => $idLancamento,
            'receivable_id' => $receivable->id,
        ]);
        return;
    }

    $payable = $this->payableService->create([
        'person_id' => $personId,
        'account_plan_id' => $accountPlanId,
        'receivable_id' => $receivable->id,
        'comissao_lancamento_id' => $idLancamento,
        'title' => __('receivables.messages.comissao_payable_title', ['code' => $receivable->code]),
        'type' => 'simple',
        'original_amount' => $valor,
        'discount' => 0,
        'additions' => 0,
        'penalty_amount' => 0,
        'interest_amount' => 0,
        'payment_date' => null,
        'issue_date' => $receivable->payment_date ?? now()->toDateString(),
        'competence_date' => $receivable->competence_date ?? ($receivable->payment_date ?? now()->toDateString()),
        'due_date' => $receivable->payment_date ?? now()->toDateString(),
    ]);

    if (!$payable) {
        Log::warning('Payable de comissão não gerado: falha de validação no PayableService.', [
            'id_comissao_lancamento' => $idLancamento,
            'receivable_id' => $receivable->id,
            'errors' => $this->payableService->getErrors(),
        ]);
    }
}
```

### C) `ContratoController::show()` — avisos visuais (sem endpoint novo)

A query de `$comissoes` (já existente, entrega B) ganha `id_pessoa_parceiro`
no `select` e deriva `parceiro_configurado` no `map()`. A resposta de `show()`
ganha um flag irmão de `comissoes`:

```php
'comissao_plano_contas_configurado' => ComissaoPayable::accountPlanId() !== null,
```

### D) Frontend (`contratoFormulario.blade.php`, aba Comissão)

- Banner único (`#avisoComissaoPlanoContas`), visível quando
  `comissao_plano_contas_configurado === false` — avisa que nenhuma Conta a
  Pagar de comissão será gerada até o tenant criar o Plano de Contas padrão
  (Financeiro > Plano de Contas).
- Por linha de modelo na lista de comissões (pré e pós-geração), um ícone/
  badge de aviso quando `parceiro_configurado === false` — mesmo texto
  conceitual do aviso de IVA, adaptado pro contexto de comissão.
- 2 chaves de idioma novas (`administracao.comissao_sem_parceiro_aviso`,
  `administracao.comissao_sem_plano_contas_aviso`), 3 idiomas.

## Fora do escopo desta entrega

- **Saldo não alocado do modo "Todas"** (`instanciarComissoesDoContrato()`/
  `processarComissaoPosGeracao()`, aviso `comissao_nao_coube_nas_parcelas`
  quando o % limite por parcela não comporta o valor inteiro) nunca vira
  Payable — só existe `COMISSAO_PAGAMENTO` pro que foi de fato alocado, e o
  caso 1 só lê essas linhas. Isso é herdado da entrega B (saldo sem alocar já
  é avisado na tela como está), não um gap novo desta entrega. O modo
  "Específicas" não tem esse problema — a regra "soma informada = valor
  total" já garante alocação integral.
- **Cancelamento automático do Payable no estorno de recebimento** — decisão
  explícita (item 6 acima). Mesmo gap do IVA, não resolvido aqui.
- **Prazo de repasse diferenciado** (ex.: vencimento X dias após o
  recebimento) — datas seguem a data do recebimento, sem regra própria.
- **Plano de contas configurável por modelo de comissão** — todo lançamento
  usa o mesmo código fixo `2.3.1`.
- **Backfill retroativo** de contratos com parcela já paga antes desta
  feature existir.
- **Qualquer mudança no cálculo/rateio de comissão em si** (`ComissaoCalculoService`,
  `instanciarComissoesDoContrato()`, `processarComissaoPosGeracao()`) — esta
  entrega só consome o valor já fixado, não recalcula nada.

## Arquivos que devem mudar (mapa inicial)

- `database/migrations/clientes/2026_10_22_*_add_comissao_lancamento_id_to_payables_table.php` (nova)
- `app/Models/Payable.php` (`$fillable`)
- `app/Services/Payable/PayableService.php` (`create()` — array explícito)
- `app/Support/ComissaoPayable.php` (novo)
- `app/Services/Receivable/ReceivableService.php` (`registrarMovimento()`,
  `gerarPayableComissao()`, `criarPayableComissao()` novos)
- `app/Http/Controllers/Api/Administracao/ContratoController.php` (`show()`
  — `$comissoes` + flag novo)
- `resources/views/administracao/contratoFormulario.blade.php` (aba
  Comissão — 2 avisos novos)
- `resources/lang/{pt,en,es}/administracao.php` (2 chaves novas)
- `resources/lang/{pt,en,es}/receivables.php` (`comissao_payable_title`)

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

- Caso 1: parcela paga gera Payable com o valor exato de `COMISSAO_PAGAMENTO`;
  reabrir/pagar de novo (estorno + recebe de novo) não duplica.
- Caso 2: primeira parcela paga do contrato gera 1 Payable pelo total; pagar
  a 2ª parcela não gera outro.
- Múltiplos modelos/parceiros no mesmo contrato geram Payables independentes
  (um por `comissao_lancamento_id`), inclusive quando a mesma parcela carrega
  alocação de mais de um modelo (caso 1).
- Sem plano de contas `2.3.1`: não gera nada, loga, não quebra a baixa da
  parcela.
- Sem `id_pessoa_parceiro`: não gera nada, loga, não quebra a baixa da
  parcela.
- `show()` devolve `parceiro_configurado=false` pro modelo sem parceiro e
  `comissao_plano_contas_configurado=false` quando o código `2.3.1` não
  existe.
- Parcela que não é `type=parcela_contrato` (fora do escopo de contrato) não
  aciona nada.
