# Tradução de tabelas — Fase 1 (Bancos e Extrato) 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:** Renomear `banks`, `bank_empreendimentos` e `bank_statements` (tabela e colunas) para `CONTA_BANCARIA`, `CONTA_BANCARIA_EMPREENDIMENTO` e `EXTRATO_BANCARIO`, dropar `people` do tenant, e atualizar todo o código que depende delas, ponta a ponta.

**Architecture:** Uma migration idempotente em `database/migrations/clientes` faz `RENAME TABLE` + `RENAME COLUMN` (via `DB::statement`, sem doctrine/dbal). O código é atualizado por consumidor: models, cadastro de banco (API + telas), consumidores de conta bancária (contrato, acordo, importação, fechamento, movimentação, relatório) e extrato/conciliação. As tabelas das fases seguintes (`receivables`, `payables`, `financial_movements`, `account_plans`) **não** mudam aqui.

**Tech Stack:** PHP 8.1, Laravel 10, MySQL 8 (produção), SQLite in-memory (testes), Blade + jQuery.

**Spec:** `docs/superpowers/specs/2026-10-29-traducao-tabelas-ingles-design.md`

## Global Constraints

- Responder ao programador em pt-BR; **nunca** rodar `git add/commit/push` nem `npm run build` — onde a skill pede commit, **pare e avise o programador** que é um bom ponto de commit.
- Ambiente do programador: **nativo (PHP + Apache)**, `php artisan ...` direto no host.
- Tabela em CAIXA ALTA; coluna minúscula com prefixo `id_`/`vl_`/`dt_`/`nr_`/`fl_`/`ds_`/`nm_`/`tp_`/`cd_`.
- Ficam como estão: `id`, `created_at`, `updated_at` e colunas já em português.
- Valores de enum **não** mudam (`'credit'`, `'debit'`, `'ofx'`, `'api'`, `'manual'`, `'P'/'V'/'S'`).
- Nomes de **relação** Eloquent (`bankAccount`, `assignor`, `empreendimentos`, `financialMovement`) e as chaves JSON derivadas deles (`bank_account`) **não** mudam nesta fase — só colunas.
- Colunas das tabelas de outras fases que apontam pra conta bancária (`receivables.bank_account_id`/`bank_id`, `payables.bank_account_id`, `financial_movements.bank_account_id`, `FECHAMENTO_MENSAL.cd_local_pagamento`) **não** mudam aqui.
- Chave de JSON/payload que espelha 1:1 uma coluna renomeada é renomeada junto; chave calculada/composta (`assignor_nome`, `empreendimento_ids`, `empreendimentos_nomes`, `date_groups`, `bank_entries`, `is_conciliated`, `date`) fica.
- Nunca use busca-e-substitui global em nomes genéricos (`code`, `active`, `amount`, `type`, `description`): altere só onde o objeto é `Bank`/`BankStatement`/`banks`/`bank_statements`.

## Mapa desta fase (referência para todas as tasks)

**`banks` → `CONTA_BANCARIA`**
`code`→`cd_codigo`, `bank_name`→`nm_banco`, `bank_code`→`cd_banco`, `agency_number`→`nr_agencia`, `agency_digit`→`nr_agencia_dv`, `account_number`→`nr_conta`, `account_digit`→`nr_conta_dv`, `assignor_contract`→`nr_contrato_cedente`, `assignor_id`→`id_cedente`, `competence_days`→`nr_dias_competencia`, `cooperative`→`ds_cooperativa`, `current_ticket_number`→`nr_boleto_atual`, `document_type`→`tp_documento`, `variation`→`ds_variacao`, `wallet`→`ds_carteira`, `active`→`fl_ativo`, `start_balance`→`vl_saldo_inicial`, `start_balance_date`→`dt_saldo_inicial`, `legacy_banco_id`→`id_banco_legado`

**`bank_empreendimentos` → `CONTA_BANCARIA_EMPREENDIMENTO`**
`bank_id`→`id_conta_bancaria`

**`bank_statements` → `EXTRATO_BANCARIO`**
`bank_account_id`→`id_conta_bancaria`, `code`→`cd_codigo`, `transaction_date`→`dt_transacao`, `description`→`ds_descricao`, `memo`→`ds_memo`, `amount`→`vl_valor`, `type`→`tp_transacao`, `balance`→`vl_saldo`, `transaction_id`→`cd_transacao`, `origin`→`tp_origem`, `financial_movement_id`→`id_movimentacao_financeira`, `active`→`fl_ativo`, `created_by`→`id_usuario_criacao`

---

### Task 1: Migration de rename + drop de `people` do tenant

**Files:**
- Create: `database/migrations/clientes/2026_10_29_110000_rename_banks_tables_to_portuguese.php`
- Test: `tests/Feature/Migrations/RenameBanksTablesMigrationTest.php`

**Interfaces:**
- Produces: tabelas `CONTA_BANCARIA`, `CONTA_BANCARIA_EMPREENDIMENTO`, `EXTRATO_BANCARIO` com as colunas do mapa; `people` inexistente no tenant.

- [ ] **Step 1: Escrever o teste (falha)**

```php
<?php

namespace Tests\Feature\Migrations;

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;
use Tests\TestCase;

/**
 * Fase 1 da tradução de tabelas (docs/superpowers/specs/2026-10-29-traducao-tabelas-ingles-design.md):
 * a migration renomeia banks/bank_empreendimentos/bank_statements preservando
 * dados, é idempotente (rodar 2x não quebra) e o down() desfaz.
 */
class RenameBanksTablesMigrationTest extends TestCase
{
    private const MIGRATION = 'database/migrations/clientes/2026_10_29_110000_rename_banks_tables_to_portuguese.php';

    protected function setUp(): void
    {
        parent::setUp();

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

        Schema::create('banks', function (Blueprint $t) {
            $t->id();
            $t->integer('code')->nullable();
            $t->string('bank_name');
            $t->string('bank_code')->nullable();
            $t->string('agency_number')->nullable();
            $t->string('agency_digit')->nullable();
            $t->string('account_number')->nullable();
            $t->string('account_digit')->nullable();
            $t->string('assignor_contract')->nullable();
            $t->unsignedBigInteger('assignor_id')->nullable();
            $t->integer('competence_days')->nullable();
            $t->string('cooperative')->nullable();
            $t->string('current_ticket_number')->nullable();
            $t->string('document_type')->nullable();
            $t->string('variation')->nullable();
            $t->string('wallet')->nullable();
            $t->boolean('active')->default(true);
            $t->decimal('start_balance', 15, 2)->nullable();
            $t->date('start_balance_date')->nullable();
            $t->unsignedInteger('legacy_banco_id')->nullable();
            $t->string('chave_pix')->nullable();
            $t->timestamps();
        });
        Schema::create('bank_empreendimentos', function (Blueprint $t) {
            $t->id();
            $t->unsignedBigInteger('bank_id');
            $t->unsignedInteger('id_empreendimento');
        });
        Schema::create('bank_statements', function (Blueprint $t) {
            $t->id();
            $t->unsignedBigInteger('bank_account_id');
            $t->integer('code');
            $t->date('transaction_date');
            $t->string('description')->nullable();
            $t->string('memo')->nullable();
            $t->decimal('amount', 15, 2);
            $t->string('type');
            $t->decimal('balance', 15, 2)->nullable();
            $t->string('transaction_id')->nullable();
            $t->string('origin')->default('ofx');
            $t->unsignedBigInteger('financial_movement_id')->nullable();
            $t->boolean('active')->default(true);
            $t->unsignedBigInteger('created_by')->nullable();
            $t->timestamps();
        });
        Schema::create('people', function (Blueprint $t) {
            $t->id();
        });

        DB::table('banks')->insert(['id' => 7, 'bank_name' => 'Banco X', 'agency_number' => '1234', 'active' => 1, 'chave_pix' => 'pix@x']);
        DB::table('bank_empreendimentos')->insert(['bank_id' => 7, 'id_empreendimento' => 3]);
        DB::table('bank_statements')->insert(['bank_account_id' => 7, 'code' => 1, 'transaction_date' => '2026-10-01', 'amount' => 10.5, 'type' => 'credit']);
    }

    private function migration()
    {
        return require base_path(self::MIGRATION);
    }

    public function test_renomeia_tabelas_e_colunas_preservando_dados(): void
    {
        $this->migration()->up();

        $this->assertFalse(Schema::hasTable('banks'));
        $this->assertFalse(Schema::hasTable('people'));
        $this->assertTrue(Schema::hasColumns('CONTA_BANCARIA', [
            'cd_codigo', 'nm_banco', 'cd_banco', 'nr_agencia', 'nr_agencia_dv', 'nr_conta', 'nr_conta_dv',
            'nr_contrato_cedente', 'id_cedente', 'nr_dias_competencia', 'ds_cooperativa', 'nr_boleto_atual',
            'tp_documento', 'ds_variacao', 'ds_carteira', 'fl_ativo', 'vl_saldo_inicial', 'dt_saldo_inicial',
            'id_banco_legado', 'chave_pix',
        ]));
        $this->assertTrue(Schema::hasColumns('CONTA_BANCARIA_EMPREENDIMENTO', ['id_conta_bancaria', 'id_empreendimento']));
        $this->assertTrue(Schema::hasColumns('EXTRATO_BANCARIO', [
            'id_conta_bancaria', 'cd_codigo', 'dt_transacao', 'ds_descricao', 'ds_memo', 'vl_valor', 'tp_transacao',
            'vl_saldo', 'cd_transacao', 'tp_origem', 'id_movimentacao_financeira', 'fl_ativo', 'id_usuario_criacao',
        ]));

        $this->assertSame('Banco X', DB::table('CONTA_BANCARIA')->where('id', 7)->value('nm_banco'));
        $this->assertSame(7, (int) DB::table('CONTA_BANCARIA_EMPREENDIMENTO')->value('id_conta_bancaria'));
        $this->assertSame('credit', DB::table('EXTRATO_BANCARIO')->value('tp_transacao'));
    }

    public function test_e_idempotente(): void
    {
        $this->migration()->up();
        $this->migration()->up();

        $this->assertTrue(Schema::hasColumn('CONTA_BANCARIA', 'nm_banco'));
    }

    public function test_down_desfaz_o_rename(): void
    {
        $this->migration()->up();
        $this->migration()->down();

        $this->assertTrue(Schema::hasColumns('banks', ['bank_name', 'active', 'code']));
        $this->assertTrue(Schema::hasColumn('bank_empreendimentos', 'bank_id'));
        $this->assertTrue(Schema::hasColumns('bank_statements', ['bank_account_id', 'amount', 'type']));
    }
}
```

