# Tradução de tabelas — Fase 2 (Plano de Contas) 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 `account_plans` (tabela e colunas) para `PLANO_CONTAS` e atualizar todo o código que depende dela, ponta a ponta.

**Architecture:** Mesmo padrão da fase 1 (`database/migrations/clientes/2026_10_29_110000_rename_banks_tables_to_portuguese.php` é a referência: guardas `hasTable`/`hasColumn`, `RENAME COLUMN` via `DB::statement`, `down()` simétrico). Código atualizado por camada de consumidor. As colunas `account_plan_id` de `receivables`/`payables`/`financial_movements`/`recurring_receivables` **não** mudam aqui (fases 3-6).

**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 em pt-BR; **nunca** rodar `git add/commit/push/rm/stash/checkout/reset` nem `npm run build`; não rodar migration em banco real (o controller roda `clientes:migrate` no fim). Onde houver "commit", pule.
- Ambiente nativo; testes com `php artisan test --filter=...` (SQLite in-memory). Os avisos `DEPR ... PDO::MYSQL_ATTR_SSL_CA` são pré-existentes — ignore.
- Tabela em CAIXA ALTA; coluna minúscula com prefixo `id_`/`vl_`/`dt_`/`nr_`/`fl_`/`ds_`/`nm_`/`tp_`/`cd_`. Ficam: `id`, `created_at`, `updated_at`.
- Valores de enum **não** mudam (`'receita'`, `'despesa'`, `'sintetico'`).
- Nomes de relação Eloquent (`accountPlan`, `parent`, `children`, `creator`, `updater`) e as chaves JSON derivadas (`account_plan`, `parent`) **não** mudam.
- Colunas `account_plan_id` das outras tabelas **não** mudam nesta fase.
- Chave de JSON/payload que espelha 1:1 uma coluna renomeada é renomeada junto (incluindo DTOs como `account_plan => ['code','name']` do relatório financeiro). **Parâmetros de filtro de listagem** (`codeFilter`, `nameFilter`, `typeFilter`, `statusFilter`, `parent_idFilter`, e o `type` de `GET api/financeiro/accountPlans`) **ficam** — são nomes de filtro, não colunas.
- O `{code}` nas URLs `api/account-plans/{code}` e `financeiro/{code}/edit-planocontas` fica na URL; o valor passa a vir de `cd_codigo`.
- Nunca busque-e-substitua global por `code`/`name`/`type`/`status`: altere só onde o objeto é `AccountPlan`/`account_plans`/`PLANO_CONTAS`. Em queries que juntam `financial_movements`/`payables`/`receivables`, as colunas dessas tabelas ficam.
- Seed migrations antigas (`2026_07_31_130100_seed_parcela_contrato_account_plan`, `2026_10_19_100400_seed_iva_account_plan`, seeds de comissão `9000`) **não** são editadas — rodam antes do rename.

## Mapa desta fase

**`account_plans` → `PLANO_CONTAS`**
`name`→`nm_conta`, `code`→`cd_codigo`, `type`→`tp_conta`, `default_person_id`→`id_pessoa_padrao`, `parent_id`→`id_plano_contas_pai`, `status`→`fl_ativo`, `created_by`→`id_usuario_criacao`, `updated_by`→`id_usuario_alteracao`

---

### Task 1: Migration de rename

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

**Interfaces:** Produces: tabela `PLANO_CONTAS` com as colunas do mapa.

- [ ] **Step 1: Teste (RED).** Seguir exatamente a estrutura de `tests/Feature/Migrations/RenameBanksTablesMigrationTest.php` (ler antes): setUp com conexão `cliente` SQLite em memória e `database.default=cliente`; cria `account_plans` com `id`, `name`, `code`, `type`, `default_person_id`, `parent_id`, `status`, `created_by`, `updated_by`, timestamps; insere 2 linhas (pai id=1 `code='2'`, `type='sintetico'`; filha id=2 `code='2.5'`, `parent_id=1`, `status=1`). Testes: (a) `up()` → `account_plans` não existe, `PLANO_CONTAS` tem as 8 colunas novas, `nm_conta`/`id_plano_contas_pai` preservados da filha; (b) `up()` 2x idempotente; (c) `up()`+`down()` → `account_plans` volta com `name`, `code`, `parent_id`.
- [ ] **Step 2:** `php artisan test --filter=RenameAccountPlansTableMigrationTest` → FAIL (arquivo não existe).
- [ ] **Step 3: Migration.** Mesma estrutura da migration da fase 1 (constante `TABELAS` com `'account_plans' => ['PLANO_CONTAS', [...mapa...]]`, `up()`/`down()`/`renomear()` idênticos), sem bloco de `people`. Comentário de cabeçalho em pt-BR: fase 2 da tradução (link do spec), idempotente, FKs/índices mantêm nomes antigos (ex. `account_plans_parent_id_foreign`, unique de `code`) — drop futuro por nome explícito.
- [ ] **Step 4:** teste → PASS.

