Arquitetura e histórico da consolidação dos painéis /admin e /manager em um único sistema baseado em Supabase Auth, com CMS headless nativo no Next.js.

Unificação do Painel Administrativo

Status: Concluído (Sprints 1–9)
Versão: 2.0
Atualizado: 2026-06-26
Responsável: Kaique Yamamoto

Arquitetura vigente: monólito Next.js 16 → Supabase (Postgres + Auth + Storage). Go API removida. Documentação técnica BMAD no repositório: docs/index.md · ADR: docs/adr/0001-unificacao-painel-administrativo.md.

Estado Atual (pós-unificação)

Componente	Rota	Auth	Papel
Manager (oficial)	`/manager`	Supabase Auth + `MANAGER_ADMIN_EMAILS`	Shell unificado — dashboard, CRUD, trilhas, métricas, mercado financeiro
CMS Admin (legado)	`/admin`	JWT (`jose` + `cms_users`)	Depreciado — redireciona para `/manager` quando `NEXT_PUBLIC_USE_UNIFIED_ADMIN=true`
CMS API (headless)	`/cms/*` (46 handlers)	JWT Bearer	CRUD nativo Next.js — usado pelo shell e por integrações

Feature flag

NEXT_PUBLIC_USE_UNIFIED_ADMIN=true

Com a flag ativa, src/proxy.ts redireciona /admin/* → /manager/* (mapeamento de entidades, mercado financeiro, login).

O que foi entregue (Sprints 1–9)

Sprint 1: ADR 0001, decisões de auth, documentação base.
Sprint 2: Login unificado Supabase Auth, shell comum, sidebar rico, ManagerNav.
Sprint 3: CRUD rico FII/ETF/Ativo/Glossário (KVFieldArray, revisions, publish).
Sprint 4: Produtos, pedidos, RevenueCard.
Sprint 5: Mídia (MediaGallery, upload Supabase Storage bucket media).
Sprint 6: Editor MDX, preview tokens, ISR via /api/revalidate.
Sprint 7: Usuários CMS, audit log, stats/timeseries.
Sprint 8: Editor de Trilhas YouTube (/manager/trilhas), métricas (/manager/metricas).
Sprint 9: Redirects /admin → /manager, testes E2E, docs sincronizadas.

Mercado financeiro: consulta de artefatos (análise + detecção de atualizações + marcar) em /manager/mercado-financeiro/analise e /manager/mercado-financeiro/atualizar.

Contexto Original (pré-unificação)

Antes da unificação (2026-06), o projeto mantinha dois painéis independentes:

CMS Admin (/admin + /cms/*): JWT custom (cms_users/cms_sessions), editor MDX, mídia, revenue, audit, revisions, preview. Herdado da migração Go → Next.js (2026-04).
Manager (/manager): Supabase Auth, EntityTable genérico, trilhas YouTube, pageviews.

Problemas resolvidos: duplicação de CRUD, dois sistemas de identidade, features fragmentadas, experiência confusa para o administrador.

Decisão Arquitetural

/manager (Supabase Auth) é o painel oficial. Funcionalidades avançadas do CMS Admin foram portadas para o shell unificado.

Preservado	Removido / depreciado
KV arrays, MDX editor, mídia, revenue, audit	Login JWT em `/admin/login` (redirect)
Editor de Trilhas YouTube	Navegação duplicada entre painéis
RLS + service_role	Dependência de Go API (removida 2026-06-26)

Roles: super_admin | editor | viewer — via Supabase Auth app_metadata.role + allowlist.

Stack Técnica do CMS

Browser (/manager ou /admin legado)
    │
    ├── Supabase Auth (cookies SSR) ──► /manager/*
    │
    └── fetch /cms/* (JWT Bearer) ──► src/app/cms/** (46 route handlers)
              │
              └── src/lib/cms/* ──► Supabase Postgres (cms_*, fiis, etfs, …)

Módulo	Arquivo	Responsabilidade
Auth CMS	`src/lib/cms/auth.ts`	JWT HS256, bcrypt, refresh em `cms_sessions`
CRUD	`src/lib/cms/content.ts`	Entidades + publish/unpublish + revisions
Páginas MDX	`src/lib/cms/pages.ts`	`cms_mdx_pages` + revalidatePath
Mídia	`src/lib/cms/media.ts`	Upload, bucket `media`
Cliente browser	`src/lib/cms-api.ts`	Fetch tipado + refresh interceptor
Manager	`src/lib/manager/*`	Auth, entities registry, métricas, trilhas

Tabelas CMS: migration 0003_cms.sql + RLS em 0004_rls_ttl.sql. Schema completo: docs/data-models-frontend.md.

Rotas do Manager

Rota	Função
`/manager/login`	Login Supabase Auth
`/manager/dashboard`	Dashboard principal
`/manager/[entity]`	CRUD genérico (fiis, etfs, ativos, glossarios, products, orders…)
`/manager/trilhas`	Editor YouTube (`youtube_modules`/`youtube_videos`)
`/manager/metricas`	Pageviews (`page_views`)
`/manager/mercado-financeiro/analise`	Consulta artefatos + detecção de desatualização
`/manager/mercado-financeiro/atualizar`	Marcar artefatos como atualizados

Variáveis de Ambiente

Variável	Papel
`NEXT_PUBLIC_SUPABASE_URL`	Projeto Supabase
`NEXT_PUBLIC_SUPABASE_ANON_KEY`	Auth browser/SSR
`SUPABASE_SERVICE_ROLE_KEY`	CRUD server-side
`MANAGER_ADMIN_EMAILS`	Allowlist emails do painel
`NEXT_PUBLIC_USE_UNIFIED_ADMIN`	Redirect `/admin` → `/manager`
`JWT_SECRET`	CMS JWT + magic-link comprador
`CMS_SEED_EMAIL` / `CMS_SEED_PASSWORD`	Seed super_admin
`MEDIA_STORAGE` / `MEDIA_BUCKET`	Storage mídia (`supabase` recomendado)

Manutenção e Referências

Contratos API: docs/api-contracts-backend.md (CMS) + docs/api-contracts-frontend.md (/api/*)
ADR: docs/adr/0001-unificacao-painel-administrativo.md
Componentes UI: src/components/admin/ (shell, forms, dashboard) — reutilizados no Manager
Testes: Vitest (src/lib/cms/*.test.ts) + Playwright (tests/admin-dashboard.spec.ts)

Pendências conhecidas

Rotas /cms/* ainda ativas (API headless) — remoção total depende de migrar 100% dos clientes para Server Actions do Manager.
useCMSAuth e links em cms-api.ts ainda referenciam paths /admin/* (redirect cobre com flag ativa).
cms_users coexiste com Supabase Auth — migração de perfis pode unificar em admin_profiles no futuro.

Este documento vive em content/docs/arquitetura-software/administracao-cms/index.mdx e reflete o estado pós-unificação (2026-06-26).

Unificação do Painel Administrativo

On this page