egg/OCR
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d20751d56bc07ed356629d16ddd15410a772c606
OCR/openspec/specs/result-export/spec.md
egg 1f18010040 fix: OCR Track reflow PDF and translation with image text filtering 
- Add OCR Track support for reflow PDF generation using raw_ocr_regions.json
- Add OCR Track translation extraction from raw_ocr_regions instead of elements
- Add raw_ocr_translations output format for OCR Track documents
- Add exclusion zone filtering to remove text overlapping with images
- Update API validation to accept both translations and raw_ocr_translations
- Add page_number field to TranslatedItem for proper tracking

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-12 11:02:35 +08:00

208 lines
9.2 KiB
Markdown
Raw Blame History

# result-export Specification
## Purpose
TBD - created by archiving change fix-v2-api-ui-issues. Update Purpose after archive.
## Requirements
### Requirement: Export Interface
The Export interface in TaskDetailPage SHALL provide streamlined download options focusing on PDF formats.
#### Scenario: Download options for completed tasks
- **WHEN** viewing a completed task in TaskDetailPage
- **THEN** the download section SHALL display only two buttons: "版面 PDF" and "流式 PDF"
- **AND** JSON, UnifiedDocument, and Markdown download buttons SHALL NOT be displayed
- **AND** the download grid SHALL use a 2-column layout
#### Scenario: Translation download options
- **WHEN** viewing completed translations in TaskDetailPage
- **THEN** each translation item SHALL display only a "流式 PDF" download button
- **AND** translation JSON download button SHALL NOT be displayed
- **AND** Layout PDF option for translations SHALL NOT be displayed
- **AND** delete translation button SHALL remain available
#### Scenario: Backend API remains unchanged
- **WHEN** external clients call download endpoints directly
- **THEN** JSON, Markdown, and UnifiedDocument endpoints SHALL still function
- **AND** translated Layout PDF endpoint SHALL still function
- **AND** no backend changes are required for this frontend simplification
### Requirement: Multi-Task Export Selection
The Export page SHALL allow users to select and export multiple tasks.
#### Scenario: Select multiple tasks for export
- **WHEN** Export page loads
- **THEN** page SHALL display list of user's completed tasks
- **AND** page SHALL provide checkboxes to select multiple tasks
- **AND** page SHALL NOT require batch ID from upload store (legacy V1 behavior)
#### Scenario: Export selected tasks
- **WHEN** user selects multiple tasks and clicks export
- **THEN** system SHALL download each selected task's results in chosen format
- **AND** downloaded files SHALL be named distinctly (e.g., `{task_id}_result.{ext}`)
- **AND** system MAY provide option to download as ZIP archive for multiple files
### Requirement: Export Configuration Persistence
Export settings (format, thresholds, templates) SHALL apply consistently to V2 task downloads.
#### Scenario: Apply confidence threshold to export
- **WHEN** user sets confidence threshold to 0.7 and exports
- **THEN** downloaded results SHALL only include OCR text with confidence >= 0.7
- **AND** threshold SHALL apply via V2 download endpoint query parameters
#### Scenario: Apply CSS template to PDF export
- **WHEN** user selects CSS template for PDF format
- **THEN** downloaded PDF SHALL use selected styling
- **AND** template SHALL be passed to V2 `/tasks/{id}/download/pdf` endpoint
### Requirement: Enhanced PDF Export with Layout Preservation
The PDF export SHALL accurately preserve document layout from both OCR and direct extraction tracks with correct coordinate transformation and multi-page support. For Direct Track, a background image rendering approach SHALL be used for visual fidelity.
#### Scenario: OCR Track reflow PDF uses raw OCR regions
- **WHEN** generating reflow PDF for an OCR Track document
- **THEN** the system SHALL load text content from `raw_ocr_regions.json` files
- **AND** text blocks SHALL be sorted by Y coordinate for reading order
- **AND** all text content SHALL match the Layout PDF output
- **AND** images and charts SHALL be embedded from element `saved_path`
#### Scenario: Direct Track reflow PDF uses structured content
- **WHEN** generating reflow PDF for a Direct Track document
- **THEN** the system SHALL use `content.cells` for table rendering
- **AND** text elements SHALL use `content` string directly
- **AND** images and charts SHALL be embedded from element `saved_path`
#### Scenario: Reflow PDF content consistency
- **WHEN** comparing Layout PDF and Reflow PDF for the same document
- **THEN** both PDFs SHALL contain the same text content
- **AND** only the presentation format SHALL differ (positioned vs flowing)
### Requirement: Structure Data Export
The system SHALL provide export formats that preserve document structure for downstream processing.
#### Scenario: Export structured JSON with hierarchy
- **WHEN** user selects structured JSON format
- **THEN** export SHALL include element hierarchy and relationships
- **AND** preserve parent-child relationships (sections, lists)
- **AND** include style and formatting information
#### Scenario: Export for translation preparation
- **WHEN** user exports with translation_ready=true parameter
- **THEN** export SHALL include translatable text segments
- **AND** maintain coordinate mappings for each segment
- **AND** mark non-translatable regions
#### Scenario: Export with layout analysis
- **WHEN** user requests layout analysis export
- **THEN** system SHALL include reading order indices
- **AND** identify layout regions (header, body, footer, sidebar)
- **AND** provide confidence scores for layout detection
### Requirement: Translation Result JSON Export
The system SHALL support exporting translation results as independent JSON files following a defined schema.
#### Scenario: Export translation result JSON
- **WHEN** translation completes for a document
- **THEN** system SHALL save translation to `{filename}_translated_{lang}.json`
- **AND** file SHALL be stored alongside original `{filename}_result.json`
- **AND** original result file SHALL remain unchanged
#### Scenario: Translation JSON schema compliance
- **WHEN** translation result is saved
- **THEN** JSON SHALL include schema_version field ("1.0.0")
- **AND** SHALL include source_document reference
- **AND** SHALL include source_lang and target_lang
- **AND** SHALL include provider identifier (e.g., "dify")
- **AND** SHALL include translated_at timestamp
- **AND** SHALL include translations dict mapping element_id to translated content
#### Scenario: Translation statistics in export
- **WHEN** translation result is saved
- **THEN** JSON SHALL include statistics object with:
- total_elements: count of all elements in document
- translated_elements: count of successfully translated elements
- skipped_elements: count of non-translatable elements (images, charts, etc.)
- total_characters: character count of translated text
- processing_time_seconds: translation duration
#### Scenario: Table cell translation in export
- **WHEN** document contains tables
- **THEN** translation JSON SHALL represent table translations as:
```json
{
"table_1_0": {
"cells": [
{"row": 0, "col": 0, "content": "Translated cell text"},
{"row": 0, "col": 1, "content": "Another cell"}
]
}
}
```
- **AND** row/col positions SHALL match original table structure
#### Scenario: Download translation result via API
- **WHEN** GET request to `/api/v2/translate/{task_id}/result?lang={lang}`
- **THEN** system SHALL return translation JSON content
- **AND** Content-Type SHALL be application/json
- **AND** response SHALL include appropriate cache headers
#### Scenario: List available translations
- **WHEN** GET request to `/api/v2/tasks/{task_id}/translations`
- **THEN** system SHALL return list of available translation languages
- **AND** include translation metadata (translated_at, provider, statistics)
### Requirement: Translated PDF Export API
The system SHALL expose an API endpoint for downloading translated documents as PDF files.
#### Scenario: Download translated PDF via API
- **GIVEN** a task with completed translation to English
- **WHEN** POST request to `/api/v2/translate/{task_id}/pdf?lang=en`
- **THEN** system returns PDF file with translated content
- **AND** Content-Type is `application/pdf`
- **AND** Content-Disposition suggests filename like `{task_id}_translated_en.pdf`
#### Scenario: Download translated PDF with layout preservation
- **WHEN** user downloads translated PDF
- **THEN** the PDF maintains original document layout
- **AND** text positions match original document coordinates
- **AND** images and tables appear at original positions
#### Scenario: Invalid language parameter
- **GIVEN** a task with translation only to English
- **WHEN** user requests PDF with `lang=ja` (Japanese)
- **THEN** system returns 404 Not Found
- **AND** response includes available languages in error message
#### Scenario: Task not found
- **GIVEN** non-existent task_id
- **WHEN** user requests translated PDF
- **THEN** system returns 404 Not Found
---
### Requirement: Frontend Translated PDF Download
The frontend SHALL provide UI controls for downloading translated PDFs.
#### Scenario: Show download button when translation complete
- **GIVEN** a task with translation status "completed"
- **WHEN** user views TaskDetailPage
- **THEN** page displays "Download Translated PDF" button
- **AND** button shows target language (e.g., "Download Translated PDF (English)")
#### Scenario: Hide download button when no translation
- **GIVEN** a task without any completed translations
- **WHEN** user views TaskDetailPage
- **THEN** "Download Translated PDF" button is not shown
#### Scenario: Download progress indication
- **GIVEN** user clicks "Download Translated PDF" button
- **WHEN** PDF generation is in progress
- **THEN** button shows loading state
- **AND** prevents double-click
- **WHEN** download completes
- **THEN** browser downloads PDF file
- **AND** button returns to normal state
Reference in New Issue View Git Blame Copy Permalink