adaptador-planilhas/docs/cursor-prompts/spreadsheet-adapter/01-MASTER-CONTEXT.md

MASTER CONTEXT — Adaptador de Planilhas Elo Pro

Use este contexto em todas as etapas de implementação.

Papel do agente

Você está implementando um módulo de produção dentro do ecossistema Elo Pro. Trabalhe como engenheiro sênior full-stack. Antes de alterar código, inspecione padrões existentes no repositório e reutilize-os. Não crie subsistemas paralelos de autenticação, autorização, design system, auditoria, observabilidade, feature flags ou acesso ao Supabase quando já houver equivalentes.

Objetivo do produto

O Adaptador recebe planilhas de origens diferentes, valida sua estrutura, mapeia colunas manualmente para um modelo padronizado, mostra uma prévia do resultado e gera um novo arquivo consolidado sem alterar o modelo original.

Fluxo principal:

Elo Pro autenticado -> Adaptador -> selecionar modelo -> carregar fonte(s) -> selecionar aba/cabeçalho quando necessário -> validar -> mapear -> revisar -> processar -> acompanhar progresso -> baixar -> continuar com outra fonte ou encerrar.

Identidade e login — regra inegociável

• O Adaptador NÃO possui login próprio.
• O Adaptador NÃO possui cadastro de senha, hash de senha, refresh token proprietário ou tabela própria de usuários.
• Use o mesmo Supabase Auth do Elo Pro.
• Use o mesmo auth.users, profiles, workspace_members, clientes Supabase SSR/server/browser e fluxo de logout já existentes.
• Ao entrar no módulo, valide sessão, workspace ativo, membership e habilitação do módulo.
• Ausência de sessão deve seguir o fluxo central de autenticação Elo Pro.
• Logout encerra a sessão Elo Pro.
• A meta é uma identidade/uma senha para vários apps do ecossistema. Não copie usuários entre bancos e não crie credenciais duplicadas.

Tenant e autorização

• Tenant técnico: workspace_id.
• Toda persistência do módulo deve ser isolada por workspace.
• RLS é obrigatória quando aplicável.
• Não aceite workspace_id do cliente como verdade. Derive/valide no servidor conforme padrão Elo Pro.
• Papéis operacionais: owner, admin, gestor, agent conforme modelo existente.
• owner/admin: gestão de modelos e configurações.
• gestor/agent: fluxo operacional. Upload de modelo só se configuração específica permitir.
• superadmin: permanece mecanismo de plataforma já existente, auditado; não crie modo especial dentro do Adaptador.
• Segurança deve existir no servidor/banco. Esconder botão no frontend é apenas UX.

Regras de negócio do MVP

• Até 10 modelos ativos por workspace.
• Nome lógico de modelo único dentro do workspace; sem versionamento automático no MVP.
• Entradas suportadas: XLSX e CSV.
• XLS, ODS e XML ficam fora do MVP.
• Fonte: até 10 MB e 50.000 linhas úteis por arquivo.
• Até 10 fontes por operação/jornada.
• XLSX pode ter múltiplas abas, mas exatamente uma aba é selecionada/processada por fonte em cada execução.
• Permitir seleção da linha de cabeçalho quando necessário.
• Toda coluna utilizada precisa ter cabeçalho identificável.
• Detectar inconsistências relevantes de tipo por coluna e impedir processamento inválido; não corrigir automaticamente.
• Mapeamento manual 1:1: uma coluna fonte -> no máximo uma coluna modelo e vice-versa.
• Todas as colunas obrigatórias do modelo devem estar mapeadas.
• Mapeamento não vira template reutilizável no MVP.
• Deve existir etapa de pré-visualização antes do processamento.
• Uma operação do usuário não executa duas transferências concorrentes.
• Modelo persistido é imutável durante transformação. Saída é sempre novo artefato.
• Modelos são persistentes. Fontes e saídas são temporárias, sujeitas a TTL.
• Exclusão de modelo exige confirmação, só owner/admin, e é bloqueada se houver processamento ativo usando o modelo.
• Configuração por workspace pode permitir/bloquear upload de modelo por perfis não administrativos. Isso não concede exclusão/gestão geral.
• Auditar upload/exclusão de modelo, alteração de configuração, início/fim/erro de processamento e downloads relevantes, sem registrar conteúdo de células.
• Sem fórmulas, normalização semântica, conversão de moeda/data, enriquecimento ou junção simultânea de fontes no MVP.

Stack obrigatória

Frontend:

• Next.js 16, App Router
• React 19
• TypeScript 5
• Tailwind CSS v4
• Lucide React
• @dnd-kit para drag and drop acessível
• TanStack Query v5 para estado remoto/cache
• @react-pdf/renderer para PDF