- [ ] **Step 2: Rodar e ver falhar**

Run: `php artisan test --filter=RenameBanksTablesMigrationTest`
Expected: FAIL — arquivo da migration não existe (`require` falha).

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

```php
<?php

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

// Fase 1 da tradução das tabelas vindas do cereus cond para o padrão do legado
// (tabela em CAIXA ALTA, coluna com prefixo de tipo) — ver
// docs/superpowers/specs/2026-10-29-traducao-tabelas-ingles-design.md.
// `BANCO` já existe no tenant (tabela legada distinta), por isso `banks` vira
// CONTA_BANCARIA. Rename via DB::statement: doctrine/dbal não está instalado.
// Idempotente (guardas hasTable/hasColumn): tenant novo cria com o nome antigo
// pelas migrations de junho/julho e esta renomeia. O MySQL 8 leva FKs e índices
// junto no rename (os nomes das constraints continuam os antigos).
// `people` sai junto: vazia e órfã (o vínculo de pessoa do financeiro é PESSOA).
return new class extends Migration
{
    private const TABELAS = [
        'banks' => ['CONTA_BANCARIA', [
            'code' => 'cd_codigo',
            'bank_name' => 'nm_banco',
            'bank_code' => 'cd_banco',
            'agency_number' => 'nr_agencia',
            'agency_digit' => 'nr_agencia_dv',
            'account_number' => 'nr_conta',
            'account_digit' => 'nr_conta_dv',
            'assignor_contract' => 'nr_contrato_cedente',
            'assignor_id' => 'id_cedente',
            'competence_days' => 'nr_dias_competencia',
            'cooperative' => 'ds_cooperativa',
            'current_ticket_number' => 'nr_boleto_atual',
            'document_type' => 'tp_documento',
            'variation' => 'ds_variacao',
            'wallet' => 'ds_carteira',
            'active' => 'fl_ativo',
            'start_balance' => 'vl_saldo_inicial',
            'start_balance_date' => 'dt_saldo_inicial',
            'legacy_banco_id' => 'id_banco_legado',
        ]],
        'bank_empreendimentos' => ['CONTA_BANCARIA_EMPREENDIMENTO', [
            'bank_id' => 'id_conta_bancaria',
        ]],
        'bank_statements' => ['EXTRATO_BANCARIO', [
            'bank_account_id' => 'id_conta_bancaria',
            'code' => 'cd_codigo',
            'transaction_date' => 'dt_transacao',
            'description' => 'ds_descricao',
            'memo' => 'ds_memo',
            'amount' => 'vl_valor',
            'type' => 'tp_transacao',
            'balance' => 'vl_saldo',
            'transaction_id' => 'cd_transacao',
            'origin' => 'tp_origem',
            'financial_movement_id' => 'id_movimentacao_financeira',
            'active' => 'fl_ativo',
            'created_by' => 'id_usuario_criacao',
        ]],
    ];

    public function up(): void
    {
        foreach (self::TABELAS as $antiga => [$nova, $colunas]) {
            $this->renomear($antiga, $nova, $colunas);
        }

        Schema::dropIfExists('people');
    }

    public function down(): void
    {
        foreach (array_reverse(self::TABELAS, true) as $antiga => [$nova, $colunas]) {
            $this->renomear($nova, $antiga, array_flip($colunas));
        }
        // `people` não é recriada: era vazia e sem uso.
    }

    private function renomear(string $de, string $para, array $colunas): void
    {
        if (Schema::hasTable($de) && !Schema::hasTable($para)) {
            Schema::rename($de, $para);
        }

        if (!Schema::hasTable($para)) {
            return;
        }

        foreach ($colunas as $antiga => $nova) {
            if (Schema::hasColumn($para, $antiga) && !Schema::hasColumn($para, $nova)) {
                DB::statement("ALTER TABLE `{$para}` RENAME COLUMN `{$antiga}` TO `{$nova}`");
            }
        }
    }
};
```

Atenção: no SQLite `hasTable` é case-insensitive, mas os nomes antigo/novo são diferentes de verdade (`banks` ≠ `CONTA_BANCARIA`), então a guarda funciona nos dois bancos.

- [ ] **Step 4: Rodar e ver passar**

Run: `php artisan test --filter=RenameBanksTablesMigrationTest`
Expected: 3 testes PASS.

- [ ] **Step 5: Ponto de commit** — avisar o programador.

---

### Task 2: Models `Bank` e `BankStatement` + remoção de `Person`/`Spouse`/`Address`/commands órfãos

**Files:**
- Modify: `app/Models/Bank.php`
- Modify: `app/Models/BankStatement.php`
- Delete: `app/Models/Person.php`, `app/Models/Spouse.php`, `app/Models/Address.php`
- Delete: `app/Console/Commands/ImportBancoContaToBanks.php`, `app/Console/Commands/ImportBancoAssociacoesToBanks.php`
- Delete (só se o grep do Step 4 confirmar zero uso): `app/Enums/PersonType.php`, `app/Enums/MaritalStatus.php`, `app/Enums/Gender.php`, `app/Enums/DocumentType.php`, `app/Enums/TaxPayerType.php`
- Test: `tests/Feature/Financeiro/ContaBancariaModelTest.php`

**Interfaces:**
- Consumes: schema da Task 1.
- Produces: `Bank` com `$table = 'CONTA_BANCARIA'`, atributos em português (mapa acima); `Bank::assignor()` (FK `id_cedente`), `Bank::empreendimentos()` (pivot `CONTA_BANCARIA_EMPREENDIMENTO`, `id_conta_bancaria`); `BankStatement` com `$table = 'EXTRATO_BANCARIO'`, `bankAccount()` (FK `id_conta_bancaria`), `financialMovement()` (FK `id_movimentacao_financeira`), `createdBy()` (FK `id_usuario_criacao`), `isCredit()/isDebit()` lendo `tp_transacao`, `isConciliated()` lendo `id_movimentacao_financeira`.

- [ ] **Step 1: Escrever o teste (falha)**

