# Tradução de tabelas — Fase 4 (Contas a Pagar) 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 `payables` → `CONTA_PAGAR` (tabela e colunas) e atualizar todo o código que depende dela, ponta a ponta.

**Architecture:** Mesmo padrão das fases 1-3 (referência: `database/migrations/clientes/2026_10_30_110000_rename_receivables_tables_to_portuguese.php` e o tratamento de `Receivable` na fase 3). `Payable` ganha `const COLUNA_ATIVO = 'fl_ativo'` (o `ActiveScope` já lê essa constante). Os pontos que hoje mantêm ramos separados por tabela porque `payables` ainda estava em inglês (`FinancialMovementService::sincronizarConta`, `PainelService::agruparPorStatus`, `FinancialReportService::COLUNAS_PAGAR`) passam a usar os nomes em português — onde os dois ramos ficarem idênticos, unificar é permitido se for trivial; caso contrário, só traduzir.

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

**Spec:** `docs/superpowers/specs/2026-10-29-traducao-tabelas-ingles-design.md` (fase 4 após a renumeração)

## 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'`, `'simple'`, `'expected'`, `'installment'`, `'installment_child'`, formas de pagamento...).
- Nomes de relação Eloquent (`person`, `accountPlan`, `bankAccount`, `parentPayable`, `childPayables`, `receivable`, `createdBy`, `updatedBy`...) e as chaves JSON derivadas **não** mudam.
- **Não muda nesta fase:** `financial_movements.*` (inclui `financial_movements.payable_id`). Arrays passados para `FinancialMovement::create`/`FinancialMovementService` continuam com chaves em inglês; só os valores lidos da conta a pagar mudam.
- Já em português (fases 1-3): `CONTA_BANCARIA`, `EXTRATO_BANCARIO` (`id_movimentacao_financeira`), `PLANO_CONTAS`, `CONTA_RECEBER`/`CONTA_RECEBER_RECORRENTE`. A coluna `payables.receivable_id` vira `id_conta_receber` nesta fase.
- Chave de JSON/payload/request que espelha 1:1 coluna renomeada é renomeada junto (payload de formulários, regras de validação, `$data['...']`, arrays passados a `PayableService::create()` — inclusive os montados em `ReceivableService::gerarPayableIva/criarPayableComissao` e `ApiFinancialMovementsController`). Chaves calculadas e parâmetros de filtro (`*Filter`, período `start_date`/`end_date`, `search`) ficam; o modo do formulário (`type` = simple/expected/installment) é coluna `tp_conta` → vira `tp_conta` no payload. Na listagem, alias calculado que sombreia coluna (CASE de status/type) segue o precedente da fase 3: alias `ds_status`/`tp_conta`.
- `{code}` das URLs (`api/payables/{code}`, `financeiro/{code}/edit-contapagar`) fica; valor vem de `cd_codigo`.
- **Nunca** busque-e-substitua global por `status`/`type`/`code`/`title`/`amount`/`active`/`description`/`due_date`. Altere só onde o objeto é `Payable` ou a tabela `payables`.
- `resources/lang/{pt,en,es}/validation.php` `attributes`: toda chave nova com regra de validação precisa de rótulo (reaproveitar texto da antiga; manter antigas se `financial_movements` ainda usar); nenhuma chave duplicada.

## Mapa desta fase

**`payables` → `CONTA_PAGAR`**
`person_id`→`id_pessoa`, `code`→`cd_codigo`, `account_plan_id`→`id_plano_contas`, `bank_account_id`→`id_conta_bancaria`, `title`→`ds_titulo`, `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`, `net_amount`→`vl_liquido`, `payment_method`→`ds_forma_pagamento`, `status`→`ds_status`, `type`→`tp_conta`, `installments_total`→`nr_total_parcelas`, `parent_payable_id`→`id_conta_pagar_pai`, `receivable_id`→`id_conta_receber`, `comissao_lancamento_id`→`id_comissao_lancamento`, `observations`→`ds_observacao`, `attachments`→`ds_anexos`, `active`→`fl_ativo`, `created_by`→`id_usuario_criacao`, `updated_by`→`id_usuario_alteracao`