Backend/infra:

• Supabase Auth + PostgreSQL com @supabase/supabase-js e @supabase/ssr
• Redis via ioredis
• Sentry client/server/edge
• postgres + tsx para migrations/ETL onde esse for o padrão do repositório

IA:

• @anthropic-ai/sdk pode existir na stack, mas não participa do caminho crítico do MVP.

Qualidade:

• Vitest
• ESLint 9
• typecheck estrito conforme padrão do monorepo/repo

UX/UI — EloPro Design System Global V2.1

O Adaptador não cria Design System próprio.

• Interface predominantemente clara.
• Cloud White #FBFBFE: base.
• Midnight Ink #071B45: texto/estrutura.
• Action/Primary Blue: ações principais conforme token oficial do repo.
• Bright Blue #2F8FFF: foco/hover/ativos quando previsto.
• Aqua Signal #00C2A8: sucesso, continuidade e progresso.
• Warning #F39A2D.
• Error #E63946, sempre com texto/ícone; nunca cor isolada.
• Tipografia operacional: Manrope.
• Espaçamento base: 4px.
• Reutilize componentes oficiais: Button, IconButton, Card/OpenFramePanel, Input, Select, Checkbox, Radio, Switch, Dialog, Toast, Tooltip, Tabs/CapsuleTabs, SemanticMarker, JourneyTrail quando semanticamente adequado.
• Lucide React para ícones.
• Drag-and-drop precisa ter alternativa via teclado/select.
• Estados obrigatórios: loading/skeleton, empty, disabled, error recuperável e success.
• Não use fluxogramas antigos como referência visual; eles são referência funcional.

Modelo de dados proposto

Adapte nomes/convenções ao repo, mantendo semântica:

• spreadsheet_adapter_settings

  • workspace_id PK/FK
  • allow_non_admin_model_upload
  • timestamps

• spreadsheet_models

  • id, workspace_id, name, original_filename, format, storage_key
  • sheet_name, header_row, columns_schema jsonb
  • created_by, created_at, status

• spreadsheet_jobs

  • id, workspace_id, user_id, model_id, status
  • source_count, current_source, output_format, progress
  • error_code, started_at, finished_at, created_at

• spreadsheet_job_sources

  • id, job_id, source_name, temp_storage_key
  • selected_sheet, header_row, row_count, size_bytes, status, expires_at

• spreadsheet_job_mappings

  • id, job_source_id, source_column, model_column, is_required, position

• Reuse audit_log existente quando compatível.

Rotas sugeridas

Adapte ao padrão existente do Elo Pro:

• GET /api/spreadsheet-adapter/models
• POST /api/spreadsheet-adapter/models
• DELETE /api/spreadsheet-adapter/models/:id
• GET/PATCH /api/spreadsheet-adapter/settings
• POST /api/spreadsheet-adapter/sources/validate
• POST /api/spreadsheet-adapter/jobs
• GET /api/spreadsheet-adapter/jobs/:id
• POST /api/spreadsheet-adapter/jobs/:id/process
• GET /api/spreadsheet-adapter/jobs/:id/download?format=xlsx|csv|pdf

Server Actions podem substituir rotas quando o padrão Elo Pro indicar, desde que contratos de segurança, teste e idempotência permaneçam claros.

Pendências que NÃO devem ser inventadas

Se o repo não trouxer uma decisão, pare e documente a alternativa recomendada em vez de “decidir silenciosamente”:

1. Object storage definitivo: Supabase Storage privado ou equivalente S3.
2. Topologia de login único entre hosts/domínios.
3. Job runner durável para processamentos que possam exceder request timeout.
4. TTL exato de fontes/saídas temporárias.
5. Biblioteca XLSX de produção (licença, segurança, manutenção, preservação de formatação).
6. Exclusão física vs soft delete de modelos.

Segurança mínima

• RLS e checagem server-side contra IDOR.
• Validar extensão, MIME e assinatura/estrutura do arquivo.
• Proteger contra path traversal e nomes maliciosos.
• Tratar CSV injection em exportações quando relevante.
• Nunca logar conteúdo de célula no Sentry/audit log.
• Não enviar planilha ao Anthropic no MVP.
• Storage privado; download somente após autorização.
• Sanitizar nomes e metadados exibidos.

Definição de pronto geral

Uma etapa só está concluída quando:

• implementação segue padrões existentes do Elo Pro;
• lint/typecheck passam;
• testes da etapa passam;
• segurança de workspace/permissões foi coberta;
• estados de UX relevantes existem;
• nenhuma nova autenticação paralela foi criada;
• mudanças e decisões abertas estão documentadas.