# Tradução de tabelas — Fase 3 (Contas a Receber: avulsa + recorrente) 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 `receivables` → `CONTA_RECEBER` e `recurring_receivables` → `CONTA_RECEBER_RECORRENTE` (tabela e colunas) e atualizar todo o código que depende delas, ponta a ponta.

**Architecture:** Fases 3 e 4 do spec foram **unidas** (ruling 30/10/2026): as duas tabelas compartilham formulário (`receivables/form.blade.php`, modo `isRecurring`), service (`ReceivableService`) e controller (`APIReceivablesController`) com as mesmas chaves de payload — separar exigiria um formulário com dois conjuntos de chaves, descartado na fase seguinte. Migration única idempotente (padrão das fases 1-2: `database/migrations/clientes/2026_10_30_100000_rename_account_plans_table_to_portuguese.php`). `ActiveScope` passa a respeitar a coluna de cada model (compartilhado com `Payable`, ainda em inglês até a fase de `payables`).

**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

- pt-BR na conversa; **nunca** `git add/commit/push/rm/stash/checkout/reset`, `npm run build`, nem migration em banco real (o controller roda `clientes:migrate` no fim).
- Testes: `php artisan test --filter=...` (SQLite). `DEPR ... PDO::MYSQL_ATTR_SSL_CA` é ruído pré-existente.
- Tabela CAIXA ALTA; coluna minúscula com prefixo. Ficam: `id`, `created_at`, `updated_at`, `id_empreendimento`.
- Valores de enum/status **não** mudam (`'pending'`, `'paid'`, `'overdue'`, `'cancelled'`, `'agreed'`, `'parcela_contrato'`, `'simple'`, `'monthly'`, `'boleto'`...).
- Nomes de relação Eloquent (`person`, `accountPlan`, `bankAccount`, `bank`, `recurringReceivable`, `receivables`, `contrato`, `createdBy`, `updatedBy`, `creator`, `updater`...) e as chaves JSON derivadas deles **não** mudam.
- **Não mudam nesta fase** (tabelas de outras fases): `payables.*` (inclui `payables.receivable_id`), `financial_movements.*` (inclui `financial_movements.receivable_id`). Em queries que juntam essas tabelas, só o lado `CONTA_RECEBER` muda.
- Chave de JSON/payload/request que espelha 1:1 uma coluna renomeada é renomeada junto (payload dos formulários, regras de validação, `$data['...']` que vira coluna, DTOs que expõem a coluna). Chaves calculadas (`client_name`, `status_label`, `is_overdue`, aliases de SELECT que não são coluna) e **parâmetros de filtro de listagem** (`*Filter`, `start_date`/`end_date` de período, `search`) ficam.
- O `{code}` das URLs (`api/receivables/{code}`, `api/recurring-receivables/{code}`, `financeiro/{code}/edit-contareceber`) fica; o valor vem de `cd_codigo`.
- **Nunca** busque-e-substitua global por `status`/`type`/`code`/`title`/`amount`/`active`/`description`: estes nomes existem em quase toda tabela. Altere só onde o objeto é `Receivable`/`Parcela`/`RecurringReceivable` ou a tabela `receivables`/`recurring_receivables`.
- Migrations antigas (inclusive seeds de antes de 2026-10-30) **não** são editadas.
- `App\Models\Vendas\Parcela` estende `Receivable` (mesma tabela, escopo `tp_conta = 'parcela_contrato'`): todo `Parcela::create([...])`/`->due_date` etc. muda junto.

## Mapa desta fase

**Núcleo comum (`receivables` e o que se aplica a `recurring_receivables`)**
`person_id`→`id_pessoa`, `code`→`cd_codigo`, `account_plan_id`→`id_plano_contas`, `bank_account_id`→`id_conta_bancaria`, `title`→`ds_titulo`, `type`→`tp_conta`, `document_type`→`tp_documento`, `document_number`→`nr_documento`, `document_series`→`ds_serie_documento`, `digitable_line`→`ds_linha_digitavel`, `issue_date`→`dt_emissao`, `competence_date`→`dt_competencia`, `due_date`→`dt_vencimento`, `payment_date`→`dt_pagamento`, `original_amount`→`vl_original`, `discount`→`vl_desconto`, `additions`→`vl_acrescimo`, `penalty_amount`→`vl_multa`, `interest_amount`→`vl_juros`, `payment_method`→`ds_forma_pagamento`, `status`→`ds_status`, `observations`→`ds_observacao`, `attachments`→`ds_anexos`, `active`→`fl_ativo`, `created_by`→`id_usuario_criacao`, `updated_by`→`id_usuario_alteracao`