---

### Task 1: Migration, model e schemas de teste

**Files:**
- Create: `database/migrations/clientes/2026_10_31_100000_rename_payables_table_to_portuguese.php`, `tests/Feature/Migrations/RenamePayablesTableMigrationTest.php`, `tests/Feature/Financeiro/ContaPagarModelTest.php`
- Modify: `app/Models/Payable.php` (`$table`, `COLUNA_ATIVO`, fillable, casts, boot/geração de `cd_codigo`, scopes globais/locais, relações com FKs novas — `parentPayable`/`childPayables` via `id_conta_pagar_pai`, `receivable()` via `id_conta_receber`, accessors, métodos de negócio); relações em outros models que apontam para payables por coluna DE payables (ex.: `Receivable` → payables via `receivable_id` agora `id_conta_receber`; `ComissaoLancamento`/outros se existirem — grep). `FinancialMovement::payable()` usa a coluna `payable_id` de `financial_movements` — **não muda**.
- Modify: schemas SQLite de `payables` em todos os testes (grep `create('payables'` e `table('payables')`) — só tabela/colunas/inserts/asserts de payables.

- [ ] Steps: teste da migration (formato de `RenameReceivablesTablesMigrationTest`: colunas do mapa, dados e vínculo pai→filha preservados, idempotente com contagem, down) → migration → `ContaPagarModelTest` (cd_codigo sequencial; ActiveScope/COLUNA_ATIVO se `Payable` registrar o scope — ler o model; parent/child; `receivable()`) → model → schemas dos testes, registrando antes/depois. Comentário de cabeçalho da migration: fase 4, idempotente, FKs/índices com nomes antigos (`payables_*`).

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

**Files:** `app/Services/Payable/PayableService.php` (inteiro, incluindo `validatePayableData`, `list` com SQL cru/CASE de status e type, criação de parcelas/filhas, `markAsPaid`/`reversePayment`/`cancel`/`delete`, `findByCode`, comentários sobre colunas), `PayableServiceInterface.php`, `app/Http/Controllers/Api/Financeiro/APIPayablesController.php`, `app/Http/Controllers/Web/Financeiro/PayablesController.php`, `app/Services/Importacao/ImportacaoPayablesService.php`, `app/Http/Controllers/Api/Financeiro/PayablesImportacaoController.php`, `resources/lang/{pt,en,es}/validation.php`; teste `tests/Feature/Financeiro/ContaPagarServiceTest.php`.
- Dentro do service, arrays para `FinancialMovement`/`FinancialMovementService` mantêm chaves em inglês.
- Registrar no relatório o contrato exato de request/response alterado (para a Task 3).
- [ ] Steps: teste (RED: create avulsa e parcelada com chaves novas; validação com erro na chave nova; markAsPaid gera movimentação; list com status calculado; importação com rótulo de validação) → implementar → GREEN → grep de sobras.

### Task 3: Telas de Contas a Pagar

**Files:** `resources/views/payables/{index,form,importar}.blade.php`, `resources/views/financial-movements/form.blade.php` (só o lado payable, ex. `movement.payable.payment_method` → `ds_forma_pagamento`), `resources/views/partials/scripts.blade.php` (se a busca global ler payables), `resources/views/cobranca/regua-formulario.blade.php`/`cadastro/taxaValorFormulario.blade.php` (só se lerem coluna de payable — confirmar).
- Seguir o contrato do relatório da Task 2 e o controller/service já migrados. Form: ids e `#X-error` seguem as chaves de validação; parcelamento dinâmico (`<template>` de parcela), totais, carga de edição, marcar como pago, estorno. Índice: colunas, renders, detalhe, agrupamento por competência.
- [ ] Steps: ler views e relatório da Task 2 → aplicar → `view:cache`/`view:clear` → grep de sobras com justificativa → render via tinker se viável.

### Task 4: Demais consumidores de `payables`

