# Aba "Comissão" no Contrato + Modo "Específicas" Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use subagent-driven-development (recommended) or executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Dar ao Contrato uma aba própria "Comissão" (depois de "Parcela") e, pra comissões do tipo "Tipo de Parcela (%)", permitir escolher entre rateio automático ("Todas", já existente) ou marcação manual parcela a parcela ("Específicas") — incluindo fechar a lacuna onde vincular um modelo de comissão depois de gerar parcela hoje não tem efeito nenhum.

**Architecture:** Reaproveita o schema já existente (`COMISSAO_LANCAMENTO`/`COMISSAO_PAGAMENTO`/`CONTRATO_PARAMETRO_COMISSAO`), só com 2 colunas novas em `COMISSAO_LANCAMENTO` pra rastreio. Toda a lógica nova vive em `ContratoController` (2 endpoints novos: listar parcelas elegíveis pra um modelo, e processar — Todas ou Específicas — pós-geração), reaproveitando `ComissaoCalculoService` sem alterá-lo. O fluxo pré-geração (`salvarComissoesContrato()`/`store()`/`update()`) não muda nada.

**Tech Stack:** Laravel 10 (PHP), Blade + jQuery (sem build step), MySQL (schema legado `CONTRATO`/`COMISSAO_LANCAMENTO`/`receivables`), PHPUnit com fixture sqlite `:memory:` (mesmo padrão dos testes já existentes nesta área).

**Spec:** `docs/superpowers/specs/2026-10-22-aba-comissao-contrato-especificas-design.md`

## Global Constraints

- Aba "Comissão" só existe em modo edição (`@if($id)`), posicionada depois de "Parcela" no `contratoFormulario.blade.php`.
- Antes de `fl_gerado='1'`: **nada muda** — a seção de vincular modelos continua exatamente como está hoje (`salvarComissoesContrato()`, `store()`/`update()`/`show()` intocados), só realocada de aba.
- Depois de `fl_gerado='1'`: vincular um modelo novo é uma ação própria com processamento imediato (endpoint novo), nunca mais um vínculo morto.
- Sub-seletor "Todas"/"Específicas" só aparece quando `tp_modalidade='parcela'` E `parcela_paga='1'`. Fora disso (outras modalidades, ou `parcela_paga='0'`), processa sempre via "Todas" sem perguntar.
- **Elegibilidade de parcela pra alocação (Todas OU Específicas) no fluxo pós-geração**: só parcela com `payment_date IS NULL` e `status != 'cancelled'`. Isso vale pros dois modos — não é exclusividade de "Específicas". A BASE de cálculo da comissão (quando a modalidade é `'parcela'`, soma de `original_amount` por `tp_parcela`) continua somando TODAS as parcelas daquele tipo (pagas ou não) — só a fase de ALOCAÇÃO (quem recebe o quê) é que filtra por elegibilidade. Esse detalhe não estava explícito na spec original; é extensão natural da regra "parcela paga não entra no modo Específicas" já aprovada, aplicada de forma consistente aos dois modos.
- Trava dura (422), nunca só aviso, se a soma de comissão já comprometida numa parcela + nova alocação ultrapassar o `original_amount` dessa parcela.
- Reprocessar um modelo já processado (reabrir "Específicas", ou rodar o endpoint de novo) substitui as linhas de `COMISSAO_PAGAMENTO` daquele `COMISSAO_LANCAMENTO` — nunca duplica.
- Tudo dentro de `DB::connection('cliente')->transaction()`.
- Moeda: usar `CurrencyConfig::format()`/`formatarMoeda()`/`mascaraMoeda()` (padrão já estabelecido no projeto), nunca hardcode de símbolo.
- Sem geração de Conta a Pagar (fora de escopo — entrega C, não desenhada ainda).
- **Lembrete de ambiente**: não existe `npm run build`/Vite neste projeto — mudança de frontend é só editar o `.blade.php` direto, sem build step. Para rodar `php artisan test`, use sempre `--filter`/caminho de arquivo específico — não existe suíte completa segura neste projeto (alguns testes usam banco real).

## Task 1: Migration — rastreio de origem e modo em `COMISSAO_LANCAMENTO`

**Files:**
- Create: `database/migrations/clientes/2026_10_22_150000_add_parametro_comissao_tracking_to_comissao_lancamento_table.php`

**Interfaces:**
- Produces: colunas `COMISSAO_LANCAMENTO.id_parametro_comissao` (integer, nullable) e `COMISSAO_LANCAMENTO.tp_parcela_comissao` (string(15), nullable, valores `'todas'`/`'especificas'`) — consumidas pelas Tasks 2-4.

- [ ] **Step 1: Escrever a migration**

```php
<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;

// Entrega B (aba "Comissão" no Contrato + modo "Específicas") — ver
// docs/superpowers/specs/2026-10-22-aba-comissao-contrato-especificas-design.md.
// id_parametro_comissao rastreia qual modelo originou o lançamento (hoje não dá
// pra saber — COMISSAO_LANCAMENTO é um snapshot dos campos do modelo no momento
// da geração, sem nenhuma coluna de volta pro PARAMETRO_COMISSAO de origem).
// tp_parcela_comissao guarda se o lançamento foi rateado automaticamente
// ('todas') ou marcado manualmente parcela a parcela ('especificas'). Sem FK
// real (schema legado, mesmo padrão do resto do projeto).
return new class extends Migration
{
    public function up(): void
    {
        Schema::connection('cliente')->table('COMISSAO_LANCAMENTO', function (Blueprint $table) {
            if (!Schema::connection('cliente')->hasColumn('COMISSAO_LANCAMENTO', 'id_parametro_comissao')) {
                $table->integer('id_parametro_comissao')->nullable()->after('id_contrato');
            }
            if (!Schema::connection('cliente')->hasColumn('COMISSAO_LANCAMENTO', 'tp_parcela_comissao')) {
                $table->string('tp_parcela_comissao', 15)->nullable()->after('parcela_paga');
            }
        });
    }

    public function down(): void
    {
        Schema::connection('cliente')->table('COMISSAO_LANCAMENTO', function (Blueprint $table) {
            if (Schema::connection('cliente')->hasColumn('COMISSAO_LANCAMENTO', 'tp_parcela_comissao')) {
                $table->dropColumn('tp_parcela_comissao');
            }
            if (Schema::connection('cliente')->hasColumn('COMISSAO_LANCAMENTO', 'id_parametro_comissao')) {
                $table->dropColumn('id_parametro_comissao');
            }
        });
    }
};
```

- [ ] **Step 2: Backfill pra contrato com 1 única comissão já processada antes desta migration**

**Achado que motiva este step**: o endpoint novo da Task 4 identifica "modelo já processado neste contrato" por `id_parametro_comissao` (coluna que não existia até agora). Sem backfill, todo `COMISSAO_LANCAMENTO` já gravado antes desta migration ficaria com essa coluna `NULL` — o endpoint trataria esses modelos como "nunca processados" e criaria um **segundo** `COMISSAO_LANCAMENTO` pro mesmo par contrato+modelo na primeira vez que alguém usasse a aba nova num contrato antigo, duplicando a comissão de verdade. Adicionar ao `up()`, depois do `Schema::table(...)` acima:

```php
        // Backfill só pro caso inequívoco: contrato com exatamente 1 comissão
        // vinculada (CONTRATO_PARAMETRO_COMISSAO) e exatamente 1 lançamento já
        // gerado (COMISSAO_LANCAMENTO) pra esse contrato — só então dá pra
        // casar os dois sem ambiguidade. Contrato com múltiplas comissões
        // concorrentes no mesmo contrato (vários vínculos) fica com
        // id_parametro_comissao NULL nos lançamentos antigos — não dá pra
        // inferir com segurança qual lançamento veio de qual modelo só pelos
        // campos copiados (podem colidir entre si). Limitação conhecida e
        // aceita: feature tem 2 dias de vida (20/10/2026), uso real esperado
        // baixo o bastante pra esse caso não ter ocorrido ainda — documentado
        // aqui, não resolvido por completo, pra não virar surpresa depois.
        DB::connection('cliente')->statement("
            UPDATE COMISSAO_LANCAMENTO cl
            JOIN (
                SELECT cpc.id_contrato, MIN(cpc.id_parametro_comissao) as id_parametro_comissao
                FROM CONTRATO_PARAMETRO_COMISSAO cpc
                GROUP BY cpc.id_contrato
                HAVING COUNT(*) = 1
            ) unico ON unico.id_contrato = cl.id_contrato
            SET cl.id_parametro_comissao = unico.id_parametro_comissao
            WHERE cl.id_parametro_comissao IS NULL
            AND (SELECT COUNT(*) FROM COMISSAO_LANCAMENTO cl2 WHERE cl2.id_contrato = cl.id_contrato) = 1
        ");
```

(Precisa de `use Illuminate\Support\Facades\DB;` no topo do arquivo, junto dos imports já presentes.)

- [ ] **Step 3: Verificar sintaxe**

Run: `php -l database/migrations/clientes/2026_10_22_150000_add_parametro_comissao_tracking_to_comissao_lancamento_table.php`
Expected: `No syntax errors detected`

Nota: a parte de `ADD COLUMN` é migration de schema pura — não precisa de teste dedicado, segue o mesmo padrão de outras migrations `ALTER` já presentes em `database/migrations/clientes/` (ex. `2026_10_20_100300_fix_comissao_lancamento_pagamento_columns.php`), nenhuma delas tem teste próprio. O backfill do Step 2 também não é testável via sqlite (sintaxe `UPDATE ... JOIN` é MySQL-específica, e a suíte de testes deste projeto roda migrations só contra fixture manual, nunca a migration de verdade) — revisão de código é a verificação disponível aqui. A Task 2 já exercita as colunas novas (gravação nova, não o backfill de dado antigo) via fixture de teste.