**`receivables` → `CONTA_RECEBER` (além do núcleo)**
`recurring_receivable_id`→`id_conta_receber_recorrente`, `agreement_id`→`id_acordo`, `contract_id`→`id_contrato`, `legacy_installment_id`→`id_parcela_legado`, `installment_number`→`nr_parcela`, `installment_category`→`ds_categoria_parcela`, `installment_type_code`→`cd_tipo_parcela`, `negotiation_id`→`id_negociacao`, `renegotiation_id`→`id_renegociacao`, `previous_installment_id`→`id_parcela_anterior`, `rate_id`→`id_taxa`, `legacy_bank_id`→`id_banco_legado`, `bank_id`→`id_banco`, `boleto_bank_id`→`id_banco_boleto`, `shipment_id`→`id_remessa`, `boleto_number`→`nr_boleto`, `boleto_increment_id`→`nr_boleto_incremento`, `boleto_issue_year`→`nr_boleto_ano_emissao`, `boleto_layout_code`→`cd_boleto_layout`, `boleto_api_code`→`cd_boleto_api`, `barcode`→`cd_barras`, `bank_reference_number`→`nr_nosso_numero`, `pix_txid`→`cd_pix_txid`, `pix_qr_code`→`ds_pix_qr_code`, `second_copy_discount`→`vl_desconto_segunda_via`, `second_copy_due_date`→`dt_vencimento_segunda_via`, `second_copy_amount`→`vl_segunda_via`, `credit_date`→`dt_credito`, `adjustment_date`→`dt_reajuste`, `adjustment_index`→`vl_indice_reajuste`, `write_off_type`→`tp_baixa`, `write_off_method`→`ds_forma_baixa`, `write_off_observations`→`ds_observacao_baixa`, `sent_flag`→`fl_enviado`, `settled_flag`→`fl_quitado`, `adjustable_flag`→`fl_reajustavel`, `installment_observations`→`ds_observacao_parcela`, `legacy_log`→`ds_log_legado`, `custom_installment_type_id`→`id_tipo_parcela_personalizado`, `iva_amount`→`vl_iva`, `total_amount`→`vl_total`

**`recurring_receivables` → `CONTA_RECEBER_RECORRENTE`**
`person_id`→`id_pessoa`, `contract_id`→`id_contrato`, `code`→`cd_codigo`, `account_plan_id`→`id_plano_contas`, `title`→`ds_titulo`, `original_amount`→`vl_original`, `frequency`→`tp_frequencia`, `due_day`→`nr_dia_vencimento`, `start_date`→`dt_inicio`, `end_date`→`dt_fim`, `next_generation_date`→`dt_proxima_geracao`, `observations`→`ds_observacao`, `active`→`fl_ativo`, `created_by`→`id_usuario_criacao`, `updated_by`→`id_usuario_alteracao`

---

### Task 1: Migration, ActiveScope, models e schemas de teste