```php
<?php

namespace Tests\Feature\Financeiro;

use App\Models\Bank;
use App\Models\BankStatement;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;
use Tests\TestCase;

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

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

        Schema::connection('cliente')->create('CONTA_BANCARIA', function (Blueprint $t) {
            $t->id();
            $t->integer('cd_codigo')->nullable();
            $t->string('nm_banco');
            $t->string('nr_conta')->nullable();
            $t->unsignedBigInteger('id_cedente')->nullable();
            $t->boolean('fl_ativo')->default(true);
            $t->decimal('vl_saldo_inicial', 15, 2)->nullable();
            $t->date('dt_saldo_inicial')->nullable();
            $t->timestamps();
        });
        Schema::connection('cliente')->create('CONTA_BANCARIA_EMPREENDIMENTO', function (Blueprint $t) {
            $t->id();
            $t->unsignedBigInteger('id_conta_bancaria');
            $t->unsignedInteger('id_empreendimento');
        });
        Schema::connection('cliente')->create('EMPREENDIMENTO', function (Blueprint $t) {
            $t->increments('id');
            $t->string('nm_empreendimento')->nullable();
        });
        Schema::connection('cliente')->create('EXTRATO_BANCARIO', function (Blueprint $t) {
            $t->id();
            $t->unsignedBigInteger('id_conta_bancaria');
            $t->integer('cd_codigo');
            $t->date('dt_transacao');
            $t->decimal('vl_valor', 15, 2);
            $t->string('tp_transacao');
            $t->unsignedBigInteger('id_movimentacao_financeira')->nullable();
            $t->boolean('fl_ativo')->default(true);
            $t->timestamps();
        });
    }

    public function test_conta_bancaria_gera_codigo_sequencial_e_faz_cast(): void
    {
        $a = Bank::create(['nm_banco' => 'A', 'fl_ativo' => 1, 'vl_saldo_inicial' => 5]);
        $b = Bank::create(['nm_banco' => 'B']);

        $this->assertSame(1, (int) $a->cd_codigo);
        $this->assertSame(2, (int) $b->cd_codigo);
        $this->assertTrue($a->fresh()->fl_ativo);
        $this->assertSame('5.00', $a->fresh()->vl_saldo_inicial);
    }

    public function test_pivot_de_empreendimentos(): void
    {
        DB::connection('cliente')->table('EMPREENDIMENTO')->insert(['id' => 3, 'nm_empreendimento' => 'Res. Sol']);
        $banco = Bank::create(['nm_banco' => 'A']);
        $banco->empreendimentos()->sync([3]);

        $this->assertSame([3], $banco->fresh()->empreendimentos->pluck('id')->all());
    }

    public function test_extrato_usa_colunas_em_portugues(): void
    {
        $banco = Bank::create(['nm_banco' => 'A']);
        $linha = BankStatement::create([
            'id_conta_bancaria' => $banco->id, 'cd_codigo' => 1, 'dt_transacao' => '2026-10-01',
            'vl_valor' => 10, 'tp_transacao' => 'credit',
        ]);

        $this->assertTrue($linha->isCredit());
        $this->assertFalse($linha->isConciliated());
        $this->assertSame('A', $linha->bankAccount->nm_banco);
    }
}
```

- [ ] **Step 2: Rodar e ver falhar**

Run: `php artisan test --filter=ContaBancariaModelTest`
Expected: FAIL — `no such table: banks` (model ainda aponta pro nome antigo).

- [ ] **Step 3: Atualizar `app/Models/Bank.php`**

- Adicionar `protected $table = 'CONTA_BANCARIA';` logo abaixo de `$connection`.
- No `$fillable`, renomear **só as colunas reais** conforme o mapa: `bank_name`→`nm_banco`, `bank_code`→`cd_banco`, `active`→`fl_ativo`, `agency_number`→`nr_agencia`, `agency_digit`→`nr_agencia_dv`, `account_number`→`nr_conta`, `account_digit`→`nr_conta_dv`, `assignor_contract`→`nr_contrato_cedente`, `assignor_id`→`id_cedente`, `document_type`→`tp_documento`, `competence_days`→`nr_dias_competencia`, `cooperative`→`ds_cooperativa`, `current_ticket_number`→`nr_boleto_atual`, `variation`→`ds_variacao`, `wallet`→`ds_carteira`, `code`→`cd_codigo`, `start_balance`→`vl_saldo_inicial`, `start_balance_date`→`dt_saldo_inicial`, `legacy_banco_id`→`id_banco_legado`.
- **Não mexer** nos itens fantasma do `$fillable` (`account_type`, `description`, `pix_key`, `current_remessa_number`, `is_main`, `penalty_type`, `penalty`, `interest_rate_type`, `interest_rate`, `boleto_message*`, `layout_id`, `boleto_enabled`, `api_*`, `cnab_version`) nem nos métodos `layout()`/`hasIntegrationConfigured()` — é o bug pré-existente de colunas fantasma documentado em `.claude/rules/backend.md`, fora do escopo.
- `$casts`: `'active' => 'boolean'` → `'fl_ativo' => 'boolean'`; `'start_balance' => 'decimal:2'` → `'vl_saldo_inicial' => 'decimal:2'`; `'start_balance_date' => 'date'` → `'dt_saldo_inicial' => 'date'`.
- `boot()`:

```php
        static::creating(function ($model) {
            if (is_null($model->cd_codigo)) {
                $maxCode = self::max('cd_codigo');
                $model->cd_codigo = is_null($maxCode) ? 1 : $maxCode + 1;
            }
        });
```

- Relações:

```php
    public function assignor()
    {
        return $this->belongsTo(\App\Models\Cadastro\Pessoa::class, 'id_cedente');
    }

    // 1 conta bancária pode ser usada em N empreendimentos — ver CONTA_BANCARIA_EMPREENDIMENTO.
    public function empreendimentos()
    {
        return $this->belongsToMany(
            \App\Models\Cadastro\Empreendimento::class,
            'CONTA_BANCARIA_EMPREENDIMENTO',
            'id_conta_bancaria',
            'id_empreendimento'
        );
    }
```

- `receivables()` (`hasMany(Receivable::class, 'bank_id')`) fica igual — `receivables.bank_id` é da fase 4.

- [ ] **Step 4: Atualizar `app/Models/BankStatement.php`**

```php
    protected $connection = 'cliente';

    protected $table = 'EXTRATO_BANCARIO';

    protected $fillable = [
        'id_conta_bancaria',
        'cd_codigo',
        'dt_transacao',
        'ds_descricao',
        'ds_memo',
        'vl_valor',
        'tp_transacao',
        'vl_saldo',
        'cd_transacao',
        'tp_origem',
        'id_movimentacao_financeira',
        'fl_ativo',
        'id_usuario_criacao',
    ];

    protected $casts = [
        'dt_transacao' => 'date',
        'vl_valor'     => 'decimal:2',
        'vl_saldo'     => 'decimal:2',
        'fl_ativo'     => 'boolean',
    ];

    public function bankAccount(): BelongsTo
    {
        return $this->belongsTo(Bank::class, 'id_conta_bancaria');
    }

    public function financialMovement(): BelongsTo
    {
        return $this->belongsTo(FinancialMovement::class, 'id_movimentacao_financeira');
    }

    public function createdBy(): BelongsTo
    {
        return $this->belongsTo(User::class, 'id_usuario_criacao');
    }

    public function isCredit(): bool
    {
        return $this->tp_transacao === 'credit';
    }

    public function isDebit(): bool
    {
        return $this->tp_transacao === 'debit';
    }

    public function isConciliated(): bool
    {
        return $this->id_movimentacao_financeira !== null;
    }
```

- [ ] **Step 5: Remover órfãos**

Apagar `app/Models/Person.php`, `app/Models/Spouse.php`, `app/Models/Address.php`, `app/Console/Commands/ImportBancoContaToBanks.php`, `app/Console/Commands/ImportBancoAssociacoesToBanks.php`. Depois:

Run: `grep -rnwE "PersonType|MaritalStatus|Gender|DocumentType|TaxPayerType" app routes tests resources/views --include=*.php`
Expected: nenhuma ocorrência fora de `app/Enums/` → apagar os 5 enums. (As ocorrências de "Gender" em `resources/lang/*` são texto de tradução, não uso do enum.) `SouthAmericaCountry` e `BankAccountType` **ficam**.

Run: `grep -rnE "banks:import-legacy|banks:import-associacoes" app routes` → Expected: vazio (Kernel não agenda esses commands).

- [ ] **Step 6: Rodar e ver passar**

Run: `php artisan test --filter=ContaBancariaModelTest`
Expected: 3 PASS.

