# Cadastro de Comissão + Aplicação no Contrato 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:** Permitir montar um "modelo de comissão" (parceiro + modalidade de cálculo), independente de contrato, e aplicar um ou mais desses modelos num contrato — gerando automaticamente `COMISSAO_LANCAMENTO`/`COMISSAO_PAGAMENTO` reais quando as parcelas do contrato são geradas.

**Architecture:** `PARAMETRO_COMISSAO` (hoje órfã) ganha os campos do "modelo"; uma tabela pivot nova (`CONTRATO_PARAMETRO_COMISSAO`) liga N modelos a um contrato; o cálculo em si (valor da comissão + rateio por parcela) vive num Service novo, puro (sem banco), chamado de dentro de `ContratoController::gerarParcelas()` — mesmo hook já usado por outras features deste controller.

**Tech Stack:** Laravel 10, PHPUnit (SQLite `:memory:` pra testes de feature na conexão `cliente`, mesmo padrão de `tests/Feature/Administracao/DistratoWorkflowTest.php`), Blade + jQuery (sem build step).

**Spec:** `docs/superpowers/specs/2026-10-20-cadastro-comissao-design.md`

## Global Constraints

- Conexão `cliente` pra tudo que é dado do tenant (`PARAMETRO_COMISSAO`, `CONTRATO_PARAMETRO_COMISSAO`, `COMISSAO_LANCAMENTO`, `COMISSAO_PAGAMENTO`, `CONTRATO`, `receivables`) — nunca a conexão default.
- Sem `doctrine/dbal` — qualquer `ALTER` em coluna existente usa `DB::statement('ALTER TABLE ... MODIFY ...')`, nunca `->change()`.
- Sem route model binding em rota sob `cliente.auth` — sempre `Model::findOrFail($id)` dentro do método.
- Valores monetários respeitam `CurrencyConfig::getConfig()['decimals']` (0 casas pra PYG) — nunca `round($v, 2)` fixo.
- Testes de feature usam SQLite `:memory:` na conexão `cliente` (ver Task 8 pro setup completo) — nunca dependem de um banco MySQL real rodando.
- Todos os textos de tela novos passam por `__()`, 3 idiomas (pt/es/en) — nunca hardcoded.
- Só 1 parceiro de comissão por contrato **não** se aplica aqui — múltiplos parceiros entram nesta entrega (decisão final da spec).

---

## Task 1: Migration — `PARAMETRO_COMISSAO` vira "modelo de comissão"

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

**Interfaces:**
- Produces: colunas `id_parceiro`, `id_pessoa_parceiro`, `tp_modalidade`, `porc_venda`, `vl_fixo`, `porc_parcela`, `tp_parcela`, `id_tabela_preco`, `parcela_paga`, `pc_limite_parcela` em `PARAMETRO_COMISSAO` — usadas por todas as tasks seguintes.

- [ ] **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;

// Transforma PARAMETRO_COMISSAO (até aqui órfã — nenhum código além do próprio
// CRUD morto a lia, confirmado por grep) no "modelo de comissão" reutilizável
// descrito em docs/superpowers/specs/2026-10-20-cadastro-comissao-design.md. As
// colunas antigas (tp_comissao, tp_local_insidencia, vl_corretor etc., de um
// conceito diferente — split fixo por papel) viram nullable: a tela nova não as
// preenche, e elas eram NOT NULL sem default no schema original (CreateParametroComissaoTable).
//
// Cada coluna nova é condicional (hasColumn) — achado real no pre-flight: tenants
// herdados de dump do acadeLotear podem já ter `tp_parcela` em PARAMETRO_COMISSAO
// (coluna "copiada por engano de PARCELA_HISTORICO", ver migration
// 2026_10_09_100000_make_copied_installment_fields_nullable_on_parametro_comissao.php,
// que só existe porque ela já estava lá nesses tenants — nenhuma migration deste
// repo a cria, ela vem do dump). Adicionar sem guarda estouraria "Duplicate column
// name" nesses tenants. Mesmo padrão defensivo já usado na migration citada acima.
return new class extends Migration
{
    private const COLUNAS_NOVAS = [
        'id_parceiro' => ['tipo' => 'integer', 'depois_de' => 'id_empreendimento'],
        'id_pessoa_parceiro' => ['tipo' => 'integer', 'depois_de' => 'id_parceiro'],
        'tp_modalidade' => ['tipo' => 'string10', 'depois_de' => 'id_pessoa_parceiro'],
        'porc_venda' => ['tipo' => 'decimal5_2', 'depois_de' => 'tp_modalidade'],
        'vl_fixo' => ['tipo' => 'decimal15_2', 'depois_de' => 'porc_venda'],
        'porc_parcela' => ['tipo' => 'decimal5_2', 'depois_de' => 'vl_fixo'],
        'tp_parcela' => ['tipo' => 'string15', 'depois_de' => 'porc_parcela'],
        'id_tabela_preco' => ['tipo' => 'integer', 'depois_de' => 'tp_parcela'],
        'parcela_paga' => ['tipo' => 'string1', 'depois_de' => 'id_tabela_preco'],
        'pc_limite_parcela' => ['tipo' => 'decimal5_2', 'depois_de' => 'parcela_paga'],
    ];

    public function up(): void
    {
        // Sem ->change() (doctrine/dbal não está instalado — ver rules/backend.md)
        // — ALTER bruto pra tornar nullable colunas que a tela nova não preenche.
        DB::statement('ALTER TABLE `PARAMETRO_COMISSAO` MODIFY `id_empreendimento` INT NULL');
        DB::statement("ALTER TABLE `PARAMETRO_COMISSAO` MODIFY `tp_comissao` ENUM('F','P') NULL");
        DB::statement("ALTER TABLE `PARAMETRO_COMISSAO` MODIFY `tp_local_insidencia` ENUM('S','P','TI') NULL");
        DB::statement('ALTER TABLE `PARAMETRO_COMISSAO` MODIFY `qt_parcela_comissao` INT NULL');

        Schema::table('PARAMETRO_COMISSAO', function (Blueprint $table) {
            foreach (self::COLUNAS_NOVAS as $coluna => $info) {
                if (Schema::hasColumn('PARAMETRO_COMISSAO', $coluna)) {
                    continue; // já existe (legado de dump ou rerun) — não recria.
                }

                match ($info['tipo']) {
                    'integer' => $table->integer($coluna)->nullable()->after($info['depois_de']),
                    'string10' => $table->string($coluna, 10)->nullable()->after($info['depois_de']),
                    'string15' => $table->string($coluna, 15)->nullable()->after($info['depois_de']),
                    'string1' => $table->string($coluna, 1)->nullable()->after($info['depois_de']),
                    'decimal15_2' => $table->decimal($coluna, 15, 2)->nullable()->after($info['depois_de']),
                    'decimal5_2' => $table->decimal($coluna, 5, 2)->nullable()->after($info['depois_de']),
                };
            }
        });
    }

    public function down(): void
    {
        // Não reverte — em tenants herdados de dump, `tp_parcela` é legado (não foi
        // esta migration que o criou); dropar indiscriminadamente arriscaria apagar
        // dado de outro schema. Mesmo padrão de down() no-op já usado em
        // 2026_10_09_100000_make_copied_installment_fields_nullable_on_parametro_comissao.php.
        // Também não reverte a nullability das colunas antigas — reimpor NOT NULL
        // sem default quebraria qualquer modelo novo criado sem elas.
    }
};
```

- [ ] **Step 2: Conferir sintaxe**

Run: `docker compose exec app php -l database/migrations/clientes/2026_10_20_100000_add_modelo_fields_to_parametro_comissao_table.php` (ou `php -l` direto se ambiente nativo)
Expected: `No syntax errors detected`

- [ ] **Step 3: Commit**

```bash
git add database/migrations/clientes/2026_10_20_100000_add_modelo_fields_to_parametro_comissao_table.php
git commit -m "feat: adiciona campos de modelo de comissao em PARAMETRO_COMISSAO"
```

---

## Task 2: Migration — tabela pivot `CONTRATO_PARAMETRO_COMISSAO`

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

**Interfaces:**
- Produces: tabela `CONTRATO_PARAMETRO_COMISSAO` (`id`, `id_contrato`, `id_parametro_comissao`) — usada pelas Tasks 8-10.

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

```php
<?php

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