**Files:**
- Create: `database/migrations/clientes/2026_10_30_110000_rename_receivables_tables_to_portuguese.php`
- Create: `tests/Feature/Migrations/RenameReceivablesTablesMigrationTest.php`
- Modify: `app/Models/Scopes/ActiveScope.php`, `app/Models/Receivable.php`, `app/Models/RecurringReceivable.php`, `app/Models/Vendas/Parcela.php`, `app/Support/ParcelaReceivable.php` (se ler colunas de receivables), `app/Models/Bank.php` (`receivables()` → FK `id_banco`), `app/Models/Vendas/ComissaoPagamento.php`, `app/Models/Cobranca/CobrancaParcela.php`, `app/Models/Cobranca/CobrancaInadimplencia.php`, `app/Models/Administracao/ContratoTipoParcela.php` (só onde referenciam colunas/tabela de receivables — ler antes)
- Modify (schema SQLite de `receivables`/`recurring_receivables` nos testes: tabela e colunas → mapa; inserts/queries/asserts que citam colunas dessas tabelas → nomes novos; **nenhuma outra mudança de lógica de teste**): todos os arquivos de `tests/` que criam/inserem/consultam `receivables` ou `recurring_receivables` (lista atual: `ContratoComissaoPosGeracaoTest`, `AcordoTermoTest`, `PainelVendaSemParcelasTest`, `PainelServiceStatusReceitasTest`, `DistratoWorkflowTest`, `ContratoComissaoWorkflowTest`, `FinancialReportServiceOverdueFilterTest`, `AcordoWorkflowTest`, `ReceivableAgreedFilterTest`, `ReceivableComissaoPayableTest`, `ModeloComissaoControllerTest`, `PlanoContasConsumidoresTest`, `ImportacaoContratosServiceTest`, `ComissaoPagamentoRelacaoTest`, `GeracaoParcelasCoincidenciaTest`, `ComissaoCalculoServiceTest`, `GrupoPermissoesTest` — conferir com grep)

**Interfaces — Produces:**
- `ActiveScope`: usa `$model::COLUNA_ATIVO` se a constante existir no model, senão `'active'` (para `Payable`, ainda em inglês). Qualifica com o nome da tabela como hoje.
- `Receivable`/`RecurringReceivable`: `$table` novo; `const COLUNA_ATIVO = 'fl_ativo'`; fillable/casts/boot (geração de `cd_codigo`, scopes globais como o `addSelect` de `RecurringReceivable` → `CONTA_RECEBER_RECORRENTE.*`), relações com FKs novas, scopes locais, accessors/mutators, métodos de negócio (`recalculateNetAmount` → `vl_total`, `isOverdue`, `hasLaunchedReceivables`, `ocorrenciasNoPeriodo`, `vencimentoNoMes`, `shouldGenerate`, `intervaloMeses` etc.) nas colunas novas. As chaves do array devolvido por `ocorrenciasNoPeriodo()` passam a ser `dt_emissao`/`dt_vencimento`/`dt_competencia` (alimentam criação de `CONTA_RECEBER`).
- `Parcela`: escopo global `CONTA_RECEBER.tp_conta = ParcelaReceivable::TYPE`; `creating` preenchendo colunas novas; `contrato()` via `id_contrato`; `scopeParaListagem` com join `CONTA_RECEBER.id_contrato` e colunas novas.
- Relações de outros models que apontam para receivables (`Bank::receivables()` FK `id_banco`; `Payable`/`FinancialMovement` → `receivable()` usam a coluna DELES `receivable_id`, que **não muda**).

- [ ] **Step 1:** Teste da migration (RED), mesmo formato de `tests/Feature/Migrations/RenameAccountPlansTableMigrationTest.php`: cria as duas tabelas antigas com todas as colunas do mapa, insere uma recorrente e uma conta ligada a ela; (a) `up()` → tabelas antigas somem, novas têm todas as colunas do mapa, dados e vínculo `id_conta_receber_recorrente` preservados; (b) idempotente (contagem de linhas preservada); (c) `down()` volta.
- [ ] **Step 2:** Migration (mesma estrutura das fases 1-2, constante `TABELAS` com as duas tabelas). Comentário de cabeçalho: fase 3 (fases 3+4 do spec unidas), idempotente, FKs/índices com nomes antigos.
- [ ] **Step 3:** Teste `tests/Feature/Financeiro/ContaReceberModelTest.php` (RED → GREEN): `Receivable::create` gera `cd_codigo` sequencial; `ActiveScope` esconde `fl_ativo=0` em `Receivable` e `RecurringReceivable` e continua filtrando `active` num model sem a constante (crie um model anônimo/de teste sobre uma tabela com coluna `active`); `Parcela::create([...mínimo...])` preenche `tp_conta='parcela_contrato'`, `dt_emissao`, `vl_total`; `RecurringReceivable::ocorrenciasNoPeriodo()` devolve as chaves novas.
- [ ] **Step 4:** Implementar `ActiveScope` + models.
- [ ] **Step 5:** Atualizar schemas dos testes existentes. Rodar cada um e registrar no relatório quais passam/falham; falhas que dependem de services ainda não migrados (Tasks 2-5) são esperadas — a Task 6 confere contra o baseline (38 falhas pré-existentes, lista em `/tmp/claude-1000/-home-gabriel-public-html-cereusLote/417799b3-87ea-4940-8c90-587f7aceb22a/scratchpad/head-result.txt`).

