# Tradução de tabelas — Fase 6 (banco geral: usuários e permissões) 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, no banco `geral`, `users` → `USUARIO`, `roles` → `PERMISSAO`, `groups` → `GRUPO`, `group_roles` → `GRUPO_PERMISSAO` (tabela e colunas) e dropar `people` do geral (só se vazia e sem FK), atualizando todo o código — autenticação (JWT), RBAC, administração de usuários/grupos, provisionamento de tenant.

**Architecture:** Migration idempotente em `database/migrations/geral` (padrão das fases 1-5). `User` sobrescreve os pontos em que o Laravel assume nomes de coluna: `getAuthPassword()` (→ `ds_senha`), `getRememberTokenName()` (→ `ds_remember_token`), `getEmailForPasswordReset()` e `routeNotificationForMail()` (→ `ds_email`); cast `'ds_senha' => 'hashed'`. **Contrato de login fica:** `POST api/auth/login` e `register` continuam recebendo `email`/`password` no request (credencial de autenticação, consumida também pelos apps mobile `cereusCorretor`/`cereusMobile`) — o controller mapeia para `['ds_email' => ..., 'password' => ...]` no `attempt()` (a chave `password` é especial no `EloquentUserProvider`: não vira coluna, é verificada via `getAuthPassword()`). O JWT usa só o `id` (`getJWTIdentifier`), que não muda.

**Tech Stack:** PHP 8.1, Laravel 10, `tymon/jwt-auth`, MySQL 8 (conexão `geral`), SQLite in-memory (testes), Blade + jQuery.

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

## 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 `php artisan migrate --path=database/migrations/geral` no fim — conferir antes como o projeto migra o geral).
- Testes: `php artisan test --filter=...` (SQLite). `DEPR ... PDO::MYSQL_ATTR_SSL_CA` é ruído.
- Tabela CAIXA ALTA; coluna minúscula com prefixo. Ficam: `id`, `created_at`, `updated_at`.
- **Fora do escopo (não renomear):** tabelas de infraestrutura do Laravel (`sessions` — inclusive `sessions.user_id` —, `jobs`, `job_batches`, `failed_jobs`, `password_reset_tokens` — inclusive a coluna `email` dela —, `migrations`, `personal_access_tokens`), e as demais tabelas do geral (`clientes`, `dicionario`, `termos_acesso`, `vendas_externas`, `translations`, `SC_CIDADE`).
- **Valores não mudam:** nomes de permissão (`nm_permissao` = `'Criar Bancos (Financeiro)'` etc., usados em `permission:X`), nomes de grupo, status.
- Nomes de relação Eloquent (`group`, `cliente`, `roles`, `groups`, `role`, `parent`...) e chaves JSON derivadas **não** mudam.
- Request/JSON: chave que espelha coluna renomeada é renomeada junto (payload/listagens das telas de Administrador > Usuários/Grupos, JSON do usuário logado consumido pelo JS), **exceto** os parâmetros de autenticação `email`/`password` de `api/auth/login`/`register`/Google (contrato externo). Chaves calculadas de `AuthController::permissoes()` (`pais`, `moeda`, lista de permissões...) ficam; se ela devolver campos do usuário que espelham coluna (`name`, `email`, `is_master`...), renomear e atualizar todo JS consumidor (`partials/scripts.blade.php`, `sidebar.blade.php`, menu/topbar, seletor de cliente master).
- **Migrations de seed de role antigas** (`database/migrations/geral/2026_*_seed_*`) não são editadas — rodam antes do rename. **Toda migration nova de seed de permissão escrita depois desta fase precisa usar `PERMISSAO`/`GRUPO_PERMISSAO`/colunas novas** — documentar com destaque.
- **Nunca** busque-e-substitua global por `name`/`email`/`status`/`code`/`client_id`/`group_id`: `client_id`/`group_id` aparecem em outras tabelas e em código morto; altere só onde o objeto é `User`/`Roles`/`Groups`/`GroupRole` ou as tabelas `users`/`roles`/`groups`/`group_roles`.

## Mapa desta fase

