{"id":"docs/export-data/context","source":"docs","sourceLabel":"docs/","sourcePath":"docs/export-data/CONTEXT.md","routePath":"/fastapp/public-docs/page/docs/export-data/context","rawPath":"/fastapp/public-docs/raw/docs/export-data/context","slug":["docs","export-data","context"],"slugPath":"docs/export-data/context","title":"Contexto Exportacao de Dados","description":"Missao: adicionar exportacao/download de dados nas abas e views do FastApp que mostram registros de objetos. A feature deve respeitar o modelo do produto: apps sao definidos por JSON, objetos sao modulares e o runtime dinamico deve ofere...","headings":["Contexto Exportacao de Dados","Overview","Decisoes Tomadas","Evidencias Lidas","Estado das Tasks","Fase 0","Sprint feat/export data","Proximo Passo","Prompt de Continuacao"],"wordCount":1384,"markdown":"# Contexto - Exportacao de Dados\r\n\r\n## Overview\r\n\r\nMissao: adicionar exportacao/download de dados nas abas e views do FastApp que\r\nmostram registros de objetos. A feature deve respeitar o modelo do produto:\r\napps sao definidos por JSON, objetos sao modulares e o runtime dinamico deve\r\noferecer a capacidade de forma transversal.\r\n\r\nBranch da sprint: `feat/export-data`, criada a partir da `main`.\r\n\r\nEstado atual: Sprint concluida na branch `feat/export-data`. Tasks 1 a 8\r\nconcluidas e notificadas no Task Board.\r\n\r\n## Decisoes Tomadas\r\n\r\n- O ponto principal da UI deve ser `CoreDynamicCRUD`, porque ele orquestra as\r\n  views de tabela, lista, kanban, agenda, mapa e hibrida.\r\n- A API ja tem parsers (`$parser=csv|yaml|markdown`) em\r\n  `server/utils/api-parser.ts`; CSV deve ser preservado e endurecido.\r\n- A sprint deve adicionar Excel e PDF como formatos reais de arquivo.\r\n- A exportacao deve reaproveitar a API dinamica e seus contratos de filtros,\r\n  sort, app hint, data sources externos, computed fields e RBAC.\r\n- Configuracao por objeto deve ser feita em `schema.ui_config.export`, com\r\n  defaults seguros quando ausente.\r\n- Tasks da sprint devem viver no Task Board (`task_item`), nao em arquivos de\r\n  task separados.\r\n\r\n## Evidencias Lidas\r\n\r\n- `docs/ura-ai/SPEC.md` e `docs/ura-ai/CONTEXT.md` para seguir o modelo SDD.\r\n- `task-board-app.json` e `scripts/seed-task-board.mjs` para entender o\r\n  taskboard como app/objeto `task_item`.\r\n- `app/pages/[app]/[module]/[object]/index.vue` para entender carregamento de\r\n  schema, dados, filtros e app hint.\r\n- `app/components/core/DynamicCRUD.vue` para localizar action bar universal,\r\n  view modes e eventos de CRUD/bulk.\r\n- `app/components/core/DynamicTable.vue` para entender DataTable, selecao,\r\n  filtros e bulk toolbar.\r\n- `server/api/v1/data/[app]/[object]/index.get.ts` para entender listagem,\r\n  data source externo/interno, RBAC, enrichment e parser.\r\n- `server/utils/api-parser.ts` e `docs/api-parsers.md` para mapear CSV atual.\r\n- `server/utils/query-parser.ts` para filtros, sort e limite.\r\n- `server/api/v1/data/[app]/[object]/bulk.patch.ts` e `bulk.delete.ts` para\r\n  entender selected/query bulk flows.\r\n- `server/utils/dynamic-db.ts`, `app/stores/appData.ts`,\r\n  `server/utils/app-catalog.ts` para confirmar Firestore como storage primario.\r\n\r\n## Estado das Tasks\r\n\r\n### Fase 0\r\n\r\n1. [x] Conferir branch atual e pendencias da URA.\r\n   - `feat/URA-AI` estava limpa, sem mudancas rastreadas para commitar.\r\n2. [x] Atualizar base e criar branch da sprint.\r\n   - `main` estava atualizada com `origin/main`.\r\n   - Branch `feat/export-data` criada a partir da `main`.\r\n3. [x] Ler arquitetura relevante.\r\n   - Validado pelas evidencias listadas acima.\r\n4. [x] Criar spec/contexto SDD.\r\n   - Criados `docs/export-data/SPEC.md` e este arquivo.\r\n5. [x] Criar cards no Task Board.\r\n   - Criados registros `task_item` `[Export Data] Task 1` ate `Task 8`.\r\n   - `Task 1` ficou em `CONCLUIDA`; `Task 2` a `Task 8` ficaram em\r\n     `BACKLOG`.\r\n   - Correcao em 2026-06-05: a primeira criacao foi feita direto no Firestore e\r\n     usou `app_origem_id: 16`, entao nao passou pelo dispatcher nem casou com a\r\n     regra de comunicado do app `task-board` (`scope_app_id: 25`). Os cards\r\n     foram removidos e recriados com `app_origem_id: 25`; a regra ativa\r\n     `Teste Taskboard` enviou notificacao por email para cada card criado.\r\n   - Ajuste posterior em 2026-06-05: os templates de alerta de `task_item`\r\n     passaram a incluir `{{record.descricao}}` no corpo do email. Tambem foram\r\n     criadas regras de update para o app `task-board` com filtros de status\r\n     `TODO`, `EM_ANDAMENTO` e `CONCLUIDA`.\r\n   - Ajuste posterior em 2026-06-05: foi criada tambem a regra generica\r\n     `Alerta Taskboard - Update Generico`, sem filtro de status, com assunto\r\n     \"Seu card foi atualizado\". O endpoint de PATCH agora passa o registro\r\n     anterior e os campos enviados ao dispatcher, permitindo usar\r\n     `{{record.__changes_summary}}` no template para listar o que mudou.\r\n\r\n### Sprint `feat/export-data`\r\n\r\n1. [x] Task 1 - Contexto e planejamento SDD.\r\n2. [x] Task 2 - Contrato server-side de exportacao.\r\n   - Movida para `EM_ANDAMENTO` em 2026-06-05. O update do card disparou a\r\n     regra especifica `Alerta Taskboard - Update EM ANDAMENTO` e a regra\r\n     generica `Alerta Taskboard - Update Generico`, validando o corpo com diff\r\n     de status.\r\n   - Movida para `CONCLUIDA` em 2026-06-05. O update do card disparou a regra\r\n     especifica `Alerta Taskboard - Update CONCLUIDA` e a regra generica.\r\n   - Implementado contrato inicial em\r\n     `server/api/v1/data/[app]/[object]/export.get.ts`.\r\n   - Criado utilitario `server/utils/export-data.ts` para config default,\r\n     colunas exportaveis, filename, headers e serializacao CSV/JSON.\r\n   - Default de formatos por objeto: `csv`, `xlsx`, `pdf`, `json`. Nesta task\r\n     CSV/JSON ja respondem; XLSX/PDF retornam `501` com mensagem explicita e\r\n     serao implementados na Task 3.\r\n   - Testes adicionados em `tests/api/export-data.spec.ts`.\r\n   - Validacao: `npm run test:api` passou. `npm run build` excedeu 120s e\r\n     `npx tsc --noEmit -p .nuxt/tsconfig.server.json` nao rodou porque\r\n     `typescript` nao esta instalado diretamente no projeto.\r\n3. [x] Task 3 - Serializadores CSV/XLSX/PDF/JSON.\r\n   - Movida para `EM_ANDAMENTO` em 2026-06-05. O update do card disparou a\r\n     regra especifica `Alerta Taskboard - Update EM ANDAMENTO` e a regra\r\n     generica `Alerta Taskboard - Update Generico`.\r\n   - Movida para `CONCLUIDA` em 2026-06-05. O update do card disparou a regra\r\n     especifica `Alerta Taskboard - Update CONCLUIDA` e a regra generica.\r\n   - Instaladas dependencias `exceljs`, `pdfkit` e `@types/pdfkit`.\r\n   - `server/utils/export-data.ts` agora serializa CSV, JSON, XLSX e PDF.\r\n   - `server/api/v1/data/[app]/[object]/export.get.ts` responde os quatro\r\n     formatos do contrato com headers de download.\r\n   - Testes cobrem buffers XLSX/PDF, CSV com BOM/escape e JSON por colunas.\r\n   - Validacao: `npm run test:api` passou com 3 arquivos e 11 testes.\r\n     `npm run build` excedeu 300s.\r\n4. [x] Task 4 - UI universal no CoreDynamicCRUD.\r\n   - Movida para `EM_ANDAMENTO` em 2026-06-05. O update do card disparou a\r\n     regra especifica `Alerta Taskboard - Update EM ANDAMENTO` e a regra\r\n     generica `Alerta Taskboard - Update Generico`.\r\n   - Implementado botao universal de exportacao no action bar do\r\n     `app/components/core/DynamicCRUD.vue`, sem duplicar logica nas views\r\n     filhas.\r\n   - O menu respeita `schema.ui_config.export.enabled` e\r\n     `schema.ui_config.export.formats`; quando ausente, todos os objetos\r\n     continuam nascendo exportaveis com `csv`, `xlsx`, `pdf` e `json`.\r\n   - O download usa `/api/v1/data/:app/:object/export`, preserva filtros atuais\r\n     de `route.query`, `fixedFilter` e `appHint`, exibe loading e toasts de\r\n     sucesso/erro.\r\n   - Movida para `CONCLUIDA` em 2026-06-05. O update do card disparou a regra\r\n     especifica `Alerta Taskboard - Update CONCLUIDA` e a regra generica.\r\n   - Validacao: `npm run test:api` passou com 3 arquivos e 11 testes.\r\n     `npm run build` voltou a exceder 300s.\r\n5. [x] Task 5 - Escopos de exportacao.\r\n   - Movida para `EM_ANDAMENTO` em 2026-06-05. O update do card disparou a\r\n     regra especifica `Alerta Taskboard - Update EM ANDAMENTO` e a regra\r\n     generica `Alerta Taskboard - Update Generico`.\r\n   - O endpoint `/api/v1/data/:app/:object/export` agora entende\r\n     `scope=current_query|current_page|selected`.\r\n   - `current_query` exporta a consulta filtrada ignorando paginacao de tela e\r\n     usando o limite seguro do schema.\r\n   - `current_page` respeita `$limit` e `$skip` para baixar apenas a pagina\r\n     visivel.\r\n   - `selected` aceita `ids` string ou numericos, busca registros locais por ID\r\n     sem depender do operador `in` do Firestore e valida o limite maximo antes\r\n     de gerar arquivo.\r\n   - O menu de exportacao do `CoreDynamicCRUD` ganhou controle compacto de\r\n     escopo antes dos formatos, com suporte opcional a\r\n     `schema.ui_config.export.scopes`.\r\n   - Testes cobrem resolucao de escopos e IDs mistos. Validacao:\r\n     `npm run test:api` passou com 3 arquivos e 12 testes.\r\n     `npm run build` voltou a exceder 300s.\r\n   - Movida para `CONCLUIDA` em 2026-06-05. O update do card disparou a regra\r\n     especifica `Alerta Taskboard - Update CONCLUIDA` e a regra generica.\r\n6. [x] Task 6 - Cobertura em CMS e views especiais.\r\n   - Movida para `EM_ANDAMENTO` em 2026-06-05. O update do card disparou a\r\n     regra especifica `Alerta Taskboard - Update EM ANDAMENTO` e a regra\r\n     generica `Alerta Taskboard - Update Generico`.\r\n   - Extraido o menu de exportacao para `CoreExportDataButton`, mantendo o\r\n     mesmo comportamento do `CoreDynamicCRUD` e permitindo reuso por views que\r\n     nao passam pelo CRUD universal.\r\n   - `CoreDynamicCRUD` agora usa `CoreExportDataButton` em vez de manter a\r\n     logica de exportacao embutida.\r\n   - `useCmsBinding` passou a expor `queryParams` derivados dos filtros, sort,\r\n     projection e limit configurados na secao CMS.\r\n   - `CoreCmsElementProxy` ganhou exportacao para elementos de listagem como\r\n     `object_list_simple`, `object_list_integrated`, `object_kanban` e\r\n     `object_schedule`.\r\n   - `CoreCmsSectionObjectTable` e `CoreCmsSectionObjectList` tambem ganharam o\r\n     botao de exportacao no cabecalho, preservando filtros/sort da binding CMS.\r\n   - Validacao: `npm run test:api` passou com 3 arquivos e 12 testes.\r\n     `npm run build` voltou a exceder 300s.\r\n   - Movida para `CONCLUIDA` em 2026-06-05. O update do card disparou a regra\r\n     especifica `Alerta Taskboard - Update CONCLUIDA` e a regra generica.\r\n7. [x] Task 7 - Testes e regressao.\r\n   - Movida para `EM_ANDAMENTO` em 2026-06-05. O update do card disparou a\r\n     regra especifica `Alerta Taskboard - Update EM_ANDAMENTO` e a regra\r\n     generica `Alerta Taskboard - Update Generico`.\r\n   - Extraido helper client-side `app/utils/export-client.ts` para tornar a\r\n     montagem de query/download do `CoreExportDataButton` testavel sem DOM.\r\n   - `CoreExportDataButton` passou a usar o helper client-side, reduzindo\r\n     logica interna e preservando o comportamento visual.\r\n   - Testes adicionados para formatos/escopos desabilitados, remocao de\r\n     paginacao em `current_query`, pagina atual, selecionados, IDs de selecao e\r\n     leitura de filename em `Content-Disposition`.\r\n   - Validacao: `npm run test:api` passou com 3 arquivos e 16 testes.\r\n     `npm run build` voltou a exceder 300s.\r\n   - Movida para `CONCLUIDA` em 2026-06-05. O update do card disparou a regra\r\n     especifica `Alerta Taskboard - Update CONCLUIDA` e a regra generica.\r\n8. [x] Task 8 - Documentacao final e handoff.\r\n   - Movida para `EM_ANDAMENTO` em 2026-06-05. O update do card disparou a\r\n     regra especifica `Alerta Taskboard - Update EM_ANDAMENTO` e a regra\r\n     generica `Alerta Taskboard - Update Generico`.\r\n   - `docs/api-parsers.md` foi atualizado para documentar a diferenca entre\r\n     parsers inline (`$parser`/`$format`) e endpoint de download `/export`.\r\n   - `docs/export-data/SPEC.md` foi atualizado de Gate 1 para spec final da\r\n     sprint, com decisoes fechadas, endpoint, configuracao JSON, arquivos de\r\n     handoff e riscos restantes.\r\n   - Este contexto foi atualizado para refletir conclusao completa da sprint.\r\n   - Validacao final: `npm run test:api` deve permanecer com 3 arquivos e 16\r\n     testes; `npm run build` permaneceu excedendo 300s durante a sprint.\r\n   - Movida para `CONCLUIDA` em 2026-06-05. O update do card disparou a regra\r\n     especifica `Alerta Taskboard - Update CONCLUIDA` e a regra generica.\r\n\r\n## Proximo Passo\r\n\r\nBranch `feat/export-data` pronta para validacao manual e posterior merge para\r\n`main` quando o usuario aprovar.\r\n\r\n## Prompt de Continuacao\r\n\r\nVoce esta na branch `feat/export-data`. Antes de continuar:\r\n\r\n1. Leia `docs/export-data/SPEC.md` e este arquivo inteiro.\r\n2. Confira `git status --short --branch`.\r\n3. Abra o Task Board e confirme os cards `Task 1` ate `Task 8`.\r\n4. Ao criar ou recriar cards do Task Board, use o fluxo da API/dispatcher ou\r\n   dispare as regras de `comunicado_config` do app `task-board`; nao inserir\r\n   direto no Firestore sem notificar.\r\n5. So implemente feature code depois da aprovacao do usuario.\r\n6. Sprint implementada em commits pequenos e cards movidos para `CONCLUIDA`.\r\n7. Antes de subir para `main`, validar manualmente os downloads CSV/XLSX/PDF/JSON\r\n   nos escopos Consulta, Pagina e Selecionados em uma tela dinamica e em uma\r\n   view CMS.\r\n"}