Timeline_Generator/SDD.md

📗 System Design Document (SDD)

1. 架構概述

PyWebview Host
 ├── FastAPI Backend
 │   ├── importer.py（CSV/XLSX 處理）
 │   ├── renderer.py（Plotly/kaleido 渲染）
 │   ├── schemas.py（資料模型定義）
 │   └── export.py（PDF/SVG/PNG 輸出）
 └── Frontend (React + Tailwind)
     ├── TimelineCanvas（vis-timeline 封裝）
     ├── EventForm / ThemePanel / ExportDialog
     └── api.ts（API 呼叫）

2. 資料模型

class Event(BaseModel):
    id: str
    title: str
    start: datetime
    end: Optional[datetime]
    group: Optional[str]
    description: Optional[str]
    color: Optional[str]

class TimelineConfig(BaseModel):
    direction: Literal['horizontal', 'vertical'] = 'horizontal'
    theme: str = 'modern'
    show_grid: bool = True

class ExportOptions(BaseModel):
    fmt: Literal['png', 'pdf', 'svg']
    dpi: int = 300

3. API 定義

Method	Endpoint	功能	輸入	輸出
POST	/import	匯入事件資料	CSV/XLSX	Event[]
GET	/events	取得事件列表	None	Event[]
POST	/render	生成時間軸 JSON	TimelineConfig	Plotly JSON
POST	/export	導出時間軸圖	ExportOptions	圖檔
GET	/themes	主題列表	None	Theme[]

4. 視覺化邏輯

• 自動調整時間刻度（日/週/月）
• 重疊節點避碰算法
• 拖曳吸附（Snap to Grid）
• Hover 顯示 Tooltip 詳細資訊

5. 前端契約

<TimelineCanvas
  events={Event[]}
  config={TimelineConfig}
  onSelect={(id)=>{}}
  onMove={(id,newStart)=>{}}
/>

6. 系統相依性

模組	用途
PyWebview	原生 GUI 容器
FastAPI	後端 API 框架
React	前端 UI
Tailwind	樣式系統
Plotly/kaleido	圖表渲染與輸出
Playwright	截圖與測試