**`users` → `USUARIO`:** `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`

**`roles` → `PERMISSAO`:** `role_name`→`nm_permissao`, `role_description`→`ds_permissao`, `role_parent_id`→`id_permissao_pai`, `role_icon`→`ds_icone`, `role_status`→`fl_ativo`

**`groups` → `GRUPO`:** `group_name`→`nm_grupo`, `group_description`→`ds_grupo`, `group_status`→`fl_ativo`, `client_id`→`id_cliente`

**`group_roles` → `GRUPO_PERMISSAO`:** `group_id`→`id_grupo`, `role_id`→`id_permissao`, `group_role_status`→`fl_ativo`

**`people` (geral):** drop só se existir, estiver vazia e sem FK apontando (senão mantém e loga) — mesmo bloco seguro da fase 1.

---

### Task 1: Migration, models e testes de base

**Files:** Create `database/migrations/geral/2026_10_31_120000_rename_geral_auth_tables_to_portuguese.php`, `tests/Feature/Migrations/RenameGeralAuthTablesMigrationTest.php`, `tests/Feature/Auth/UsuarioModelTest.php`. Modify `app/Models/User.php`, `app/Models/Roles.php`, `app/Models/Groups.php`, `app/Models/GroupRole.php`, `app/Models/Cliente.php` (relações com users/groups por coluna), demais models com relação para `User` **por coluna de users** (as FKs `created_by` etc. de outras tabelas apontam para `users.id`, que não muda — só `$table`/relações inversas como `Cliente::users()` via `client_id`→`id_cliente`); schemas SQLite de `users`/`roles`/`groups`/`group_roles` nos testes (grep, inclusive `RefreshDatabase`/factories `database/factories/UserFactory.php`).
- `User`: `$table='USUARIO'`, fillable/hidden/casts com nomes novos (`'ds_senha' => 'hashed'`, `dt_email_verificado` datetime), `getAuthPassword()`, `getRememberTokenName()`, `getEmailForPasswordReset()`, `routeNotificationForMail()`, relações `cliente()` (`id_cliente`), `group()` (`id_grupo`), `hasRole()`/`permissionNames()`/`clienteDaRequisicao()` com colunas/tabelas novas, accessor de avatar (`ds_avatar`).
- [ ] Steps: teste da migration (4 tabelas com colunas do mapa, dados e vínculos preservados, `people` vazia dropada / com dado mantida, idempotente, down) → migration → `UsuarioModelTest` (criar usuário com `ds_senha` gera hash; `Auth::guard('api')->attempt(['ds_email'=>..,'password'=>..])` retorna token com o provider real — configurar `jwt.secret` no teste; `hasRole()` respeita `fl_ativo` de `GRUPO_PERMISSAO` e `PERMISSAO`; `permissionNames()`) → models → schemas dos testes com antes/depois.

### Task 2: Autenticação, middleware e RBAC

**Files:** `app/Http/Controllers/Api/AuthController.php` (login com mapeamento `email`→`ds_email`, Google login `User::where('ds_email', ...)`, `register` mantendo request `email`/`password` e gravando `ds_email`/`ds_senha`, `me`/`permissoes`/troca de cliente selecionado/avatar/termo), `app/Http/Middleware/AuthenticateCliente.php`, `app/Http/Middleware/CheckPermission.php`, demais middlewares/policies/gates que leem colunas de usuário, `app/Http/Controllers/Api/MasterClienteController.php`, `app/Services/ClienteProvisioningService.php` (cria usuário admin + grupo + vínculos `group_roles`), `app/Console/Commands/CreateCliente.php` e qualquer command que crie/leia usuário, `app/Http/Controllers/Api/TermoAcessoController.php`, `database/seeders/*` (usuários/roles), `config/auth.php` (só se precisar), `resources/views/partials/{scripts,sidebar,topbar,...}.blade.php` e `resources/views/login.blade.php` (só leituras de campos do usuário/permissões no JS; o POST de login continua `email`/`password`); teste `tests/Feature/Auth/LoginUsuarioTest.php` (login via HTTP `POST api/auth/login` com `email`/`password` devolve token; senha errada 401; `api/auth/permissoes` com o token devolve as permissões do grupo; master com `id_cliente_selecionado`).
- [ ] Steps: teste (RED) → implementar → GREEN → `view:cache`/`view:clear` → grep de sobras.