// Pivot N:N entre CONTRATO e PARAMETRO_COMISSAO (múltiplos parceiros de comissão
// por contrato — ver docs/superpowers/specs/2026-10-20-cadastro-comissao-design.md).
// CONTRATO.id_parametro_comissao (coluna antiga, já existia) continua morta: uma
// FK simples não serve mais depois dessa decisão. Sem FK real (schema legado,
// mesmo padrão do resto do projeto). A ordem "em que foi adicionado" (usada no
// algoritmo de rateio) é lida por `id` ascendente — sem coluna de ordem própria.
//
// Índice único (não só índice simples) em (id_contrato, id_parametro_comissao)
// — achado do task review (20/10/2026): sem isso, nada impede o mesmo modelo de
// comissão ser vinculado duas vezes ao mesmo contrato, duplicando o lançamento
// em COMISSAO_LANCAMENTO. Nome explícito curto porque o nome que o Laravel
// geraria por convenção estoura o limite de 64 caracteres do MySQL.
return new class extends Migration
{
    public function up(): void
    {
        Schema::create('CONTRATO_PARAMETRO_COMISSAO', function (Blueprint $table) {
            $table->id();
            $table->integer('id_contrato');
            $table->integer('id_parametro_comissao');
            $table->unique(['id_contrato', 'id_parametro_comissao'], 'ux_contrato_parametro_comissao');
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('CONTRATO_PARAMETRO_COMISSAO');
    }
};
```

- [ ] **Step 2: Conferir sintaxe**

Run: `docker compose exec app php -l database/migrations/clientes/2026_10_20_100100_create_contrato_parametro_comissao_table.php`
Expected: `No syntax errors detected`

- [ ] **Step 3: Commit**

```bash
git add database/migrations/clientes/2026_10_20_100100_create_contrato_parametro_comissao_table.php
git commit -m "feat: cria tabela pivot CONTRATO_PARAMETRO_COMISSAO"
```

---

## Task 3: Model `ParametroComissao` — novos campos + relação com Contrato

**Files:**
- Modify: `app/Models/Vendas/ParametroComissao.php`

**Interfaces:**
- Consumes: colunas da Task 1.
- Produces: `ParametroComissao::$fillable` com os campos novos — usado pelas Tasks 5, 6, 10, 11.

- [ ] **Step 1: Atualizar `$fillable`**

Arquivo atual (linhas 19-31):

```php
    protected $fillable = [
        'id_empreendimento',
        'tp_comissao',
        'tp_local_insidencia',
        'vl_corretor',
        'vl_coordenador',
        'vl_indicador',
        'vl_imobiliaria',
        'vl_outros',
        'qt_parcela_comissao',
        'nm_parametro_comissao',
        'ds_log',
    ];
```

Substituir por:

```php
    protected $fillable = [
        'id_empreendimento',
        'tp_comissao',
        'tp_local_insidencia',
        'vl_corretor',
        'vl_coordenador',
        'vl_indicador',
        'vl_imobiliaria',
        'vl_outros',
        'qt_parcela_comissao',
        'nm_parametro_comissao',
        'ds_log',
        'id_parceiro',
        'id_pessoa_parceiro',
        'tp_modalidade',
        'porc_venda',
        'vl_fixo',
        'porc_parcela',
        'tp_parcela',
        'id_tabela_preco',
        'parcela_paga',
        'pc_limite_parcela',
    ];
```

- [ ] **Step 2: Rodar `php -l` no arquivo**

Run: `docker compose exec app php -l app/Models/Vendas/ParametroComissao.php`
Expected: `No syntax errors detected`

- [ ] **Step 3: Commit**

```bash
git add app/Models/Vendas/ParametroComissao.php
git commit -m "feat: adiciona campos de modelo de comissao ao fillable de ParametroComissao"
```

---

## Task 4: Corrigir relação quebrada `ComissaoPagamento::parcela()`

**Files:**
- Modify: `app/Models/Vendas/ComissaoPagamento.php`
- Test: `tests/Unit/Vendas/ComissaoPagamentoRelacaoTest.php`

**Interfaces:**
- Consumes: `App\Models\Vendas\Parcela` (já existe, `$table = 'receivables'`, PK `id`).
- Produces: `ComissaoPagamento::parcela()` correta — necessária pra Task 10 calcular comprometimento.

- [ ] **Step 1: Escrever o teste que expõe o bug atual**

```php
<?php

namespace Tests\Unit\Vendas;

use App\Models\Vendas\ComissaoPagamento;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Tests\TestCase;

class ComissaoPagamentoRelacaoTest extends TestCase
{
    public function test_relacao_parcela_aponta_para_a_coluna_id_real_de_receivables(): void
    {
        $relacao = (new ComissaoPagamento())->parcela();

        $this->assertInstanceOf(BelongsTo::class, $relacao);
        $this->assertSame('id_parcela', $relacao->getForeignKeyName());
        $this->assertSame('id', $relacao->getOwnerKeyName());
    }
}
```

- [ ] **Step 2: Rodar o teste pra confirmar que falha**

Run: `docker compose exec app php artisan test --filter=ComissaoPagamentoRelacaoTest`
Expected: FAIL — `getOwnerKeyName()` retorna `id_parcela_contrato`, não `id`.

- [ ] **Step 3: Corrigir a relação**

Arquivo atual:

```php
    public function parcela()
    {
        return $this->belongsTo(Parcela::class, 'id_parcela', 'id_parcela_contrato');
    }
```

Substituir por:

```php
    // Corrigido 20/10/2026 — 'id_parcela_contrato' não existe em receivables/Parcela
    // (a PK real é 'id', herdada de Receivable). Relação nunca tinha sido exercitada
    // de verdade até esta entrega (ver docs/superpowers/specs/2026-10-20-cadastro-comissao-design.md).
    public function parcela()
    {
        return $this->belongsTo(Parcela::class, 'id_parcela', 'id');
    }
```

- [ ] **Step 4: Rodar o teste de novo**

Run: `docker compose exec app php artisan test --filter=ComissaoPagamentoRelacaoTest`
Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add app/Models/Vendas/ComissaoPagamento.php tests/Unit/Vendas/ComissaoPagamentoRelacaoTest.php
git commit -m "fix: corrige relacao quebrada ComissaoPagamento::parcela()"
```

---

## Task 5: `ComissaoCalculoService::calcularValorComissao()`

**Files:**
- Create: `app/Services/Comissao/ComissaoCalculoService.php`
- Test: `tests/Unit/Comissao/ComissaoCalculoServiceTest.php`

**Interfaces:**
- Consumes: `App\Models\Vendas\ParametroComissao` (campo `tp_modalidade`, `porc_venda`, `vl_fixo`, `porc_parcela`).
- Produces: `ComissaoCalculoService::calcularValorComissao(ParametroComissao $modelo, float $base, int $decimais = 2): float` — usado pela Task 10.

- [ ] **Step 1: Escrever os testes (falhando — a classe ainda não existe)**

```php
<?php

namespace Tests\Unit\Comissao;

use App\Models\Vendas\ParametroComissao;
use App\Services\Comissao\ComissaoCalculoService;
use Tests\TestCase;

class ComissaoCalculoServiceTest extends TestCase
{
    private ComissaoCalculoService $service;

    protected function setUp(): void
    {
        parent::setUp();
        $this->service = new ComissaoCalculoService();
    }

    public function test_modalidade_venda_calcula_percentual_sobre_a_base(): void
    {
        $modelo = new ParametroComissao(['tp_modalidade' => 'venda', 'porc_venda' => 8]);

        $valor = $this->service->calcularValorComissao($modelo, 10000.0);

        $this->assertSame(800.0, $valor);
    }

    public function test_modalidade_fixo_ignora_a_base_e_devolve_o_valor_fixo(): void
    {
        $modelo = new ParametroComissao(['tp_modalidade' => 'fixo', 'vl_fixo' => 500]);

        $valor = $this->service->calcularValorComissao($modelo, 999999.0);

        $this->assertSame(500.0, $valor);
    }

    public function test_modalidade_parcela_usa_porc_parcela(): void
    {
        $modelo = new ParametroComissao(['tp_modalidade' => 'parcela', 'porc_parcela' => 10, 'tp_parcela' => 'N']);

        $valor = $this->service->calcularValorComissao($modelo, 2000.0);

        $this->assertSame(200.0, $valor);
    }

    public function test_modalidade_tabela_usa_porc_parcela(): void
    {
        $modelo = new ParametroComissao(['tp_modalidade' => 'tabela', 'porc_parcela' => 5, 'id_tabela_preco' => 1]);

        $valor = $this->service->calcularValorComissao($modelo, 40000.0);

        $this->assertSame(2000.0, $valor);
    }

    public function test_respeita_a_quantidade_de_casas_decimais_da_moeda(): void
    {
        $modelo = new ParametroComissao(['tp_modalidade' => 'venda', 'porc_venda' => 10]);

        $valor = $this->service->calcularValorComissao($modelo, 15000.0, 0);

        $this->assertSame(1500.0, $valor);
    }
}
```

- [ ] **Step 2: Rodar os testes pra confirmar que falham**

Run: `docker compose exec app php artisan test --filter=ComissaoCalculoServiceTest`
Expected: FAIL — `Class "App\Services\Comissao\ComissaoCalculoService" not found`

- [ ] **Step 3: Implementar a classe**

```php
<?php

namespace App\Services\Comissao;

use App\Models\Vendas\ParametroComissao;

/**
 * Cálculo puro da comissão (valor total e rateio por parcela) — sem acesso a
 * banco, pra ser testável com dados de exemplo. O acesso a dado real (valor do
 * contrato, parcelas geradas, tabela de preço) é responsabilidade de quem chama
 * (ContratoController::gerarParcelas()) — ver
 * docs/superpowers/specs/2026-10-20-cadastro-comissao-design.md.
 */
class ComissaoCalculoService
{
    /**
     * Calcula o valor final da comissão (vl_comissao_total) conforme a
     * modalidade do modelo. $base é o valor de referência já calculado pelo
     * chamador (total do contrato, soma das parcelas do tipo escolhido, ou
     * valor da tabela de preço) — ignorado quando a modalidade é 'fixo'.
     */
    public function calcularValorComissao(ParametroComissao $modelo, float $base, int $decimais = 2): float
    {
        if ($modelo->tp_modalidade === 'fixo') {
            return round((float) $modelo->vl_fixo, $decimais);
        }

        $percentual = $modelo->tp_modalidade === 'venda'
            ? (float) $modelo->porc_venda
            : (float) $modelo->porc_parcela;

        return round($base * $percentual / 100, $decimais);
    }
}
```

- [ ] **Step 4: Rodar os testes de novo**

Run: `docker compose exec app php artisan test --filter=ComissaoCalculoServiceTest`
Expected: PASS (5 testes)

- [ ] **Step 5: Commit**

```bash
git add app/Services/Comissao/ComissaoCalculoService.php tests/Unit/Comissao/ComissaoCalculoServiceTest.php
git commit -m "feat: calculo das 4 modalidades de comissao (ComissaoCalculoService)"
```

---

## Task 6: `ComissaoCalculoService::ratear()` — algoritmo "Todas até completar"

**Files:**
- Modify: `app/Services/Comissao/ComissaoCalculoService.php`
- Test: `tests/Unit/Comissao/ComissaoCalculoServiceTest.php`

**Interfaces:**
- Produces: `ComissaoCalculoService::ratear(float $totalComissao, float $pcLimiteParcela, array $parcelas, array $comprometidoPorParcela, int $decimais = 2): array{alocacoes: array, saldo_nao_alocado: float}` — usado pela Task 10.

- [ ] **Step 1: Acrescentar os testes do rateio (falhando — método ainda não existe)**

Acrescentar ao final da classe `ComissaoCalculoServiceTest` (depois do último teste da Task 5):

```php

    public function test_rateio_fecha_exatamente_quando_o_limite_e_suficiente(): void
    {
        $resultado = $this->service->ratear(
            totalComissao: 300.0,
            pcLimiteParcela: 10,
            parcelas: [
                ['id' => 1, 'valor' => 1000.0],
                ['id' => 2, 'valor' => 1000.0],
                ['id' => 3, 'valor' => 1000.0],
            ],
            comprometidoPorParcela: []
        );

        $this->assertSame([
            ['id_parcela' => 1, 'valor' => 100.0],
            ['id_parcela' => 2, 'valor' => 100.0],
            ['id_parcela' => 3, 'valor' => 100.0],
        ], $resultado['alocacoes']);
        $this->assertSame(0.0, $resultado['saldo_nao_alocado']);
    }

    public function test_rateio_para_de_alocar_assim_que_o_saldo_fecha(): void
    {
        $resultado = $this->service->ratear(
            totalComissao: 150.0,
            pcLimiteParcela: 10,
            parcelas: [
                ['id' => 1, 'valor' => 1000.0],
                ['id' => 2, 'valor' => 1000.0],
                ['id' => 3, 'valor' => 1000.0],
            ],
            comprometidoPorParcela: []
        );

        $this->assertSame([
            ['id_parcela' => 1, 'valor' => 100.0],
            ['id_parcela' => 2, 'valor' => 50.0],
        ], $resultado['alocacoes']);
        $this->assertSame(0.0, $resultado['saldo_nao_alocado']);
    }

    public function test_rateio_avisa_quando_o_limite_nao_fecha_o_total(): void
    {
        $resultado = $this->service->ratear(
            totalComissao: 1000.0,
            pcLimiteParcela: 10,
            parcelas: [
                ['id' => 1, 'valor' => 1000.0],
                ['id' => 2, 'valor' => 1000.0],
            ],
            comprometidoPorParcela: []
        );

        $this->assertSame([
            ['id_parcela' => 1, 'valor' => 100.0],
            ['id_parcela' => 2, 'valor' => 100.0],
        ], $resultado['alocacoes']);
        $this->assertSame(800.0, $resultado['saldo_nao_alocado']);
    }

    public function test_rateio_respeita_o_que_outra_comissao_ja_comprometeu_na_mesma_parcela(): void
    {
        $resultado = $this->service->ratear(
            totalComissao: 200.0,
            pcLimiteParcela: 50,
            parcelas: [
                ['id' => 1, 'valor' => 1000.0],
            ],
            comprometidoPorParcela: [1 => 480.0]
        );

        $this->assertSame([
            ['id_parcela' => 1, 'valor' => 20.0],
        ], $resultado['alocacoes']);
        $this->assertSame(180.0, $resultado['saldo_nao_alocado']);
    }

    public function test_rateio_pula_parcela_totalmente_comprometida_sem_gerar_alocacao_zerada(): void
    {
        $resultado = $this->service->ratear(
            totalComissao: 100.0,
            pcLimiteParcela: 50,
            parcelas: [
                ['id' => 1, 'valor' => 1000.0],
                ['id' => 2, 'valor' => 1000.0],
            ],
            comprometidoPorParcela: [1 => 500.0]
        );

        $this->assertSame([
            ['id_parcela' => 2, 'valor' => 100.0],
        ], $resultado['alocacoes']);
        $this->assertSame(0.0, $resultado['saldo_nao_alocado']);
    }
```

- [ ] **Step 2: Rodar os testes pra confirmar que falham**

Run: `docker compose exec app php artisan test --filter=ComissaoCalculoServiceTest`
Expected: FAIL — `Call to undefined method ...::ratear()`

- [ ] **Step 3: Implementar `ratear()`**

Acrescentar à classe `ComissaoCalculoService` (depois de `calcularValorComissao`):

```php

    /**
     * Rateia $totalComissao entre as parcelas, na ordem recebida (deve vir
     * ordenado por vencimento), respeitando o % limite por parcela E o que já
     * foi comprometido por outras comissões do mesmo contrato.
     *
     * @param array<int, array{id: int, valor: float}> $parcelas
     * @param array<int, float> $comprometidoPorParcela chave = id da parcela
     * @return array{alocacoes: array<int, array{id_parcela: int, valor: float}>, saldo_nao_alocado: float}
     */
    public function ratear(
        float $totalComissao,
        float $pcLimiteParcela,
        array $parcelas,
        array $comprometidoPorParcela,
        int $decimais = 2
    ): array {
        $saldo = round($totalComissao, $decimais);
        $alocacoes = [];

        foreach ($parcelas as $parcela) {
            if ($saldo <= 0) {
                break;
            }

            $comprometido = $comprometidoPorParcela[$parcela['id']] ?? 0.0;
            $tetoLimite = max($parcela['valor'] * $pcLimiteParcela / 100, 0);
            // $comprometido já consome o TETO (pc_limite_parcela% da parcela), não o
            // valor cheio da parcela — é o que outra comissão já alocou ali dentro
            // desse mesmo teto. Usar $parcela['valor'] aqui (em vez de $tetoLimite)
            // deixaria cada comissão calcular seu próprio teto contra o valor cheio,
            // ignorando o que as outras já consumiram DENTRO do teto compartilhado —
            // bug real encontrado rodando os testes desta própria task antes do
            // dispatch (as 2 asserções de comprometimento cruzado abaixo falhavam).
            $tetoReal = max($tetoLimite - $comprometido, 0);

            $valorAlocado = round(min($tetoReal, $saldo), $decimais);

            if ($valorAlocado <= 0) {
                continue;
            }

            $alocacoes[] = ['id_parcela' => $parcela['id'], 'valor' => $valorAlocado];
            $saldo = round($saldo - $valorAlocado, $decimais);
        }

        return ['alocacoes' => $alocacoes, 'saldo_nao_alocado' => max($saldo, 0.0)];
    }
```

- [ ] **Step 4: Rodar os testes de novo**

Run: `docker compose exec app php artisan test --filter=ComissaoCalculoServiceTest`
Expected: PASS (10 testes no total)

- [ ] **Step 5: Commit**

```bash
git add app/Services/Comissao/ComissaoCalculoService.php tests/Unit/Comissao/ComissaoCalculoServiceTest.php
git commit -m "feat: algoritmo de rateio de comissao por parcela com comprometimento"
```

---

## Task 7: `ContratoController::comissoesDisponiveis()` — combo sem filtro de empreendimento

**Files:**
- Modify: `app/Http/Controllers/Api/Administracao/ContratoController.php`
- Modify: `routes/api.php`
- Test: `tests/Feature/Administracao/ContratoComissoesDisponiveisTest.php`

**Interfaces:**
- Produces: `GET administracao/contrato/comissoesDisponiveis` → `[{id, text}, ...]`, usado pela Task 14 (frontend).

- [ ] **Step 1: Escrever o teste de feature (falhando — método ainda não existe)**

```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 Tests\TestCase;

class ContratoComissoesDisponiveisTest 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('PARAMETRO_COMISSAO', function (Blueprint $table) {
            $table->increments('id_parametro_comissao');
            $table->integer('id_empreendimento')->nullable();
            $table->string('nm_parametro_comissao')->nullable();
            $table->string('tp_modalidade', 10)->nullable();
        });

        DB::connection('cliente')->table('PARAMETRO_COMISSAO')->insert([
            ['id_parametro_comissao' => 1, 'id_empreendimento' => null, 'nm_parametro_comissao' => 'Comissão B', 'tp_modalidade' => 'venda'],
            ['id_parametro_comissao' => 2, 'id_empreendimento' => 5, 'nm_parametro_comissao' => 'Comissão A', 'tp_modalidade' => 'fixo'],
            ['id_parametro_comissao' => 3, 'id_empreendimento' => 5, 'nm_parametro_comissao' => 'Legado sem modalidade', 'tp_modalidade' => null],
        ]);
    }

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

    public function test_lista_todas_as_comissoes_com_modalidade_independente_do_empreendimento(): void
    {
        $resposta = (new ContratoController())->comissoesDisponiveis();
        $dados = json_decode($resposta->getContent(), true);

        $this->assertCount(2, $dados);
        $this->assertSame(['Comissão A', 'Comissão B'], array_column($dados, 'text'));
    }
}
```

- [ ] **Step 2: Rodar o teste pra confirmar que falha**

Run: `docker compose exec app php artisan test --filter=ContratoComissoesDisponiveisTest`
Expected: FAIL — `Call to undefined method ContratoController::comissoesDisponiveis()`

- [ ] **Step 3: Implementar o método**

Em `app/Http/Controllers/Api/Administracao/ContratoController.php`, logo depois de `indicesEmpreendimento()` (linha ~207, antes de `public function show($id)`):

```php
    // Sem filtro de empreendimento de propósito — decisão da spec (comissão é
    // montada livremente, qualquer modelo cadastrado aparece em qualquer contrato).
    // whereNotNull('tp_modalidade') exclui linhas antigas de PARAMETRO_COMISSAO que
    // usam o conceito antigo (split fixo por papel), nunca pensadas como "modelo".
    public function comissoesDisponiveis()
    {
        return response()->json(
            DB::connection('cliente')->table('PARAMETRO_COMISSAO')
                ->whereNotNull('tp_modalidade')
                ->orderBy('nm_parametro_comissao')
                ->get(['id_parametro_comissao as id', 'nm_parametro_comissao as text'])
        );
    }

```

- [ ] **Step 4: Adicionar a rota**

Em `routes/api.php`, dentro do grupo `Route::middleware('permission:Listar Contrato')` (linha 175-183), depois da linha `bancosAtivos`:

```php
        Route::get('/administracao/contrato/comissoesDisponiveis', [ContratoController::class, 'comissoesDisponiveis'])->name('contrato.comissoesDisponiveis');
```

- [ ] **Step 5: Rodar o teste de novo**

Run: `docker compose exec app php artisan test --filter=ContratoComissoesDisponiveisTest`
Expected: PASS

- [ ] **Step 6: Commit**

```bash
git add app/Http/Controllers/Api/Administracao/ContratoController.php routes/api.php tests/Feature/Administracao/ContratoComissoesDisponiveisTest.php
git commit -m "feat: endpoint comissoesDisponiveis sem filtro de empreendimento"
```

---

## Task 8: Vincular comissões ao Contrato (`store`/`update`)

**Files:**
- Modify: `app/Http/Controllers/Api/Administracao/ContratoController.php`
- Test: `tests/Feature/Administracao/ContratoComissaoWorkflowTest.php`

**Interfaces:**
- Consumes: tabela `CONTRATO_PARAMETRO_COMISSAO` (Task 2).
- Produces: `ContratoController::salvarComissoesContrato(int $idContrato, array $idsComissoes): void` — usado pelas Tasks 9 e 10 (mesma classe).

- [ ] **Step 1: Escrever o teste de feature (falhando)**

```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 Tests\TestCase;

class ContratoComissaoWorkflowTest 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->string('quadra')->nullable();
            $table->string('lote')->nullable();
            $table->decimal('valor', 15, 2)->nullable();
            $table->boolean('reservado')->default(false);
        });

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

        Schema::connection('cliente')->create('CONTRATO', function (Blueprint $table) {
            $table->increments('id');
            $table->integer('id_lote');
            $table->integer('id_pessoa');
            $table->integer('id_corretor')->nullable();
            $table->integer('id_banco')->nullable();
            $table->integer('id_indice')->nullable();
            $table->decimal('porcentagem_participacao_contrato')->nullable();
            $table->string('nr_proposta')->nullable();
            $table->date('dt_contrato')->nullable();
            $table->decimal('desconto')->nullable();
            $table->string('fl_fm_pagamento')->nullable();
            $table->string('fl_gerado')->default('0');
            $table->string('fl_distrato')->default('0');
            $table->string('fl_aprovar_contrato')->default('1');
            $table->decimal('vl_sinal')->nullable()->default(0);
            $table->integer('nr_parcela_sinal')->nullable()->default(0);
            $table->date('dt_sinal')->nullable();
            $table->string('fl_itens_contrato')->default('0');
            $table->text('log')->nullable();
        });

        Schema::connection('cliente')->create('CONTRATO_PESSOA', function (Blueprint $table) {
            $table->integer('id_contrato');
            $table->integer('id_pessoa');
            $table->decimal('porcentagem_participacao_contrato')->nullable();
        });

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

        Schema::connection('cliente')->create('SINAL', function (Blueprint $table) {
            $table->increments('id');
            $table->integer('idContrato');
            $table->integer('parcela')->nullable();
            $table->decimal('valor', 15, 2)->nullable();
            $table->date('dtVencimento')->nullable();
        });

        Schema::connection('cliente')->create('CONTATO', function (Blueprint $table) {
            $table->increments('id');
            $table->integer('idContrato');
            $table->date('data')->nullable();
            $table->integer('agr_idStatus')->nullable();
            $table->text('assunto')->nullable();
            $table->integer('usuario')->nullable();
            $table->text('log')->nullable();
        });

        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();
        });

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

        DB::connection('cliente')->table('EMPREENDIMENTO')->insert(['id' => 1]);
        DB::connection('cliente')->table('LOTES')->insert(['id' => 10, 'id_empreendimento' => 1, 'status' => 'D']);
        DB::connection('cliente')->table('PESSOA')->insert(['id' => 20, 'nm_pessoa' => 'Comprador Teste']);
        DB::connection('cliente')->table('PARAMETRO_COMISSAO')->insert([
            ['id_parametro_comissao' => 1, 'nm_parametro_comissao' => 'Comissão A', 'tp_modalidade' => 'venda', 'porc_venda' => 8],
            ['id_parametro_comissao' => 2, 'nm_parametro_comissao' => 'Comissão B', 'tp_modalidade' => 'venda', 'porc_venda' => 2],
        ]);
    }

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

    private function dadosContratoBase(): array
    {
        return [
            'id_lote' => 10,
            'id_pessoa' => 20,
            'id_corretor' => null,
            'id_banco' => null,
            'id_indice' => 6,
            'dt_contrato' => '2026-10-20',
            'fl_fm_pagamento' => 'PC',
            'tp_parcelamento' => 'N',
            'nr_parcela' => 1,
            'vl_parcela' => 1000,
            'dt_primeira_parcela' => '2026-11-20',
            'fl_frequencia' => 'M',
        ];
    }

    public function test_salva_as_comissoes_vinculadas_ao_criar_contrato(): void
    {
        $dados = array_merge($this->dadosContratoBase(), ['comissoes' => [1, 2]]);

        (new ContratoController())->store(request()->create('/api/administracao/contrato', 'POST', $dados));

        $vinculadas = DB::connection('cliente')->table('CONTRATO_PARAMETRO_COMISSAO')
            ->where('id_contrato', 1)
            ->orderBy('id')
            ->pluck('id_parametro_comissao')
            ->all();

        $this->assertSame([1, 2], $vinculadas);
    }

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

        $dadosUpdate = array_merge($this->dadosContratoBase(), ['comissoes' => [2]]);
        (new ContratoController())->update(request()->create('/api/administracao/contrato/1', 'PUT', $dadosUpdate), 1);

        $vinculadas = DB::connection('cliente')->table('CONTRATO_PARAMETRO_COMISSAO')
            ->where('id_contrato', 1)
            ->pluck('id_parametro_comissao')
            ->all();

        $this->assertSame([2], $vinculadas);
    }
}
```

- [ ] **Step 2: Rodar os testes pra confirmar que falham**

Run: `docker compose exec app php artisan test --filter=ContratoComissaoWorkflowTest`
Expected: FAIL — os dois testes passam no `store()`/`update()` mas `CONTRATO_PARAMETRO_COMISSAO` fica vazia (campo `comissoes` ainda não é lido em lugar nenhum).

- [ ] **Step 3: Adicionar `comissoes` às `REGRAS`**

Em `app/Http/Controllers/Api/Administracao/ContratoController.php:327` (logo depois de `'co_compradores.*.percentual' => 'required_with:co_compradores|numeric|min:0|max:100',`):

```php
        'comissoes' => 'nullable|array',
        'comissoes.*' => 'required_with:comissoes|integer',
```

- [ ] **Step 4: Criar `salvarComissoesContrato()`**

Logo depois de `salvarCoCompradores()` (linha ~771, mesmo padrão):

```php

    // Mesmo padrão "apaga tudo e recria" de salvarCoCompradores() — ver
    // docs/superpowers/specs/2026-10-20-cadastro-comissao-design.md. array_unique
    // evita violar o índice único de CONTRATO_PARAMETRO_COMISSAO (Task 2) se o
    // mesmo id vier repetido no payload — sem isso, o insert quebraria com
    // QueryException (1062 Duplicate entry) em vez de simplesmente ignorar a
    // repetição (achado do task review da Task 2, 20/10/2026).
    private function salvarComissoesContrato($idContrato, array $idsComissoes)
    {
        DB::connection('cliente')->table('CONTRATO_PARAMETRO_COMISSAO')->where('id_contrato', $idContrato)->delete();

        foreach (array_unique($idsComissoes) as $idComissao) {
            DB::connection('cliente')->table('CONTRATO_PARAMETRO_COMISSAO')->insert([
                'id_contrato' => $idContrato,
                'id_parametro_comissao' => $idComissao,
            ]);
        }
    }
```

- [ ] **Step 5: Chamar no `store()`**

Logo depois de `$this->salvarCoCompradores($contrato->id, $data['co_compradores'] ?? []);` (linha 419):

```php
            $this->salvarComissoesContrato($contrato->id, $data['comissoes'] ?? []);
```

- [ ] **Step 6: Chamar no `update()` (gated por `fl_gerado`, mesmo padrão de tipos/sinal)**

Bloco atual (linhas ~488-493):

```php
            // Mesma trava de fl_gerado dos 4 tipos fixos acima — estrutura financeira do
            // contrato não muda depois que as parcelas já foram geradas.
            if ($contrato->fl_gerado !== '1') {
                $this->salvarTiposParcelaPersonalizados($contrato->id, $data['tipos_parcela_customizados'] ?? []);
                $this->salvarSinais($contrato->id, $data['sinal'] ?? []);
            }
```

Substituir por:

```php
            // Mesma trava de fl_gerado dos 4 tipos fixos acima — estrutura financeira do
            // contrato não muda depois que as parcelas já foram geradas. Comissão segue
            // a mesma regra: depois de gerarParcelas(), os COMISSAO_LANCAMENTO já foram
            // instanciados contra a lista de hoje — trocar a lista depois ficaria
            // dessincronizado (ver docs/superpowers/specs/2026-10-20-cadastro-comissao-design.md).
            if ($contrato->fl_gerado !== '1') {
                $this->salvarTiposParcelaPersonalizados($contrato->id, $data['tipos_parcela_customizados'] ?? []);
                $this->salvarSinais($contrato->id, $data['sinal'] ?? []);
                $this->salvarComissoesContrato($contrato->id, $data['comissoes'] ?? []);
            }
```

- [ ] **Step 7: Excluir `comissoes` de `montarCampos()` (não é coluna de `CONTRATO`)**

Linha 710, atual:

```php
        unset($campos['co_compradores'], $campos['tp_parcelamento'], $campos['sinal']);
```

Substituir por:

```php
        unset($campos['co_compradores'], $campos['tp_parcelamento'], $campos['sinal'], $campos['comissoes']);
```

- [ ] **Step 8: Rodar os testes de novo**

Run: `docker compose exec app php artisan test --filter=ContratoComissaoWorkflowTest`
Expected: PASS (2 testes)

- [ ] **Step 9: Commit**

```bash
git add app/Http/Controllers/Api/Administracao/ContratoController.php tests/Feature/Administracao/ContratoComissaoWorkflowTest.php
git commit -m "feat: vincula multiplas comissoes ao salvar/editar contrato"
```

---

## Task 9: `ContratoController::show()` devolve as comissões vinculadas

**Files:**
- Modify: `app/Http/Controllers/Api/Administracao/ContratoController.php`
- Modify: `tests/Feature/Administracao/ContratoComissaoWorkflowTest.php`

**Interfaces:**
- Produces: `show($id)` inclui `comissoes` (`[{id, nome}, ...]`) no JSON de resposta — usado pela Task 14 (tela reabre preenchida).

- [ ] **Step 1: Acrescentar o teste (falhando)**

Acrescentar à classe `ContratoComissaoWorkflowTest` (depois do teste da Task 8):

```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));

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

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

- [ ] **Step 2: Rodar o teste pra confirmar que falha**

Run: `docker compose exec app php artisan test --filter=ContratoComissaoWorkflowTest::test_show_devolve_as_comissoes_vinculadas_com_nome`
Expected: FAIL — `Undefined array key "comissoes"`

- [ ] **Step 3: Incluir a consulta em `show()`**

Em `app/Http/Controllers/Api/Administracao/ContratoController.php`, dentro de `show($id)` (linha ~209), logo depois do bloco de `$sinais` (antes do `$result = array_merge(...)`):

```php

        // Mesmo padrão de co_compradores logo acima — ordenado por CONTRATO_PARAMETRO_COMISSAO.id
        // (ordem de inserção), que é a mesma ordem usada no rateio por parcela (gerarParcelas()).
        $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']);
```

E no `array_merge` que monta `$result` (linha ~249), acrescentar a chave:

```php
            'comissoes' => $comissoes,
```

- [ ] **Step 4: Rodar o teste de novo**

Run: `docker compose exec app php artisan test --filter=ContratoComissaoWorkflowTest`
Expected: PASS (3 testes)

- [ ] **Step 5: Commit**

```bash
git add app/Http/Controllers/Api/Administracao/ContratoController.php tests/Feature/Administracao/ContratoComissaoWorkflowTest.php
git commit -m "feat: show de contrato devolve as comissoes vinculadas"
```

---

## Task 10: Instanciar `COMISSAO_LANCAMENTO`/`COMISSAO_PAGAMENTO` no `gerarParcelas()`

Esta é a integração principal — calcula e persiste a comissão de verdade contra as parcelas reais, pra cada modelo vinculado ao contrato.

**Files:**
- Modify: `app/Http/Controllers/Api/Administracao/ContratoController.php`
- Modify: `tests/Feature/Administracao/ContratoComissaoWorkflowTest.php`

**Interfaces:**
- Consumes: `ComissaoCalculoService::calcularValorComissao()`/`ratear()` (Tasks 5, 6), `CONTRATO_PARAMETRO_COMISSAO` (Task 8).
- Produces: `COMISSAO_LANCAMENTO`/`COMISSAO_PAGAMENTO` reais + aviso informativo na resposta de `gerarParcelas()`.

- [ ] **Step 1: Acrescentar as tabelas que faltam no `setUp()` do teste**

No `setUp()` de `ContratoComissaoWorkflowTest`, logo depois do `Schema::connection('cliente')->create('CONTRATO_PARAMETRO_COMISSAO', ...)`:

```php

        Schema::connection('cliente')->create('receivables', function (Blueprint $table) {
            $table->increments('id');
            $table->integer('code')->nullable();
            $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();
        });

        Schema::connection('cliente')->create('COMISSAO_LANCAMENTO', function (Blueprint $table) {
            $table->increments('id');
            $table->integer('id_contrato');
            $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->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);
        });
```

- [ ] **Step 2: Escrever os testes do fluxo completo (falhando)**

Acrescentar à classe `ContratoComissaoWorkflowTest`:

```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->assertNotNull($lancamento);
        // valor total do contrato (2 x 500 = 1000) x 8% = 80. Cast pra float — o
        // sqlite :memory: do teste (NUMERIC affinity) devolve valores "redondos"
        // como int, não string (MySQL real devolveria string "80.00" de um DECIMAL,
        // mas o teste não roda contra MySQL — achado antes do dispatch desta task).
        $this->assertSame(80.0, (float) $lancamento->vl_comissao_total);
    }

    public function test_gerar_parcelas_rateia_comissao_sobre_parcelas_quando_configurado(): void
    {
        DB::connection('cliente')->table('PARAMETRO_COMISSAO')->where('id_parametro_comissao', 1)->update([
            'parcela_paga' => '1',
            'pc_limite_parcela' => 10,
        ]);

        $dados = array_merge($this->dadosContratoBase(), ['comissoes' => [1], 'nr_parcela' => 2, 'vl_parcela' => 500]);
        (new ContratoController())->store(request()->create('/api/administracao/contrato', 'POST', $dados));

        $resposta = (new ContratoController())->gerarParcelas(request(), 1);
        $json = json_decode($resposta->getContent(), true);

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

        // total 80, limite 10% de 500 = 50 por parcela -> 50 + 30 fecha nas 2 parcelas
        $this->assertCount(2, $pagamentos);
        $this->assertSame(50.0, (float) $pagamentos[0]->vl_comissao_parcela);
        $this->assertSame(30.0, (float) $pagamentos[1]->vl_comissao_parcela);
        $this->assertArrayNotHasKey('avisos_comissao', $json);
    }

    public function test_gerar_parcelas_avisa_quando_limite_nao_fecha_o_total_da_comissao(): void
    {
        DB::connection('cliente')->table('PARAMETRO_COMISSAO')->where('id_parametro_comissao', 1)->update([
            'parcela_paga' => '1',
            'pc_limite_parcela' => 1, // 1% de 500 = 5 por parcela, insuficiente pra fechar 80
        ]);

        $dados = array_merge($this->dadosContratoBase(), ['comissoes' => [1], 'nr_parcela' => 2, 'vl_parcela' => 500]);
        (new ContratoController())->store(request()->create('/api/administracao/contrato', 'POST', $dados));

        $resposta = (new ContratoController())->gerarParcelas(request(), 1);
        $json = json_decode($resposta->getContent(), true);

        $this->assertNotEmpty($json['avisos_comissao']);
    }

    public function test_gerar_parcelas_com_duas_comissoes_respeita_comprometimento_entre_elas(): void
    {
        DB::connection('cliente')->table('PARAMETRO_COMISSAO')->whereIn('id_parametro_comissao', [1, 2])->update([
            'parcela_paga' => '1',
            'pc_limite_parcela' => 100,
        ]);

        $dados = array_merge($this->dadosContratoBase(), ['comissoes' => [1, 2], 'nr_parcela' => 1, 'vl_parcela' => 1000]);
        (new ContratoController())->store(request()->create('/api/administracao/contrato', 'POST', $dados));

        (new ContratoController())->gerarParcelas(request(), 1);

        $lancamentos = DB::connection('cliente')->table('COMISSAO_LANCAMENTO')->where('id_contrato', 1)->orderBy('id')->get();
        // Comissão 1 (8% de 1000 = 80) processada primeiro, comissão 2 (2% de 1000 = 20) depois
        $pagamento1 = DB::connection('cliente')->table('COMISSAO_PAGAMENTO')->where('id_comissao_lanc', $lancamentos[0]->id)->first();
        $pagamento2 = DB::connection('cliente')->table('COMISSAO_PAGAMENTO')->where('id_comissao_lanc', $lancamentos[1]->id)->first();

        $this->assertSame(80.0, (float) $pagamento1->vl_comissao_parcela);
        // teto da parcela é o valor dela (1000) menos o que a comissão 1 já tomou (80) = 920, sobra de sobra pros 20 da comissão 2
        $this->assertSame(20.0, (float) $pagamento2->vl_comissao_parcela);
    }