---

### Task 2: Model `AccountPlan`, classes de apoio e schemas dos testes existentes

**Files:**
- Modify: `app/Models/AccountPlan.php`
- Modify: `app/Support/IvaPayable.php`, `app/Support/ParcelaReceivable.php`, `app/Support/ComissaoPayable.php`
- Modify (schema SQLite de `account_plans` montado no setUp + inserts/queries de `account_plans` → `PLANO_CONTAS` com colunas novas): `tests/Feature/Administracao/ContratoComissaoWorkflowTest.php`, `tests/Feature/Financeiro/AcordoWorkflowTest.php`, `tests/Feature/Financeiro/ReceivableAgreedFilterTest.php`, `tests/Feature/Administracao/ContratoIvaStatusTest.php`, `tests/Feature/FinancialReport/FinancialReportServiceOverdueFilterTest.php`, `tests/Feature/Financeiro/ReceivableComissaoPayableTest.php`
- Test: `tests/Feature/Financeiro/PlanoContasModelTest.php`

**Interfaces:** Produces: `AccountPlan` com `$table='PLANO_CONTAS'`, fillable/casts com colunas do mapa; `parent()`/`children()` via `id_plano_contas_pai`; `creator()`/`updater()` via `id_usuario_criacao`/`id_usuario_alteracao`; `boot()` gera `cd_codigo` (mesma lógica de hoje, lendo/gravando `cd_codigo`); scopes reescritos nas colunas novas (ler o model inteiro — ex. `scopeRoot` → `whereNull('id_plano_contas_pai')`, `scopeByCode` → `cd_codigo`, e qualquer scope de `type`/`status`). `IvaPayable::accountPlanId()/credorPersonId()`, `ParcelaReceivable` e `ComissaoPayable` consultam `PLANO_CONTAS` por `cd_codigo` e leem `id_pessoa_padrao`.

- [ ] **Step 1: Teste (RED)** `PlanoContasModelTest`: schema `PLANO_CONTAS` mínimo; (a) `AccountPlan::create(['nm_conta'=>'X','tp_conta'=>'receita'])` gera `cd_codigo` 1 e o próximo 2; `fl_ativo` cast boolean; (b) `children()`/`parent()` funcionam via `id_plano_contas_pai`; (c) `IvaPayable::accountPlanId()` acha a linha `cd_codigo='9001'` e `IvaPayable::credorPersonId()` devolve o `id_pessoa_padrao` dela (ler `IvaPayable` antes para usar os nomes reais dos métodos).
- [ ] **Step 2:** RED.
- [ ] **Step 3:** Implementar model + 3 classes de apoio.
- [ ] **Step 4:** Atualizar os 6 testes existentes listados: só o schema/insert/queries de `account_plans` (tabela → `PLANO_CONTAS`, colunas → mapa). **Baseline antes desta fase** (não piorar): `ContratoComissaoWorkflowTest` 6 passam/2 falham; `AcordoWorkflowTest` 3 passam; `ReceivableAgreedFilterTest` 2 asserções passam; `ContratoIvaStatusTest` 1 passa; `FinancialReportServiceOverdueFilterTest` 2 passam; `ReceivableComissaoPayableTest` 3 passam/4 falham. Os testes que dependem de services ainda não migrados (Task 3/4) podem falhar temporariamente — registre quais no relatório; a Task 5 confere o baseline final.
- [ ] **Step 5:** `php artisan test --filter=PlanoContasModelTest` → PASS; rodar `--filter=ContratoIvaStatusTest` também.

---

### Task 3: Cadastro do Plano de Contas (service, API, telas)

