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>
2026-10-02 23:02:00 -03:00
commit 6e23f1533b
@@ -0,0 +1,40 @@
+# Fundação, rotas e feature flag
+
+## Rotas de página
+
+- `/login` redireciona ao login central (`ELO_PRO_LOGIN_URL`) ou, só fora de produção, oferece identidades locais sem senha
+- `/adaptador` dashboard
+- `/adaptador/operacao` jornada
+- `/adaptador/configuracoes` somente owner/admin
+
+`loading.tsx` e `error.tsx` cobrem espera e falha recuperável. Sem sessão, o proxy manda para `/login`. Sem a flag `spreadsheet_adapter`, a página informa que o módulo está desligado e as APIs respondem `FEATURE_DISABLED`.
+
+## APIs
+
+- `GET/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`
+- `PUT /api/spreadsheet-adapter/jobs/:id/mappings`
+- `POST /api/spreadsheet-adapter/jobs/:id/preview`
+- `POST /api/spreadsheet-adapter/jobs/:id/process`
+- `PATCH/DELETE /api/spreadsheet-adapter/jobs/:id/sources/:sourceId`
+- `GET /api/spreadsheet-adapter/jobs/:id/download?format=xlsx|csv|pdf&sourceId=`
+
+O `workspace_id` do corpo é ignorado como tenant. Se vier diferente da sessão, a chamada é negada e auditada.
+
+## Códigos de erro estáveis
+
+`UNAUTHENTICATED`, `WORKSPACE_FORBIDDEN`, `FEATURE_DISABLED`, `FORBIDDEN`, `TOO_MANY_MODELS`, `DUPLICATE_MODEL_NAME`, `TOO_MANY_SOURCES`, `FILE_TOO_LARGE`, `TOO_MANY_ROWS`, `UNSUPPORTED_FORMAT`, `MIME_MISMATCH`, `INVALID_STRUCTURE`, `ZIP_BOMB`, `EMPTY_HEADER`, `DUPLICATE_HEADER`, `HEADER_ROW_INVALID`, `SHEET_REQUIRED`, `TYPE_INCONSISTENT`, `MAPPING_CONFLICT`, `MAPPING_INCOMPLETE`, `MAPPING_UNKNOWN`, `MODEL_IN_USE`, `JOB_LOCKED`, `REDIS_UNAVAILABLE`, `MODEL_TAMPERED`, `NOT_FOUND`.
+
+## Contratos
+
+Upload de modelo: `multipart` com `file`, `name`, `sheet` opcional, `headerRow`, `requiredColumns` (JSON). Sem `requiredColumns`, todas as colunas nascem obrigatórias e a tela permite desmarcar.
+
+Validação de fonte: `file`, `jobId`, `sheet`, `headerRow`. Várias abas devolvem `409 SHEET_REQUIRED` com a fonte já armazenada para troca de aba sem novo upload. Tipo misto devolve `422` e preserva as outras fontes.
+
+Prévia: `{ preview: true, columns, rows, rowCount, truncated }`. Colunas na ordem do modelo. Não grava saída nem altera o modelo.
+
+Temporários: `expires_at = agora + SPREADSHEET_TEMP_TTL_SECONDS`. Em produção a variável é obrigatória. Fora de produção, a ausência usa 3600 segundos apenas como apoio de desenvolvimento, não como política de produto.