```

- [ ] **Step 3: Rodar os testes pra confirmar que falham**

Run: `docker compose exec app php artisan test --filter=ContratoComissaoWorkflowTest`
Expected: FAIL — `COMISSAO_LANCAMENTO` continua vazia depois de `gerarParcelas()`.

- [ ] **Step 4: Implementar a instanciação dentro de `gerarParcelas()`**

Localizar o bloco final do método (linhas ~632-638):

```php
            if ($total > 0) {
                $contrato->fl_gerado = '1';
                $contrato->save();
                DB::connection('cliente')->table('LOTES')->where('id', $contrato->id_lote)->update(['status' => 'V']);
            }

            return response()->json(['message' => __('administracao.messages.parcelas_geradas_sucesso'), 'total_parcelas' => $total]);
        });
    }
```

Substituir por:

```php
            if ($total > 0) {
                $contrato->fl_gerado = '1';
                $contrato->save();
                DB::connection('cliente')->table('LOTES')->where('id', $contrato->id_lote)->update(['status' => 'V']);
            }

            $avisosComissao = $this->instanciarComissoesDoContrato($contrato);

            $resposta = ['message' => __('administracao.messages.parcelas_geradas_sucesso'), 'total_parcelas' => $total];
            if (!empty($avisosComissao)) {
                $resposta['avisos_comissao'] = $avisosComissao;
            }

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

    // Pra cada PARAMETRO_COMISSAO vinculado ao contrato (na ordem em que foi
    // adicionado — CONTRATO_PARAMETRO_COMISSAO.id ascendente), calcula o valor da
    // comissão (ComissaoCalculoService::calcularValorComissao()) e, se
    // parcela_paga='1', rateia entre as parcelas reais (ComissaoCalculoService::ratear()),
    // respeitando o que comissões anteriores já comprometeram na mesma parcela. Ver
    // docs/superpowers/specs/2026-10-20-cadastro-comissao-design.md (seções C e D).
    private function instanciarComissoesDoContrato(Contrato $contrato): array
    {
        $conexao = DB::connection('cliente');
        $calculo = app(\App\Services\Comissao\ComissaoCalculoService::class);
        $decimais = \App\Helpers\CurrencyConfig::getConfig()['decimals'];

        $idsModelos = $conexao->table('CONTRATO_PARAMETRO_COMISSAO')
            ->where('id_contrato', $contrato->id)
            ->orderBy('id')
            ->pluck('id_parametro_comissao');

        if ($idsModelos->isEmpty()) {
            return [];
        }

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

        $comprometidoPorParcela = [];
        $avisos = [];

        foreach ($idsModelos as $idModelo) {
            // Busca pelo model Eloquent (não pela linha crua do join acima) — evita
            // depender de mass-assignment silenciosamente ignorar a PK/colunas fora
            // do $fillable ao hidratar um stdClass num ParametroComissao novo.
            $modelo = ParametroComissao::find($idModelo);
            if (!$modelo) {
                continue; // modelo apagado depois de vinculado ao contrato — ignora, não quebra a geração.
            }

            $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,
            ]);

            if ($modelo->parcela_paga === '1') {
                $parcelasParaRateio = $parcelasGeradas->map(fn ($p) => ['id' => $p->id, 'valor' => (float) $p->original_amount])->all();

                $resultado = $calculo->ratear(
                    $valorComissao,
                    (float) $modelo->pc_limite_parcela,
                    $parcelasParaRateio,
                    $comprometidoPorParcela,
                    $decimais
                );

                foreach ($resultado['alocacoes'] as $alocacao) {
                    $parcela = $parcelasGeradas->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'],
                    ]);

                    $comprometidoPorParcela[$alocacao['id_parcela']] = ($comprometidoPorParcela[$alocacao['id_parcela']] ?? 0.0) + $alocacao['valor'];
                }

                if ($resultado['saldo_nao_alocado'] > 0) {
                    $avisos[] = __('administracao.messages.comissao_nao_coube_nas_parcelas', [
                        'nome' => $modelo->nm_parametro_comissao,
                        'saldo' => \App\Helpers\CurrencyConfig::format($resultado['saldo_nao_alocado']),
                    ]);
                }
            }
        }

        return $avisos;
    }