- [ ] **Step 4: Commit**

```bash
git add database/migrations/clientes/2026_10_22_150000_add_parametro_comissao_tracking_to_comissao_lancamento_table.php
git commit -m "feat: adiciona rastreio de modelo e modo em COMISSAO_LANCAMENTO"
```

## Task 2: Extrair cálculo reaproveitável + gravar `id_parametro_comissao`/`tp_parcela_comissao` no fluxo já existente

**Files:**
- Modify: `app/Http/Controllers/Api/Administracao/ContratoController.php:729-824` (`instanciarComissoesDoContrato()`)
- Modify: `tests/Feature/Administracao/ContratoComissaoWorkflowTest.php` (fixture + 1 asserção nova)

**Interfaces:**
- Produces: `private function calcularValorComissaoModelo(Contrato $contrato, ParametroComissao $modelo, \Illuminate\Support\Collection $parcelasGeradas, int $decimais): array` — devolve `['base' => float, 'valor' => float]`. Consumida por `instanciarComissoesDoContrato()` (já existente) e pelas Tasks 3 e 4 (endpoints novos).
- Consumes: `ComissaoCalculoService::calcularValorComissao()` (já existente, sem mudança de assinatura).

- [ ] **Step 1: Atualizar a fixture do teste existente pras 2 colunas novas**

Em `tests/Feature/Administracao/ContratoComissaoWorkflowTest.php`, no bloco `Schema::connection('cliente')->create('COMISSAO_LANCAMENTO', ...)` (linha ~187), adicionar as 2 colunas novas:

```php
        Schema::connection('cliente')->create('COMISSAO_LANCAMENTO', function (Blueprint $table) {
            $table->increments('id');
            $table->integer('id_contrato');
            $table->integer('id_parametro_comissao')->nullable();
            $table->integer('id_parceiro')->nullable();
            $table->integer('id_pessoa_parceiro')->nullable();
            $table->decimal('porc_venda', 15, 2)->nullable();
            $table->decimal('porc_parcela', 15, 2)->nullable();
            $table->string('tp_parcela')->nullable();
            $table->integer('id_tabela_preco')->nullable();
            $table->decimal('vl_fixo', 15, 2)->nullable();
            $table->string('parcela_paga')->nullable();
            $table->string('tp_parcela_comissao', 15)->nullable();
            $table->decimal('vl_comissao_total', 15, 2);
        });
```

- [ ] **Step 2: Escrever o teste que falha (asserção nova em cima do teste já existente)**

Adicionar, logo depois de `test_gerar_parcelas_instancia_comissao_lancamento_modalidade_venda()` (linha ~319-332), sem remover nada do teste existente — só uma asserção extra dentro dele:

```php
    public function test_gerar_parcelas_instancia_comissao_lancamento_modalidade_venda(): void
    {
        $dados = array_merge($this->dadosContratoBase(), ['comissoes' => [1], 'nr_parcela' => 2, 'vl_parcela' => 500]);
        (new ContratoController())->store(request()->create('/api/administracao/contrato', 'POST', $dados));
        (new ContratoController())->gerarParcelas(request(), 1);

        $lancamento = DB::connection('cliente')->table('COMISSAO_LANCAMENTO')->where('id_contrato', 1)->first();

        $this->assertSame(80.0, (float) $lancamento->vl_comissao_total);
        $this->assertSame(1, $lancamento->id_parametro_comissao);
        $this->assertSame('todas', $lancamento->tp_parcela_comissao);
    }
```

(Mantenha o corpo original do teste — as 2 linhas novas são só as 2 últimas asserções, `id_parametro_comissao` e `tp_parcela_comissao`.)

- [ ] **Step 3: Rodar o teste e confirmar que falha nas 2 asserções novas**

Run: `php artisan test --filter=test_gerar_parcelas_instancia_comissao_lancamento_modalidade_venda`
Expected: FAIL em `$this->assertSame(1, $lancamento->id_parametro_comissao)` (`id_parametro_comissao` ainda `null`, coluna nem gravada)

- [ ] **Step 4: Implementar — extrair o método + gravar as 2 colunas**

Em `app/Http/Controllers/Api/Administracao/ContratoController.php`, dentro de `instanciarComissoesDoContrato()` (método privado, linha ~729), substituir o bloco do `match` + chamada a `calcularValorComissao()` por uma chamada ao método novo, e adicionar as 2 colunas no insert de `COMISSAO_LANCAMENTO`:

Trecho atual (a substituir):
```php
            $base = match ($modelo->tp_modalidade) {
                'venda' => Contrato::calcularValorTotal($contrato),
                'parcela' => (float) $parcelasGeradas->where('installment_category', $modelo->tp_parcela)->sum('original_amount'),
                'tabela' => (float) $conexao->table('TABELA_PRECO_LOTES')
                    ->where('id_tabela_preco', $modelo->id_tabela_preco)
                    ->where('id_lote', $contrato->id_lote)
                    ->value('vl_total') ?? 0.0,
                default => 0.0, // 'fixo' não usa base
            };

            $valorComissao = $calculo->calcularValorComissao($modelo, $base, $decimais);

            $idLancamento = $conexao->table('COMISSAO_LANCAMENTO')->insertGetId([
                'id_contrato' => $contrato->id,
                'id_parceiro' => $modelo->id_parceiro,
                'id_pessoa_parceiro' => $modelo->id_pessoa_parceiro,
                'porc_venda' => $modelo->porc_venda,
                'porc_parcela' => $modelo->porc_parcela,
                'tp_parcela' => $modelo->tp_parcela,
                'id_tabela_preco' => $modelo->id_tabela_preco,
                'vl_fixo' => $modelo->vl_fixo,
                'parcela_paga' => $modelo->parcela_paga,
                'vl_comissao_total' => $valorComissao,
            ]);
```

Trecho novo:
```php
            ['valor' => $valorComissao] = $this->calcularValorComissaoModelo($contrato, $modelo, $parcelasGeradas, $decimais);

            $idLancamento = $conexao->table('COMISSAO_LANCAMENTO')->insertGetId([
                'id_contrato' => $contrato->id,
                'id_parametro_comissao' => $idModelo,
                'id_parceiro' => $modelo->id_parceiro,
                'id_pessoa_parceiro' => $modelo->id_pessoa_parceiro,
                'porc_venda' => $modelo->porc_venda,
                'porc_parcela' => $modelo->porc_parcela,
                'tp_parcela' => $modelo->tp_parcela,
                'id_tabela_preco' => $modelo->id_tabela_preco,
                'vl_fixo' => $modelo->vl_fixo,
                'parcela_paga' => $modelo->parcela_paga,
                'tp_parcela_comissao' => 'todas',
                'vl_comissao_total' => $valorComissao,
            ]);
```

Logo depois do método `instanciarComissoesDoContrato()` (depois do seu `}` de fechamento, antes do comentário de `logAlteracoesContrato()`), adicionar o método novo:

```php
    // Base + valor da comissão conforme a modalidade do modelo — extraído de
    // instanciarComissoesDoContrato() pra ser reaproveitado também pelo picker
    // de "Específicas" (parcelasComissaoEspecifica()) e pelo processamento
    // pós-geração (processarComissaoPosGeracao()), ver
    // docs/superpowers/specs/2026-10-22-aba-comissao-contrato-especificas-design.md.
    // $parcelasGeradas é a coleção de TODAS as parcelas reais do contrato (pagas
    // ou não) — a base da modalidade 'parcela' soma o valor total daquele tipo,
    // independente de status de pagamento.
    private function calcularValorComissaoModelo(
        Contrato $contrato,
        ParametroComissao $modelo,
        \Illuminate\Support\Collection $parcelasGeradas,
        int $decimais
    ): array {
        $base = match ($modelo->tp_modalidade) {
            'venda' => Contrato::calcularValorTotal($contrato),
            'parcela' => (float) $parcelasGeradas->where('installment_category', $modelo->tp_parcela)->sum('original_amount'),
            'tabela' => (float) DB::connection('cliente')->table('TABELA_PRECO_LOTES')
                ->where('id_tabela_preco', $modelo->id_tabela_preco)
                ->where('id_lote', $contrato->id_lote)
                ->value('vl_total') ?? 0.0,
            default => 0.0, // 'fixo' não usa base
        };

        $valor = app(ComissaoCalculoService::class)->calcularValorComissao($modelo, $base, $decimais);

        return ['base' => $base, 'valor' => $valor];
    }
```

- [ ] **Step 5: Rodar o teste e confirmar que passa**

Run: `php artisan test --filter=ContratoComissaoWorkflowTest`
Expected: PASS (todos os testes do arquivo, não só o editado — confirma que a extração não quebrou os outros 8 testes já existentes)

- [ ] **Step 6: Escrever o teste que falha — `show()` precisa expor quais modelos já foram processados**

A aba nova (Task 5) precisa saber, pra cada modelo vinculado, se ele já tem `COMISSAO_LANCAMENTO` gerado (pra decidir entre mostrar na lista simples editável ou na lista travada/somente-leitura) — reaproveita o `show()` já existente em vez de criar endpoint à parte. Editar `test_show_devolve_as_comissoes_vinculadas_com_nome()` (já existente, linha ~295-317), substituindo o corpo inteiro por:

