# 📗 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. 資料模型
```python
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. 前端契約
```tsx
<TimelineCanvas
  events={Event[]}
  config={TimelineConfig}
  onSelect={(id)=>{}}
  onMove={(id,newStart)=>{}}
/>
```

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