### Task 3: Administração de usuários e grupos + demais consumidores

**Files:** `app/Http/Controllers/Api/Administrador/{UsuarioController,GrupoController}.php` (regras `unique:users,email` → `unique:geral.USUARIO,ds_email`, listagens, payloads), `resources/views/administrador/{usuarios,usuariosFormulario,grupos,gruposFormulario}.blade.php`, `app/Services/Relatorios/{RelatorioPainelClienteService,RelatorioComercialService}.php`, `app/Http/Controllers/Api/Administracao/{JuridicoController,AgendamentoController}.php` (joins/consultas em `users`), `app/Services/FinancialReport/FinancialReportService.php` e `resources/views/bank-statements/index.blade.php` (o grep achou `groups` — confirmar se é a tabela ou outra coisa), qualquer `DB::connection('geral')->table('users'|'roles'|'groups'|'group_roles')`, `resources/lang/{pt,en,es}/validation.php` (rótulos `nm_usuario`, `ds_email`, `id_grupo`, `id_cliente`, `nm_grupo`, `ds_grupo`, `nm_permissao`...); teste `tests/Feature/Administrador/UsuarioGrupoAdminTest.php` (criar/editar usuário via controller com chaves novas e senha; e-mail duplicado → erro na chave nova; grupo com permissões grava `GRUPO_PERMISSAO`).
- `tests/Feature/Administrador/GrupoPermissoesTest.php` (5 falhas pré-existentes por falta de `roles` no schema) — atualizar o schema para as tabelas novas; se passar a funcionar com o schema completo, ótimo (complemento de fixture legítimo, sem mudar asserção).
- [ ] Steps: teste (RED) → implementar → GREEN → `view:cache` → grep.

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

- [ ] Varredura: `grep -rnE "['\"\`](users|roles|groups|group_roles)['\"\`. ]|\b(users|roles|groups|group_roles)\.[a-z_]+|unique:(geral\.)?users|exists:(geral\.)?(users|roles|groups)" app routes config database/seeders resources/views public/assets/js tests` e por `->(is_master|selected_client_id|role_name|role_status|group_role_status|group_name|role_parent_id)\b` / `->email\b`/`->password\b` sobre `User` — justificar sobras (`password_reset_tokens`, `sessions.user_id`, chaves de tradução, rotas, request de login `email`/`password`).
- [ ] Suíte: nenhuma falha nova contra `/tmp/claude-1000/-home-gabriel-public-html-cereusLote/417799b3-87ea-4940-8c90-587f7aceb22a/scratchpad/head-result.txt` (já sem as 4 de comissão).
- [ ] Docs: `.claude/CLAUDE.md` (todas as fases concluídas; seção Autenticação: login segue recebendo `email`/`password`, `User` sobrescreve `getAuthPassword`/`getRememberTokenName`/`getEmailForPasswordReset`/`routeNotificationForMail`; **aviso em destaque: migration de seed de permissão nova deve usar `PERMISSAO`/`GRUPO_PERMISSAO`/`nm_permissao`/`id_grupo`/`id_permissao`/`fl_ativo` e ser datada depois de `2026_10_31_120000`** — atualizar também o item "Seed de role nova: NUNCA conceda por contagem..." e a referência `2026_08_19_100000`), `.claude/rules/auth.md` (inteiro: nomes de tabela/coluna), `.claude/rules/backend.md`, `ActiveScope.php:15-16` comentário (já desatualizado desde a fase 5), spec (fases concluídas). Registrar tabelas do geral ainda em inglês/minúsculo fora do escopo (`translations`, `personal_access_tokens` mortas; `clientes`/`dicionario`/`termos_acesso`/`vendas_externas` em português minúsculo) como candidatas a uma rodada futura.
