adaptador-planilhas/docs/cursor-prompts/spreadsheet-adapter/10-JOBS-PROCESSING-EXPORTS.md

PROMPT 10 — Jobs, processamento e geração de arquivos

Use o MASTER CONTEXT.

Objetivo

Implementar o processamento real de uma fonte mapeada para um novo arquivo baseado no modelo, preservando o original.

Ciclo do job

Defina estados explícitos e tipados, por exemplo: draft -> validating -> ready -> processing -> completed | failed | expired | cancelled Adapte ao padrão do repo sem perder clareza.

Regras

• job sempre pertence a workspace e usuário;
• validar novamente autorização e integridade no servidor antes de processar;
• uma mesma operação do usuário não executa duas transferências simultâneas;
• processamento deve ser idempotente para evitar cliques duplicados;
• múltiplas fontes na mesma jornada são processadas sequencialmente;
• o modelo original jamais é sobrescrito;
• saída é novo arquivo;
• mapping 1:1 e obrigatórias devem ser revalidados server-side;
• erros não devem expor conteúdo sensível.

Saídas

• XLSX;
• CSV;
• PDF via @react-pdf/renderer quando o formato fizer sentido para o resultado definido no produto.

Garanta compatibilidade de nomes, encoding, caracteres especiais e download autorizado.

Preservação de modelo

Se o requisito de “manter formatação do modelo” depender da biblioteca XLSX, escreva teste de não regressão e documente limitações reais. Não prometa preservação que a implementação não suporte.

Download

• autorização no momento do download;
• URL assinada/stream privado conforme storage;
• audit event relevante;
• temporário com expiração;
• nome de arquivo seguro e previsível.

Job runner

Se o repo já tiver fila/worker, use-o. Se não tiver e o processamento puder exceder timeout do runtime atual, não esconda o problema dentro de uma request longa: crie abstração/ADR e implemente somente solução aprovada.

Testes

• sucesso XLSX/CSV/PDF;
• modelo intacto;
• mapping inválido barrado;
• idempotência;
• dupla submissão;
• usuário/workspace indevido;
• caracteres especiais;
• erro de storage;
• retry seguro quando aplicável.