```php
    public function test_show_devolve_as_comissoes_vinculadas_com_nome(): void
    {
        $dados = array_merge($this->dadosContratoBase(), ['comissoes' => [2, 1]]);
        (new ContratoController())->store(request()->create('/api/administracao/contrato', 'POST', $dados));

        // Vínculo de OUTRO contrato (id_contrato=999) — prova que o where() filtra de verdade.
        DB::connection('cliente')->table('CONTRATO_PARAMETRO_COMISSAO')->insert([
            'id_contrato' => 999,
            'id_parametro_comissao' => 1,
        ]);

        // Modelo 2 já foi processado (tem COMISSAO_LANCAMENTO); modelo 1 ainda não.
        DB::connection('cliente')->table('COMISSAO_LANCAMENTO')->insert([
            'id_contrato' => 1, 'id_parametro_comissao' => 2, 'tp_parcela_comissao' => 'todas', 'vl_comissao_total' => 20,
        ]);

        $resposta = (new ContratoController())->show(1);
        $dados = json_decode($resposta->getContent(), true);

        $this->assertSame([
            ['id' => 2, 'nome' => 'Comissão B', 'tp_parcela_comissao' => 'todas', 'processado' => true],
            ['id' => 1, 'nome' => 'Comissão A', 'tp_parcela_comissao' => null, 'processado' => false],
        ], $dados['comissoes']);
    }
```

- [ ] **Step 7: Rodar e confirmar que falha**

Run: `php artisan test --filter=test_show_devolve_as_comissoes_vinculadas_com_nome`
Expected: FAIL (resposta ainda não tem as chaves `tp_parcela_comissao`/`processado`)

- [ ] **Step 8: Implementar — estender a query de `$comissoes` dentro de `show()`**

Em `app/Http/Controllers/Api/Administracao/ContratoController.php`, dentro de `show()` (linha ~286-290), substituir:

```php
        $comissoes = DB::connection('cliente')->table('CONTRATO_PARAMETRO_COMISSAO')
            ->join('PARAMETRO_COMISSAO', 'PARAMETRO_COMISSAO.id_parametro_comissao', '=', 'CONTRATO_PARAMETRO_COMISSAO.id_parametro_comissao')
            ->where('CONTRATO_PARAMETRO_COMISSAO.id_contrato', $id)
            ->orderBy('CONTRATO_PARAMETRO_COMISSAO.id')
            ->get(['PARAMETRO_COMISSAO.id_parametro_comissao as id', 'PARAMETRO_COMISSAO.nm_parametro_comissao as nome']);
```

por:

```php
        // leftJoin com COMISSAO_LANCAMENTO (por id_contrato + id_parametro_comissao) pra
        // UI decidir entre a lista simples editável (ainda não processado) e a lista
        // travada/somente-leitura (já processado) — ver
        // docs/superpowers/specs/2026-10-22-aba-comissao-contrato-especificas-design.md.
        $comissoes = DB::connection('cliente')->table('CONTRATO_PARAMETRO_COMISSAO')
            ->join('PARAMETRO_COMISSAO', 'PARAMETRO_COMISSAO.id_parametro_comissao', '=', 'CONTRATO_PARAMETRO_COMISSAO.id_parametro_comissao')
            ->leftJoin('COMISSAO_LANCAMENTO', function ($join) use ($id) {
                $join->on('COMISSAO_LANCAMENTO.id_parametro_comissao', '=', 'CONTRATO_PARAMETRO_COMISSAO.id_parametro_comissao')
                    ->where('COMISSAO_LANCAMENTO.id_contrato', '=', $id);
            })
            ->where('CONTRATO_PARAMETRO_COMISSAO.id_contrato', $id)
            ->orderBy('CONTRATO_PARAMETRO_COMISSAO.id')
            ->get([
                'PARAMETRO_COMISSAO.id_parametro_comissao as id',
                'PARAMETRO_COMISSAO.nm_parametro_comissao as nome',
                'COMISSAO_LANCAMENTO.tp_parcela_comissao as tp_parcela_comissao',
            ])
            ->map(function ($c) {
                return [
                    'id' => $c->id,
                    'nome' => $c->nome,
                    'tp_parcela_comissao' => $c->tp_parcela_comissao,
                    'processado' => $c->tp_parcela_comissao !== null,
                ];
            });
```

- [ ] **Step 9: Rodar e confirmar que passa**

Run: `php artisan test --filter=ContratoComissaoWorkflowTest`
Expected: PASS (todos os testes do arquivo)

- [ ] **Step 10: Commit**

```bash
git add app/Http/Controllers/Api/Administracao/ContratoController.php tests/Feature/Administracao/ContratoComissaoWorkflowTest.php
git commit -m "refactor: extrai cálculo de comissão reaproveitável e expõe estado de processamento em show()"
```

## Task 3: Endpoint — listar parcelas elegíveis pra comissão "Específicas"

**Files:**
- Modify: `app/Http/Controllers/Api/Administracao/ContratoController.php` (2 métodos privados novos + 1 público)
- Modify: `routes/api.php` (1 rota nova)
- Create: `tests/Feature/Administracao/ContratoComissaoPosGeracaoTest.php`

**Interfaces:**
- Consumes: `calcularValorComissaoModelo()` (Task 2).
- Produces: `private function parcelasElegiveisParaComissao(int $idContrato): \Illuminate\Support\Collection` (linhas: `id`, `installment_number`, `installment_category`, `due_date`, `original_amount`) e `private function comissaoComprometidaPorParcela(int $idContrato, ?int $excluirLancamento = null): array` (chave = `id_parcela`, valor = soma comprometida) — ambos reaproveitados pela Task 4. `public function parcelasComissaoEspecifica($id, $idParametroComissao)` — endpoint novo.

- [ ] **Step 1: Criar o arquivo de teste com a fixture (mesmo padrão de `ContratoComissaoWorkflowTest`)**

```php
<?php

namespace Tests\Feature\Administracao;

use App\Http\Controllers\Api\Administracao\ContratoController;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;
use Symfony\Component\HttpKernel\Exception\HttpException;
use Tests\TestCase;

class ContratoComissaoPosGeracaoTest extends TestCase
{
    protected function setUp(): void
    {
        parent::setUp();

        config(['database.connections.cliente' => [
            'driver' => 'sqlite',
            'database' => ':memory:',
            'prefix' => '',
            'foreign_key_constraints' => true,
        ]]);
        DB::purge('cliente');

        Schema::connection('cliente')->create('EMPREENDIMENTO', function (Blueprint $table) {
            $table->increments('id');
        });

        Schema::connection('cliente')->create('LOTES', function (Blueprint $table) {
            $table->increments('id');
            $table->integer('id_empreendimento');
            $table->string('status')->default('D');
            $table->decimal('valor', 15, 2)->nullable();
        });

        Schema::connection('cliente')->create('PESSOA', function (Blueprint $table) {
            $table->increments('id');
            $table->string('nm_pessoa');
        });

        Schema::connection('cliente')->create('CONTRATO', function (Blueprint $table) {
            $table->increments('id');
            $table->integer('id_lote');
            $table->integer('id_pessoa');
            $table->string('fl_gerado')->default('0');
            $table->string('fl_distrato')->default('0');
        });

        Schema::connection('cliente')->create('receivables', function (Blueprint $table) {
            $table->increments('id');
            $table->string('type')->nullable();
            $table->integer('contract_id');
            $table->integer('installment_number')->nullable();
            $table->string('installment_category')->nullable();
            $table->date('due_date')->nullable();
            $table->decimal('original_amount', 15, 2)->nullable();
            $table->date('payment_date')->nullable();
            $table->string('status')->nullable();
            $table->timestamps();
        });

        Schema::connection('cliente')->create('PARAMETRO_COMISSAO', function (Blueprint $table) {
            $table->increments('id_parametro_comissao');
            $table->string('nm_parametro_comissao')->nullable();
            $table->string('tp_modalidade', 10)->nullable();
            $table->decimal('porc_venda', 15, 2)->nullable();
            $table->integer('id_parceiro')->nullable();
            $table->integer('id_pessoa_parceiro')->nullable();
            $table->decimal('vl_fixo', 15, 2)->nullable();
            $table->decimal('porc_parcela', 15, 2)->nullable();
            $table->string('tp_parcela', 15)->nullable();
            $table->integer('id_tabela_preco')->nullable();
            $table->string('parcela_paga', 1)->nullable();
            $table->decimal('pc_limite_parcela', 15, 2)->nullable();
        });

        Schema::connection('cliente')->create('CONTRATO_PARAMETRO_COMISSAO', function (Blueprint $table) {
            $table->increments('id');
            $table->integer('id_contrato');
            $table->integer('id_parametro_comissao');
        });

        Schema::connection('cliente')->create('COMISSAO_LANCAMENTO', function (Blueprint $table) {
            $table->increments('id');
            $table->integer('id_contrato');
            $table->integer('id_parametro_comissao')->nullable();
            $table->integer('id_parceiro')->nullable();
            $table->integer('id_pessoa_parceiro')->nullable();
            $table->decimal('porc_venda', 15, 2)->nullable();
            $table->decimal('porc_parcela', 15, 2)->nullable();
            $table->string('tp_parcela')->nullable();
            $table->integer('id_tabela_preco')->nullable();
            $table->decimal('vl_fixo', 15, 2)->nullable();
            $table->string('parcela_paga')->nullable();
            $table->string('tp_parcela_comissao', 15)->nullable();
            $table->decimal('vl_comissao_total', 15, 2);
        });

        Schema::connection('cliente')->create('COMISSAO_PAGAMENTO', function (Blueprint $table) {
            $table->increments('id');
            $table->integer('id_comissao_lanc');
            $table->float('porc_parcela')->nullable();
            $table->integer('id_parcela');
            $table->string('tp_parcela')->nullable();
            $table->integer('id_tabela_preco')->nullable();
            $table->decimal('vl_parcela', 15, 2);
            $table->decimal('vl_comissao_parcela', 15, 2);
        });

        DB::connection('cliente')->table('EMPREENDIMENTO')->insert(['id' => 1]);
        DB::connection('cliente')->table('LOTES')->insert(['id' => 10, 'id_empreendimento' => 1, 'status' => 'V']);
        DB::connection('cliente')->table('PESSOA')->insert(['id' => 20, 'nm_pessoa' => 'Comprador Teste']);
        DB::connection('cliente')->table('CONTRATO')->insert(['id' => 1, 'id_lote' => 10, 'id_pessoa' => 20, 'fl_gerado' => '1']);
        DB::connection('cliente')->table('PARAMETRO_COMISSAO')->insert([
            'id_parametro_comissao' => 1,
            'nm_parametro_comissao' => 'Comissão Parcela',
            'tp_modalidade' => 'parcela',
            'tp_parcela' => 'N',
            'porc_parcela' => 10,
            'parcela_paga' => '1',
            'pc_limite_parcela' => 50,
            'id_parceiro' => 100,
            'id_pessoa_parceiro' => 101,
        ]);
        DB::connection('cliente')->table('receivables')->insert([
            ['id' => 1, 'type' => 'parcela_contrato', 'contract_id' => 1, 'installment_number' => 1, 'installment_category' => 'N', 'due_date' => '2026-11-01', 'original_amount' => 500, 'status' => 'pending'],
            ['id' => 2, 'type' => 'parcela_contrato', 'contract_id' => 1, 'installment_number' => 2, 'installment_category' => 'N', 'due_date' => '2026-12-01', 'original_amount' => 500, 'status' => 'pending'],
            ['id' => 3, 'type' => 'parcela_contrato', 'contract_id' => 1, 'installment_number' => 3, 'installment_category' => 'N', 'due_date' => '2027-01-01', 'original_amount' => 500, 'payment_date' => '2026-10-20', 'status' => 'paid'],
        ]);
    }

    protected function tearDown(): void
    {
        DB::purge('cliente');
        parent::tearDown();
    }
}
```