```

- [ ] **Step 5: Adicionar o import que falta**

No topo do arquivo (linha 10, depois de `use App\Services\GeracaoParcelasService;`):

```php
use App\Services\Comissao\ComissaoCalculoService;
use App\Helpers\CurrencyConfig;
use App\Models\Vendas\ParametroComissao;
```

- [ ] **Step 6: Criar as 3 chaves de tradução novas (mínimo pra teste/execução, 3 idiomas)**

Em `resources/lang/pt/administracao.php`, `resources/lang/es/administracao.php`, `resources/lang/en/administracao.php`, acrescentar à seção `messages` (ou criar, seguindo o padrão já usado por `parcelas_geradas_sucesso`):

pt:
```php
    'comissao_nao_coube_nas_parcelas' => 'A comissão ":nome" não coube inteira dentro das parcelas geradas — sobrou :saldo sem ratear. Ajuste o % limite por parcela ou o modelo de comissão.',
```

es:
```php
    'comissao_nao_coube_nas_parcelas' => 'La comisión ":nome" no cupo entera dentro de las cuotas generadas — sobró :saldo sin repartir. Ajuste el % límite por cuota o el modelo de comisión.',
```

en:
```php
    'comissao_nao_coube_nas_parcelas' => 'Commission ":nome" did not fit entirely within the generated installments — :saldo was left unallocated. Adjust the per-installment limit % or the commission template.',