- [ ] **Step 7: Ponto de commit** — avisar o programador.

---

### Task 3: Cadastro de Conta Bancária (API + listagem + formulário)

**Files:**
- Modify: `app/Http/Controllers/Api/Financeiro/BankController.php`
- Modify: `resources/views/banks/index.blade.php:161-199`
- Modify: `resources/views/banks/form.blade.php` (ids de input/erro + JS de carga e payload)
- Modify: `resources/lang/{pt,en,es}/validation.php` (bloco `attributes`)
- Test: `tests/Feature/Financeiro/ContaBancariaApiTest.php`

**Interfaces:**
- Consumes: `Bank` da Task 2.
- Produces: `GET api/financeiro/banks` → itens `{id, nm_banco, cd_banco, nr_agencia, nr_conta, assignor_nome, empreendimentos_nomes, empreendimento_ids, ds_carteira, fl_ativo}`; `GET api/financeiro/banks/{id}` → `toArray()` do model (colunas em português) + `assignor_nome` + `empreendimentos`; `POST/PUT` aceitam as chaves em português.

- [ ] **Step 1: Escrever o teste (falha)**

Chama o controller direto (padrão de `AcordoTermoTest`, sem passar por `cliente.auth`):

```php
<?php

namespace Tests\Feature\Financeiro;

use App\Http\Controllers\Api\Financeiro\BankController;
use App\Models\Bank;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;
use Illuminate\Validation\ValidationException;
use Tests\TestCase;

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

        config(['database.connections.cliente' => ['driver' => 'sqlite', 'database' => ':memory:', 'prefix' => '']]);
        DB::purge('cliente');
        $s = Schema::connection('cliente');

        $s->create('PESSOA', function (Blueprint $t) { $t->increments('id'); $t->string('nm_pessoa')->nullable(); });
        $s->create('EMPREENDIMENTO', function (Blueprint $t) { $t->increments('id'); $t->string('nm_empreendimento')->nullable(); });
        $s->create('CONTA_BANCARIA', function (Blueprint $t) {
            $t->id();
            $t->integer('cd_codigo')->nullable();
            foreach (['nm_banco', 'cd_banco', 'nr_agencia', 'nr_agencia_dv', 'nr_conta', 'nr_conta_dv', 'nr_contrato_cedente',
                      'ds_cooperativa', 'nr_boleto_atual', 'tp_documento', 'ds_variacao', 'ds_carteira', 'tp_juros', 'tp_multa'] as $c) {
                $t->string($c)->nullable();
            }
            $t->unsignedBigInteger('id_cedente')->nullable();
            $t->integer('nr_dias_competencia')->nullable();
            $t->boolean('fl_ativo')->default(true);
            $t->decimal('juros', 10, 4)->nullable();
            $t->decimal('multa', 10, 4)->nullable();
            $t->timestamps();
        });
        $s->create('CONTA_BANCARIA_EMPREENDIMENTO', function (Blueprint $t) {
            $t->id();
            $t->unsignedBigInteger('id_conta_bancaria');
            $t->unsignedInteger('id_empreendimento');
        });

        DB::connection('cliente')->table('PESSOA')->insert(['id' => 1, 'nm_pessoa' => 'Cedente SA']);
        DB::connection('cliente')->table('EMPREENDIMENTO')->insert(['id' => 3, 'nm_empreendimento' => 'Res. Sol']);
    }

    private function payload(array $extra = []): array
    {
        return array_merge([
            'nm_banco' => 'Banco X', 'cd_banco' => '001', 'nr_agencia' => '1234', 'nr_conta' => '999',
            'nr_contrato_cedente' => 'C1', 'id_cedente' => 1, 'empreendimentos' => [3],
            'nr_dias_competencia' => 90, 'nr_boleto_atual' => '0', 'tp_documento' => 'DM', 'ds_carteira' => '17',
            'fl_ativo' => 1, 'tp_juros' => 'P', 'tp_multa' => 'S',
        ], $extra);
    }

    public function test_store_grava_colunas_em_portugues_e_sincroniza_empreendimentos(): void
    {
        $resposta = app(BankController::class)->store(Request::create('/', 'POST', $this->payload()));

        $this->assertSame(201, $resposta->getStatusCode());
        $banco = Bank::first();
        $this->assertSame('Banco X', $banco->nm_banco);
        $this->assertSame('', $banco->ds_variacao);
        $this->assertSame([3], $banco->empreendimentos->pluck('id')->all());
    }

    public function test_store_valida_campos_em_portugues(): void
    {
        $this->expectException(ValidationException::class);
        try {
            app(BankController::class)->store(Request::create('/', 'POST', $this->payload(['nm_banco' => ''])));
        } catch (ValidationException $e) {
            $this->assertArrayHasKey('nm_banco', $e->errors());
            throw $e;
        }
    }

    public function test_index_e_show_devolvem_chaves_em_portugues(): void
    {
        app(BankController::class)->store(Request::create('/', 'POST', $this->payload()));

        $item = app(BankController::class)->index()->first();
        $this->assertSame('Banco X', $item['nm_banco']);
        $this->assertSame('17', $item['ds_carteira']);
        $this->assertTrue($item['fl_ativo']);
        $this->assertSame('Cedente SA', $item['assignor_nome']);

        $show = app(BankController::class)->show(Bank::first()->id);
        $this->assertSame('1234', $show['nr_agencia']);
        $this->assertArrayNotHasKey('bank_name', $show);
    }
}
```

- [ ] **Step 2: Rodar e ver falhar**

Run: `php artisan test --filter=ContaBancariaApiTest`
Expected: FAIL — validação exige `bank_name` etc.

- [ ] **Step 3: Atualizar `BankController`**

`REGRAS` (mesma validação, chaves novas; o comentário sobre `bank_empreendimentos` passa a citar `CONTA_BANCARIA_EMPREENDIMENTO`):

```php
    private const REGRAS = [
        'nm_banco' => 'required|string|max:255',
        'cd_banco' => 'required|string|max:255',
        'nr_agencia' => 'required|string|max:255',
        'nr_agencia_dv' => 'nullable|string|max:255',
        'nr_conta' => 'required|string|max:255',
        'nr_conta_dv' => 'nullable|string|max:255',
        'nr_contrato_cedente' => 'required|string|max:255',
        'id_cedente' => 'required|integer|exists:cliente.PESSOA,id',
        // Sem pelo menos 1 empreendimento a conta nunca aparece no combo de
        // /administracao/contrato/bancosAtivos (join com CONTA_BANCARIA_EMPREENDIMENTO). Uma
        // conta pode ser reaproveitada em vários empreendimentos — ver Bank::empreendimentos().
        'empreendimentos' => 'required|array|min:1',
        'empreendimentos.*' => 'integer|exists:cliente.EMPREENDIMENTO,id',
        'nr_dias_competencia' => 'required|integer',
        'ds_cooperativa' => 'nullable|string|max:255',
        'nr_boleto_atual' => 'required|string|max:255',
        'tp_documento' => 'required|string|max:255',
        'ds_variacao' => 'nullable|string|max:255',
        'ds_carteira' => 'required|string|max:255',
        'fl_ativo' => 'nullable|boolean',
        'juros' => 'nullable|numeric|min:0|max:999999.9999',
        'multa' => 'nullable|numeric|min:0|max:999999.9999',
        'tp_juros' => 'nullable|in:P,V,S',
        'tp_multa' => 'nullable|in:P,V,S',
    ];
```

`index()`:

```php
        return Bank::with(['assignor', 'empreendimentos'])->orderBy('nm_banco')->get()->map(fn ($b) => [
            'id' => $b->id,
            'nm_banco' => $b->nm_banco,
            'cd_banco' => $b->cd_banco,
            'nr_agencia' => $b->nr_agencia,
            'nr_conta' => $b->nr_conta,
            'assignor_nome' => $b->assignor->nm_pessoa ?? null,
            'empreendimentos_nomes' => $b->empreendimentos->pluck('nm_empreendimento')->implode(', ') ?: null,
            // Ids em paralelo aos nomes — usados pelo filtro de empreendimento da busca avançada (client-side).
            'empreendimento_ids' => $b->empreendimentos->pluck('id')->map(fn ($id) => (string) $id)->values()->all(),
            'ds_carteira' => $b->ds_carteira,
            'fl_ativo' => (bool) $b->fl_ativo,
        ]);
```

`store()` e `update()`: trocar as 2 linhas