- [ ] **Step 2: Rodar pra confirmar que a fixture sobe sem erro**

Run: `php artisan test --filter=ContratoComissaoPosGeracaoTest`
Expected: `No tests found` (nenhum `test_*` ainda, mas sem erro de fixture/schema)

- [ ] **Step 3: Escrever o teste que falha**

```php
    public function test_lista_apenas_parcelas_elegiveis_com_comissao_comprometida(): void
    {
        // Parcela 1 já tem R$40 comprometido por OUTRO lançamento, do mesmo contrato.
        DB::connection('cliente')->table('COMISSAO_LANCAMENTO')->insert([
            'id' => 99, 'id_contrato' => 1, 'id_parametro_comissao' => 2, 'vl_comissao_total' => 40,
        ]);
        DB::connection('cliente')->table('COMISSAO_PAGAMENTO')->insert([
            'id_comissao_lanc' => 99, 'id_parcela' => 1, 'tp_parcela' => 'N', 'vl_parcela' => 500, 'vl_comissao_parcela' => 40,
        ]);

        $resposta = (new ContratoController())->parcelasComissaoEspecifica(1, 1);
        $dados = json_decode($resposta->getContent(), true);

        $this->assertSame(10.0, $dados['modelo']['porc_parcela']);
        $this->assertCount(2, $dados['parcelas']); // parcela 3 (paga) fica de fora
        $this->assertSame([1, 2], array_column($dados['parcelas'], 'id'));
        $this->assertSame(40.0, $dados['parcelas'][0]['comissao_comprometida']);
        $this->assertSame(0.0, $dados['parcelas'][1]['comissao_comprometida']);
    }
```

- [ ] **Step 4: Rodar e confirmar que falha**

Run: `php artisan test --filter=test_lista_apenas_parcelas_elegiveis_com_comissao_comprometida`
Expected: FAIL (`Call to undefined method ContratoController::parcelasComissaoEspecifica()`)

- [ ] **Step 5: Implementar**

Em `app/Http/Controllers/Api/Administracao/ContratoController.php`, logo depois do método `calcularValorComissaoModelo()` (adicionado na Task 2), adicionar:

```php
    // Parcelas reais do contrato elegíveis pra receber alocação de comissão
    // (manual ou automática) no fluxo pós-geração — parcela paga ou cancelada
    // nunca entra, ver Global Constraints do plano desta entrega.
    private function parcelasElegiveisParaComissao(int $idContrato): \Illuminate\Support\Collection
    {
        return DB::connection('cliente')->table('receivables')
            ->where('type', ParcelaReceivable::TYPE)
            ->where('contract_id', $idContrato)
            ->whereNull('payment_date')
            ->where('status', '!=', 'cancelled')
            ->orderBy('due_date')
            ->get(['id', 'installment_number', 'installment_category', 'due_date', 'original_amount']);
    }

    // Soma de comissão já comprometida por parcela, considerando TODOS os
    // COMISSAO_LANCAMENTO do contrato (de qualquer modelo) — $excluirLancamento
    // tira o próprio lançamento sendo reeditado do cálculo, pra não contar a
    // seleção anterior dele como "comprometida contra si mesma".
    private function comissaoComprometidaPorParcela(int $idContrato, ?int $excluirLancamento = null): array
    {
        $query = DB::connection('cliente')->table('COMISSAO_PAGAMENTO')
            ->join('COMISSAO_LANCAMENTO', 'COMISSAO_LANCAMENTO.id', '=', 'COMISSAO_PAGAMENTO.id_comissao_lanc')
            ->where('COMISSAO_LANCAMENTO.id_contrato', $idContrato);

        if ($excluirLancamento) {
            $query->where('COMISSAO_LANCAMENTO.id', '!=', $excluirLancamento);
        }

        return $query->selectRaw('COMISSAO_PAGAMENTO.id_parcela, SUM(COMISSAO_PAGAMENTO.vl_comissao_parcela) as total')
            ->groupBy('COMISSAO_PAGAMENTO.id_parcela')
            ->pluck('total', 'id_parcela')
            ->map(fn ($v) => (float) $v)
            ->all();
    }

    // Dados pro picker de "Específicas" — parcelas elegíveis + comissão já
    // comprometida por outros modelos + dados do modelo (pra UI mostrar "total
    // a distribuir"). Se o modelo já tem COMISSAO_LANCAMENTO neste contrato,
    // devolve também a seleção já salva, pra UI reabrir preenchida.
    public function parcelasComissaoEspecifica($id, $idParametroComissao)
    {
        $contrato = Contrato::findOrFail($id);
        $modelo = ParametroComissao::whereNotNull('tp_modalidade')->findOrFail($idParametroComissao);

        $todasAsParcelas = DB::connection('cliente')->table('receivables')
            ->where('type', ParcelaReceivable::TYPE)
            ->where('contract_id', $contrato->id)
            ->get(['id', 'original_amount', 'installment_category']);

        $decimais = CurrencyConfig::getConfig()['decimals'];
        ['valor' => $valorComissao] = $this->calcularValorComissaoModelo($contrato, $modelo, $todasAsParcelas, $decimais);

        $lancamentoExistente = DB::connection('cliente')->table('COMISSAO_LANCAMENTO')
            ->where('id_contrato', $contrato->id)
            ->where('id_parametro_comissao', $idParametroComissao)
            ->first();

        $comprometido = $this->comissaoComprometidaPorParcela($contrato->id, $lancamentoExistente->id ?? null);

        $selecaoExistente = $lancamentoExistente
            ? DB::connection('cliente')->table('COMISSAO_PAGAMENTO')
                ->where('id_comissao_lanc', $lancamentoExistente->id)
                ->pluck('vl_comissao_parcela', 'id_parcela')
            : collect();

        $parcelas = $this->parcelasElegiveisParaComissao($contrato->id)->map(function ($p) use ($comprometido, $selecaoExistente) {
            return [
                'id' => $p->id,
                'installment_number' => $p->installment_number,
                'installment_category' => $p->installment_category,
                'due_date' => $p->due_date,
                'original_amount' => (float) $p->original_amount,
                'comissao_comprometida' => $comprometido[$p->id] ?? 0.0,
                'valor_selecionado' => isset($selecaoExistente[$p->id]) ? (float) $selecaoExistente[$p->id] : null,
            ];
        });

        return response()->json([
            'modelo' => [
                'nm_parametro_comissao' => $modelo->nm_parametro_comissao,
                'tp_modalidade' => $modelo->tp_modalidade,
                'parcela_paga' => $modelo->parcela_paga,
                'porc_parcela' => $modelo->porc_parcela,
                'valor_total_comissao' => $valorComissao,
                'ja_processado' => $lancamentoExistente !== null,
            ],
            'parcelas' => $parcelas->values(),
        ]);
    }
```

- [ ] **Step 6: Rodar e confirmar que passa**

Run: `php artisan test --filter=ContratoComissaoPosGeracaoTest`
Expected: PASS

- [ ] **Step 7: Registrar a rota**

Em `routes/api.php`, dentro do grupo `Route::middleware('permission:Listar Contrato')` (mesmo grupo de `contrato.parcelas`, linha ~188), adicionar logo depois:

```php
        Route::get('/administracao/contrato/{id}/comissao/{idParametroComissao}/parcelas', [ContratoController::class, 'parcelasComissaoEspecifica'])->name('contrato.comissao.parcelas');
```

- [ ] **Step 8: Verificar sintaxe e sanidade de rota**

