Timeline_Generator/backend/export.py

"""
匯出模組

本模組負責將時間軸圖表匯出為各種格式（PDF、PNG、SVG）。
使用 Plotly 的 kaleido 引擎進行圖片生成。
"""

import os
from pathlib import Path
from datetime import datetime
from typing import Union, Optional
import logging
import re

try:
    import plotly.graph_objects as go
    from plotly.io import write_image
    PLOTLY_AVAILABLE = True
except ImportError:
    PLOTLY_AVAILABLE = False

from .schemas import ExportOptions, ExportFormat

logger = logging.getLogger(__name__)


class ExportError(Exception):
    """匯出錯誤基礎類別"""
    pass


class FileNameSanitizer:
    """
    檔名淨化器

    移除非法字元並處理過長的檔名。
    """

    # 非法字元（Windows + Unix）
    ILLEGAL_CHARS = r'[<>:"/\\|?*\x00-\x1f]'

    # 保留字（Windows）
    RESERVED_NAMES = [
        'CON', 'PRN', 'AUX', 'NUL',
        'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
        'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9',
    ]

    MAX_LENGTH = 200  # 最大檔名長度

    @classmethod
    def sanitize(cls, filename: str) -> str:
        """
        淨化檔名

        Args:
            filename: 原始檔名

        Returns:
            淨化後的檔名
        """
        # 移除非法字元
        sanitized = re.sub(cls.ILLEGAL_CHARS, '_', filename)

        # 移除前後空白
        sanitized = sanitized.strip()

        # 移除尾部的點和空格（Windows 限制）
        sanitized = sanitized.rstrip('. ')

        # 檢查保留字
        name_upper = sanitized.upper()
        if name_upper in cls.RESERVED_NAMES:
            sanitized = '_' + sanitized

        # 限制長度
        if len(sanitized) > cls.MAX_LENGTH:
            sanitized = sanitized[:cls.MAX_LENGTH]

        # 如果為空，使用預設名稱
        if not sanitized:
            sanitized = 'timeline'

        return sanitized


class ExportEngine:
    """
    匯出引擎

    負責將 Plotly 圖表匯出為不同格式的檔案。
    """

    def __init__(self):
        if not PLOTLY_AVAILABLE:
            raise ImportError("需要安裝 plotly 和 kaleido 以使用匯出功能")

        self.filename_sanitizer = FileNameSanitizer()

    def export(
        self,
        fig: go.Figure,
        output_path: Union[str, Path],
        options: ExportOptions
    ) -> Path:
        """
        匯出圖表

        Args:
            fig: Plotly Figure 物件
            output_path: 輸出路徑
            options: 匯出選項

        Returns:
            實際輸出檔案的路徑

        Raises:
            ExportError: 匯出失敗時拋出
        """
        output_path = Path(output_path)

        # 確保目錄存在
        output_path.parent.mkdir(parents=True, exist_ok=True)

        # 淨化檔名
        filename = self.filename_sanitizer.sanitize(output_path.stem)
        sanitized_path = output_path.parent / f"{filename}{output_path.suffix}"

        try:
            if options.fmt == ExportFormat.PDF:
                return self._export_pdf(fig, sanitized_path, options)
            elif options.fmt == ExportFormat.PNG:
                return self._export_png(fig, sanitized_path, options)
            elif options.fmt == ExportFormat.SVG:
                return self._export_svg(fig, sanitized_path, options)
            else:
                raise ExportError(f"不支援的匯出格式: {options.fmt}")

        except PermissionError:
            raise ExportError(f"無法寫入檔案（權限不足）: {sanitized_path}")
        except OSError as e:
            if e.errno == 28:  # ENOSPC
                raise ExportError("磁碟空間不足")
            else:
                raise ExportError(f"檔案系統錯誤: {str(e)}")
        except Exception as e:
            logger.error(f"匯出失敗: {str(e)}")
            raise ExportError(f"匯出失敗: {str(e)}")

    def _export_pdf(self, fig: go.Figure, output_path: Path, options: ExportOptions) -> Path:
        """
        匯出為 PDF

        Args:
            fig: Plotly Figure
            output_path: 輸出路徑
            options: 匯出選項

        Returns:
            輸出檔案路徑
        """
        # 確保副檔名
        if output_path.suffix.lower() != '.pdf':
            output_path = output_path.with_suffix('.pdf')

        # 設定 DPI 和尺寸
        scale = options.dpi / 72.0  # Plotly 使用 72 DPI 作為基準

        # 匯出
        write_image(
            fig,
            str(output_path),
            format='pdf',
            width=options.width,
            height=options.height,
            scale=scale
        )

        logger.info(f"PDF 匯出成功: {output_path}")
        return output_path

    def _export_png(self, fig: go.Figure, output_path: Path, options: ExportOptions) -> Path:
        """
        匯出為 PNG

        Args:
            fig: Plotly Figure
            output_path: 輸出路徑
            options: 匯出選項

        Returns:
            輸出檔案路徑
        """
        # 確保副檔名
        if output_path.suffix.lower() != '.png':
            output_path = output_path.with_suffix('.png')

        # 設定 DPI 和尺寸
        scale = options.dpi / 72.0

        # 處理透明背景
        if options.transparent_background:
            fig.update_layout(
                paper_bgcolor='rgba(0,0,0,0)',
                plot_bgcolor='rgba(0,0,0,0)'
            )

        # 匯出
        write_image(
            fig,
            str(output_path),
            format='png',
            width=options.width,
            height=options.height,
            scale=scale
        )

        logger.info(f"PNG 匯出成功: {output_path}")
        return output_path

    def _export_svg(self, fig: go.Figure, output_path: Path, options: ExportOptions) -> Path:
        """
        匯出為 SVG

        Args:
            fig: Plotly Figure
            output_path: 輸出路徑
            options: 匯出選項

        Returns:
            輸出檔案路徑
        """
        # 確保副檔名
        if output_path.suffix.lower() != '.svg':
            output_path = output_path.with_suffix('.svg')

        # SVG 是向量格式，不需要 DPI 設定
        write_image(
            fig,
            str(output_path),
            format='svg',
            width=options.width,
            height=options.height
        )

        logger.info(f"SVG 匯出成功: {output_path}")
        return output_path


