docs/export-data/CONTEXT.md

Contexto Exportacao de Dados

Voltar ao índiceMarkdown rawllms.txt

Public Markdown Document

Contexto Exportacao de Dados

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...

1384 palavras9 headingsdocs/

Contexto - Exportacao de Dados

Overview

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
oferecer a capacidade de forma transversal.

Branch da sprint: feat/export-data, criada a partir da main.

Estado atual: Sprint concluida na branch feat/export-data. Tasks 1 a 8
concluidas e notificadas no Task Board.

Decisoes Tomadas

  • O ponto principal da UI deve ser CoreDynamicCRUD, porque ele orquestra as
    views de tabela, lista, kanban, agenda, mapa e hibrida.
  • A API ja tem parsers ($parser=csv|yaml|markdown) em
    server/utils/api-parser.ts; CSV deve ser preservado e endurecido.
  • A sprint deve adicionar Excel e PDF como formatos reais de arquivo.
  • A exportacao deve reaproveitar a API dinamica e seus contratos de filtros,
    sort, app hint, data sources externos, computed fields e RBAC.
  • Configuracao por objeto deve ser feita em schema.ui_config.export, com
    defaults seguros quando ausente.
  • Tasks da sprint devem viver no Task Board (task_item), nao em arquivos de
    task separados.

Evidencias Lidas

  • docs/ura-ai/SPEC.md e docs/ura-ai/CONTEXT.md para seguir o modelo SDD.
  • task-board-app.json e scripts/seed-task-board.mjs para entender o
    taskboard como app/objeto task_item.
  • app/pages/[app]/[module]/[object]/index.vue para entender carregamento de
    schema, dados, filtros e app hint.
  • app/components/core/DynamicCRUD.vue para localizar action bar universal,
    view modes e eventos de CRUD/bulk.
  • app/components/core/DynamicTable.vue para entender DataTable, selecao,
    filtros e bulk toolbar.
  • server/api/v1/data/[app]/[object]/index.get.ts para entender listagem,
    data source externo/interno, RBAC, enrichment e parser.
  • server/utils/api-parser.ts e docs/api-parsers.md para mapear CSV atual.
  • server/utils/query-parser.ts para filtros, sort e limite.
  • server/api/v1/data/[app]/[object]/bulk.patch.ts e bulk.delete.ts para
    entender selected/query bulk flows.
  • server/utils/dynamic-db.ts, app/stores/appData.ts,
    server/utils/app-catalog.ts para confirmar Firestore como storage primario.

Estado das Tasks

Fase 0

  1. Conferir branch atual e pendencias da URA.
    • feat/URA-AI estava limpa, sem mudancas rastreadas para commitar.
  2. Atualizar base e criar branch da sprint.
    • main estava atualizada com origin/main.
    • Branch feat/export-data criada a partir da main.
  3. Ler arquitetura relevante.
    • Validado pelas evidencias listadas acima.
  4. Criar spec/contexto SDD.
    • Criados docs/export-data/SPEC.md e este arquivo.
  5. Criar cards no Task Board.
    • Criados registros task_item [Export Data] Task 1 ate Task 8.
    • Task 1 ficou em CONCLUIDA; Task 2 a Task 8 ficaram em
      BACKLOG.
    • Correcao em 2026-06-05: a primeira criacao foi feita direto no Firestore e
      usou app_origem_id: 16, entao nao passou pelo dispatcher nem casou com a
      regra de comunicado do app task-board (scope_app_id: 25). Os cards
      foram removidos e recriados com app_origem_id: 25; a regra ativa
      Teste Taskboard enviou notificacao por email para cada card criado.
    • Ajuste posterior em 2026-06-05: os templates de alerta de task_item
      passaram a incluir {{record.descricao}} no corpo do email. Tambem foram
      criadas regras de update para o app task-board com filtros de status
      TODO, EM_ANDAMENTO e CONCLUIDA.
    • Ajuste posterior em 2026-06-05: foi criada tambem a regra generica
      Alerta Taskboard - Update Generico, sem filtro de status, com assunto
      "Seu card foi atualizado". O endpoint de PATCH agora passa o registro
      anterior e os campos enviados ao dispatcher, permitindo usar
      {{record.__changes_summary}} no template para listar o que mudou.

