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.