---

### Task 2: Núcleo de Contas a Receber (service, API, importação)

**Files:**
- Modify: `app/Services/Receivable/ReceivableService.php` (inteiro: validação `validateReceivableData`, `list`/`listRecurring` com SQL cru, `create`/`update`/`markAsPaid`/`reversePayment`/`registrarMovimento`/`gerarPayableIva`/`gerarPayableComissao`/`createRecurring`/`updateRecurring`/`launchRecurring`/`toggleStatus*`/`delete*`/`find*`), `app/Services/Receivable/ReceivableServiceInterface.php`
- Modify: `app/Http/Controllers/Api/Financeiro/APIReceivablesController.php`, `app/Http/Controllers/Web/Financeiro/ReceivablesController.php`
- Modify: `app/Services/Importacao/ImportacaoReceivablesService.php`, `app/Http/Controllers/Api/Financeiro/ReceivablesImportacaoController.php`
- Test: `tests/Feature/Financeiro/ContaReceberServiceTest.php`

**Atenção específica:** dentro do `ReceivableService`, ao gerar `Payable` (IVA/comissão) e `FinancialMovement`, as **chaves desses arrays continuam em inglês** (são colunas de `payables`/`financial_movements`, fases seguintes) — só os **valores** lidos da conta a receber mudam (`$receivable->vl_iva` etc.). `payables.receivable_id`/`financial_movements.receivable_id` continuam. Planilha de importação: os cabeçalhos/chaves de `$dados` vindos do Excel (`account_plan_code`, `bank_account_name`...) são formato de arquivo — ficam; só o que vira coluna muda.

- [ ] **Step 1:** Teste (RED) chamando o service: criar conta avulsa com payload em chaves novas (`ds_titulo`, `vl_original`, `dt_vencimento`, `id_plano_contas`, `id_pessoa`...) → grava; validação sem `ds_titulo` → erro na chave `ds_titulo`; `markAsPaid` muda `ds_status` para `paid` e cria `FinancialMovement` (schema `financial_movements` em inglês no teste); `createRecurring` + `launchRecurring` gera contas com `id_conta_receber_recorrente`; `listRecurring` roda (SQL cru). Ler o service antes para montar o schema mínimo e os nomes reais dos métodos.
- [ ] **Step 2-4:** RED → implementar → GREEN. Grep final nos arquivos da task por nomes antigos do mapa usados sobre Receivable/RecurringReceivable/`receivables.` — justificar cada sobra no relatório.

---

### Task 3: Telas de Contas a Receber

**Files:**
- Modify: `resources/views/receivables/index.blade.php`, `resources/views/receivables/form.blade.php`, `resources/views/receivables/importar.blade.php`, `resources/views/financial-movements/form.blade.php` (só o que lê dados de conta a receber), `resources/views/partials/scripts.blade.php` (só se ler coluna de receivable), `routes/web.php`/`routes/api.php` (só comentários/nomes que citem colunas — URLs ficam)

**Contrato:** consumir exatamente as chaves que a Task 2 produz (ler o relatório da Task 2 e o controller/service já alterados). Formulário: ids dos campos e `#X-error` seguem as chaves novas de validação (o `showErrors` mapeia chave→id); carga de edição (avulsa e recorrente), payload de submit, cálculo de líquido (`vl_original`, `vl_desconto`, ...), modal "Marcar como recebido", estorno, lançamento de recorrente. Listagem: colunas do DataTable, renders, view/detalhe (~1135), agrupamento por competência, badges de status (lê `ds_status`). Filtros de listagem (`*Filter`) ficam.