```

- [ ] **Step 7: Rodar os testes de novo**

Run: `docker compose exec app php artisan test --filter=ContratoComissaoWorkflowTest`
Expected: PASS (7 testes no total)

- [ ] **Step 8: Rodar a suíte inteira pra garantir que nada quebrou**

Run: `docker compose exec app php artisan test`
Expected: todos os testes passando (incluindo os já existentes de `DistratoWorkflowTest` etc.)

- [ ] **Step 9: Commit**

```bash
git add app/Http/Controllers/Api/Administracao/ContratoController.php tests/Feature/Administracao/ContratoComissaoWorkflowTest.php resources/lang/pt/administracao.php resources/lang/es/administracao.php resources/lang/en/administracao.php
git commit -m "feat: instancia comissao real (lancamento + rateio) ao gerar parcelas do contrato"
```

---

## Task 11: Tela de Cadastro de Comissão — API CRUD

**Files:**
- Create: `app/Http/Controllers/Api/Administracao/ModeloComissaoController.php`
- Modify: `routes/api.php`
- Test: `tests/Feature/Administracao/ModeloComissaoControllerTest.php`

**Interfaces:**
- Produces: `GET/POST/PUT/DELETE administracao/comissao` (CRUD de `PARAMETRO_COMISSAO`), consumido pela Task 13 (view).

- [ ] **Step 1: Escrever o teste de feature (falhando — controller ainda não existe)**

```php
<?php

namespace Tests\Feature\Administracao;

use App\Http\Controllers\Api\Administracao\ModeloComissaoController;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;
use Illuminate\Validation\ValidationException;
use Tests\TestCase;

class ModeloComissaoControllerTest 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('PARAMETRO_COMISSAO', function (Blueprint $table) {
            $table->increments('id_parametro_comissao');
            $table->integer('id_empreendimento')->nullable();
            $table->string('tp_comissao')->nullable();
            $table->string('tp_local_insidencia')->nullable();
            $table->decimal('vl_corretor', 12, 2)->nullable();
            $table->decimal('vl_coordenador', 12, 2)->nullable();
            $table->decimal('vl_indicador', 12, 2)->nullable();
            $table->decimal('vl_imobiliaria', 12, 2)->nullable();
            $table->decimal('vl_outros', 12, 2)->nullable();
            $table->integer('qt_parcela_comissao')->nullable();
            $table->string('nm_parametro_comissao')->nullable();
            $table->text('ds_log')->nullable();
            $table->integer('id_parceiro')->nullable();
            $table->integer('id_pessoa_parceiro')->nullable();
            $table->string('tp_modalidade', 10)->nullable();
            $table->decimal('porc_venda', 15, 2)->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', 5, 2)->nullable();
        });
    }

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

    public function test_cria_modelo_de_comissao_sem_exigir_empreendimento(): void
    {
        $dados = [
            'nm_parametro_comissao' => 'Comissão Ana',
            'id_parceiro' => 1,
            'id_pessoa_parceiro' => 2,
            'tp_modalidade' => 'venda',
            'porc_venda' => 8,
            'parcela_paga' => '0',
        ];

        $resposta = (new ModeloComissaoController())->store(request()->create('/api/administracao/comissao', 'POST', $dados));

        $this->assertSame(201, $resposta->getStatusCode());
        $modelo = DB::connection('cliente')->table('PARAMETRO_COMISSAO')->first();
        $this->assertNull($modelo->id_empreendimento);
        $this->assertSame('Comissão Ana', $modelo->nm_parametro_comissao);
    }

    public function test_exige_percentual_quando_a_modalidade_e_porcentual(): void
    {
        $dados = [
            'nm_parametro_comissao' => 'Comissão Inválida',
            'id_parceiro' => 1,
            'id_pessoa_parceiro' => 2,
            'tp_modalidade' => 'venda',
            'parcela_paga' => '0',
        ];

        try {
            (new ModeloComissaoController())->store(request()->create('/api/administracao/comissao', 'POST', $dados));
            $this->fail('Deveria ter rejeitado porc_venda ausente.');
        } catch (ValidationException $exception) {
            $this->assertArrayHasKey('porc_venda', $exception->errors());
        }
    }

    public function test_exige_limite_por_parcela_quando_forma_de_pagamento_e_sobre_parcelas(): void
    {
        $dados = [
            'nm_parametro_comissao' => 'Comissão Sobre Parcelas',
            'id_parceiro' => 1,
            'id_pessoa_parceiro' => 2,
            'tp_modalidade' => 'fixo',
            'vl_fixo' => 500,
            'parcela_paga' => '1',
        ];

        try {
            (new ModeloComissaoController())->store(request()->create('/api/administracao/comissao', 'POST', $dados));
            $this->fail('Deveria ter rejeitado pc_limite_parcela ausente.');
        } catch (ValidationException $exception) {
            $this->assertArrayHasKey('pc_limite_parcela', $exception->errors());
        }
    }
}
```

- [ ] **Step 2: Rodar os testes pra confirmar que falham**

Run: `docker compose exec app php artisan test --filter=ModeloComissaoControllerTest`
Expected: FAIL — `Class "App\Http\Controllers\Api\Administracao\ModeloComissaoController" not found`

- [ ] **Step 3: Implementar o controller**

```php
<?php

namespace App\Http\Controllers\Api\Administracao;

use App\Http\Controllers\Controller;
use App\Models\Vendas\ParametroComissao;
use Illuminate\Http\Request;