Run: `php -l app/Http/Controllers/Api/Administracao/ContratoController.php && php -l routes/api.php`
Run: `php artisan route:list | grep "contrato.comissao.parcelas"`
Expected: sem erro de sintaxe, rota aparece listada

- [ ] **Step 9: Commit**

```bash
git add app/Http/Controllers/Api/Administracao/ContratoController.php routes/api.php tests/Feature/Administracao/ContratoComissaoPosGeracaoTest.php
git commit -m "feat: endpoint de listagem de parcelas elegíveis pra comissão específica"
```

## Task 4: Endpoint — processar comissão pós-geração (Todas ou Específicas)

**Files:**
- Modify: `app/Http/Controllers/Api/Administracao/ContratoController.php` (1 método público novo)
- Modify: `routes/api.php` (1 rota nova)
- Modify: `tests/Feature/Administracao/ContratoComissaoPosGeracaoTest.php` (mesma fixture da Task 3, testes novos)
- Modify: `resources/lang/{pt,es,en}/administracao.php` (mensagens novas)

**Interfaces:**
- Consumes: `calcularValorComissaoModelo()`, `parcelasElegiveisParaComissao()`, `comissaoComprometidaPorParcela()` (Tasks 2-3), `ComissaoCalculoService::ratear()` (já existente).
- Produces: `public function processarComissaoPosGeracao(Request $request, $id, $idParametroComissao)`.

- [ ] **Step 1: Adicionar as mensagens de erro/sucesso nas traduções**

Em `resources/lang/pt/administracao.php`, dentro do array `'messages' => [...]` (mesmo array que já tem `'modelo_comissao_vinculado_contrato'`/`'comissao_nao_coube_nas_parcelas'`), adicionar:

```php
        'comissao_pos_geracao_exige_parcela' => 'Só é possível processar comissão depois que as parcelas do contrato forem geradas.',
        'comissao_especificas_modalidade_invalida' => 'O modo "Específicas" só está disponível para comissão do tipo "Tipo de Parcela (%)" paga sobre parcelas.',
        'comissao_especificas_ultrapassa_parcela' => 'A parcela :numero não comporta esse valor de comissão — disponível: :disponivel.',
        'comissao_processada_sucesso' => 'Comissão processada com sucesso.',
        'parcela_nao_pertence_contrato' => 'Uma das parcelas selecionadas não pertence a este contrato.',
```

Repetir a mesma lista de chaves em `resources/lang/es/administracao.php` e `resources/lang/en/administracao.php`, traduzidas:

`es/administracao.php`:
```php
        'comissao_pos_geracao_exige_parcela' => 'Solo es posible procesar la comisión después de que las cuotas del contrato sean generadas.',
        'comissao_especificas_modalidade_invalida' => 'El modo "Específicas" solo está disponible para comisión del tipo "Tipo de Cuota (%)" pagada sobre cuotas.',
        'comissao_especificas_ultrapassa_parcela' => 'La cuota :numero no admite ese valor de comisión — disponible: :disponivel.',
        'comissao_processada_sucesso' => 'Comisión procesada con éxito.',
        'parcela_nao_pertence_contrato' => 'Una de las cuotas seleccionadas no pertenece a este contrato.',
```

`en/administracao.php`:
```php
        'comissao_pos_geracao_exige_parcela' => 'Commission can only be processed after the contract installments have been generated.',
        'comissao_especificas_modalidade_invalida' => 'The "Specific" mode is only available for "Installment Type (%)" commission paid over installments.',
        'comissao_especificas_ultrapassa_parcela' => 'Installment :numero cannot take this commission value — available: :disponivel.',
        'comissao_processada_sucesso' => 'Commission processed successfully.',
        'parcela_nao_pertence_contrato' => 'One of the selected installments does not belong to this contract.',
```

- [ ] **Step 2: Escrever o teste que falha — caminho feliz "Específicas"**

Adicionar em `tests/Feature/Administracao/ContratoComissaoPosGeracaoTest.php`:

```php
    public function test_processa_comissao_especifica_gravando_exatamente_os_valores_informados(): void
    {
        $request = request()->create('/api/administracao/contrato/1/comissao/1/processar', 'POST', [
            'tp_parcela_comissao' => 'especificas',
            'parcelas' => [
                ['id_parcela' => 1, 'valor' => 60],
                ['id_parcela' => 2, 'valor' => 40],
            ],
        ]);

        (new ContratoController())->processarComissaoPosGeracao($request, 1, 1);

        $lancamento = DB::connection('cliente')->table('COMISSAO_LANCAMENTO')->where('id_contrato', 1)->first();
        $this->assertSame('especificas', $lancamento->tp_parcela_comissao);
        $this->assertSame(1, $lancamento->id_parametro_comissao);

        $pagamentos = DB::connection('cliente')->table('COMISSAO_PAGAMENTO')
            ->where('id_comissao_lanc', $lancamento->id)->orderBy('id_parcela')->get();

        $this->assertCount(2, $pagamentos);
        $this->assertSame(60.0, (float) $pagamentos[0]->vl_comissao_parcela);
        $this->assertSame(40.0, (float) $pagamentos[1]->vl_comissao_parcela);

        $vinculado = DB::connection('cliente')->table('CONTRATO_PARAMETRO_COMISSAO')
            ->where('id_contrato', 1)->where('id_parametro_comissao', 1)->exists();
        $this->assertTrue($vinculado);
    }

    public function test_processa_comissao_todas_usando_o_rateio_existente(): void
    {
        // Sobe porc_parcela pra 30% só nesta fixture local — força o total da
        // comissão (450) a precisar de 2 parcelas (o teto de 250 por parcela,
        // pc_limite_parcela=50% × 500, não comporta tudo numa só), provando que
        // o rateio pós-geração de fato distribui entre as elegíveis.
        DB::connection('cliente')->table('PARAMETRO_COMISSAO')->where('id_parametro_comissao', 1)->update(['porc_parcela' => 30]);

        $request = request()->create('/api/administracao/contrato/1/comissao/1/processar', 'POST', [
            'tp_parcela_comissao' => 'todas',
        ]);

        (new ContratoController())->processarComissaoPosGeracao($request, 1, 1);

        $lancamento = DB::connection('cliente')->table('COMISSAO_LANCAMENTO')->where('id_contrato', 1)->first();
        $this->assertSame('todas', $lancamento->tp_parcela_comissao);
        // porc_parcela=30%, base (soma das parcelas tipo N, as 3, incluindo a
        // paga) = 1500 → comissão total = 450.
        $this->assertSame(450.0, (float) $lancamento->vl_comissao_total);

        $pagamentos = DB::connection('cliente')->table('COMISSAO_PAGAMENTO')->where('id_comissao_lanc', $lancamento->id)->get();
        // Só 2 parcelas elegíveis (a 3ª já está paga) — rateio precisa das 2 pra
        // fechar os 450 (250 na primeira, 200 na segunda).
        $this->assertCount(2, $pagamentos);
        $this->assertSame(450.0, (float) $pagamentos->sum('vl_comissao_parcela'));
    }

    public function test_rejeita_especificas_quando_ultrapassa_valor_da_parcela_considerando_comprometido(): void
    {
        DB::connection('cliente')->table('CONTRATO_PARAMETRO_COMISSAO')->insert(['id_contrato' => 1, 'id_parametro_comissao' => 1]);
        DB::connection('cliente')->table('COMISSAO_LANCAMENTO')->insert([
            'id' => 50, 'id_contrato' => 1, 'id_parametro_comissao' => 1, 'vl_comissao_total' => 300, 'tp_parcela_comissao' => 'especificas',
        ]);
        DB::connection('cliente')->table('COMISSAO_PAGAMENTO')->insert([
            'id_comissao_lanc' => 50, 'id_parcela' => 1, 'vl_parcela' => 500, 'vl_comissao_parcela' => 480,
        ]);

        DB::connection('cliente')->table('PARAMETRO_COMISSAO')->insert([
            'id_parametro_comissao' => 2, 'nm_parametro_comissao' => 'Comissão B', 'tp_modalidade' => 'parcela',
            'tp_parcela' => 'N', 'porc_parcela' => 5, 'parcela_paga' => '1', 'pc_limite_parcela' => 50,
        ]);

        $request = request()->create('/api/administracao/contrato/1/comissao/2/processar', 'POST', [
            'tp_parcela_comissao' => 'especificas',
            'parcelas' => [['id_parcela' => 1, 'valor' => 30]],
        ]);

        try {
            (new ContratoController())->processarComissaoPosGeracao($request, 1, 2);
            $this->fail('Deveria ter rejeitado — só sobram R$20 disponíveis na parcela 1 (500 - 480), tentando alocar R$30.');
        } catch (HttpException $exception) {
            $this->assertSame(422, $exception->getStatusCode());
        }
    }

    public function test_reprocessar_especificas_substitui_selecao_anterior_sem_duplicar(): void
    {
        $processar = fn (array $parcelas) => (new ContratoController())->processarComissaoPosGeracao(
            request()->create('/api/administracao/contrato/1/comissao/1/processar', 'POST', ['tp_parcela_comissao' => 'especificas', 'parcelas' => $parcelas]),
            1,
            1
        );

        $processar([['id_parcela' => 1, 'valor' => 60]]);
        $processar([['id_parcela' => 2, 'valor' => 40]]);

        $this->assertSame(1, DB::connection('cliente')->table('COMISSAO_LANCAMENTO')->where('id_contrato', 1)->count());
        $pagamentos = DB::connection('cliente')->table('COMISSAO_PAGAMENTO')->get();
        $this->assertCount(1, $pagamentos);
        $this->assertSame(2, $pagamentos[0]->id_parcela);
        $this->assertSame(40.0, (float) $pagamentos[0]->vl_comissao_parcela);
    }

    public function test_modalidade_fora_de_parcela_processa_direto_via_todas_sem_opcao(): void
    {
        DB::connection('cliente')->table('PARAMETRO_COMISSAO')->insert([
            'id_parametro_comissao' => 3, 'nm_parametro_comissao' => 'Comissão Venda', 'tp_modalidade' => 'venda', 'porc_venda' => 2,
        ]);

        $request = request()->create('/api/administracao/contrato/1/comissao/3/processar', 'POST', ['tp_parcela_comissao' => 'todas']);
        (new ContratoController())->processarComissaoPosGeracao($request, 1, 3);

        $lancamento = DB::connection('cliente')->table('COMISSAO_LANCAMENTO')->where('id_parametro_comissao', 3)->first();
        $this->assertNotNull($lancamento);
        $this->assertSame('todas', $lancamento->tp_parcela_comissao);
        // parcela_paga é NULL pra essa modelo (não setado) — não gera COMISSAO_PAGAMENTO nenhum.
        $this->assertSame(0, DB::connection('cliente')->table('COMISSAO_PAGAMENTO')->where('id_comissao_lanc', $lancamento->id)->count());
    }
```