```php
        $data['fl_ativo'] = $request->boolean('fl_ativo', true);
        // Coluna NOT NULL sem default no schema real — string vazia é um valor válido.
        $data['ds_variacao'] = $data['ds_variacao'] ?? '';
```

`show()`, `destroy()` e `normalizarEncargos()` não mudam (`juros`/`multa`/`tp_*` já estão em português).

- [ ] **Step 4: Rodar e ver passar**

Run: `php artisan test --filter=ContaBancariaApiTest`
Expected: 3 PASS.

- [ ] **Step 5: Atualizar `resources/views/banks/index.blade.php`**

Filtro client-side (linhas ~161-165) e colunas do DataTable (~188-195):

```js
        return contem(row.nm_banco, $('#bancoFilter').val())
            && contem(row.nr_agencia, $('#agenciaFilter').val())
            && contem(row.nr_conta, $('#contaFilter').val())
```
```js
            && contem(row.ds_carteira, $('#carteiraFilter').val())
```
```js
            { data: 'nm_banco', defaultContent: '---' },
            ...
            { data: 'nr_agencia', defaultContent: '---' },
            { data: 'nr_conta', defaultContent: '---' },
            ...
            { data: 'ds_carteira', defaultContent: '---' },
            { data: 'fl_ativo', render: function (v) { ...mesmo corpo... } },
```

Ler as linhas 155-200 antes de editar para preservar o que está entre elas (filtro de cedente/empreendimento/situação). O filtro de situação compara `row.active` → trocar por `row.fl_ativo`.

- [ ] **Step 6: Atualizar `resources/views/banks/form.blade.php`**

`showErrors()` usa `'#' + campo + '-error'`, então os ids do HTML têm de seguir as chaves novas. Renomear `id="X"` e `id="X-error"` (HTML, linhas ~25-155) e as leituras `$('#X')`:

| id atual | id novo |
|---|---|
| `bank_code-error` | `cd_banco-error` (o select continua `bank_code_select`) |
| `bank_name`, `bank_name-error` | `nm_banco`, `nm_banco-error` |
| `active` | `fl_ativo` |
| `agency_number`, `-error` | `nr_agencia`, `nr_agencia-error` |
| `agency_digit` | `nr_agencia_dv` |
| `account_number`, `-error` | `nr_conta`, `nr_conta-error` |
| `account_digit` | `nr_conta_dv` |
| `assignor_id`, `-error` | `id_cedente`, `id_cedente-error` |
| `assignor_contract`, `-error` | `nr_contrato_cedente`, `nr_contrato_cedente-error` |
| `wallet`, `-error` | `ds_carteira`, `ds_carteira-error` |
| `variation` | `ds_variacao` |
| `document_type`, `-error` | `tp_documento`, `tp_documento-error` |
| `cooperative` | `ds_cooperativa` |
| `competence_days`, `-error` | `nr_dias_competencia`, `nr_dias_competencia-error` |
| `current_ticket_number`, `-error` | `nr_boleto_atual`, `nr_boleto_atual-error` |

Os `for=` dos `<label>` (se houver) acompanham. `assignor_busca`, `assignorResultados`, `bank_code_select`, `empreendimentos`, `juros`, `multa`, `tp_juros`, `tp_multa`, `bank_id` (hidden), `bankForm*` ficam.

Handler do select de código e cedente:

```js
    $('#bank_code_select').on('change', function () {
        var nome = $(this).find(':selected').data('nome');
        if (nome) $('#nm_banco').val(nome);
    });
```
```js
        $('#id_cedente').val($(this).data('id'));
```

`carregarBancoEmEdicao()`:

```js
        apiGet('api/financeiro/banks/' + id).done(function (data) {
            $('#bank_code_select').val(data.cd_banco).trigger('change');
            $('#nm_banco').val(data.nm_banco);
            $('#fl_ativo').val(data.fl_ativo ? '1' : '0').trigger('change');
            $('#empreendimentos').val((data.empreendimentos || []).map(String)).trigger('change');
            $('#nr_agencia').val(data.nr_agencia);
            $('#nr_agencia_dv').val(data.nr_agencia_dv);
            $('#nr_conta').val(data.nr_conta);
            $('#nr_conta_dv').val(data.nr_conta_dv);
            $('#id_cedente').val(data.id_cedente);
            $('#assignor_busca').val(data.assignor_nome || '');
            $('#nr_contrato_cedente').val(data.nr_contrato_cedente);
            $('#ds_carteira').val(data.ds_carteira);
            $('#ds_variacao').val(data.ds_variacao);
            $('#tp_documento').val(data.tp_documento);
            $('#ds_cooperativa').val(data.ds_cooperativa);
            $('#nr_dias_competencia').val(data.nr_dias_competencia);
            $('#nr_boleto_atual').val(data.nr_boleto_atual);
            $('#juros').val(data.juros ?? '');
            $('#multa').val(data.multa ?? '');
            $('#tp_juros').val(data.tp_juros || 'P').trigger('change');
            $('#tp_multa').val(data.tp_multa || 'P').trigger('change');
        });
```

Payload do submit:

```js
        var payload = {
            cd_banco: $('#bank_code_select').val(),
            nm_banco: $('#nm_banco').val(),
            fl_ativo: $('#fl_ativo').val(),
            nr_agencia: $('#nr_agencia').val(),
            nr_agencia_dv: $('#nr_agencia_dv').val(),
            nr_conta: $('#nr_conta').val(),
            nr_conta_dv: $('#nr_conta_dv').val(),
            empreendimentos: $('#empreendimentos').val(),
            id_cedente: $('#id_cedente').val(),
            nr_contrato_cedente: $('#nr_contrato_cedente').val(),
            ds_carteira: $('#ds_carteira').val(),
            ds_variacao: $('#ds_variacao').val(),
            tp_documento: $('#tp_documento').val(),
            ds_cooperativa: $('#ds_cooperativa').val(),
            nr_dias_competencia: $('#nr_dias_competencia').val(),
            nr_boleto_atual: $('#nr_boleto_atual').val(),
            juros: $('#tp_juros').val() === 'S' ? null : $('#juros').val(),
            multa: $('#tp_multa').val() === 'S' ? null : $('#multa').val(),
            tp_juros: $('#tp_juros').val(),
            tp_multa: $('#tp_multa').val(),
        };
```

- [ ] **Step 7: Atributos de validação (3 idiomas)**

Em `resources/lang/{pt,en,es}/validation.php`, bloco `attributes`: para cada chave antiga de banco que existir (`bank_name`, `bank_code`, `agency_number`, `account_number`, `assignor_contract`, `assignor_id`, `competence_days`, `current_ticket_number`, `wallet`, `document_type`, `cooperative`, `variation`), adicionar a chave nova com o mesmo texto (`'nm_banco' => <texto de bank_name>`, etc.). Remover a antiga **só** se `grep -rn "'<chave antiga>'" app/Http app/Services` não achar outro validador usando (ex.: `document_type` também é campo de `receivables`/`payables` → **fica**).

- [ ] **Step 8: Verificação manual** — pedir ao programador (depois da Task 6, quando a migration tiver rodado): abrir `/cadastros/bancos`, listar, filtrar, criar, editar e excluir uma conta; forçar erro de validação (salvar sem nome) e confirmar que a mensagem aparece embaixo do campo certo.

- [ ] **Step 9: Ponto de commit** — avisar o programador.

---

### Task 4: Consumidores de conta bancária fora do cadastro

**Files:**
- Modify: `app/Http/Controllers/Api/Financeiro/LookupController.php:20-30`
- Modify: `app/Http/Controllers/Api/Administracao/ContratoController.php:245-260`
- Modify: `app/Services/Cadastro/ModeloVariavelResolver.php:19,71-72,100-103`
- Modify: `app/Services/Acordo/AcordoService.php:411-420`
- Modify: `app/Services/Importacao/ImportacaoPayablesService.php:194`
- Modify: `app/Services/Importacao/ImportacaoReceivablesService.php:196-200`
- Modify: `app/Services/Importacao/ImportacaoContratosService.php:306-310`
- Modify: `app/Services/FechamentoMensal/FechamentoMensalService.php:165,203,209,217,413,431,435,440,447,464-465,501,511`
- Modify: `app/Http/Controllers/Api/Financeiro/ApiFechamentoMensalController.php:30,55,87`
- Modify: `app/Services/FinancialMovement/FinancialMovementService.php:214-216,227-229`
- Modify: `app/Services/FinancialReport/FinancialReportService.php:651-656`
- Modify: `resources/views/financial-movements/index.blade.php:304-305`
- Modify: `resources/views/fechamento-mensal/index.blade.php:301`
- Modify: `resources/views/payables/form.blade.php:676-679`
- Test: `tests/Feature/Financeiro/ContaBancariaConsumidoresTest.php`

