# 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. [x] Conferir branch atual e pendencias da URA.
   - `feat/URA-AI` estava limpa, sem mudancas rastreadas para commitar.
2. [x] Atualizar base e criar branch da sprint.
   - `main` estava atualizada com `origin/main`.
   - Branch `feat/export-data` criada a partir da `main`.
3. [x] Ler arquitetura relevante.
   - Validado pelas evidencias listadas acima.
4. [x] Criar spec/contexto SDD.
   - Criados `docs/export-data/SPEC.md` e este arquivo.
5. [x] 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. [x] Task 1 - Contexto e planejamento SDD.
2. [x] 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. [x] 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. [x] 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. [x] 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. [x] 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. [x] 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. [x] 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.