- [ ] **Step 3: Rodar e confirmar que falham (método não existe)**

Run: `php artisan test --filter=ContratoComissaoPosGeracaoTest`
Expected: FAIL em todos os testes novos (`Call to undefined method ContratoController::processarComissaoPosGeracao()`)

- [ ] **Step 4: Implementar**

Em `app/Http/Controllers/Api/Administracao/ContratoController.php`, logo depois de `parcelasComissaoEspecifica()` (Task 3), adicionar:

```php
    private const REGRAS_COMISSAO_POS_GERACAO = [
        'tp_parcela_comissao' => 'required|in:todas,especificas',
        'parcelas' => 'required_if:tp_parcela_comissao,especificas|array',
        'parcelas.*.id_parcela' => 'required_with:parcelas|integer',
        'parcelas.*.valor' => 'required_with:parcelas|numeric|min:0.01',
    ];

    // Processa (Todas ou Específicas) um modelo de comissão vinculado a um
    // contrato que JÁ TEM parcela gerada — fecha a lacuna onde vincular um
    // modelo depois de fl_gerado='1' não tinha efeito nenhum (ver spec desta
    // entrega). Idempotente: reprocessar substitui a seleção anterior.
    public function processarComissaoPosGeracao(Request $request, $id, $idParametroComissao)
    {
        $contrato = Contrato::findOrFail($id);
        abort_if($contrato->fl_gerado !== '1', 422, __('administracao.messages.comissao_pos_geracao_exige_parcela'));

        $modelo = ParametroComissao::whereNotNull('tp_modalidade')->findOrFail($idParametroComissao);
        $data = $request->validate(self::REGRAS_COMISSAO_POS_GERACAO);

        $modoEspecificas = $data['tp_parcela_comissao'] === 'especificas';
        $permiteEspecificas = $modelo->tp_modalidade === 'parcela' && $modelo->parcela_paga === '1';
        abort_if($modoEspecificas && !$permiteEspecificas, 422, __('administracao.messages.comissao_especificas_modalidade_invalida'));

        return DB::connection('cliente')->transaction(function () use ($contrato, $modelo, $idParametroComissao, $data, $modoEspecificas) {
            $conexao = DB::connection('cliente');
            $decimais = CurrencyConfig::getConfig()['decimals'];

            $conexao->table('CONTRATO_PARAMETRO_COMISSAO')->updateOrInsert(
                ['id_contrato' => $contrato->id, 'id_parametro_comissao' => $idParametroComissao],
                []
            );

            $lancamentoExistente = $conexao->table('COMISSAO_LANCAMENTO')
                ->where('id_contrato', $contrato->id)
                ->where('id_parametro_comissao', $idParametroComissao)
                ->first();

            if ($lancamentoExistente) {
                $conexao->table('COMISSAO_PAGAMENTO')->where('id_comissao_lanc', $lancamentoExistente->id)->delete();
            }

            $todasAsParcelas = $conexao->table('receivables')
                ->where('type', ParcelaReceivable::TYPE)
                ->where('contract_id', $contrato->id)
                ->get(['id', 'original_amount', 'installment_category']);

            ['valor' => $valorComissao] = $this->calcularValorComissaoModelo($contrato, $modelo, $todasAsParcelas, $decimais);

            $camposLancamento = [
                'id_contrato' => $contrato->id,
                'id_parametro_comissao' => $idParametroComissao,
                'id_parceiro' => $modelo->id_parceiro,
                'id_pessoa_parceiro' => $modelo->id_pessoa_parceiro,
                'porc_venda' => $modelo->porc_venda,
                'porc_parcela' => $modelo->porc_parcela,
                'tp_parcela' => $modelo->tp_parcela,
                'id_tabela_preco' => $modelo->id_tabela_preco,
                'vl_fixo' => $modelo->vl_fixo,
                'parcela_paga' => $modelo->parcela_paga,
                'tp_parcela_comissao' => $data['tp_parcela_comissao'],
                'vl_comissao_total' => $valorComissao,
            ];

            if ($lancamentoExistente) {
                $conexao->table('COMISSAO_LANCAMENTO')->where('id', $lancamentoExistente->id)->update($camposLancamento);
                $idLancamento = $lancamentoExistente->id;
            } else {
                $idLancamento = $conexao->table('COMISSAO_LANCAMENTO')->insertGetId($camposLancamento);
            }

            if ($modelo->parcela_paga !== '1') {
                return response()->json(['message' => __('administracao.messages.comissao_processada_sucesso')]);
            }

            $parcelasElegiveis = $this->parcelasElegiveisParaComissao($contrato->id);
            $comprometidoPorParcela = $this->comissaoComprometidaPorParcela($contrato->id, $lancamentoExistente->id ?? null);

            if ($modoEspecificas) {
                foreach ($data['parcelas'] as $linha) {
                    $parcela = $parcelasElegiveis->firstWhere('id', $linha['id_parcela']);
                    abort_if(!$parcela, 422, __('administracao.messages.parcela_nao_pertence_contrato'));

                    $comprometido = $comprometidoPorParcela[$linha['id_parcela']] ?? 0.0;
                    $disponivel = round((float) $parcela->original_amount - $comprometido, $decimais);
                    abort_if($linha['valor'] > $disponivel, 422, __('administracao.messages.comissao_especificas_ultrapassa_parcela', [
                        'numero' => $parcela->installment_number,
                        'disponivel' => CurrencyConfig::format($disponivel),
                    ]));

                    $percentual = (float) $parcela->original_amount > 0
                        ? round($linha['valor'] / (float) $parcela->original_amount * 100, $decimais)
                        : 0;

                    $conexao->table('COMISSAO_PAGAMENTO')->insert([
                        'id_comissao_lanc' => $idLancamento,
                        'porc_parcela' => $percentual,
                        'id_parcela' => $linha['id_parcela'],
                        'tp_parcela' => $parcela->installment_category,
                        'id_tabela_preco' => $modelo->id_tabela_preco,
                        'vl_parcela' => $parcela->original_amount,
                        'vl_comissao_parcela' => $linha['valor'],
                    ]);

                    $comprometidoPorParcela[$linha['id_parcela']] = $comprometido + $linha['valor'];
                }

                return response()->json(['message' => __('administracao.messages.comissao_processada_sucesso')]);
            }

            // "Todas" — mesmo algoritmo de rateio já usado em instanciarComissoesDoContrato(),
            // só que agora contra as parcelas ELEGÍVEIS (não todas), ver Global Constraints.
            $parcelasParaRateio = $parcelasElegiveis->map(fn ($p) => ['id' => $p->id, 'valor' => (float) $p->original_amount])->all();
            $resultado = app(ComissaoCalculoService::class)->ratear(
                $valorComissao,
                (float) $modelo->pc_limite_parcela,
                $parcelasParaRateio,
                $comprometidoPorParcela,
                $decimais
            );

            foreach ($resultado['alocacoes'] as $alocacao) {
                $parcela = $parcelasElegiveis->firstWhere('id', $alocacao['id_parcela']);
                $conexao->table('COMISSAO_PAGAMENTO')->insert([
                    'id_comissao_lanc' => $idLancamento,
                    'porc_parcela' => $modelo->porc_parcela,
                    'id_parcela' => $alocacao['id_parcela'],
                    'tp_parcela' => $parcela->installment_category,
                    'id_tabela_preco' => $modelo->id_tabela_preco,
                    'vl_parcela' => $parcela->original_amount,
                    'vl_comissao_parcela' => $alocacao['valor'],
                ]);
            }

            $resposta = ['message' => __('administracao.messages.comissao_processada_sucesso')];
            if ($resultado['saldo_nao_alocado'] > 0) {
                $resposta['aviso'] = __('administracao.messages.comissao_nao_coube_nas_parcelas', [
                    'nome' => $modelo->nm_parametro_comissao,
                    'saldo' => CurrencyConfig::format($resultado['saldo_nao_alocado']),
                ]);
            }

            return response()->json($resposta);
        });
    }
```

- [ ] **Step 5: Rodar e confirmar que passa**

Run: `php artisan test --filter=ContratoComissaoPosGeracaoTest`
Expected: PASS (todos os testes do arquivo, incluindo os da Task 3)

- [ ] **Step 6: Registrar a rota**

Em `routes/api.php`, dentro do grupo `Route::middleware('permission:Editar Contrato')` (mesmo grupo de `contrato.gerarParcelas`, linha ~195), adicionar:

