Document View
Overview
The Document view is a document library for a feature: a master-detail layout with an explorer panel (grouping tree) on the left, document cards in the middle, and a preview panel on the right. It covers uploading (file picker or mobile camera scan), previewing, downloading, organising via drag-and-drop, bulk operations, and AI structured extraction.
On narrow screens (<600px) the explorer collapses into a drawer and selecting a document swaps the body to the preview.
Explorer (grouping)
The explorer groups documents along one axis. The chosen axis, collapsed nodes, and active folder are all saved per user per view and sync across devices.
| Axis | Groups by | Accepts drag-drop |
|---|---|---|
| Coluna | Up to 3 nested columns, building a category tree | Yes — moves the document into the dropped folder |
| Tipo | File type (PDF, imagem, …) — derived | No |
| Data | Upload month — derived | No |
| Estado | AI staging state (Por processar, Pendente, A processar, Em staging, Rascunho, Validado, Duplicado, Importado, Ignorado, Erro) — only shown when an AI workflow is configured | No |
Dragging a card onto a Coluna node updates the row's column values to match the full folder path (all levels). When the move would push the document out of the view's currently active filter (the same column/search filters the view applies, evaluated by the filter engine — not the explorer folder), a 5-second snackbar appears with an Anular (undo) action — the filter itself is never changed.
The explorer has its own search field to filter the folder list by name; this is separate from the main document search.
Breadcrumb
When a folder is active, a breadcrumb bar appears above the document cards showing the full active path, for example:
Todos os documentos › Categoria A › Sub-categoria B
Clicking Todos os documentos clears the active folder and shows all documents.
Layout and persisted preferences
On wide screens the three panels (explorer, cards, preview) are separated by draggable splitters. You can:
- Resize the explorer (left) and preview (right) panels by dragging their borders.
- Hide or show either panel using the toggle buttons in the header.
All of these — panel widths, whether each panel is visible, the chosen grouping axis, and the sort order — are saved per user per view and follow you across devices.
Uploading documents
Upload is always available from the header (not only on the empty state):
- Carregar — opens the file picker (multiple files allowed; restricted by Allowed extensions when configured). Each file becomes a new record with the file mapped to the view's document column.
- Digitalizar (Android/iOS only) — scans pages with the camera:
- One page → ingested immediately as one record.
- Multiple pages → a grouping dialog opens. Consecutive pages belong to the same document; use the Novo doc. chip to split. Each multi-page document is merged into a single PDF (e.g., a 3-page invoice becomes one PDF with all 3 pages) — one document, one record.
Failed uploads surface a per-file error snackbar with a Tentar de novo action; succeeded files are never rolled back.
Display modes
| Mode | Description |
|---|---|
| List | Compact list with file details in rows |
| Grid | Thumbnail grid with configurable items per row (default: 3) |
| Full width | Each document takes the full width |
The chosen mode is saved per user and overrides the admin default without changing it.
Search and sort
The Pesquisar button in the header opens a search field. The search matches, per document:
- The file name.
- The OCR text ("texto extraído") — the text captured off the document itself.
- The extracted/structured field values ("dados extraídos"), checked recursively — only the values, never the field names.
It does not match other columns on the record (title/subtitle mappings only control what a card displays, not what search looks at). Accents are folded, so typing "informacao" also finds "informação". Results update as you type; when a match comes from OCR or extracted data, the preview panel shows a Correspondência section with the matching snippets highlighted, and the Texto extraído section (when present) highlights the term inline.
Sorting is available via the sort button in the header:
| Option | |
|---|---|
| Nome | Alphabetical by filename |
| Data | By upload date |
| Tamanho | By file size |
Each can be toggled between ascending and descending. The chosen sort is saved per user and overrides the admin default.
Card labels
Each card's label is configurable in the Cabeçalhos tab of the view config:
- Title column — when set and non-empty on the row, replaces the filename as the card title (the filename moves to the meta line)
- Subtitle column — secondary descriptive text
- Additional columns — extra values appended to the meta line
- File size / upload date / uploaded by — toggled by the corresponding settings
Without a title column, the card shows the file name.
Document actions
Every document exposes the same set of single-document actions, reachable from two places:
Card overflow menu (the ⋮ button on each card):
| Action | Notes |
|---|---|
| Pré-visualizar | Selects the document, showing it in the preview panel |
| Abrir registo | Opens the underlying record |
| Descarregar | Signed-URL download (hidden when enableDownload is off) |
| Copiar nome | Copies the file name to the clipboard |
| Renomear | Changes the display name only — the stored file is untouched |
| Copiar ligação | Copies a shareable signed link to the clipboard |
| Substituir | See Replacing a file below |
| Editar páginas | PDFs only — see Editing PDF pages below |
| Apagar | Removes the file from storage and clears the row (confirmation required; hidden when enableDelete is off) |
Preview panel toolbar (when a document is selected): fullscreen expand, download, Substituir, and Editar páginas as icon buttons, plus a Mais menu with Renomear, Copiar nome, and Copiar ligação.
Replacing a file
Substituir swaps a document's file in place: it uploads the new file, deletes the associated AI extraction, and resets the document's staging status to "Por processar" — it does not trigger reprocessing on its own. A confirmation dialog explains this before you pick the replacement file, and progress is shown while the upload/patch runs. This action cannot be undone.
Editing PDF pages
Editar páginas opens a page editor for PDF documents. Per page you can:
- Rodar — rotate 90°
- Remover — delete the page (disabled when only one page remains)
- Reordenar — drag pages into a new order
- Juntar PDF — append the pages of another PDF you pick
Select one or more pages with their checkbox to Separar them into a brand-new document (the selection must be some, not all, of the pages).
Aplicar only becomes active once you've made a real edit to the page plan (rotate/remove/reorder/merge — selecting pages alone doesn't count) and asks for confirmation: it replaces the current file with the edited pages and deletes the associated extraction, and cannot be undone. Separar also asks for confirmation before moving the selected pages to the new document.
Selection and bulk actions
Long-press (or tap, once a selection exists) toggles a document in the multi-select. A floating bar appears at the bottom with:
| Action | Description | Config toggle |
|---|---|---|
| Selecionar todos | Extends the selection to every visible document (shown while some remain unselected) | — |
| Descarregar | Signed-URL download of each selected file | enableDownload |
| Processar com AI | Runs the configured AI workflow on each selected document | AI workflow configured + document column set |
| Apagar | Removes files from storage and clears the rows (confirmation required) | enableDelete |
Cmd/Ctrl+F abre o campo de pesquisa. Esc closes an open search field first; if search is already closed, it clears the multi-select; if there's no multi-select, it clears the preview selection.
Preview panel
Selecting a card shows the inline preview (PDF/image render, metadata table). The toolbar and overflow menu expose the per-document actions described in Document actions above.
AI processing
Set Workflow AI (the AI tab of the view config) to a workflow containing the AI — processar documento action.
When an AI workflow is configured:
- A Processar com AI button appears on the preview panel and in the bulk bar for unprocessed documents.
- A live status chip tracks the run: Em fila → A processar (n) → Processado / Erro — no manual refresh needed.
- Re-processar re-runs a document already in a terminal state (done/error). Each retry produces a distinct log entry; the button is disabled while a run is queued or running.
- The Estado grouping axis becomes available in the explorer, letting you see at a glance how many documents are pending, processing, done, or in error.
Sorting and filtering
| Setting | Options |
|---|---|
| Search | Matches the file name, OCR text, and extracted/structured field values (see Search and sort) |
| Sort by | Nome, Data, or Tamanho — ascending or descending; persisted per user |
| Filters | Admin base filters + per-user advanced filters |
| Allowed extensions | Restrict uploads/display to specific file types (e.g., only PDFs) |