**Files:** `app/Services/Receivable/ReceivableService.php` (`gerarPayableIva`, `criarPayableComissao` e consultas de idempotência `Payable::where('receivable_id'...)` → chaves/colunas novas), `app/Services/FinancialMovement/FinancialMovementService.php` (`createFromPayable`, ramo payable de `sincronizarConta`/`delete`/`update`) + interface, `app/Http/Controllers/Api/Financeiro/ApiFinancialMovementsController.php` (array `$conta` de payable e mapa de erros), `app/Services/FinancialReport/FinancialReportService.php` (`COLUNAS_PAGAR`, `getPayablesReport`, desconto sintético, `detalharPorCategoria` com `payables.*` em SQL cru) + interface + `ApiFinancialReportsController.php` + `resources/views/financial-reports/index.blade.php` (só se chaves de saída mudarem), `app/Services/PainelService.php` (`statusPagaveis`/`agruparPorStatus` ramo payables), `app/Services/Relatorios/RelatorioComercialService.php`, `app/Http/Controllers/Api/Administracao/ContratoController.php` + `resources/views/administracao/contratoFormulario.blade.php` (só referências a payables), `app/Support/IvaPayable.php`, `app/Support/ComissaoPayable.php`, `app/Services/FechamentoMensal/FechamentoMensalService.php`, `app/Http/Controllers/Api/Financeiro/LookupController.php`, `app/Services/BankStatement/BankStatementService.php` (rótulo de estorno lê `payable?->code`), `app/Http/Controllers/Api/Cobranca/{APICobrancaReguaController,APICobrancaCrmController}.php`, `app/Enums/{PaymentMethod,PayableStatus}.php` (só comentários/colunas); teste `tests/Feature/Financeiro/ContaPagarConsumidoresTest.php` (geração de Payable de IVA a partir da baixa de receivable grava colunas novas e é idempotente via `id_conta_receber`; relatório financeiro de pagáveis roda; painel de pagáveis roda).
- [ ] Steps: teste (RED) → implementar → GREEN → `view:cache` se Blade → grep de sobras.

### Task 5: Varredura, suíte, docs

- [ ] Varredura: `grep -rnE "['\"\`]payables['\"\`. ]|\bpayables\.[a-z_]+|cliente\.payables" app routes resources/views public/assets/js tests` e por `->(net_amount|parent_payable_id|installments_total|comissao_lancamento_id)` e colunas do núcleo sobre objetos Payable — justificar sobras (rotas/URLs `api/payables`, views `payables.*`, `__('payables.*')`, comentários históricos, `financial_movements.payable_id`).
- [ ] Suíte completa: lista de falhas idêntica a `/tmp/claude-1000/-home-gabriel-public-html-cereusLote/417799b3-87ea-4940-8c90-587f7aceb22a/scratchpad/head-result.txt` (38 pré-existentes).
- [ ] Docs (`.claude/CLAUDE.md`, `.claude/rules/*.md`, spec): fase 4 concluída (`payables`→`CONTA_PAGAR`, migration), cuidados (iii)/(iv) incluindo `payables` antes de `2026_10_31_100000`; "Pontos de atenção" sobre `PayableService` (bug de `'type' => 'expense'`, chaves sem `??`) e IVA/comissão com nomes novos. **Itens carregados da revisão final da fase 3:** `CLAUDE.md` ~110 (DistratoWorkflowTest: `$table->boolean('fl_ativo')` no schema `CONTA_RECEBER`), ~91 (Acordos → `CONTA_RECEBER` `tp_conta = parcela_contrato`), bullet do Painel ("só `client_id`" desatualizado — `CONTA_RECEBER` tem `id_empreendimento`), `rules/backend.md:10` (people do geral sai na fase 6), `rules/relatorios.md:59` (`p.due_date` → nome atual), `rules/comissao.md:104` (`installment_category` → `ds_categoria_parcela`), `rules/backend.md:54` (`receivables.bank_account_id` → `CONTA_RECEBER.id_conta_bancaria`). E `app/Models/Receivable.php`: `'id_banco'` duplicado no `$fillable` — remover a duplicata.