- [ ] **Step 1:** Ler as views inteiras e o relatório da Task 2.
- [ ] **Step 2:** Aplicar. `php artisan view:cache && php artisan view:clear`.
- [ ] **Step 3:** Grep nas views por `\.(title|original_amount|due_date|payment_date|status|code|person_id|account_plan_id|total_amount|discount|additions|penalty_amount|interest_amount|competence_date|issue_date|contract_id|installment_number|active|type|observations)\b` e por esses nomes como chave de payload/id de campo — justificar cada sobra (ex.: objeto que é `payable`/`movement`, filtro, tradução `__('receivables.fields.*')`).
- [ ] **Step 4:** Teste de feature leve se viável (ex.: `GET` da view de edição renderiza sem erro de Blade) — senão, `view:cache` é a verificação.

---

### Task 4: Contrato, parcelas e comissão

**Files:**
- Modify: `app/Http/Controllers/Api/Administracao/ContratoController.php` (gerarParcelas, listagem/edição de parcelas, ivaStatus, destroy etc.), `resources/views/administracao/contratoFormulario.blade.php`, `app/Services/GeracaoParcelasService.php`, `app/Http/Controllers/Api/Vendas/SimuladorVendaController.php`, `app/Services/Importacao/ImportacaoContratosService.php`, `resources/views/administracao/contratoImportar.blade.php`, `app/Http/Controllers/Api/Administracao/DistratoController.php`, `app/Http/Controllers/Api/Administracao/TransferenciaTitularidadeController.php`, `app/Services/Comissao/ComissaoCalculoService.php`, `resources/views/cadastro/comissaoFormulario.blade.php`, `resources/views/cadastro/taxaValorFormulario.blade.php`, `app/Services/Cadastro/ModeloVariavelResolver.php`, `resources/views/administracao/contrato/pdf/layouts/partials/lotear-urb-contrato.blade.php`, `resources/views/administracao/contrato/pdf/layouts/3ag.blade.php`, `resources/views/administracao/contrato/pdf/layouts/4ce.blade.php`, `app/Console/Commands/MigrateParcelasToReceivables.php` (destino `CONTA_RECEBER` com colunas novas; origem `PARCELA` fica)
- Test: estender `tests/Unit/Vendas/GeracaoParcelasCoincidenciaTest.php`/`tests/Feature/Administracao/ContratoComissao*Test.php` só se precisarem; criar `tests/Feature/Administracao/ContratoParcelasContaReceberTest.php` cobrindo `ContratoController::gerarParcelas` gravando colunas novas (ler o controller para montar o schema mínimo).

**Atenção:** muitos arrays aqui são de **geração de parcela** (`GeracaoParcelasService` devolve linhas que viram `Parcela::create`) — as chaves que viram coluna mudam; chaves internas da simulação que não viram coluna podem ficar, mas documente. Colunas de `CONTRATO`/`LOTES`/`PESSOA`/`COMISSAO_*` **não** mudam. JS do formulário de contrato lê a listagem de parcelas — seguir as chaves que o controller passar a devolver.

- [ ] **Step 1-4:** Teste (RED) → implementar → GREEN → `view:cache`/`view:clear` → grep de sobras com justificativa.

---

### Task 5: Demais consumidores (Acordo, Cobrança, Painel, Relatórios, Financeiro)

