# Tradução das tabelas em inglês para português (CAIXA ALTA) — Design

**Data:** 2026-10-29
**Branch de origem:** `cereuslote-136-geracao-parcela`

## Objetivo

O schema mistura tabelas herdadas do `acadeLotear` (português, CAIXA ALTA, colunas com prefixo de tipo) com tabelas vindas do `cereus` cond (inglês, minúsculo). Converter as tabelas em inglês — nome **e colunas** — para o padrão do legado, e atualizar todo o código que depende delas **ponta a ponta** (banco, models, services, queries cruas, JSON da API, Blade/JS).

## Decisões

1. **Escopo:** financeiro do tenant + tabelas de negócio do `geral` (`users`, `roles`, `groups`, `group_roles`). Tabelas de infraestrutura do Laravel (`sessions`, `jobs`, `job_batches`, `failed_jobs`, `password_reset_tokens`, `migrations`) ficam como estão.
2. **Ponta a ponta:** o nome em português vale também nas chaves do JSON da API e no frontend. Sem camada de tradução/API Resource mantendo nomes em inglês.
3. **Entrega em fases**, um grupo de tabelas por vez, cada uma com migration + código + teste das telas do grupo.
4. **`people`** (tenant e geral): **dropar só se vazia e sem FK apontando pra ela** (senão fica e é logada) — 0 linhas, só usada por `App\Models\Person` (órfão). Saem junto (decisão do programador, 29/10/2026 — nenhum é usado por rota/scheduler/teste): `App\Models\Person`, `App\Models\Spouse`, `App\Models\Address` e os commands one-off de importação do legado `ImportBancoContaToBanks` (`banks:import-legacy`) e `ImportBancoAssociacoesToBanks` (`banks:import-associacoes`). Enums que só eles importam (ex. `PersonType`) saem se ficarem sem uso; `SouthAmericaCountry` fica (usado pelo Cadastro de Cliente). Referência em `.claude/rules/backend.md` é atualizada.
5. **Valores de enum não mudam** (`'paid'`, `'simple'`, `'credit'`, `'receita'`…). Só nomes de tabela/coluna.
6. Colunas que **ficam**: `id`, `created_at`, `updated_at` (dependência do Eloquent) e colunas já em português.

## Convenção de coluna

Minúsculo com prefixo, igual ao legado: `id_` (FK), `vl_` (valor), `dt_` (data), `nr_` (número), `fl_` (booleano), `ds_` (texto), `nm_` (nome), `tp_` (tipo/enum), `cd_` (código).
Regras comuns: `code`→`cd_codigo`, `active`→`fl_ativo`, `created_by`→`id_usuario_criacao`, `updated_by`→`id_usuario_alteracao`.

## Mapa de tabelas e colunas

### `banks` → `CONTA_BANCARIA`
(`BANCO` já existe no tenant — tabela legada distinta.)

| atual | novo |
|---|---|
| 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 |

Ficam: `id_empreendimento`, `conta_cobranca`, `conta_cobranca_dv`, `carteira_variacao`, `juros`, `multa`, `tp_juros`, `tp_multa`, `msg_boleto`, `msg_adicional`, `fl_ativo_boleto`, `fl_ativo_remessa`, `fl_ativo_baixamanual`, `chave_pix`, `nm_avalista`, `cnpj_avalista`, `cpf_avalista`.

### `bank_empreendimentos` → `CONTA_BANCARIA_EMPREENDIMENTO`

| atual | novo |
|---|---|
| bank_id | id_conta_bancaria |

### `bank_statements` → `EXTRATO_BANCARIO`

| atual | novo |
|---|---|
| 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 |

### `account_plans` → `PLANO_CONTAS`

| atual | novo |
|---|---|
| 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 / updated_by | id_usuario_criacao / id_usuario_alteracao |

### `recurring_receivables` → `CONTA_RECEBER_RECORRENTE`

| atual | novo |
|---|---|
| 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 / updated_by | id_usuario_criacao / id_usuario_alteracao |

### Núcleo comum `CONTA_RECEBER` / `CONTA_PAGAR`

| atual | novo |
|---|---|
| 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 / updated_by | id_usuario_criacao / id_usuario_alteracao |

### `receivables` → `CONTA_RECEBER` (além do núcleo)

| atual | novo |
|---|---|
| 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 |

Fica: `id_empreendimento`.

### `payables` → `CONTA_PAGAR` (além do núcleo)

| atual | novo |
|---|---|
| net_amount | vl_liquido |
| installments_total | nr_total_parcelas |
| parent_payable_id | id_conta_pagar_pai |
| receivable_id | id_conta_receber |
| comissao_lancamento_id | id_comissao_lancamento |

Fica: `id_empreendimento`.

### `financial_movements` → `MOVIMENTACAO_FINANCEIRA`

| atual | novo |
|---|---|
| code | cd_codigo |
| account_plan_id | id_plano_contas |
| bank_account_id | id_conta_bancaria |
| type | tp_movimento |
| origin_type | tp_origem |
| transfer_id | cd_transferencia |
| payable_id | id_conta_pagar |
| receivable_id | id_conta_receber |
| amount | vl_valor |
| transaction_date | dt_transacao |
| description | ds_descricao |
| notes | ds_observacao |
| document_number | nr_documento |
| active | fl_ativo |
| conciliated | fl_conciliado |
| created_by / updated_by | id_usuario_criacao / id_usuario_alteracao |

### Geral: `users` → `USUARIO`