**Interfaces:**
- Consumes: `Bank` (Task 2).
- Produces: nenhuma interface nova — os mesmos endpoints, lendo colunas novas. `LookupController::bancos()` continua devolvendo `{id, text, juros, multa, tp_juros, tp_multa}` (o `text` muda só de origem).

- [ ] **Step 1: Escrever o teste (falha)** — cobre as duas queries cruas com join (as mais fáceis de quebrar em silêncio):

```php
<?php

namespace Tests\Feature\Financeiro;

use App\Http\Controllers\Api\Financeiro\LookupController;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;
use Tests\TestCase;

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

        config(['database.connections.cliente' => ['driver' => 'sqlite', 'database' => ':memory:', 'prefix' => '']]);
        DB::purge('cliente');
        $s = Schema::connection('cliente');

        $s->create('CONTA_BANCARIA', function (Blueprint $t) {
            $t->id();
            $t->integer('cd_codigo')->nullable();
            $t->string('nm_banco');
            $t->string('nr_conta')->nullable();
            $t->boolean('fl_ativo')->default(true);
            $t->decimal('juros', 10, 4)->nullable();
            $t->decimal('multa', 10, 4)->nullable();
            $t->string('tp_juros')->nullable();
            $t->string('tp_multa')->nullable();
            $t->timestamps();
        });
        DB::connection('cliente')->table('CONTA_BANCARIA')->insert([
            ['id' => 1, 'nm_banco' => 'Ativo', 'nr_conta' => '55', 'fl_ativo' => 1],
            ['id' => 2, 'nm_banco' => 'Inativo', 'nr_conta' => '66', 'fl_ativo' => 0],
        ]);
    }

    public function test_lookup_de_bancos_lista_so_ativos_com_texto_montado(): void
    {
        $lista = collect(app(LookupController::class)->bancos());

        $this->assertCount(1, $lista);
        $this->assertSame(1, $lista->first()['id']);
        $this->assertStringContainsString('Ativo', $lista->first()['text']);
        $this->assertStringContainsString('55', $lista->first()['text']);
    }
}
```

Antes de escrever, ler `LookupController::bancos()` inteiro (linhas 20-35) e ajustar as asserções ao formato real do item devolvido.

- [ ] **Step 2: Rodar e ver falhar**

Run: `php artisan test --filter=ContaBancariaConsumidoresTest`
Expected: FAIL — `no such column: active`.

- [ ] **Step 3: Aplicar as trocas** (ler cada trecho antes de editar)

`LookupController::bancos()`:
```php
        return Bank::where('fl_ativo', true)->get()->map(fn ($b) => [
            ...
            'text' => $b->nm_banco . ($b->nr_conta ? ' - Cc: ' . $b->nr_conta : ''),
```
O comentário da linha ~63-68 (busca de cedente) que cita `Bank.assignor_id` passa a citar `Bank.id_cedente`. A linha 44 (`account_plans`) **não** mexe — é da fase 2.

`ContratoController` (bancosAtivos, ~245-260):
```php
            DB::connection('cliente')->table('CONTA_BANCARIA')
                // ver CONTA_BANCARIA_EMPREENDIMENTO (App\Models\Bank::empreendimentos()).
                ->join('CONTA_BANCARIA_EMPREENDIMENTO', 'CONTA_BANCARIA_EMPREENDIMENTO.id_conta_bancaria', '=', 'CONTA_BANCARIA.id')
                ->leftJoin('PESSOA', 'PESSOA.id', '=', 'CONTA_BANCARIA.id_cedente')
                ->where('CONTA_BANCARIA_EMPREENDIMENTO.id_empreendimento', $request->input('empreendimento'))
                ->where('CONTA_BANCARIA.fl_ativo', 1)
                ->orderBy('CONTA_BANCARIA.nm_banco')
                ->get(['CONTA_BANCARIA.id', 'CONTA_BANCARIA.nm_banco', 'CONTA_BANCARIA.nr_agencia', 'CONTA_BANCARIA.nr_conta', 'PESSOA.nm_pessoa'])
                ...
                    'text' => ($item->nm_pessoa ?? $item->nm_banco) . ' - Ag: ' . $item->nr_agencia . ' - Ct: ' . $item->nr_conta,
```

`ModeloVariavelResolver`:
```php
        $banco = $contrato->id_banco ? $conexao->table('CONTA_BANCARIA')->where('id', $contrato->id_banco)->first() : null;
        $cedente = $banco && $banco->id_cedente ? $conexao->table('PESSOA')->where('id', $banco->id_cedente)->first() : null;
```
```php
            'contrato0nome_banco' => $banco->nm_banco ?? null,
            'agenciaNR' => $banco ? ($banco->nr_agencia . ($banco->nr_agencia_dv ? '-' . $banco->nr_agencia_dv : '')) : null,
            'nmBanco' => $banco->nm_banco ?? null,
```
Docblock da linha 19: `banks.assignor_id` → `CONTA_BANCARIA.id_cedente`.

`AcordoService::taxasDoContrato()`: `->join('banks as b', ...)` → `->join('CONTA_BANCARIA as b', ...)`; docblock (411-412) troca `banks` por `CONTA_BANCARIA`. As colunas selecionadas (`juros`/`multa`/`tp_*`) não mudam.

`ImportacaoPayablesService:194`:
```php
            $bankId = DB::connection('cliente')->table('CONTA_BANCARIA')->where('nm_banco', 'like', $dados['bank_account_name'])->value('id');
```
(`$dados['bank_account_name']` é coluna da planilha de importação — fica.)

`ImportacaoReceivablesService:196-200` e `ImportacaoContratosService:306-310` (mesmo formato):
```php
DB::connection('cliente')->table('CONTA_BANCARIA')
    ->join('CONTA_BANCARIA_EMPREENDIMENTO', 'CONTA_BANCARIA_EMPREENDIMENTO.id_conta_bancaria', '=', 'CONTA_BANCARIA.id')
    ->where('CONTA_BANCARIA_EMPREENDIMENTO.id_empreendimento', $idEmpreendimento)
    ->where('CONTA_BANCARIA.nm_banco', 'like', <mesma expressão de hoje>)
    ->value('CONTA_BANCARIA.id')
```

`FechamentoMensalService`: todo `$conta->bank_name` → `$conta->nm_banco`; `$conta->start_balance` → `$conta->vl_saldo_inicial`; `$conta->start_balance_date` → `$conta->dt_saldo_inicial`; `Bank::where('active', true)` → `Bank::where('fl_ativo', true)`; `orderBy('bank_name')` → `orderBy('nm_banco')`. A chave de saída `'bank_account_name'` (DTO) e o filtro de request `bank_account_id` **ficam**.

`ApiFechamentoMensalController` (3 regras): `exists:cliente.banks,id` → `exists:cliente.CONTA_BANCARIA,id`.

`FinancialMovementService::createTransfer()` (214-216 e 227-229): `bank_name`→`nm_banco`, `agency_number`→`nr_agencia`, `agency_digit`→`nr_agencia_dv`, `account_number`→`nr_conta`, `account_digit`→`nr_conta_dv` nos dois blocos. `$data['bank_account_id']`/`destination_bank_account_id` (request de movimentação) **ficam** — fase 6.

`FinancialReportService::saldosPorBanco()`:
```php
        return Bank::where('fl_ativo', true)
            ->orderBy('nm_banco')
            ->get()
            ->map(fn (Bank $banco) => [
                'name' => $banco->nm_banco,
                'bank_number' => $banco->nr_conta,
```
(as chaves `name`/`bank_number` são DTO consumido pelo relatório — ficam; o `where('bank_account_id')`/`transaction_date` dentro é de `financial_movements`, fase 6 — **não mexer**.)

`financial-movements/index.blade.php:304-305` (`v` é o objeto `bank_account` serializado do model `Bank`):
```js
                return v.nm_banco + ' - ' + movements.agency_abbr + ': ' + v.nr_agencia + '-' + v.nr_agencia_dv
                    + ' - ' + movements.checking_account_abbr + ': ' + v.nr_conta + '-' + v.nr_conta_dv;
```