class TimelineExporter:
    """
    時間軸匯出器

    高層級介面，整合渲染與匯出功能。
    """

    def __init__(self):
        self.export_engine = ExportEngine()

    def export_from_plotly_json(
        self,
        plotly_data: dict,
        plotly_layout: dict,
        output_path: Union[str, Path],
        options: ExportOptions,
        filename_prefix: str = "timeline"
    ) -> Path:
        """
        從 Plotly JSON 資料匯出

        Args:
            plotly_data: Plotly data 部分
            plotly_layout: Plotly layout 部分
            output_path: 輸出路徑（目錄或完整路徑）
            options: 匯出選項
            filename_prefix: 檔名前綴

        Returns:
            實際輸出檔案的路徑
        """
        # 建立 Plotly Figure
        fig = go.Figure(data=plotly_data.get('data', []), layout=plotly_layout)

        # 處理輸出路徑
        output_path = Path(output_path)
        if output_path.is_dir():
            # 如果是目錄，生成預設檔名
            timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
            filename = f"{filename_prefix}_{timestamp}.{options.fmt.value}"
            full_path = output_path / filename
        else:
            full_path = output_path

        # 匯出
        return self.export_engine.export(fig, full_path, options)

    def generate_default_filename(self, fmt: ExportFormat) -> str:
        """
        生成預設檔名

        Args:
            fmt: 檔案格式

        Returns:
            預設檔名
        """
        timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
        return f"timeline_{timestamp}.{fmt.value}"


def create_metadata(title: str = "TimeLine Designer") -> dict:
    """
    建立 PDF 元資料

    Args:
        title: 文件標題

    Returns:
        元資料字典
    """
    return {
        'Title': title,
        'Creator': 'TimeLine Designer v1.0',
        'Producer': 'Plotly + Kaleido',
        'CreationDate': datetime.now().strftime('%Y-%m-%d %H:%M:%S'),
    }


# 匯出主要介面
__all__ = [
    'ExportEngine',
    'TimelineExporter',
    'ExportError',
    'ExportOptions',
    'ExportFormat',
]