// Cadastro de "modelo de comissão" — ver
// docs/superpowers/specs/2026-10-20-cadastro-comissao-design.md. Molde de
// App\Http\Controllers\Api\Vendas\ParametroComissaoController, mas sem exigir
// empreendimento (decisão da spec) e com os campos novos das 4 modalidades.
class ModeloComissaoController extends Controller
{
    // Regras condicionais compostas como ARRAY (string 'required'/'nullable' +
    // demais regras como elementos separados) — nunca concatene Rule::requiredIf()
    // com '.' numa string: o objeto não tem conversão pra string compatível com o
    // formato pipe, e isso quebra em runtime ("Object could not be converted to
    // string"). Achado no pre-flight scan desta task, antes de qualquer dispatch.
    private function regras(array $data): array
    {
        $modalidade = $data['tp_modalidade'] ?? null;
        $pagamento = $data['parcela_paga'] ?? null;

        return [
            'nm_parametro_comissao' => 'required|string|max:50',
            'id_empreendimento' => 'nullable|integer',
            'id_parceiro' => 'required|integer',
            'id_pessoa_parceiro' => 'required|integer',
            'tp_modalidade' => 'required|in:venda,fixo,parcela,tabela',
            'porc_venda' => [$modalidade === 'venda' ? 'required' : 'nullable', 'numeric', 'min:0', 'max:100'],
            'vl_fixo' => [$modalidade === 'fixo' ? 'required' : 'nullable', 'numeric', 'min:0'],
            'porc_parcela' => [in_array($modalidade, ['parcela', 'tabela'], true) ? 'required' : 'nullable', 'numeric', 'min:0', 'max:100'],
            'tp_parcela' => [$modalidade === 'parcela' ? 'required' : 'nullable', 'in:N,S,I,C'],
            'id_tabela_preco' => [$modalidade === 'tabela' ? 'required' : 'nullable', 'integer'],
            'parcela_paga' => 'required|in:0,1',
            'pc_limite_parcela' => [$pagamento === '1' ? 'required' : 'nullable', 'numeric', 'min:0', 'max:100'],
        ];
    }

    public function index(Request $request)
    {
        return response()->json(
            ParametroComissao::query()->whereNotNull('tp_modalidade')->orderBy('nm_parametro_comissao')->get()
        );
    }

    public function show($id)
    {
        return response()->json(ParametroComissao::findOrFail($id));
    }

    public function store(Request $request)
    {
        $data = $request->validate($this->regras($request->all()));

        return response()->json(ParametroComissao::create($data), 201);
    }

    public function update(Request $request, $id)
    {
        $modelo = ParametroComissao::findOrFail($id);
        $data = $request->validate($this->regras($request->all()));

        $modelo->update($data);

        return response()->json($modelo);
    }

    public function destroy($id)
    {
        ParametroComissao::findOrFail($id)->delete();

        return response()->noContent();
    }
}
```

- [ ] **Step 4: Adicionar as rotas**

Em `routes/api.php`, no bloco de rotas de Administração (perto das rotas de `ContratoController`), acrescentar:

```php
use App\Http\Controllers\Api\Administracao\ModeloComissaoController;
```

(junto dos outros `use` de `Api\Administracao`, topo do arquivo) e, dentro de um grupo próprio:

```php
    Route::middleware('permission:Listar Modelo de Comissão')->group(function () {
        Route::get('/administracao/comissao', [ModeloComissaoController::class, 'index'])->name('comissao.listar');
        Route::get('/administracao/comissao/{id}', [ModeloComissaoController::class, 'show'])->name('comissao.show');
    });
    Route::middleware('permission:Criar Modelo de Comissão')->group(function () {
        Route::post('/administracao/comissao', [ModeloComissaoController::class, 'store'])->name('comissao.store');
    });
    Route::middleware('permission:Editar Modelo de Comissão')->group(function () {
        Route::put('/administracao/comissao/{id}', [ModeloComissaoController::class, 'update'])->name('comissao.update');
    });
    Route::middleware('permission:Excluir Modelo de Comissão')->group(function () {
        Route::delete('/administracao/comissao/{id}', [ModeloComissaoController::class, 'destroy'])->name('comissao.destroy');
    });
```

- [ ] **Step 5: Rodar os testes de novo**

Run: `docker compose exec app php artisan test --filter=ModeloComissaoControllerTest`
Expected: PASS (3 testes)

- [ ] **Step 6: Commit**

```bash
git add app/Http/Controllers/Api/Administracao/ModeloComissaoController.php routes/api.php tests/Feature/Administracao/ModeloComissaoControllerTest.php
git commit -m "feat: CRUD de modelo de comissao (ModeloComissaoController)"
```

---

## Task 12: Seed das permissões novas

**Files:**
- Create: `database/migrations/geral/2026_10_20_100200_seed_modelo_comissao_permission_roles.php`

**Interfaces:**
- Produces: roles `Listar/Criar/Editar/Excluir Modelo de Comissão` — consumidas pelas rotas da Task 11.

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

```php
<?php

use App\Models\Roles;
use Illuminate\Database\Migrations\Migration;
use Illuminate\Support\Facades\DB;

// Roles novas pro Cadastro de Comissão (Administração) — não reaproveitar
// "Comissão"/"Listar Comissão", que já são do módulo Vendas (COMISSAO_LANCAMENTO,
// 2026_07_29_130000_seed_vendas_module_roles.php). Concede por equivalência
// semântica a quem já tem "Criar/Editar/Excluir/Listar Contrato" (mesma área de
// Administração) — NUNCA pelo contador de "100% das roles" (ver CLAUDE.md,
// "Pontos de atenção conhecidos": esse heurístico já falhou em silêncio 2x).
//
// role_parent_id é obrigatório, não cosmético (achado do task review, 20/10/2026):
// User::permissionNames() (usado pro menu no frontend, app/Models/User.php:121,132)
// e GrupoController (tela de gestão de permissão por grupo) filtram explicitamente
// whereNotNull('role_parent_id') — uma role sem pai nunca aparece no menu nem fica
// gerenciável na tela de Grupos, mesmo que o Gate (CheckPermission, via hasRole())
// a reconheça pra autorizar rota. Mesmo padrão já usado por "Gerar Contrato"
// (2026_09_25_100000_seed_gerar_contrato_permission_role.php) — find-or-create do
// pai "Administração".
return new class extends Migration
{
    private const MAPA = [
        'Listar Modelo de Comissão' => 'Listar Contrato',
        'Criar Modelo de Comissão' => 'Criar Contrato',
        'Editar Modelo de Comissão' => 'Editar Contrato',
        'Excluir Modelo de Comissão' => 'Excluir Contrato',
    ];

    public function up(): void
    {
        $parentId = DB::table('roles')->where('role_name', 'Administração')->whereNull('role_parent_id')->value('id')
            ?? DB::table('roles')->insertGetId([
                'role_name' => 'Administração',
                'role_status' => true,
                'created_at' => now(),
                'updated_at' => now(),
            ]);

        foreach (self::MAPA as $nomeNovo => $roleIrma) {
            $roleNova = Roles::firstOrCreate(
                ['role_name' => $nomeNovo],
                ['role_parent_id' => $parentId, 'role_status' => true]
            );

            $idsRoleIrma = DB::table('group_roles')
                ->join('roles', 'roles.id', '=', 'group_roles.role_id')
                ->where('roles.role_name', $roleIrma)
                ->where('group_roles.group_role_status', true)
                ->pluck('group_roles.group_id');

            foreach ($idsRoleIrma as $idGrupo) {
                DB::table('group_roles')->updateOrInsert(
                    ['group_id' => $idGrupo, 'role_id' => $roleNova->id],
                    ['group_role_status' => true, 'created_at' => now(), 'updated_at' => now()]
                );
            }
        }
    }

    public function down(): void
    {
        $nomes = array_keys(self::MAPA);
        DB::table('group_roles')->whereIn('role_id', Roles::whereIn('role_name', $nomes)->pluck('id'))->delete();
        Roles::whereIn('role_name', $nomes)->delete();
    }
};
```

- [ ] **Step 2: Conferir sintaxe**

Run: `docker compose exec app php -l database/migrations/geral/2026_10_20_100200_seed_modelo_comissao_permission_roles.php`
Expected: `No syntax errors detected`

- [ ] **Step 3: Commit**

```bash
git add database/migrations/geral/2026_10_20_100200_seed_modelo_comissao_permission_roles.php
git commit -m "feat: seed das permissoes do cadastro de modelo de comissao"
```

---

## Task 13: Views — Cadastro de Comissão (listagem + formulário)

Sem teste automatizado (Blade/JS puro, sem suíte de testes de UI neste projeto — mesmo padrão de todas as outras telas) — verificação manual depois, pelo navegador.

**Files:**
- Create: `app/Http/Controllers/AdministracaoController.php` (modificar, 2 métodos novos)
- Create: `resources/views/administracao/comissao.blade.php`
- Create: `resources/views/administracao/comissaoFormulario.blade.php`
- Modify: `routes/web.php`
- Modify: `resources/lang/{pt,es,en}/administracao.php`

**Interfaces:**
- Consumes: `GET/POST/PUT administracao/comissao` (Task 11), `api/cadastro/pessoas/buscar` (já existe).

- [ ] **Step 1: Métodos no `AdministracaoController`**

Em `app/Http/Controllers/AdministracaoController.php`, logo depois de `contratoFormulario()` (linha ~70):

```php

    public function comissao()
    {
        return view('administracao.comissao');
    }

    public function comissaoFormulario($id = null)
    {
        return view('administracao.comissaoFormulario', compact('id'));
    }
```

- [ ] **Step 2: Rotas web**

Em `routes/web.php`, dentro do bloco `Route::prefix('administracao')` (linha ~159), logo depois do bloco de `contrato` (linha ~185):

```php

    Route::get('comissao', [AdministracaoController::class, 'comissao'])->name('comissao');
    Route::get('comissao/add', [AdministracaoController::class, 'comissaoFormulario'])->name('comissao.add');
    Route::get('comissao/{id?}', [AdministracaoController::class, 'comissaoFormulario'])->name('comissao.formulario');
```

- [ ] **Step 3: Traduções (3 idiomas)**

Em `resources/lang/pt/administracao.php`, acrescentar (ordem alfabética, mesmo padrão do arquivo):

```php
    'modelo_de_comissao' => 'Modelo de Comissão',
    'novo_modelo_de_comissao' => 'Novo Modelo de Comissão',
    'editar_modelo_de_comissao' => 'Editar Modelo de Comissão',
    'nome_do_modelo' => 'Nome do modelo',
    'parceiro' => 'Parceiro',
    'pessoa_de_contato_do_parceiro' => 'Pessoa de contato do parceiro',
    'modalidade_de_calculo' => 'Modalidade de cálculo',
    'modalidade_total_venda' => 'Total Venda (%)',
    'modalidade_valor_fixo' => 'Valor Fixo (R$)',
    'modalidade_tipo_parcela' => 'Tipo Parcela (%)',
    'modalidade_tabela_preco' => 'Tabela de Preço (%)',
    'forma_de_pagamento_comissao' => 'Forma de pagamento',
    'pagamento_total' => 'Total (à vista)',
    'pagamento_sobre_parcelas' => 'Sobre parcelas',
    'limite_por_parcela' => '% limite por parcela',
    'valor_de_referencia_simulacao' => 'Valor de referência (simulação, não salvo)',
    'porc_sobre_venda' => '% sobre a Venda',
    'sinal' => 'Sinal',
    'intercalada' => 'Intercalada',
    'chave' => 'Chave',
    'porc_por_parcela' => '% por Parcela',
    'id_tabela_preco' => 'Tabela de Preço',
    'erro_salvar_modelo_comissao' => 'Erro ao salvar modelo de comissão.',