`fechamento-mensal/index.blade.php:301`:
```js
                return escapeHtml(v.nm_banco) + (v.nr_conta ? ' - ' + escapeHtml(v.nr_conta) : '');
```

`payables/form.blade.php:676-679` (bloco hoje inerte — `$bankAccounts` não é passado pelo controller — mas atualizado pra não deixar nome velho):
```blade
                                                {{ $bankAccount->nm_banco }} - Ag:
                                                {{ $bankAccount->nr_agencia }}-{{ $bankAccount->nr_agencia_dv }}
                                                - C/C:
                                                {{ $bankAccount->nr_conta }}-{{ $bankAccount->nr_conta_dv }}
```

`CadastroController.php:10`, `AdministracaoController.php:40`, `routes/api.php:237,528`: comentários "tabela `banks`" → "tabela `CONTA_BANCARIA`". As rotas `api/financeiro/banks*` **não** mudam de URL (URL não é nome de tabela).

- [ ] **Step 4: Rodar e ver passar**

Run: `php artisan test --filter=ContaBancariaConsumidoresTest`
Expected: PASS.

- [ ] **Step 5: Ponto de commit** — avisar o programador.

---

### Task 5: Extrato bancário / conciliação

**Files:**
- Modify: `app/Services/BankStatement/BankStatementService.php`
- Modify: `app/Http/Controllers/Api/Financeiro/ApiBankStatementsController.php`
- Modify: `resources/views/bank-statements/index.blade.php` (~466, 778-807, 886-907, 973)
- Modify: `app/Services/Receivable/ReceivableService.php:1136-1138`
- Modify: `app/Services/FinancialMovement/FinancialMovementService.php:516-518`
- Test: `tests/Feature/Financeiro/ExtratoBancarioServiceTest.php`

**Interfaces:**
- Consumes: `BankStatement` (Task 2).
- Produces: `POST api/bank-statements/import` aceita `id_conta_bancaria` (+ `ofx_file`); `GET api/bank-statements/conciliation` aceita `id_conta_bancaria`, `start_date`, `end_date`; cada item de `date_groups[].bank_entries` vira `{id, cd_codigo, date, ds_descricao, ds_memo, vl_valor, tp_transacao, tp_origem, cd_transacao, id_movimentacao_financeira, is_conciliated}`. `system_entries` (movimentação) **não muda** — fase 6.

- [ ] **Step 1: Escrever o teste (falha)**

```php
<?php

namespace Tests\Feature\Financeiro;

use App\Models\BankStatement;
use App\Services\BankStatement\BankStatementService;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;
use Tests\TestCase;

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

        config(['database.connections.cliente' => ['driver' => 'sqlite', 'database' => ':memory:', 'prefix' => '']]);
        DB::purge('cliente');
        $s = Schema::connection('cliente');

        $s->create('EXTRATO_BANCARIO', function (Blueprint $t) {
            $t->id();
            $t->unsignedBigInteger('id_conta_bancaria');
            $t->integer('cd_codigo');
            $t->date('dt_transacao');
            $t->string('ds_descricao')->nullable();
            $t->string('ds_memo')->nullable();
            $t->decimal('vl_valor', 15, 2);
            $t->string('tp_transacao');
            $t->decimal('vl_saldo', 15, 2)->nullable();
            $t->string('cd_transacao')->nullable();
            $t->string('tp_origem')->default('ofx');
            $t->unsignedBigInteger('id_movimentacao_financeira')->nullable();
            $t->boolean('fl_ativo')->default(true);
            $t->unsignedBigInteger('id_usuario_criacao')->nullable();
            $t->timestamps();
        });
        // Lado "sistema" ainda em inglês (fase 6) — schema mínimo que getConciliationData() consulta.
        $s->create('financial_movements', function (Blueprint $t) {
            $t->id();
            $t->integer('code')->nullable();
            $t->unsignedBigInteger('bank_account_id');
            $t->unsignedBigInteger('payable_id')->nullable();
            $t->string('type')->default('receita');
            $t->string('origin_type')->nullable();
            $t->decimal('amount', 15, 2)->default(0);
            $t->date('transaction_date');
            $t->string('description')->nullable();
            $t->boolean('active')->default(true);
            $t->boolean('conciliated')->default(false);
            $t->timestamps();
        });
        $s->create('payables', function (Blueprint $t) { $t->id(); $t->integer('code')->nullable(); });

        BankStatement::create([
            'id_conta_bancaria' => 9, 'cd_codigo' => 1, 'dt_transacao' => '2026-10-05',
            'ds_descricao' => 'TED', 'vl_valor' => 100, 'tp_transacao' => 'credit', 'cd_transacao' => 'X1',
        ]);
    }

    public function test_conciliacao_devolve_lancamento_bancario_com_chaves_em_portugues(): void
    {
        $dados = app(BankStatementService::class)->getConciliationData(9, '2026-10-01', '2026-10-31');

        $entrada = $dados['date_groups'][0]['bank_entries'][0];
        $this->assertSame(1, (int) $entrada['cd_codigo']);
        $this->assertSame('TED', $entrada['ds_descricao']);
        $this->assertSame(100.0, $entrada['vl_valor']);
        $this->assertSame('credit', $entrada['tp_transacao']);
        $this->assertFalse($entrada['is_conciliated']);
        $this->assertSame(100.0, $dados['date_groups'][0]['bank_closing_balance']);
    }

    public function test_find_by_code_e_delete_logico(): void
    {
        $servico = app(BankStatementService::class);
        $linha = $servico->findByCode('1');

        $this->assertNotNull($linha);
        $servico->delete($linha);
        $this->assertNull($servico->findByCode('1'));
    }
}
```

Antes de escrever, ler `BankStatementService` inteiro (ele pode receber dependências no construtor e `formatSystemEntry()` pode ler colunas além das listadas — ajustar o schema mínimo de `financial_movements` ao que ele realmente consulta).

- [ ] **Step 2: Rodar e ver falhar**

Run: `php artisan test --filter=ExtratoBancarioServiceTest`
Expected: FAIL — `BankStatement::create` passa (Task 2), mas a conciliação consulta `bank_account_id`/`transaction_date` no extrato.

- [ ] **Step 3: Atualizar `BankStatementService`** (só o lado extrato)

`importFromOFX()`:
```php
            if (BankStatement::withoutGlobalScopes()
                ->where('id_conta_bancaria', $bankAccountId)
                ->where('cd_transacao', $txn['transaction_id'])
                ->exists()) {
                $skipped++;
                continue;
            }

            $nextCode = (BankStatement::withoutGlobalScopes()
                ->max('cd_codigo') ?? 0) + 1;

            BankStatement::create([
                'id_conta_bancaria' => $bankAccountId,
                'cd_codigo'         => $nextCode,
                'dt_transacao'      => $txn['date'],
                'ds_descricao'      => $txn['description'],
                'vl_valor'          => $txn['amount'],
                'tp_transacao'      => $txn['type'],
                'cd_transacao'      => $txn['transaction_id'],
                'tp_origem'         => 'ofx',
                'fl_ativo'          => true,
                'id_usuario_criacao'=> Auth::id(),
            ]);
```
(`$txn[...]` são chaves do array do `OFXParser`, não colunas — ficam.)

`getConciliationData()` — **só** a query de `$bankEntries` e o que lê dela:
```php
        $bankEntries = BankStatement::where('id_conta_bancaria', $bankAccountId)
            ->where('fl_ativo', true)
            ->whereBetween('dt_transacao', [$startDate, $endDate])
            ->orderBy('dt_transacao')
            ->orderBy('id')
            ->get();
```
```php
        $bankDates   = $bankEntries->pluck('dt_transacao')->map(fn($d) => $d->format('Y-m-d'));
```
No laço de datas: `$dayBank = $bankEntries->filter(fn($e) => $e->dt_transacao->format('Y-m-d') === $date)` e `$bankRunning += $dayBank->sum('vl_valor');`. Em `$conciliatedBalance`: `->sum('vl_valor')`. Em `buildDayStatuses()`: `$dayBank = $bankEntries->filter(fn($e) => $e->dt_transacao->format('Y-m-d') === $date);`.
**Não mexer** em `$systemEntries`, `$daySystem`, `transaction_date`/`amount`/`conciliated` do lado `FinancialMovement`.

