Implementa o MVP do Adaptador de Planilhas no Elo Pro.

O módulo usa a identidade Supabase, isola cada workspace e registra storage, TTL, runner e biblioteca XLSX como decisões ainda abertas.

Co-authored-by: Cursor <cursoragent@cursor.com>

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

@@ -0,0 +1,185 @@
+# 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.