| atual | novo |
|---|---|
| name | nm_usuario |
| email | ds_email |
| avatar | ds_avatar |
| email_verified_at | dt_email_verificado |
| password | ds_senha |
| status | nr_status |
| remember_token | ds_remember_token |
| client_id | id_cliente |
| group_id | id_grupo |
| is_master | fl_master |
| code | cd_codigo |
| selected_client_id | id_cliente_selecionado |

`User` precisa sobrescrever `getAuthPassword()` (→ `ds_senha`) e `getRememberTokenName()` (→ `ds_remember_token`); login (`AuthController::store()`) e `config/auth.php` passam a usar `ds_email` como credencial. `sessions.user_id` (Laravel) não muda.

### Geral: `roles` → `PERMISSAO`

| atual | novo |
|---|---|
| role_name | nm_permissao |
| role_description | ds_permissao |
| role_parent_id | id_permissao_pai |
| role_icon | ds_icone |
| role_status | fl_ativo |

### Geral: `groups` → `GRUPO`

| atual | novo |
|---|---|
| group_name | nm_grupo |
| group_description | ds_grupo |
| group_status | fl_ativo |
| client_id | id_cliente |

### Geral: `group_roles` → `GRUPO_PERMISSAO`

| atual | novo |
|---|---|
| group_id | id_grupo |
| role_id | id_permissao |
| group_role_status | fl_ativo |

Os **valores** de `nm_permissao` (ex. `'Criar Bancos (Financeiro)'`, usados em `permission:X`) não mudam.

## Fases

| # | Tabelas | Observação |
|---|---|---|
| 1 | `banks`, `bank_empreendimentos`, `bank_statements` (+ drop `people` do tenant) | folhas; telas Bancos, Extrato |
| 2 | `account_plans` | Plano de Contas, seeds `9000`/`9001`, `AccountPlanName`, `IvaPayable`, `ParcelaReceivable` |
| 3 | `recurring_receivables` + `receivables` (fases 3 e 4 unidas) | maior raio: parcelas de contrato, Acordos, Distrato, Painel, Relatórios, Comissão, Cobrança, Gestão de Carteira |
| 4 | `payables` | Contas a Pagar, IVA, comissão |
| 5 | `financial_movements` | Movimentação, Fechamento Mensal, Relatórios Financeiros, Painel |
| 6 | `roles`, `groups`, `group_roles`, `users` (+ drop `people` do geral) | maior risco: auth/JWT/RBAC; fica por último |

**Status (31/10/2026): todas as 6 fases concluídas no código** (migrations `2026_10_29_110000`, `2026_10_30_100000`, `2026_10_30_110000`, `2026_10_31_100000`, `2026_10_31_110000` em `clientes`; `2026_10_31_120000` em `geral`). Planos em `docs/superpowers/plans/2026-10-*-traducao-tabelas-*.md`. Na fase 6 o request de login (`email`/`password`) foi mantido como contrato externo; o JSON do usuário e `api/auth/permissoes` (`fl_master`) passaram às chaves novas — ver `.claude/CLAUDE.md` (seção Autenticação e checklist de deploy).

**Fora do escopo, candidatas a uma rodada futura** (ainda em minúsculo no `geral`): `translations` e `personal_access_tokens` (mortas — sem leitura em runtime / Sanctum removido; candidatas a drop, não a rename); `clientes`, `dicionario`, `termos_acesso`, `vendas_externas` (já em português, só fora do padrão CAIXA ALTA + prefixo). Tabelas de infraestrutura do Laravel continuam fora por decisão (item 1 acima).

Cada fase:
1. Migration nova (`database/migrations/clientes` ou `geral`) com `RENAME TABLE` e `ALTER TABLE ... RENAME COLUMN` via `DB::statement` (doctrine/dbal não está instalado), idempotente com guardas `hasTable`/`hasColumn`. `down()` reverte. MySQL 8 leva FKs/índices junto no rename.
2. Migrations antigas **não** são editadas — tenant novo cria com nome antigo e a migration nova renomeia.
3. Atualizar: model (`$table`, `$fillable`, `$casts`, relações com FK explícita, scopes), services, controllers (regras de validação/chaves de request), queries cruas (`DB::table`, `join`, `selectRaw`), relatórios, views Blade e JS (chaves de payload e de leitura de JSON), traduções que usem nome de campo como chave, testes em `tests/`.
4. Varredura final por grep dos nomes antigos (tabela e coluna) no escopo da fase.
5. Rodar `php artisan clientes:migrate` (usuário, ambiente nativo) e testar as telas do grupo; rodar a suíte de testes afetada.

## Riscos

- **Conflito com branches abertas** que mexem no financeiro — combinar janela de merge por fase.
- **Colunas com nome genérico** (`status`, `amount`, `type`, `code`, `title`) aparecem em centenas de pontos que **não** pertencem a estas tabelas (legado, outras APIs) — o rename tem que ser guiado por contexto (model/tabela), nunca por busca-e-substitui global.
- **App `cereusCorretor`** consome este backend e não está nesta máquina — confirmar antes de cada fase se ele usa algum endpoint afetado.
- **Banco misto durante as fases** — aceitável, cada fase é autossuficiente.
- **Nomes de FK/índice não mudam no rename** (ex. `bank_statements_bank_account_id_foreign` segue dentro de `EXTRATO_BANCARIO`) — migrations das fases 2-6 devem dropar FK/índice por nome explícito, não por array de coluna.
- **Tenant `ativo=0`** é pulado por `clientes:migrate`; ao reativar, migrar antes de usar (vale pras fases 2-6).
- **Produção:** cada fase só funciona depois de `clientes:migrate` em todos os tenants (e `migrate --path=database/migrations/geral` na fase 6); deploy de código e migration precisam ir juntos.
