Timeline_Generator/README.md

📊 TimeLine Designer

輕鬆建立專業的時間軸圖表

TimeLine Designer 是一款桌面應用程式，讓您能夠輕鬆匯入事件資料並生成高品質的時間軸圖表。支援 CSV/XLSX 匯入，可匯出為 PNG、PDF、SVG 等多種格式。

✨ 主要特性

• 零程式門檻 - 直覺的 GUI 操作介面
• 快速渲染 - 100 筆事件 < 2 秒
• 高解析輸出 - 支援 300 DPI 印刷品質
• 多格式匯出 - PNG / PDF / SVG
• 跨平台支援 - Windows / macOS
• 主題系統 - 多種視覺主題可選
• 智能刻度 - 自動調整時間刻度單位

🚀 快速開始

環境需求

• Python 3.8 或以上版本
• Windows 10/11 或 macOS 10.14+

安裝步驟

1. 克隆專案

git clone <repository-url>
cd Timeline_Generator

2. 建立虛擬環境

python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

3. 安裝依賴

pip install -r requirements.txt

4. 啟動應用程式

python app.py

📖 使用說明

1. 匯入資料

準備一個 CSV 或 XLSX 檔案，包含以下欄位：

欄位名稱	必填	說明	範例
id	✅	事件唯一識別碼	evt-001
title	✅	事件標題	專案啟動
start	✅	開始時間	2024-01-01 09:00:00
end	❌	結束時間	2024-01-01 17:00:00
group	❌	事件群組/分類	Phase 1
description	❌	事件詳細描述	專案正式啟動會議
color	❌	事件顏色 (HEX)	#3B82F6

範例 CSV 檔案：

id,title,start,end,group,description,color
evt-001,專案啟動,2024-01-01 09:00:00,2024-01-01 17:00:00,Phase 1,專案正式啟動會議,#3B82F6
evt-002,需求分析,2024-01-02 09:00:00,2024-01-05 18:00:00,Phase 1,收集並分析系統需求,#10B981

常用顏色代碼

顏色	色碼	適用情境
藍色	#3B82F6	一般事件、資訊類
綠色	#10B981	完成、成功、正面事件
黃色	#F59E0B	警告、待處理、重要提醒
紅色	#EF4444	緊急、錯誤、負面事件
紫色	#8B5CF6	特殊事件、里程碑
粉色	#EC4899	個人事件、慶祝活動
靛藍色	#6366F1	專業、企業
青色	#06B6D4	清新、創新
橙色	#F97316	活力、創意

示範檔案說明

examples/ 目錄包含三個示範檔案：

1. template.csv - 空白模板

   • 包含所有欄位標題
   • 適合建立新時間軸

2. demo_project_timeline.csv - 專案開發時間軸

   • 15 筆事件，完整開發週期
   • 涵蓋：需求分析、研發、測試、部署
   • 時間範圍：2024/01-02

3. demo_life_events.csv - 個人生活時間軸

   • 11 筆事件，記錄 11 年生涯
   • 涵蓋：教育、職涯、生活里程碑
   • 時間範圍：2015-2026

4. demo_product_roadmap.csv - 產品路線圖

   • 14 筆事件，季度規劃
   • 涵蓋：募資、產品發布、市場擴展
   • 時間範圍：2024-2025

2. 生成時間軸

點擊「生成時間軸」按鈕，系統將自動：

• 計算最佳時間刻度
• 處理重疊事件排版
• 渲染互動式時間軸

3. 匯出圖表

選擇匯出格式和解析度，點擊「匯出」按鈕：

• PNG - 適合插入文件或簡報
• PDF - 適合印刷和存檔
• SVG - 適合進一步編輯

🏗️ 專案架構

Timeline_Generator/
├── backend/                 # 後端模組
│   ├── __init__.py
│   ├── main.py             # FastAPI 主程式
│   ├── schemas.py          # 資料模型定義
│   ├── importer.py         # CSV/XLSX 匯入
│   ├── renderer.py         # 時間軸渲染
│   └── export.py           # 圖表匯出
├── frontend/               # 前端介面
│   └── static/
│       └── index.html      # HTML GUI
├── tests/                  # 測試套件
│   ├── unit/              # 單元測試
│   └── e2e/               # 端對端測試
├── docs/                   # 文檔
│   ├── PRD.md             # 產品需求文檔
│   ├── SDD.md             # 系統設計文檔
│   ├── TDD.md             # 測試驅動開發文檔
│   └── GUIDLINE.md        # AI 開發指南
├── app.py                  # PyWebview 主程式
├── requirements.txt        # Python 依賴
└── README.md              # 本文件

🧪 執行測試

# 執行所有測試
pytest

# 執行單元測試
pytest tests/unit/ -v

# 執行測試並生成覆蓋率報告
pytest --cov=backend --cov-report=html

# 執行效能測試
pytest tests/unit/ -m performance

📚 API 文檔

應用程式啟動後，可訪問以下 API 文檔：

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc

主要 API 端點

Method	Endpoint	功能
POST	/api/import	匯入 CSV/XLSX 檔案
GET	/api/events	取得事件列表
POST	/api/render	生成時間軸 JSON
POST	/api/export	匯出時間軸圖檔
GET	/api/themes	取得主題列表

🎨 主題系統

支援四種內建主題：

1. 現代風格 (Modern) - 清新的藍色調
2. 經典風格 (Classic) - 優雅的紫色調
3. 極簡風格 (Minimal) - 黑白簡約設計
4. 企業風格 (Corporate) - 專業的灰色調

🔧 開發指南

程式碼規範

遵循 VIBE 開發原則：

• Vision - 理解產品願景
• Interface - 定義介面契約
• Behavior - 實作對應行為
• Evidence - 驗證成果

測試先行

本專案遵循 TDD (Test-Driven Development) 原則：

1. 先撰寫測試案例
2. 實作功能代碼
3. 執行測試驗證
4. 重構優化

程式碼檢查

# Linting
flake8 backend/

# Type checking
mypy backend/

# Security scan
bandit -r backend/

📊 效能指標

根據 PRD.md 定義的 KPI：

指標	目標	驗收標準
新手上手時間	< 5 分鐘	教學引導完整
渲染效能	100 筆 < 2 秒	通過效能測試
輸出品質	300 DPI	PDF/SVG 通過印刷驗證

🐛 問題回報

如果您發現任何問題，請提供以下資訊：

1. 作業系統與版本
2. Python 版本
3. 錯誤訊息或截圖
4. 重現步驟

📄 授權條款

本專案採用 MIT 授權條款。

🙏 致謝

本專案使用以下開源套件：

• FastAPI - Web 框架
• Plotly - 圖表渲染
• PyWebview - GUI 容器
• Pydantic - 資料驗證
• Pandas - 資料處理

---

Version: 1.0.0 Author: AI Agent Documentation: See docs/ folder for detailed specifications