```php
        Route::post('/administracao/contrato/{id}/comissao/{idParametroComissao}/processar', [ContratoController::class, 'processarComissaoPosGeracao'])->name('contrato.comissao.processar');
```

- [ ] **Step 7: Verificar sintaxe e rodar a suíte inteira desta área (regressão)**

Run: `php -l app/Http/Controllers/Api/Administracao/ContratoController.php && php -l routes/api.php`
Run: `php artisan test tests/Feature/Administracao/ContratoComissaoWorkflowTest.php tests/Feature/Administracao/ContratoComissaoPosGeracaoTest.php tests/Unit/Comissao/`
Expected: todos passando, nenhuma regressão nos testes já existentes

- [ ] **Step 8: Commit**

```bash
git add app/Http/Controllers/Api/Administracao/ContratoController.php routes/api.php resources/lang/pt/administracao.php resources/lang/es/administracao.php resources/lang/en/administracao.php tests/Feature/Administracao/ContratoComissaoPosGeracaoTest.php
git commit -m "feat: endpoint de processamento de comissão pós-geração (Todas/Específicas)"
```

## Task 5: Frontend — aba "Comissão" no formulário de Contrato

**Files:**
- Modify: `resources/views/administracao/contratoFormulario.blade.php`
- Modify: `resources/lang/{pt,es,en}/administracao.php` (rótulos de UI, além das mensagens da Task 4)

**Interfaces:**
- Consumes: `GET api/administracao/contrato/{id}/comissao/{idParametroComissao}/parcelas` (Task 3), `POST api/administracao/contrato/{id}/comissao/{idParametroComissao}/processar` (Task 4), `GET api/administracao/contrato/comissoesDisponiveis` (já existente), `formatarMoeda()`/`mascaraMoeda()`/`desfazerMascaraMoeda()`/`moedaPronta` (globais já existentes, `partials/scripts.blade.php`).

Esta é uma task de UI (Blade + jQuery, sem build step) — sem teste PHPUnit dedicado, consistente com o resto do formulário de Contrato (nenhuma outra aba tem teste próprio). Verificação é `php -l` + **verificação manual no navegador antes de considerar a task concluída** (CLAUDE.md exige isso pra mudança de frontend).

- [ ] **Step 1: Adicionar o botão da aba nova, depois de "Parcela"**

Em `contratoFormulario.blade.php`, logo depois do botão `tab-parcelas-tab` (linha ~47-49):

```blade
							<button class="nav-link nav-form" id="tab-comissao-tab" data-bs-toggle="tab" data-bs-target="#tab-comissao" type="button" role="tab" aria-controls="tab-comissao" aria-selected="false">{{ __('administracao.aba_comissao') }}</button>
```

(Envolvido pelo mesmo `@if($id)` que já envolve o botão de `tab-parcelas` — confirmar que ambos ficam dentro do mesmo bloco condicional.)

- [ ] **Step 2: Mover a seção de modelos vinculados da aba Pessoa pra aba Comissão nova, e adicionar a seção pós-geração**

Remover de dentro de `tab-pessoa` (linhas ~458-472, bloco `<h6>` + `<table id="tabelaComissoesContrato">` + combo + botão) e criar a aba nova logo depois de `</div> <!-- end tab-parcelas -->`:

```blade
						@if($id)
						<div class="tab-pane fade" id="tab-comissao" role="tabpanel" aria-labelledby="tab-comissao-tab">

							<h6 class="mt-2">{{ __('administracao.modelo_de_comissao') }}</h6>
							<table class="table table-sm" id="tabelaComissoesContrato">
								<thead><tr><th>{{ __('administracao.nome_do_modelo') }}</th><th style="width:90px;"></th></tr></thead>
								<tbody></tbody>
							</table>
							<div class="row mb-3" id="linhaAdicionarComissaoPreGeracao">
								<div class="col-md-6">
									<select class="form-select" id="comissao_select">
										<option value="">{{ __('administracao.selecione') }}</option>
									</select>
								</div>
								<div class="col-md-3">
									<button type="button" class="btn btn-light" id="btnAdicionarComissao">{{ __('common.add') }}</button>
								</div>
							</div>

							<div class="d-none" id="blocoComissaoPosGeracao">
								<hr>
								<h6>{{ __('administracao.adicionar_comissao_pos_geracao') }}</h6>
								<div class="row mb-3">
									<div class="col-md-6">
										<select class="form-select" id="comissao_pos_geracao_select">
											<option value="">{{ __('administracao.selecione') }}</option>
										</select>
									</div>
									<div class="col-md-3">
										<button type="button" class="btn btn-light" id="btnAdicionarComissaoPosGeracao">{{ __('common.add') }}</button>
									</div>
								</div>

								<div class="d-none" id="blocoModoComissao">
									<div class="row mb-3">
										<div class="col-md-6">
											<div class="form-check form-check-inline">
												<input class="form-check-input" type="radio" name="tp_parcela_comissao_pos" id="modoTodas" value="todas" checked>
												<label class="form-check-label" for="modoTodas">{{ __('administracao.modo_todas') }}</label>
											</div>
											<div class="form-check form-check-inline">
												<input class="form-check-input" type="radio" name="tp_parcela_comissao_pos" id="modoEspecificas" value="especificas">
												<label class="form-check-label" for="modoEspecificas">{{ __('administracao.modo_especificas') }}</label>
											</div>
										</div>
									</div>

									<div class="d-none" id="blocoParcelasEspecificas">
										<p class="mb-1">{{ __('administracao.total_a_distribuir') }}: <strong id="comissaoEspecificaTotal">---</strong></p>
										<div class="table-responsive">
											<table class="table table-sm" id="tabelaComissaoEspecifica">
												<thead>
													<tr>
														<th></th>
														<th>{{ __('administracao.numero_da_parcela') }}</th>
														<th>{{ __('administracao.data_vencimento') }}</th>
														<th>{{ __('administracao.valor_original') }}</th>
														<th>%</th>
														<th>{{ __('administracao.valor_comissao') }}</th>
														<th>{{ __('administracao.comissao_comprometida') }}</th>
													</tr>
												</thead>
												<tbody></tbody>
											</table>
										</div>
									</div>

									<button type="button" class="btn btn-success" id="btnConfirmarComissaoPosGeracao">{{ __('common.save') }}</button>
									<button type="button" class="btn btn-light" id="btnCancelarComissaoPosGeracao">{{ __('common.cancel') }}</button>
								</div>
							</div>

						</div> <!-- end tab-comissao -->
						@endif
```

- [ ] **Step 3: JS — resolver `fl_gerado` e alternar visibilidade da seção pós-geração**

Dentro do `window.onload` principal (mesmo escopo do JS já existente de `comissoesContrato`, perto da linha ~680), adicionar:

```javascript
	var flGerado = null; // setado dentro do success do GET api/administracao/contrato/{id} já existente (ver abaixo) — não há função nomeada reaproveitável ali, é um bloco $.ajax inline (contratoFormulario.blade.php:1016-1019).

	function aplicarVisibilidadeComissaoPosGeracao() {
		$('#blocoComissaoPosGeracao').toggleClass('d-none', flGerado !== '1');
	}
```

Localizar o `success` já existente do `GET api/administracao/contrato/' + id` (callback que hoje preenche `comissoesContrato` na linha ~1063) e adicionar, dentro dele:

```javascript
					flGerado = data.fl_gerado;
					aplicarVisibilidadeComissaoPosGeracao();
					if (flGerado === '1') { carregarComboComissaoPosGeracao(); }
```

- [ ] **Step 4: JS — combo de modelos ainda não processados + escolha de modo**

```javascript
	function carregarComboComissaoPosGeracao() {
		$.ajax({
			url: url + 'api/administracao/contrato/comissoesDisponiveis',
			headers: { 'Authorization': `Bearer ${token.access_token}` },
			success: function (comissoes) {
				var select = $('#comissao_pos_geracao_select');
				select.empty().append('<option value="">' + '{{ __("administracao.selecione") }}' + '</option>');
				comissoes.forEach(function (c) {
					select.append($('<option>', { value: c.id, text: c.text, 'data-modalidade': c.tp_modalidade, 'data-parcela-paga': c.parcela_paga }));
				});
			}
		});
	}

	var idModeloPosGeracaoAtual = null;

	$('#comissao_pos_geracao_select').on('change', function () {
		var opcao = $(this).find(':selected');
		var permiteEscolha = opcao.data('modalidade') === 'parcela' && String(opcao.data('parcela-paga')) === '1';
		$('#blocoModoComissao').toggleClass('d-none', !$(this).val());
		$('.form-check-inline', '#blocoModoComissao').toggle(permiteEscolha);
		if (!permiteEscolha) { $('#modoTodas').prop('checked', true); }
		$('#blocoParcelasEspecificas').addClass('d-none');
	});

	$('#btnAdicionarComissaoPosGeracao').on('click', function () {
		idModeloPosGeracaoAtual = $('#comissao_pos_geracao_select').val();
		if (!idModeloPosGeracaoAtual) { return; }
		$('#blocoModoComissao').removeClass('d-none');
	});

	$('input[name="tp_parcela_comissao_pos"]').on('change', function () {
		if ($(this).val() === 'especificas' && idModeloPosGeracaoAtual) {
			carregarPickerEspecificas(idModeloPosGeracaoAtual);
		} else {
			$('#blocoParcelasEspecificas').addClass('d-none');
		}
	});
```

- [ ] **Step 5: JS — picker de "Específicas" (consome o endpoint da Task 3)**