**Files:**
- Modify: `app/Services/AccountPlan/AccountPlanService.php` (inteiro: regras de validação ~33-40 incluindo `exists:cliente.account_plans,id` → `exists:cliente.PLANO_CONTAS,id`; `buildFilteredQuery` ~90-160 com SQL cru `account_plans.*`/`account_plans.type`/`status`/`parent_id`/`code`/`name`, subqueries `EXISTS(SELECT 1 FROM account_plans ...)`, join `parent_display`; `findByCodeAndClient`; `create`/`update`/`toggleStatus`/`delete`; `validateHierarchy`/`codeExists`/`generateNextCode`; `createDefaultAccountPlans`/`getDefaultAccountPlansStructure` — arrays de estrutura com `name`/`code`/`type`)
- Modify: `app/Services/AccountPlan/AccountPlanServiceInterface.php` (só comentários se citarem colunas)
- Modify: `app/Http/Controllers/Api/Financeiro/ApiAccountPlansController.php` (`index` usa `$accountPlan->code/name`; `generateCode` lê `parent_id` do request e `$parent?->code`; `createDefault` `whereIn('code',...)`)
- Modify: `resources/views/account-plans/index.blade.php`, `resources/views/account-plans/form.blade.php`
- Modify: `resources/lang/{pt,en,es}/validation.php` (attributes: adicionar `nm_conta`, `cd_codigo`, `tp_conta`, `id_plano_contas_pai`, `id_pessoa_padrao` com o texto das chaves antigas equivalentes; remover antiga só se nenhum outro validador usar)
- Test: `tests/Feature/Financeiro/PlanoContasServiceTest.php`

**Interfaces:**
- Consumes: `AccountPlan` (Task 2).
- Produces: payload de create/update aceita `nm_conta`, `cd_codigo`, `tp_conta`, `id_plano_contas_pai`, `id_pessoa_padrao`, `fl_ativo`; erros de validação usam essas chaves; `GET api/account-plans` devolve linhas com colunas novas + campos calculados (`has_children`, `children_count`, `type_label`/`status_icon` etc. — manter os nomes calculados como estão); `GET api/account-plans/generate-code` aceita `id_plano_contas_pai` no lugar de `parent_id`; `GET api/account-plans/{code}` devolve `account_plan` com colunas novas.

- [ ] **Step 1: Teste (RED)** `PlanoContasServiceTest` chamando `AccountPlanService` direto (resolver via container): schema `PLANO_CONTAS` + o que o service consultar (ler o service antes); (a) `create(['nm_conta'=>'Receitas','tp_conta'=>'sintetico'])` cria com `cd_codigo` gerado; (b) criar filha com `id_plano_contas_pai` gera código hierárquico (`generateNextCode`); (c) `buildFilteredQuery(['nameFilter'=>'Rec'])->get()` acha a linha e traz `has_children`; (d) `create` sem `nm_conta` falha e `getErrors()` tem a chave `nm_conta`; (e) `createDefaultAccountPlans('PY')` não cria o grupo `2.5` e `('BR')` cria (regra atual do service — confirmar lendo o código).
- [ ] **Step 2:** RED.
- [ ] **Step 3:** Implementar service + interface + API controller.
- [ ] **Step 4:** Telas: ler as duas views inteiras. Em `index.blade.php`, todo acesso a coluna de linha do plano (`row.code`, `row.name`, `row.type`, `row.status`, `row.parent_id`, `selected.code` usado na URL de toggle/delete, payload do `POST api/account-plans` do cadastro rápido ~565) → nomes novos; parâmetros de filtro (`codeFilter` etc.) ficam. Em `form.blade.php`: ids dos campos e `#X-error` seguem as chaves novas (o `showErrors` mapeia chave→id, igual à fase 1), carga de edição (`response.account_plan.*`), combo de pai (lista sintética: `p.code`/`p.name`), `generate-code` (param `id_plano_contas_pai`), payload do submit, campo "Credor padrão" (`default_person_id` → `id_pessoa_padrao`).
- [ ] **Step 5:** validation.php (3 idiomas).
- [ ] **Step 6:** `php artisan test --filter=PlanoContasServiceTest` PASS; `php artisan view:cache && php artisan view:clear`.

---

### Task 4: Consumidores do plano de contas fora do cadastro