**Files:**
- Modify: `app/Services/Acordo/AcordoService.php`, `app/Services/Acordo/AcordoServiceInterface.php`, `resources/views/financeiro/acordo/acordo-form.blade.php`, `app/Http/Controllers/Web/Financeiro/AcordoController.php`
- Modify: `app/Services/Cobranca/CobrancaCrmService.php`, `CobrancaCartaService.php`, `CobrancaReguaService.php`, `app/Console/Commands/ProcessarReguaCobranca.php`
- Modify: `app/Services/PainelService.php`, `app/Services/FinancialReport/FinancialReportService.php`, `app/Services/FinancialReport/FinancialReportServiceInterface.php`, `app/Http/Controllers/Api/Financeiro/ApiFinancialReportsController.php`, `resources/views/financial-reports/index.blade.php`
- Modify: `app/Services/Relatorios/RelatorioParcelaService.php`, `RelatorioContratoService.php`, `RelatorioCobrancaBoletoService.php`, `RelatorioFiscalService.php`, `RelatorioContabilService.php`, `RelatorioComercialService.php`, `RelatorioRegistry.php` (colunas de saída/`colunasMoeda` que sejam colunas de receivables), `app/Http/Controllers/Api/Vendas/RelatorioVendasController.php` (+ `COLUNAS_MOEDA` e a view `vendas/relatorios.blade.php`/`vendas/pdf/relatorio.blade.php` se as chaves mudarem)
- Modify: `app/Services/FinancialMovement/FinancialMovementService.php`, `app/Services/FinancialMovement/FinancialMovementServiceInterface.php`, `app/Http/Controllers/Api/Financeiro/ApiFinancialMovementsController.php` (só o lado conta a receber: `Receivable::...`, `$receivable->...`; colunas de `financial_movements` ficam), `app/Services/Payable/PayableService.php` (idem), `app/Services/FechamentoMensal/FechamentoMensalService.php`, `app/Http/Controllers/Api/Financeiro/LookupController.php`, `app/Http/Controllers/FinanceiroController.php`, `app/Support/IvaPayable.php`, `app/Support/ComissaoPayable.php`, `app/Enums/PaymentMethod.php`/`ReceivableStatus.php` (só se citarem coluna)
- Test: `tests/Feature/Financeiro/ContaReceberConsumidoresTest.php` — cobrir ao menos uma query crua de relatório de parcelas (`RelatorioParcelaService`) e o `PainelService` (status de receitas), lendo os métodos antes.

**Atenção:** **saídas de relatório** (`RelatorioRegistry` colunas exibidas): se a coluna de saída é um alias (`as valor`, `as vencimento`), o alias fica e só a coluna de origem muda; se a saída é o nome cru da coluna (`vl_parcela`-like vindo de `receivables.original_amount` sem alias), a chave muda e `colunasMoeda`/labels do registry e de `resources/lang/*/relatorios.php` acompanham.

- [ ] **Step 1-4:** Teste (RED) → implementar → GREEN → `view:cache`/`view:clear` → grep de sobras com justificativa.

---

### Task 6: Varredura, suíte, migrate e documentação

- [ ] **Step 1:** `grep -rnE "['\"\`](receivables|recurring_receivables)['\"\`. ]|\b(receivables|recurring_receivables)\.[a-z_]+|cliente\.(receivables|recurring_receivables)" app routes resources/views public/assets/js tests --include=*.php --include=*.js | grep -v vendor` → só sobras legítimas (rotas/URLs `api/receivables`, nomes de view `receivables.*`, chaves de tradução `__('receivables.*')`, comentários históricos, `payables.receivable_id`/`financial_movements.receivable_id`). Grep por `->(due_date|original_amount|total_amount|payment_date|installment_number|contract_id|recurring_receivable_id|iva_amount|person_id|account_plan_id)\b` em `app/` e justificar cada sobra (objeto de outra tabela).
- [ ] **Step 2:** Suíte completa; comparar a lista de testes falhos com `/tmp/claude-1000/-home-gabriel-public-html-cereusLote/417799b3-87ea-4940-8c90-587f7aceb22a/scratchpad/head-result.txt` (38 pré-existentes) — nenhuma falha nova.
- [ ] **Step 3:** Docs: `.claude/CLAUDE.md` (bullet da conversão: fase 3 concluída — `receivables`→`CONTA_RECEBER`, `recurring_receivables`→`CONTA_RECEBER_RECORRENTE`, fases 3+4 unidas; `ActiveScope` lê `COLUNA_ATIVO`; atualizar "Pontos de atenção" que citam `Receivable.code`, `receivables.code`, `type = parcela_contrato`, `recurring_receivables.code`, `receivables` etc. para os nomes novos mantendo a história), `.claude/rules/backend.md`, `.claude/rules/multi-pais.md`, `.claude/rules/comissao.md`, `.claude/rules/painel.md`, `.claude/rules/relatorios.md` (onde citarem colunas/tabela de receivables). Spec: registrar que fases 3 e 4 foram unidas e renumerar a tabela de fases (payables vira fase 4, financial_movements fase 5, geral fase 6).