```

Em `resources/lang/es/administracao.php`:

```php
    'modelo_de_comissao' => 'Modelo de Comisión',
    'novo_modelo_de_comissao' => 'Nuevo Modelo de Comisión',
    'editar_modelo_de_comissao' => 'Editar Modelo de Comisión',
    'nome_do_modelo' => 'Nombre del modelo',
    'parceiro' => 'Socio',
    'pessoa_de_contato_do_parceiro' => 'Persona de contacto del socio',
    'modalidade_de_calculo' => 'Modalidad de cálculo',
    'modalidade_total_venda' => 'Total Venta (%)',
    'modalidade_valor_fixo' => 'Valor Fijo (Gs.)',
    'modalidade_tipo_parcela' => 'Tipo Cuota (%)',
    'modalidade_tabela_preco' => 'Tabla de Precio (%)',
    'forma_de_pagamento_comissao' => 'Forma de pago',
    'pagamento_total' => 'Total (al contado)',
    'pagamento_sobre_parcelas' => 'Sobre cuotas',
    'limite_por_parcela' => '% límite por cuota',
    'valor_de_referencia_simulacao' => 'Valor de referencia (simulación, no guardado)',
    'porc_sobre_venda' => '% sobre la Venta',
    'sinal' => 'Señal',
    'intercalada' => 'Intercalada',
    'chave' => 'Llave',
    'porc_por_parcela' => '% por Cuota',
    'id_tabela_preco' => 'Tabla de Precios',
    'erro_salvar_modelo_comissao' => 'Error al guardar el modelo de comisión.',
```

Em `resources/lang/en/administracao.php`:

```php
    'modelo_de_comissao' => 'Commission Template',
    'novo_modelo_de_comissao' => 'New Commission Template',
    'editar_modelo_de_comissao' => 'Edit Commission Template',
    'nome_do_modelo' => 'Template name',
    'parceiro' => 'Partner',
    'pessoa_de_contato_do_parceiro' => "Partner's contact person",
    'modalidade_de_calculo' => 'Calculation method',
    'modalidade_total_venda' => 'Total Sale (%)',
    'modalidade_valor_fixo' => 'Fixed Amount',
    'modalidade_tipo_parcela' => 'Installment Type (%)',
    'modalidade_tabela_preco' => 'Price Table (%)',
    'forma_de_pagamento_comissao' => 'Payment method',
    'pagamento_total' => 'Total (upfront)',
    'pagamento_sobre_parcelas' => 'Per installment',
    'limite_por_parcela' => 'Per-installment limit %',
    'valor_de_referencia_simulacao' => 'Reference value (simulation only, not saved)',
    'porc_sobre_venda' => '% on the Sale',
    'sinal' => 'Down payment',
    'intercalada' => 'Interspersed',
    'chave' => 'Key/handover',
    'porc_por_parcela' => '% per Installment',
    'id_tabela_preco' => 'Price Table',
    'erro_salvar_modelo_comissao' => 'Error saving commission template.',
```

- [ ] **Step 4: View de listagem**

```php
@extends('partials.page')

@section('title', __('administracao.modelo_de_comissao'))

@section('content')
<div class="row">
	<div class="col-12">
		<div class="page-title-box d-flex align-items-center justify-content-between">
			<h4 class="page-title">{{ __('administracao.modelo_de_comissao') }}</h4>
			<a href="{{ route('administracao.comissao.add') }}" class="btn btn-primary">
				<i class="mdi mdi-plus"></i> {{ __('administracao.novo_modelo_de_comissao') }}
			</a>
		</div>
	</div>
</div>
<div class="row">
	<div class="col-12">
		<div class="card">
			<div class="card-body">
				<table class="table table-striped" id="tabelaComissoes">
					<thead>
						<tr>
							<th>{{ __('administracao.nome_do_modelo') }}</th>
							<th>{{ __('administracao.modalidade_de_calculo') }}</th>
							<th></th>
						</tr>
					</thead>
					<tbody></tbody>
				</table>
			</div>
		</div>
	</div>
</div>
@endsection

@section('scriptsAdicional')
<script>
window.onload = function () {
	var labelsModalidade = {
		venda: '{{ __('administracao.modalidade_total_venda') }}',
		fixo: '{{ __('administracao.modalidade_valor_fixo') }}',
		parcela: '{{ __('administracao.modalidade_tipo_parcela') }}',
		tabela: '{{ __('administracao.modalidade_tabela_preco') }}',
	};

	$.ajax({
		url: url + 'api/administracao/comissao',
		headers: { 'Authorization': `Bearer ${token.access_token}` },
		success: function (modelos) {
			var tbody = $('#tabelaComissoes tbody');
			modelos.forEach(function (m) {
				tbody.append(
					'<tr><td>' + m.nm_parametro_comissao + '</td><td>' + (labelsModalidade[m.tp_modalidade] || m.tp_modalidade) + '</td>' +
					'<td class="text-end"><a href="' + url + 'administracao/comissao/' + m.id_parametro_comissao + '" class="btn btn-sm btn-light"><i class="mdi mdi-pencil"></i></a></td></tr>'
				);
			});
		}
	});
};
</script>
@endsection
```

- [ ] **Step 5: View de formulário (modalidades + simulação)**

```php
@extends('partials.page')

@section('title', $id ? __('administracao.editar_modelo_de_comissao') : __('administracao.novo_modelo_de_comissao'))

@section('content')
<div class="row">
	<div class="col-12">
		<div class="page-title-box">
			<h4 class="page-title">{{ $id ? __('administracao.editar_modelo_de_comissao') : __('administracao.novo_modelo_de_comissao') }}</h4>
		</div>
	</div>
</div>
<div class="row">
	<div class="col-12">
		<div class="card">
			<div class="card-body">
				<form id="formComissao">
					<div class="row mb-3">
						<div class="col-md-6">
							<label class="form-label">{{ __('administracao.nome_do_modelo') }} <span class="text-danger">*</span></label>
							<input type="text" class="form-control" id="nm_parametro_comissao" required>
						</div>
						<div class="col-md-6">
							<label class="form-label">{{ __('administracao.empreendimento') }}</label>
							<select class="form-select" id="id_empreendimento" data-toggle="select2">
								<option value="">{{ __('administracao.selecione') }}</option>
							</select>
						</div>
					</div>

					<div class="row mb-3 position-relative">
						<div class="col-md-6">
							<label class="form-label">{{ __('administracao.parceiro') }} <span class="text-danger">*</span></label>
							<input type="text" class="form-control" id="parceiro_busca" autocomplete="off" required>
							<input type="hidden" id="id_parceiro">
							<div id="parceiroResultados" class="list-group position-absolute w-100" style="z-index:1000;"></div>
						</div>
						<div class="col-md-6 position-relative">
							<label class="form-label">{{ __('administracao.pessoa_de_contato_do_parceiro') }} <span class="text-danger">*</span></label>
							<input type="text" class="form-control" id="pessoaParceiro_busca" autocomplete="off" required>
							<input type="hidden" id="id_pessoa_parceiro">
							<div id="pessoaParceiroResultados" class="list-group position-absolute w-100" style="z-index:1000;"></div>
						</div>
					</div>

					<div class="row mb-3">
						<div class="col-md-4">
							<label class="form-label">{{ __('administracao.modalidade_de_calculo') }} <span class="text-danger">*</span></label>
							<select class="form-select" id="tp_modalidade" required>
								<option value="venda">{{ __('administracao.modalidade_total_venda') }}</option>
								<option value="fixo">{{ __('administracao.modalidade_valor_fixo') }}</option>
								<option value="parcela">{{ __('administracao.modalidade_tipo_parcela') }}</option>
								<option value="tabela">{{ __('administracao.modalidade_tabela_preco') }}</option>
							</select>
						</div>
						<div class="col-md-4">
							<label class="form-label">{{ __('administracao.valor_de_referencia_simulacao') }}</label>
							<input type="text" class="form-control" id="valor_simulacao" placeholder="0,00">
						</div>
					</div>

					<div class="row mb-3 d-none" id="blocoVenda">
						<div class="col-md-4">
							<label class="form-label">{{ __('administracao.porc_sobre_venda') }}</label>
							<input type="text" class="form-control campo-percentual-simulado" id="porc_venda" placeholder="0,00">
							<small class="text-muted" id="simuladoVenda"></small>
						</div>
					</div>

					<div class="row mb-3 d-none" id="blocoFixo">
						<div class="col-md-4">
							<label class="form-label">{{ __('administracao.valor_fixo') }}</label>
							<input type="text" class="form-control" id="vl_fixo" placeholder="0,00">
						</div>
					</div>

					<div class="row mb-3 d-none" id="blocoParcela">
						<div class="col-md-4">
							<label class="form-label">{{ __('administracao.tipo_de_tabela_de_parcelamento') }}</label>
							<select class="form-select" id="tp_parcela">
								<option value="N">{{ __('administracao.normal') }}</option>
								<option value="S">{{ __('administracao.sinal') }}</option>
								<option value="I">{{ __('administracao.intercalada') }}</option>
								<option value="C">{{ __('administracao.chave') }}</option>
							</select>
						</div>
						<div class="col-md-4">
							<label class="form-label">{{ __('administracao.porc_por_parcela') }}</label>
							<input type="text" class="form-control campo-percentual-simulado" id="porc_parcela_tipo" placeholder="0,00">
							<small class="text-muted" id="simuladoParcela"></small>
						</div>
					</div>

					<div class="row mb-3 d-none" id="blocoTabela">
						<div class="col-md-4">
							<label class="form-label">{{ __('administracao.id_tabela_preco') }}</label>
							<input type="number" class="form-control" id="id_tabela_preco">
						</div>
						<div class="col-md-4">
							<label class="form-label">{{ __('administracao.porc_por_parcela') }}</label>
							<input type="text" class="form-control campo-percentual-simulado" id="porc_parcela_tabela" placeholder="0,00">
							<small class="text-muted" id="simuladoTabela"></small>
						</div>
					</div>

					<div class="row mb-3">
						<div class="col-md-4">
							<label class="form-label">{{ __('administracao.forma_de_pagamento_comissao') }}</label>
							<select class="form-select" id="parcela_paga">
								<option value="0">{{ __('administracao.pagamento_total') }}</option>
								<option value="1">{{ __('administracao.pagamento_sobre_parcelas') }}</option>
							</select>
						</div>
						<div class="col-md-4 d-none" id="blocoLimiteParcela">
							<label class="form-label">{{ __('administracao.limite_por_parcela') }}</label>
							<input type="text" class="form-control" id="pc_limite_parcela" placeholder="0,00">
						</div>
					</div>

					<button type="button" class="btn btn-success" id="btnSalvar">{{ __('common.save') }}</button>
					<a href="{{ route('administracao.comissao') }}" class="btn btn-light">{{ __('common.back') }}</a>
				</form>
			</div>
		</div>
	</div>
</div>
@endsection