**Files:**
- Modify: `app/Http/Controllers/Api/Financeiro/LookupController.php` (`accountPlans()`: `where('status')`→`fl_ativo`, `where('type', $request->input('type'))`→`where('tp_conta', ...)` mantendo o parâmetro `type`, `get(['id','nm_conta','cd_codigo','tp_conta'])`)
- Modify: `resources/views/financial-movements/form.blade.php` (~235), `resources/views/payables/form.blade.php` (~878), `resources/views/receivables/form.blade.php` (~402) — leitura dos itens do lookup (`p.name`/`p.code`/`p.type` → novos)
- Modify: `app/Services/Receivable/ReceivableService.php` (~489, ~660: `->with('accountPlan:id,code,name')` → `'accountPlan:id,cd_codigo,nm_conta'`)
- Modify: `app/Services/Payable/PayableService.php` (~306 idem; ~647/~682 `with(['accountPlan'])` ok)
- Modify: `resources/views/payables/index.blade.php` (`accountPlanLabel` ~487 e usos), `resources/views/receivables/index.blade.php` (`accountPlanLabel` ~612; ~1135-1146), `resources/views/financial-movements/index.blade.php` (~308 render de `account_plan`)
- Modify: `app/Services/FinancialReport/FinancialReportService.php` (~282-330 `accountPlan.parent`, `->name`, `->code`; ~456-462 DTO `account_plan => [code, name]` → `[cd_codigo, nm_conta]`; ~558 `accountPlan->code`; ~587-593 SQL cru `account_plans.name`/`parents.name`/`account_plans.parent_id` e joins) + `resources/views/financial-reports/index.blade.php` (~457, ~487 `group.account_plan.code/name`)
- Modify: `app/Services/PainelService.php` (~420-426 join `account_plans as ap` → `PLANO_CONTAS as ap`, `ap.name` → `ap.nm_conta`; comentário ~16)
- Modify: `app/Services/Importacao/ImportacaoPayablesService.php` (~186 `whereRaw('TRIM(code) = ?')`, `where('type','despesa')`), `app/Services/Importacao/ImportacaoReceivablesService.php` (~188)
- Modify (comentários citando `account_plans`): `ApiAccountPlansController.php:15`, `PayableService.php:305`, `ReceivableService.php:488`, `ComissaoPayable.php:22` se a Task 2 não tiver feito.
- Grep obrigatório antes de terminar: `grep -rnE "account_plan\??\.(code|name|type|status|parent_id)|accountPlan->(code|name|type|status|parent_id)|accountPlan\??\.(code|name)|'accountPlan:id" app resources/views` — toda ocorrência restante precisa ser justificada no relatório.
- Test: `tests/Feature/Financeiro/PlanoContasConsumidoresTest.php`

- [ ] **Step 1: Teste (RED)**: (a) `LookupController::accountPlans()` com request `type=receita` devolve só ativas do tipo, com chaves `nm_conta`/`cd_codigo`/`tp_conta`; (b) a query de detalhamento do `FinancialReportService` que faz o join cru (~587) roda e traz `category_name`/`item_name` (montar schema mínimo de `financial_movements` em inglês + `PLANO_CONTAS`; ler o método antes e chamar o método público que o usa).
- [ ] **Step 2:** RED.
- [ ] **Step 3:** Implementar todos os arquivos.
- [ ] **Step 4:** PASS; `view:cache`/`view:clear`; grep obrigatório.

---

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

- [ ] **Step 1:** Varredura: `grep -rnE "['\"\`]account_plans['\"\`. ]|account_plans\.|cliente\.account_plans|\b(default_person_id)\b" app routes resources/views tests --include=*.php` → só ocorrências legítimas (comentários históricos). Revisar também `accountPlan` em `resources/views` por leituras de `.code`/`.name`.
- [ ] **Step 2:** `php artisan test` completo. Baseline fase 1: 38 falhas pré-existentes (Auth/Profile do Breeze removido, DistratoWorkflow, ContratoComissao*, ReceivableComissaoPayable, GrupoPermissoes, Importacao* sem phpspreadsheet). Nenhuma falha nova permitida.
- [ ] **Step 3:** Docs: `.claude/CLAUDE.md` (bullet da conversão por fases: fase 2 concluída; seção "Pontos de atenção" que cita `account_plans`/`AccountPlanName`/`default_person_id` atualizada), `.claude/rules/backend.md` e `.claude/rules/multi-pais.md` (card #12 IVA cita `account_plans.default_person_id`; card #07 cita grupo `2.5`) — trocar nomes de tabela/coluna atuais, mantendo narrativa histórica.