Sprint feat/export-data

  1. Task 1 - Contexto e planejamento SDD.
  2. Task 2 - Contrato server-side de exportacao.
    • Movida para EM_ANDAMENTO em 2026-06-05. O update do card disparou a
      regra especifica Alerta Taskboard - Update EM ANDAMENTO e a regra
      generica Alerta Taskboard - Update Generico, validando o corpo com diff
      de status.
    • Movida para CONCLUIDA em 2026-06-05. O update do card disparou a regra
      especifica Alerta Taskboard - Update CONCLUIDA e a regra generica.
    • Implementado contrato inicial em
      server/api/v1/data/[app]/[object]/export.get.ts.
    • Criado utilitario server/utils/export-data.ts para config default,
      colunas exportaveis, filename, headers e serializacao CSV/JSON.
    • Default de formatos por objeto: csv, xlsx, pdf, json. Nesta task
      CSV/JSON ja respondem; XLSX/PDF retornam 501 com mensagem explicita e
      serao implementados na Task 3.
    • Testes adicionados em tests/api/export-data.spec.ts.
    • Validacao: npm run test:api passou. npm run build excedeu 120s e
      npx tsc --noEmit -p .nuxt/tsconfig.server.json nao rodou porque
      typescript nao esta instalado diretamente no projeto.
  3. Task 3 - Serializadores CSV/XLSX/PDF/JSON.
    • Movida para EM_ANDAMENTO em 2026-06-05. O update do card disparou a
      regra especifica Alerta Taskboard - Update EM ANDAMENTO e a regra
      generica Alerta Taskboard - Update Generico.
    • Movida para CONCLUIDA em 2026-06-05. O update do card disparou a regra
      especifica Alerta Taskboard - Update CONCLUIDA e a regra generica.
    • Instaladas dependencias exceljs, pdfkit e @types/pdfkit.
    • server/utils/export-data.ts agora serializa CSV, JSON, XLSX e PDF.
    • server/api/v1/data/[app]/[object]/export.get.ts responde os quatro
      formatos do contrato com headers de download.
    • Testes cobrem buffers XLSX/PDF, CSV com BOM/escape e JSON por colunas.
    • Validacao: npm run test:api passou com 3 arquivos e 11 testes.
      npm run build excedeu 300s.
  4. Task 4 - UI universal no CoreDynamicCRUD.
    • Movida para EM_ANDAMENTO em 2026-06-05. O update do card disparou a
      regra especifica Alerta Taskboard - Update EM ANDAMENTO e a regra
      generica Alerta Taskboard - Update Generico.
    • Implementado botao universal de exportacao no action bar do
      app/components/core/DynamicCRUD.vue, sem duplicar logica nas views
      filhas.
    • O menu respeita schema.ui_config.export.enabled e
      schema.ui_config.export.formats; quando ausente, todos os objetos
      continuam nascendo exportaveis com csv, xlsx, pdf e json.
    • O download usa /api/v1/data/:app/:object/export, preserva filtros atuais
      de route.query, fixedFilter e appHint, exibe loading e toasts de
      sucesso/erro.
    • Movida para CONCLUIDA em 2026-06-05. O update do card disparou a regra
      especifica Alerta Taskboard - Update CONCLUIDA e a regra generica.
    • Validacao: npm run test:api passou com 3 arquivos e 11 testes.
      npm run build voltou a exceder 300s.
  5. Task 5 - Escopos de exportacao.
    • Movida para EM_ANDAMENTO em 2026-06-05. O update do card disparou a
      regra especifica Alerta Taskboard - Update EM ANDAMENTO e a regra
      generica Alerta Taskboard - Update Generico.
    • O endpoint /api/v1/data/:app/:object/export agora entende
      scope=current_query|current_page|selected.
    • current_query exporta a consulta filtrada ignorando paginacao de tela e
      usando o limite seguro do schema.
    • current_page respeita $limit e $skip para baixar apenas a pagina
      visivel.
    • selected aceita ids string ou numericos, busca registros locais por ID
      sem depender do operador in do Firestore e valida o limite maximo antes
      de gerar arquivo.
    • O menu de exportacao do CoreDynamicCRUD ganhou controle compacto de
      escopo antes dos formatos, com suporte opcional a
      schema.ui_config.export.scopes.
    • Testes cobrem resolucao de escopos e IDs mistos. Validacao:
      npm run test:api passou com 3 arquivos e 12 testes.
      npm run build voltou a exceder 300s.
    • Movida para CONCLUIDA em 2026-06-05. O update do card disparou a regra
      especifica Alerta Taskboard - Update CONCLUIDA e a regra generica.
  6. Task 6 - Cobertura em CMS e views especiais.
    • Movida para EM_ANDAMENTO em 2026-06-05. O update do card disparou a
      regra especifica Alerta Taskboard - Update EM ANDAMENTO e a regra
      generica Alerta Taskboard - Update Generico.
    • Extraido o menu de exportacao para CoreExportDataButton, mantendo o
      mesmo comportamento do CoreDynamicCRUD e permitindo reuso por views que
      nao passam pelo CRUD universal.
    • CoreDynamicCRUD agora usa CoreExportDataButton em vez de manter a
      logica de exportacao embutida.
    • useCmsBinding passou a expor queryParams derivados dos filtros, sort,
      projection e limit configurados na secao CMS.
    • CoreCmsElementProxy ganhou exportacao para elementos de listagem como
      object_list_simple, object_list_integrated, object_kanban e
      object_schedule.
    • CoreCmsSectionObjectTable e CoreCmsSectionObjectList tambem ganharam o
      botao de exportacao no cabecalho, preservando filtros/sort da binding CMS.
    • Validacao: npm run test:api passou com 3 arquivos e 12 testes.
      npm run build voltou a exceder 300s.
    • Movida para CONCLUIDA em 2026-06-05. O update do card disparou a regra
      especifica Alerta Taskboard - Update CONCLUIDA e a regra generica.
  7. Task 7 - Testes e regressao.
    • Movida para EM_ANDAMENTO em 2026-06-05. O update do card disparou a
      regra especifica Alerta Taskboard - Update EM_ANDAMENTO e a regra
      generica Alerta Taskboard - Update Generico.
    • Extraido helper client-side app/utils/export-client.ts para tornar a
      montagem de query/download do CoreExportDataButton testavel sem DOM.
    • CoreExportDataButton passou a usar o helper client-side, reduzindo
      logica interna e preservando o comportamento visual.
    • Testes adicionados para formatos/escopos desabilitados, remocao de
      paginacao em current_query, pagina atual, selecionados, IDs de selecao e
      leitura de filename em Content-Disposition.
    • Validacao: npm run test:api passou com 3 arquivos e 16 testes.
      npm run build voltou a exceder 300s.
    • Movida para CONCLUIDA em 2026-06-05. O update do card disparou a regra
      especifica Alerta Taskboard - Update CONCLUIDA e a regra generica.
  8. Task 8 - Documentacao final e handoff.
    • Movida para EM_ANDAMENTO em 2026-06-05. O update do card disparou a
      regra especifica Alerta Taskboard - Update EM_ANDAMENTO e a regra
      generica Alerta Taskboard - Update Generico.
    • docs/api-parsers.md foi atualizado para documentar a diferenca entre
      parsers inline ($parser/$format) e endpoint de download /export.
    • docs/export-data/SPEC.md foi atualizado de Gate 1 para spec final da
      sprint, com decisoes fechadas, endpoint, configuracao JSON, arquivos de
      handoff e riscos restantes.
    • Este contexto foi atualizado para refletir conclusao completa da sprint.
    • Validacao final: npm run test:api deve permanecer com 3 arquivos e 16
      testes; npm run build permaneceu excedendo 300s durante a sprint.
    • Movida para CONCLUIDA em 2026-06-05. O update do card disparou a regra
      especifica Alerta Taskboard - Update CONCLUIDA e a regra generica.

Proximo Passo

Branch feat/export-data pronta para validacao manual e posterior merge para
main quando o usuario aprovar.

Prompt de Continuacao

Voce esta na branch feat/export-data. Antes de continuar:

  1. Leia docs/export-data/SPEC.md e este arquivo inteiro.
  2. Confira git status --short --branch.
  3. Abra o Task Board e confirme os cards Task 1 ate Task 8.
  4. Ao criar ou recriar cards do Task Board, use o fluxo da API/dispatcher ou
    dispare as regras de comunicado_config do app task-board; nao inserir
    direto no Firestore sem notificar.
  5. So implemente feature code depois da aprovacao do usuario.
  6. Sprint implementada em commits pequenos e cards movidos para CONCLUIDA.
  7. Antes de subir para main, validar manualmente os downloads CSV/XLSX/PDF/JSON
    nos escopos Consulta, Pagina e Selecionados em uma tela dinamica e em uma
    view CMS.