@section('scriptsAdicional')
<script>
window.onload = function () {
	var id = @json($id);

	function buscaPessoa(inputId, resultadosId, hiddenId) {
		let timeoutBusca;
		$('#' + inputId).on('input', function () {
			clearTimeout(timeoutBusca);
			var termo = this.value;
			if (termo.length < 2) { $('#' + resultadosId).empty(); return; }
			timeoutBusca = setTimeout(function () {
				$.ajax({
					url: url + 'api/cadastro/pessoas/buscar',
					data: { search: termo },
					headers: { 'Authorization': `Bearer ${token.access_token}` },
					success: function (pessoas) {
						var box = $('#' + resultadosId);
						box.empty();
						pessoas.forEach(function (p) {
							box.append('<a href="javascript:void(0);" class="list-group-item list-group-item-action" data-id="' + p.id + '" data-text="' + p.text + '">' + p.text + '</a>');
						});
					}
				});
			}, 300);
		});
		$('#' + resultadosId).on('click', 'a', function () {
			$('#' + hiddenId).val($(this).data('id'));
			$('#' + inputId).val($(this).data('text'));
			$('#' + resultadosId).empty();
		});
	}

	buscaPessoa('parceiro_busca', 'parceiroResultados', 'id_parceiro');
	buscaPessoa('pessoaParceiro_busca', 'pessoaParceiroResultados', 'id_pessoa_parceiro');

	// --- Toggle de bloco por modalidade ---
	function aplicarModalidade() {
		var modalidade = $('#tp_modalidade').val();
		$('#blocoVenda, #blocoFixo, #blocoParcela, #blocoTabela').addClass('d-none');
		$('#bloco' + modalidade.charAt(0).toUpperCase() + modalidade.slice(1)).removeClass('d-none');
	}
	$('#tp_modalidade').on('change', aplicarModalidade);
	aplicarModalidade();

	$('#parcela_paga').on('change', function () {
		$('#blocoLimiteParcela').toggleClass('d-none', $(this).val() !== '1');
	}).trigger('change');

	// --- Simulação (client-side, nunca enviada no payload) ---
	function percentualParaNumero(valor) {
		var texto = String(valor ?? '').trim();
		if (!texto) return 0;
		if (texto.indexOf(',') !== -1) texto = texto.replace(/\./g, '').replace(',', '.');
		return Number(texto) || 0;
	}
	function atualizarSimulacao() {
		var base = percentualParaNumero($('#valor_simulacao').val());
		if (!base) { $('#simuladoVenda, #simuladoParcela, #simuladoTabela').text(''); return; }
		var resultado = function (percInputId, labelId) {
			var pc = percentualParaNumero($('#' + percInputId).val());
			$('#' + labelId).text(pc ? '≈ ' + (base * pc / 100).toLocaleString() : '');
		};
		resultado('porc_venda', 'simuladoVenda');
		resultado('porc_parcela_tipo', 'simuladoParcela');
		resultado('porc_parcela_tabela', 'simuladoTabela');
	}
	$('#valor_simulacao, #porc_venda, #porc_parcela_tipo, #porc_parcela_tabela').on('input', atualizarSimulacao);

	// --- Empreendimento (opcional) ---
	$.ajax({
		url: url + 'api/cadastro/empreendimento/lista',
		headers: { 'Authorization': `Bearer ${token.access_token}` },
		success: function (empreendimentos) {
			empreendimentos.forEach(function (e) {
				$('#id_empreendimento').append($('<option>', { value: e.id, text: e.nome }));
			});
			// select2 não redesenha a lista só de ->append() — precisa do change pra
			// refletir (mesmo padrão já usado em vendas/parametroComissaoFormulario.blade.php,
			// achado no task review desta task antes do dispatch).
			$('#id_empreendimento').trigger('change');
			if (id) { carregarDados(); }
		}
	});

	function carregarDados() {
		$.ajax({
			url: url + 'api/administracao/comissao/' + id,
			headers: { 'Authorization': `Bearer ${token.access_token}` },
			success: function (data) {
				$('#nm_parametro_comissao').val(data.nm_parametro_comissao);
				$('#id_empreendimento').val(data.id_empreendimento).trigger('change');
				$('#id_parceiro').val(data.id_parceiro);
				$('#id_pessoa_parceiro').val(data.id_pessoa_parceiro);
				$('#tp_modalidade').val(data.tp_modalidade).trigger('change');
				$('#porc_venda').val(data.porc_venda);
				$('#vl_fixo').val(data.vl_fixo);
				$('#porc_parcela_tipo, #porc_parcela_tabela').val(data.porc_parcela);
				$('#tp_parcela').val(data.tp_parcela);
				$('#id_tabela_preco').val(data.id_tabela_preco);
				$('#parcela_paga').val(data.parcela_paga).trigger('change');
				$('#pc_limite_parcela').val(data.pc_limite_parcela);
			}
		});
	}

	$('#btnSalvar').on('click', function () {
		var modalidade = $('#tp_modalidade').val();
		var porcParcela = modalidade === 'parcela' ? $('#porc_parcela_tipo').val() : (modalidade === 'tabela' ? $('#porc_parcela_tabela').val() : null);

		var dados = {
			nm_parametro_comissao: $('#nm_parametro_comissao').val(),
			id_empreendimento: $('#id_empreendimento').val() || null,
			id_parceiro: $('#id_parceiro').val(),
			id_pessoa_parceiro: $('#id_pessoa_parceiro').val(),
			tp_modalidade: modalidade,
			porc_venda: modalidade === 'venda' ? percentualParaNumero($('#porc_venda').val()) : null,
			vl_fixo: modalidade === 'fixo' ? percentualParaNumero($('#vl_fixo').val()) : null,
			porc_parcela: porcParcela ? percentualParaNumero(porcParcela) : null,
			tp_parcela: modalidade === 'parcela' ? $('#tp_parcela').val() : null,
			id_tabela_preco: modalidade === 'tabela' ? $('#id_tabela_preco').val() : null,
			parcela_paga: $('#parcela_paga').val(),
			pc_limite_parcela: $('#parcela_paga').val() === '1' ? percentualParaNumero($('#pc_limite_parcela').val()) : null,
		};

		$.ajax({
			url: url + 'api/administracao/comissao' + (id ? '/' + id : ''),
			method: id ? 'PUT' : 'POST',
			data: dados,
			headers: { 'Authorization': `Bearer ${token.access_token}` },
			success: function () { window.location.href = url + 'administracao/comissao'; },
			error: function (xhr) { alert(xhr.responseJSON?.message || '{{ __('administracao.erro_salvar_modelo_comissao') }}'); }
		});
	});
};
</script>
@endsection
```

- [ ] **Step 6: Verificação manual (sem teste automatizado — Blade/JS)**

Abrir `administracao/comissao/add` no navegador, criar 1 modelo de cada modalidade, confirmar que o bloco certo aparece ao trocar a modalidade, que o campo de simulação calcula ao digitar, e que salvar funciona sem exigir empreendimento.

- [ ] **Step 7: Commit**

```bash
git add app/Http/Controllers/AdministracaoController.php resources/views/administracao/comissao.blade.php resources/views/administracao/comissaoFormulario.blade.php routes/web.php resources/lang/pt/administracao.php resources/lang/es/administracao.php resources/lang/en/administracao.php
git commit -m "feat: telas de cadastro de modelo de comissao"
```

---

## Task 14: Frontend do Contrato — seção "Parceiros de Comissão"

Sem teste automatizado (Blade/JS) — verificação manual.

**Files:**
- Modify: `resources/views/administracao/contratoFormulario.blade.php`

**Interfaces:**
- Consumes: `GET administracao/contrato/comissoesDisponiveis` (Task 7), payload `comissoes` lido/gravado pelo backend (Task 8/9).

- [ ] **Step 1: HTML da seção nova**

Na aba `tab-pessoa` (linha ~417-448), logo antes de `</div> <!-- end tab-pessoa -->`:

```php

						<h6 class="mt-4">{{ __('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">
							<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>
```

- [ ] **Step 2: JS — carregar combo, adicionar/remover da lista**

Logo depois do bloco de `coCompradores` (linha ~605, depois de `buscaPessoa('cocomprador_busca', ...)`):

```php

	// --- Parceiros de Comissão (mesmo padrão de lista de Co-compradores acima) ---
	var comissoesContrato = [];
	function renderComissoesContrato() {
		var tbody = $('#tabelaComissoesContrato tbody');
		tbody.empty();
		comissoesContrato.forEach(function (c, idx) {
			tbody.append('<tr><td>' + c.nome + '</td><td class="text-center"><button type="button" class="btn btn-sm btn-light btnRemoverComissao" data-idx="' + idx + '"><i class="mdi mdi-delete"></i></button></td></tr>');
		});
	}
	$('#tabelaComissoesContrato').on('click', '.btnRemoverComissao', function () {
		comissoesContrato.splice($(this).data('idx'), 1);
		renderComissoesContrato();
	});
	$.ajax({
		url: url + 'api/administracao/contrato/comissoesDisponiveis',
		headers: { 'Authorization': `Bearer ${token.access_token}` },
		success: function (lista) {
			lista.forEach(function (c) {
				$('#comissao_select').append($('<option>', { value: c.id, text: c.text }));
			});
		}
	});
	$('#btnAdicionarComissao').on('click', function () {
		var select = $('#comissao_select');
		var id = select.val();
		if (!id) { return; }
		comissoesContrato.push({ id: id, nome: select.find(':selected').text() });
		renderComissoesContrato();
		select.val('');
	});
```

- [ ] **Step 3: Carregar em modo edição**

No callback de carga do contrato (linha ~952-955, logo depois de `renderCoCompradores();`):

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

- [ ] **Step 4: Incluir no payload de submit**

Na montagem do `payload` (linha ~1215, logo depois de `co_compradores: coCompradores.map(...)`):

```php
			comissoes: comissoesContrato.map(function (c) { return c.id; }),
```

- [ ] **Step 5: Verificação manual**

Abrir um contrato existente (sem `fl_gerado`), adicionar 2 modelos de comissão na lista, salvar, reabrir e confirmar que os 2 continuam lá. Gerar as parcelas e confirmar (via `api/payables`/consulta direta, não tem tela de listagem de `COMISSAO_LANCAMENTO` pronta nesta entrega) que os lançamentos foram criados.

- [ ] **Step 6: Commit**

```bash
git add resources/views/administracao/contratoFormulario.blade.php
git commit -m "feat: secao Parceiros de Comissao no formulario de contrato"
```

---

## Task 15: Menu lateral

Sem teste automatizado (Blade) — verificação manual.

**Files:**
- Modify: `resources/views/partials/sidebar.blade.php`
- Modify: `resources/lang/{pt,es,en}/menu.php`

**Interfaces:**
- Produces: item de menu "Modelo de Comissão" dentro do bloco Administração, visível só com a permissão `Listar Modelo de Comissão` (Task 12).

- [ ] **Step 1: Traduções do menu**

`resources/lang/pt/menu.php`:
```php
    'modelo_de_comissao' => 'Modelo de Comissão',
```

`resources/lang/es/menu.php`:
```php
    'modelo_de_comissao' => 'Modelo de Comisión',
```

`resources/lang/en/menu.php`:
```php
    'modelo_de_comissao' => 'Commission Template',
```

- [ ] **Step 2: Item de menu**

Em `resources/views/partials/sidebar.blade.php`, no bloco Administração (perto do item de "Contrato", linhas ~82-119), acrescentar:

```php
                        <li class="side-nav-item" data-permission="Listar Modelo de Comissão">
                            <a href="{{url('/administracao/comissao')}}">{{ __('menu.modelo_de_comissao') }}</a>
                        </li>
```

Sem ícone, sem `class="side-nav-link"`, com `url()` (não `route()`) e indentação
em espaços — achado do task review (20/10/2026): o HTML original deste passo
usava um padrão de ícone/classe que não existe em NENHUM item irmão deste
mesmo bloco (todos os ~15 itens de "Administração" em
`resources/views/partials/sidebar.blade.php:86-114` são `<a href="{{url(...)}}">{{ __('menu.X') }}</a>`
puro, sem ícone nem `side-nav-link` — esse padrão com ícone é de outro nível
do menu, não deste). Corrigido pra bater exatamente com os vizinhos.

- [ ] **Step 3: Verificação manual**

Logar com um usuário que tenha a role `Listar Modelo de Comissão` (via equivalência semântica da Task 12, quem já tem `Listar Contrato`) e confirmar que o item aparece no menu e navega pra `administracao/comissao`.

- [ ] **Step 4: Commit**

```bash
git add resources/views/partials/sidebar.blade.php resources/lang/pt/menu.php resources/lang/es/menu.php resources/lang/en/menu.php
git commit -m "feat: item de menu Modelo de Comissão em Administracao"
```