```javascript
	function carregarPickerEspecificas(idModelo) {
		$.ajax({
			url: url + 'api/administracao/contrato/' + id + '/comissao/' + idModelo + '/parcelas',
			headers: { 'Authorization': `Bearer ${token.access_token}` },
			success: function (resposta) {
				$('#comissaoEspecificaTotal').text(formatarMoeda(resposta.modelo.valor_total_comissao));
				var tbody = $('#tabelaComissaoEspecifica tbody');
				tbody.empty();
				resposta.parcelas.forEach(function (p) {
					var marcado = p.valor_selecionado !== null;
					var valorInicial = marcado ? p.valor_selecionado : '';
					var percInicial = marcado && p.original_amount > 0 ? (p.valor_selecionado / p.original_amount * 100).toFixed(2).replace('.', ',') : '';
					tbody.append(
						'<tr data-id-parcela="' + p.id + '" data-valor-parcela="' + p.original_amount + '">' +
							'<td><input type="checkbox" class="chkParcelaEspecifica"' + (marcado ? ' checked' : '') + '></td>' +
							'<td>' + (p.installment_number ?? '---') + '</td>' +
							'<td>' + (p.due_date ? new Date(p.due_date).toLocaleDateString('pt-BR', { timeZone: 'UTC' }) : '---') + '</td>' +
							'<td>' + formatarMoeda(p.original_amount) + '</td>' +
							'<td><input type="text" class="form-control form-control-sm percParcelaEspecifica" value="' + percInicial + '" disabled="' + !marcado + '"></td>' +
							'<td><input type="text" class="form-control form-control-sm valorParcelaEspecifica" value="' + (valorInicial !== '' ? formatarValorMascara(valorInicial) : '') + '" disabled="' + !marcado + '"></td>' +
							'<td>' + formatarMoeda(p.comissao_comprometida) + '</td>' +
						'</tr>'
					);
				});
				$('.percParcelaEspecifica, .valorParcelaEspecifica').mask(mascaraMoeda(), { reverse: true });
				$('#blocoParcelasEspecificas').removeClass('d-none');
			}
		});
	}

	$('#tabelaComissaoEspecifica').on('change', '.chkParcelaEspecifica', function () {
		var marcado = $(this).is(':checked');
		$(this).closest('tr').find('.percParcelaEspecifica, .valorParcelaEspecifica').prop('disabled', !marcado);
	});

	$('#tabelaComissaoEspecifica').on('input', '.valorParcelaEspecifica', function () {
		var linha = $(this).closest('tr');
		var valorParcela = parseFloat(linha.data('valor-parcela'));
		var valor = desfazerMascaraMoeda($(this).val());
		linha.find('.percParcelaEspecifica').val(valorParcela > 0 ? (valor / valorParcela * 100).toFixed(2).replace('.', ',') : '0,00');
	});

	$('#tabelaComissaoEspecifica').on('input', '.percParcelaEspecifica', function () {
		var linha = $(this).closest('tr');
		var valorParcela = parseFloat(linha.data('valor-parcela'));
		var perc = parseFloat($(this).val().replace(',', '.')) || 0;
		linha.find('.valorParcelaEspecifica').val(formatarValorMascara(valorParcela * perc / 100));
	});
```

- [ ] **Step 6: JS — salvar (Todas ou Específicas) consumindo o endpoint da Task 4**

```javascript
	$('#btnConfirmarComissaoPosGeracao').on('click', function () {
		var modo = $('input[name="tp_parcela_comissao_pos"]:checked').val();
		var nomeModelo = $('#comissao_pos_geracao_select option:selected').text();
		var payload = { tp_parcela_comissao: modo };

		if (modo === 'especificas') {
			payload.parcelas = [];
			$('#tabelaComissaoEspecifica tbody tr').each(function () {
				if (!$(this).find('.chkParcelaEspecifica').is(':checked')) { return; }
				payload.parcelas.push({
					id_parcela: $(this).data('id-parcela'),
					valor: desfazerMascaraMoeda($(this).find('.valorParcelaEspecifica').val())
				});
			});
		}

		$.ajax({
			url: url + 'api/administracao/contrato/' + id + '/comissao/' + idModeloPosGeracaoAtual + '/processar',
			method: 'POST',
			data: payload,
			headers: { 'Authorization': `Bearer ${token.access_token}` },
			success: function (resposta) {
				if (resposta.aviso) { alert(resposta.aviso); }
				var rotuloModo = modo === 'especificas' ? '{{ __("administracao.modo_especificas") }}' : '{{ __("administracao.modo_todas") }}';
				$('#tabelaComissoesProcessadas tbody').append('<tr><td>' + nomeModelo + ' (' + rotuloModo + ')</td></tr>');
				$('#blocoModoComissao').addClass('d-none');
				$('#comissao_pos_geracao_select').val('');
				idModeloPosGeracaoAtual = null;
				carregarComboComissaoPosGeracao(); // modelo recém-processado some da lista "ainda não vinculados"
			},
			error: function (xhr) { alert(xhr.responseJSON?.message || '{{ __("common.error_unexpected") }}'); }
		});
	});

	$('#btnCancelarComissaoPosGeracao').on('click', function () {
		$('#blocoModoComissao').addClass('d-none');
		$('#comissao_pos_geracao_select').val('');
		idModeloPosGeracaoAtual = null;
	});
```

- [ ] **Step 7: JS — lista somente-leitura de modelos já processados (reaproveita `show()`, estendido na Task 2)**

Não é uma chamada nova — `GET api/administracao/contrato/{id}` (já consumida por este mesmo form pra carregar o resto do contrato) agora devolve, em cada item de `comissoes`, `processado` e `tp_parcela_comissao` (Task 2, Step 8). Em `contratoFormulario.blade.php:1062-1065`, dentro do `success` já existente desse GET, substituir:

```javascript
						(data.comissoes || []).forEach(function (c) {
							comissoesContrato.push({ id: c.id, nome: c.nome });
						});
						renderComissoesContrato();
```

por:

```javascript
						(data.comissoes || []).forEach(function (c) {
							if (c.processado) {
								$('#tabelaComissoesProcessadas tbody').append(
									'<tr><td>' + c.nome + ' (' + (c.tp_parcela_comissao === 'especificas' ? '{{ __("administracao.modo_especificas") }}' : '{{ __("administracao.modo_todas") }}') + ')</td></tr>'
								);
							} else {
								comissoesContrato.push({ id: c.id, nome: c.nome });
							}
						});
						renderComissoesContrato();
```

Adicionar a tabela nova no HTML do Step 2 desta mesma task, dentro de `#blocoComissaoPosGeracao`, antes do `<hr>`:

```blade
								<h6 class="mt-2">{{ __('administracao.comissoes_ja_processadas') }}</h6>
								<table class="table table-sm" id="tabelaComissoesProcessadas">
									<thead><tr><th>{{ __('administracao.nome_do_modelo') }}</th></tr></thead>
									<tbody></tbody>
								</table>
```

E remover a chamada a `carregarListaComissoesProcessadas()` mencionada no Step 3 (não existe mais como requisição à parte — a lista vem junto do `GET` que o form já faz).

- [ ] **Step 8: Rótulos novos em `resources/lang/{pt,es,en}/administracao.php`**

`pt/administracao.php`:
```php
        'aba_comissao' => 'Comissão',
        'adicionar_comissao_pos_geracao' => 'Adicionar comissão',
        'modo_todas' => 'Todas',
        'modo_especificas' => 'Específicas',
        'total_a_distribuir' => 'Total a distribuir',
        'valor_comissao' => 'Valor da comissão',
        'comissao_comprometida' => 'Comissão comprometida',
```

`es/administracao.php`:
```php
        'aba_comissao' => 'Comisión',
        'adicionar_comissao_pos_geracao' => 'Agregar comisión',
        'modo_todas' => 'Todas',
        'modo_especificas' => 'Específicas',
        'total_a_distribuir' => 'Total a distribuir',
        'valor_comissao' => 'Valor de la comisión',
        'comissao_comprometida' => 'Comisión comprometida',
```

`en/administracao.php`:
```php
        'aba_comissao' => 'Commission',
        'adicionar_comissao_pos_geracao' => 'Add commission',
        'modo_todas' => 'All',
        'modo_especificas' => 'Specific',
        'total_a_distribuir' => 'Total to distribute',
        'valor_comissao' => 'Commission amount',
        'comissao_comprometida' => 'Committed commission',
```

- [ ] **Step 9: Verificar sintaxe**

Run: `php -l resources/views/administracao/contratoFormulario.blade.php`
Expected: `No syntax errors detected`

- [ ] **Step 10: Verificação manual no navegador (obrigatória por CLAUDE.md pra mudança de frontend)**

Abrir um contrato existente (com e sem parcela gerada) no navegador e confirmar:
- Aba "Comissão" aparece depois de "Parcela", só em modo edição.
- Antes de gerar parcela: comportamento idêntico ao de hoje (vincular/desvincular modelo, salvar junto com o resto do contrato).
- Depois de gerar parcela: seção "Adicionar comissão" aparece; escolher um modelo `parcela`+`parcela_paga=1` mostra o rádio Todas/Específicas; "Específicas" carrega a tabela de parcelas reais com comprometida; salvar grava e reflete na lista de processados.
- Tentar estourar o valor de uma parcela em "Específicas" mostra o erro 422 vindo do backend.

- [ ] **Step 11: Commit**

```bash
git add resources/views/administracao/contratoFormulario.blade.php resources/lang/pt/administracao.php resources/lang/es/administracao.php resources/lang/en/administracao.php
git commit -m "feat: aba Comissão no formulário de Contrato com modo Específicas"
```