`conciliate()`/`unconciliate()`:
```php
        $statement->update(['id_movimentacao_financeira' => $financialMovementId]);
```
```php
        $movementId = $statement->id_movimentacao_financeira;
        $statement->update(['id_movimentacao_financeira' => null]);

        if ($movementId) {
            $stillLinked = BankStatement::withoutGlobalScopes()
                ->where('id_movimentacao_financeira', $movementId)
                ->where('id', '!=', $statement->id)
                ->exists();
```
(o `FinancialMovement::...->update(['conciliated' => ...])` fica.)

`findByCode()` / `delete()` / `calculateBankBalanceBefore()`:
```php
        return BankStatement::where('cd_codigo', $code)->where('fl_ativo', true)->first();
```
```php
        return $statement->update(['fl_ativo' => false]);
```
```php
        return (float) BankStatement::where('id_conta_bancaria', $bankAccountId)
            ->where('fl_ativo', true)
            ->where('dt_transacao', '<', $date)
            ->sum('vl_valor');
```

`formatBankEntry()`:
```php
        return [
            'id'                         => $entry->id,
            'cd_codigo'                  => $entry->cd_codigo,
            'date'                       => $entry->dt_transacao->format('Y-m-d'),
            'ds_descricao'               => $entry->ds_descricao,
            'ds_memo'                    => $entry->ds_memo,
            'vl_valor'                   => (float) $entry->vl_valor,
            'tp_transacao'               => $entry->tp_transacao,
            'tp_origem'                  => $entry->tp_origem,
            'cd_transacao'               => $entry->cd_transacao,
            'id_movimentacao_financeira' => $entry->id_movimentacao_financeira,
            'is_conciliated'             => $entry->isConciliated(),
        ];
```

Docblock "lado bancário (bank_statements)" → "(EXTRATO_BANCARIO)".

- [ ] **Step 4: Atualizar `ApiBankStatementsController`**

`import()`:
```php
        $request->validate([
            'ofx_file'          => 'required|file|max:5120',
            'id_conta_bancaria' => 'required|integer|exists:cliente.CONTA_BANCARIA,id',
        ]);

        $result = $this->service->importFromOFX(
            $request->file('ofx_file'),
            (int) $request->input('id_conta_bancaria')
        );
```
`getConciliation()`: `'bank_account_id' => 'required|integer'` → `'id_conta_bancaria' => 'required|integer'` e `$request->input('id_conta_bancaria')`. `conciliate()` mantém a validação `exists:cliente.financial_movements,id` (fase 6) mas a chave do request vira `id_movimentacao_financeira` (é a coluna de `EXTRATO_BANCARIO` que ela preenche):
```php
            'id_movimentacao_financeira' => 'required|integer|exists:cliente.financial_movements,id',
        ...
        $statement = $this->service->conciliate($statement, (int) $request->input('id_movimentacao_financeira'));
```
Docblock "salva as transações em bank_statements" → "EXTRATO_BANCARIO".

- [ ] **Step 5: Atualizar `resources/views/bank-statements/index.blade.php`**

Ler o arquivo inteiro primeiro: os renders de `bank_entries` usam `entry.*` e os de `system_entries` também — **só os do lado banco mudam**.
- linha ~466: `data: { id_conta_bancaria: bankAccountId, start_date: startDate, end_date: endDate }`
- render da entrada bancária (~778-788): `entry.code`→`entry.cd_codigo`, `entry.type`→`entry.tp_transacao`, `entry.amount`→`entry.vl_valor`, `entry.description`→`entry.ds_descricao`.
- render da entrada do sistema (~800-805) **fica**.
- modal de conciliação (~886-907): `group.bank_entries.find(function (e) { return String(e.cd_codigo) === String(bankCode); })`, `bankEntry.tp_transacao`, `bankEntry.vl_valor`, `bankEntry.ds_descricao`. As linhas ~917-926 (`entry` = movimento do sistema) **ficam**.
- envio da conciliação (~947): o corpo do POST passa a mandar `id_movimentacao_financeira: <mesmo valor>` em vez de `financial_movement_id`.
- import (~973): `formData.append('id_conta_bancaria', accountSelect.value);`
- Qualquer outra leitura de `entry.memo`/`origin`/`transaction_id`/`financial_movement_id` sobre um `bank_entries` → nome novo.

- [ ] **Step 6: Atualizar os dois pontos que desfazem conciliação**

`ReceivableService.php:1136-1138` e `FinancialMovementService.php:516-518`:
```php
            BankStatement::withoutGlobalScopes()
                ->where('id_movimentacao_financeira', $movimento->id)
                ->update(['id_movimentacao_financeira' => null]);
```
(no segundo, a variável é `$item->id`.)

- [ ] **Step 7: Rodar e ver passar**

Run: `php artisan test --filter=ExtratoBancarioServiceTest`
Expected: 2 PASS.

- [ ] **Step 8: Ponto de commit** — avisar o programador.

---

### Task 6: Varredura, migração real, verificação e documentação

**Files:**
- Modify: `.claude/CLAUDE.md`, `.claude/rules/backend.md`, `.claude/rules/multi-pais.md` (referências a `banks`/`bank_statements`/`banks:import-associacoes`)

- [ ] **Step 1: Varredura de nomes antigos**

Run:
```bash
grep -rnE "['\"\`](banks|bank_empreendimentos|bank_statements)['\"\`. ]|cliente\.banks|\b(bank_name|bank_code|agency_number|agency_digit|account_number|account_digit|assignor_contract|assignor_id|competence_days|current_ticket_number|start_balance_date|start_balance|legacy_banco_id)\b" app routes resources/views tests --include=*.php
```
Expected: só ocorrências legítimas — `resources/views/banks/*` (nome de pasta/`__('banks.*')`), chaves de tradução `resources/lang/*/banks.php`, rotas `api/financeiro/banks`, DTO `bank_account_name`, e `$txn['transaction_id']` do OFX. Qualquer outra → corrigir.

Run: `grep -rn "Person\b\|Spouse\|Address::" app routes --include=*.php | grep -v "Pessoa"`
Expected: vazio (fora de `config/mail.php`, que é texto).

- [ ] **Step 2: Suíte completa**

Run: `php artisan test`
Expected: tudo verde, exceto `DistratoWorkflowTest` (falha pré-existente documentada em `CLAUDE.md`, coluna `active` no schema de teste de `receivables`). Qualquer falha nova → investigar antes de seguir.

- [ ] **Step 3: Rodar a migration nos tenants** — pedir ao programador:

```bash
php artisan clientes:migrate
```
Depois conferir num tenant: `php artisan tinker --execute='config(["database.connections.cliente.database"=>"cereus_cliente_grupoll_1786024296"]); DB::purge("cliente"); print_r(Schema::connection("cliente")->getColumnListing("CONTA_BANCARIA"));'` — deve listar as colunas novas, e `hasTable("banks")`/`hasTable("people")` devem ser `false`.

- [ ] **Step 4: Verificação manual nas telas** — pedir ao programador:
1. `/cadastros/bancos`: listar, filtros, criar, editar, excluir, erro de validação.
2. Contrato (`/administracao/contrato/{id}`, aba Financeiro): combo de banco lista as contas do empreendimento.
3. Movimentação Financeira: listagem mostra a coluna de conta bancária; criar uma transferência entre contas e conferir a descrição gerada.
4. Fechamento Mensal: listagem e prévia de fechamento.
5. Relatórios Financeiros: saldo por banco.
6. Extrato/Conciliação: importar um OFX, ver a conciliação, conciliar, desconciliar, excluir linha.
7. Acordos: simular (juros/multa vêm da conta bancária do contrato).
8. Emissão de contrato/modelo Word com `${nmBanco}`/`${agenciaNR}`.

- [ ] **Step 5: Documentação**

- `.claude/CLAUDE.md`: na seção de arquitetura multi-tenant, registrar a convenção (tabelas do cereus cond sendo convertidas para CAIXA ALTA/prefixo, fase 1 concluída, link pro spec); atualizar a menção a `Bank`/`banks` em "Pontos de atenção" (cadastro de banco 403).
- `.claude/rules/backend.md:87`: `banks` → `CONTA_BANCARIA`, colunas novas, e remover a menção a `ImportBancoAssociacoesToBanks` (removido).
- `.claude/rules/multi-pais.md`: trocar `banks`/`Bank.php` (campos `agency_number/digit` etc.) pelos nomes novos onde aparecem.
- Perguntar ao programador se algo mais desta fase deve virar regra (regra do projeto, seção "Comportamento").

- [ ] **Step 6: Ponto de commit final da fase** — avisar o programador.
