5e088fa473
主要變更： - 刪除 PRD.md（產品需求文檔） - 刪除 examples 目錄中的文檔檔案（README.md, QUICK_START.md, color_reference.md） - 整合 examples 文檔內容到根目錄 README.md - 新增常用顏色代碼表格 - 新增示範檔案說明 - 保留所有重要使用資訊 - 合併 requirements.txt 和 requirements-core.txt - 更新所有套件到最新相容版本 - 支援 Python 3.8 - 3.13 - 統一依賴管理 技術細節： - FastAPI: 0.104.1 → 0.115.6 - Pydantic: 2.5.0 → 2.10.5（新增 pydantic-settings） - Pytest: 7.4.3 → 8.3.4 - 其他套件同步更新 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
266 lines
6.8 KiB
Markdown
266 lines
6.8 KiB
Markdown
# 📊 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. **克隆專案**
|
||
```bash
|
||
git clone <repository-url>
|
||
cd Timeline_Generator
|
||
```
|
||
|
||
2. **建立虛擬環境**
|
||
```bash
|
||
python -m venv venv
|
||
|
||
# Windows
|
||
venv\Scripts\activate
|
||
|
||
# macOS/Linux
|
||
source venv/bin/activate
|
||
```
|
||
|
||
3. **安裝依賴**
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
4. **啟動應用程式**
|
||
```bash
|
||
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 檔案：**
|
||
```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 # 本文件
|
||
```
|
||
|
||
## 🧪 執行測試
|
||
|
||
```bash
|
||
# 執行所有測試
|
||
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** 開發原則：
|
||
- **V**ision - 理解產品願景
|
||
- **I**nterface - 定義介面契約
|
||
- **B**ehavior - 實作對應行為
|
||
- **E**vidence - 驗證成果
|
||
|
||
### 測試先行
|
||
|
||
本專案遵循 TDD (Test-Driven Development) 原則：
|
||
1. 先撰寫測試案例
|
||
2. 實作功能代碼
|
||
3. 執行測試驗證
|
||
4. 重構優化
|
||
|
||
### 程式碼檢查
|
||
|
||
```bash
|
||
# 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](https://fastapi.tiangolo.com/) - Web 框架
|
||
- [Plotly](https://plotly.com/) - 圖表渲染
|
||
- [PyWebview](https://pywebview.flowrl.com/) - GUI 容器
|
||
- [Pydantic](https://pydantic-docs.helpmanual.io/) - 資料驗證
|
||
- [Pandas](https://pandas.pydata.org/) - 資料處理
|
||
|
||
---
|
||
|
||
**Version:** 1.0.0
|
||
**Author:** AI Agent
|
||
**Documentation:** See `docs/` folder for detailed specifications
|