OCR/openspec/specs/result-export/spec.md

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:

  {
    "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