文檔整理與依賴整合

主要變更:
- 刪除 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>
This commit is contained in:
beabigegg
2025-11-06 12:07:01 +08:00
parent ad9ba59fdf
commit 5e088fa473
7 changed files with 47 additions and 682 deletions

44
PRD.md
View File

@@ -1,44 +0,0 @@
# 📘 Product Requirement Document (PRD)
## 1. 概述與願景
**產品名稱**TimeLine Designer
**願景**:提供使用者以最直覺的方式輸入關鍵事件,並自動生成高品質時間軸。
### 1.1 目標
- **零程式門檻**:使用者能以 GUI 操作完成輸入與生成。
- **高解析輸出**PNG、SVG、PDF 支援高 DPI。
- **快速渲染**100 筆事件 < 2
- **跨平台支援**Windows/macOS
### 1.2 產品價值主張
| 面向 | 說明 |
|------|------|
| 使用體驗 | 拖曳縮放即時預覽主題切換 |
| 視覺品質 | React + Tailwind 現代化設計 |
| 可擴充性 | 模組化結構可加入 AI 摘要 |
---
## 2. 使用案例
| 編號 | 行為 | 系統反應 |
|------|------|-----------|
| UC01 | 輸入關鍵事件 | 即時生成時間軸 |
| UC02 | 匯入 CSV | 自動解析排序並渲染 |
| UC03 | 切換主題 | UI 即時更新 |
| UC04 | 匯出 PDF | 輸出高解析結果 |
---
## 3. 範圍
**In Scope**事件輸入渲染互動匯出主題與模板
**Out of Scope**多人協作雲端儲存
---
## 4. 目標指標 (KPI)
| 指標 | 目標 | 驗收 |
|------|------|------|
| 新手上手時間 | <5 分鐘 | 教學引導完整 |
| 渲染性能 | 100 <2 | 通過效能測試 |
| 輸出品質 | 300 DPI | PDF/SVG 通過印刷驗證 |

View File

@@ -66,8 +66,6 @@ python app.py
| description | | 事件詳細描述 | 專案正式啟動會議 |
| color | | 事件顏色 (HEX) | #3B82F6 |
> 💡 **顏色代碼參考**:查看 [examples/color_reference.md](examples/color_reference.md) 了解常用顏色代碼及使用建議。
**範例 CSV 檔案:**
```csv
id,title,start,end,group,description,color
@@ -75,6 +73,43 @@ evt-001,專案啟動,2024-01-01 09:00:00,2024-01-01 17:00:00,Phase 1,專案正
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. 生成時間軸
點擊生成時間軸按鈕系統將自動

View File

@@ -1,187 +0,0 @@
# TimeLine Designer - 快速入門
## 🚀 5 分鐘快速上手
### 步驟 1: 啟動系統 (30 秒)
```batch
# Windows 雙擊執行
start_dev.bat
```
等待看到以下訊息:
```
Backend: http://localhost:8000 ✅
Frontend: http://localhost:12010 ✅
```
---
### 步驟 2: 開啟瀏覽器 (10 秒)
訪問: **http://localhost:12010**
---
### 步驟 3: 匯入示範檔案 (30 秒)
1. 拖曳 `examples/demo_project_timeline.csv` 到上傳區
2. 看到 "✅ 成功匯入 15 筆事件!"
---
### 步驟 4: 生成時間軸 (10 秒)
1. 點擊 **「生成時間軸」** 按鈕
2. 等待 1-2 秒渲染完成
---
### 步驟 5: 互動與匯出 (1 分鐘)
- 🖱️ **滑鼠滾輪**:縮放
- 🖱️ **拖曳**:平移
- 🎯 **懸停**:查看詳情
- 💾 **匯出**:選擇格式 (PDF/PNG/SVG) 和 DPI點擊匯出
---
## 📋 三個示範檔案
### 1⃣ `template.csv` - 空白模板
**用途**: 建立您自己的時間軸
**內容**: 只有欄位標題 + 1 行範例
### 2⃣ `demo_project_timeline.csv` - 專案開發
**事件**: 15 筆(專案管理、需求、開發、測試、部署)
**時間**: 2024/01-02 (2 個月)
### 3⃣ `demo_life_events.csv` - 個人履歷
**事件**: 11 筆(教育、職涯、生活里程碑)
**時間**: 2015-2026 (11 年)
### 4⃣ `demo_product_roadmap.csv` - 產品路線圖
**事件**: 14 筆(季度規劃、募資、產品發布)
**時間**: 2024-2025 (1.5 年)
---
## 🎯 核心功能
| 功能 | 操作 |
|-----|-----|
| 📁 **匯入資料** | 拖放 CSV/XLSX 到上傳區 |
| 🎨 **生成圖表** | 點擊「生成時間軸」 |
| 🔍 **縮放** | 滑鼠滾輪 |
| 🖱️ **平移** | 拖曳圖表 |
| 💾 **匯出** | 選擇格式 + DPI點擊匯出 |
| 🗑️ **清空** | 點擊「清空事件」 |
---
## 📊 CSV 格式速查
### 必填欄位
```csv
id,title,start
event-001,事件標題,2024-01-01
```
### 完整欄位
```csv
id,title,start,end,group,description,color
event-001,事件標題,2024-01-01,2024-01-05,分組A,描述文字,#3B82F6
```
---
## 🎨 常用色碼
```
#3B82F6 藍色 (科技、信任)
#10B981 綠色 (成功、成長)
#F59E0B 黃色 (警示、重要)
#EF4444 紅色 (緊急、里程碑)
#8B5CF6 紫色 (創新、高級)
#EC4899 粉色 (溫馨、生活)
```
---
## 💡 快速技巧
### 建立單日事件
留空 `end` 欄位:
```csv
id,title,start,end
M001,里程碑,2024-01-15,
```
### 使用群組分類
同一群組會自動上下排列:
```csv
id,title,start,end,group
E001,事件A,2024-01-01,2024-01-05,開發階段
E002,事件B,2024-01-03,2024-01-07,開發階段
E003,事件C,2024-01-06,2024-01-10,測試階段
```
### Excel 快速填充
- **ID 序列**: 使用公式 `=TEXT(ROW()-1,"event-000")`
- **日期序列**: 選取起始日期,拖曳填充把手
---
## ❓ 常見問題速解
### Q: 中文亂碼?
**A**: Excel → 另存新檔 → **CSV UTF-8 (逗號分隔)**
### Q: 日期錯誤?
**A**: 使用格式 `2024-01-01` (YYYY-MM-DD)
### Q: 圖表沒顯示?
**A**:
1. 確認已點擊「生成時間軸」
2. 檢查瀏覽器 Console (F12) 是否有錯誤
### Q: 匯出失敗?
**A**: 必須先生成時間軸才能匯出
---
## 🔧 故障排除
### 後端無法啟動
```bash
# 檢查環境
conda activate timeline_designer
conda list | grep fastapi
# 重新安裝依賴
pip install -r requirements.txt
```
### 前端無法啟動
```bash
cd frontend-react
npm install
npm run dev
```
### 端口被佔用
```bash
# Windows
netstat -ano | findstr :8000
netstat -ano | findstr :12010
# 終止進程
taskkill /PID <PID> /F
```
---
## 📞 需要更多幫助?
- 📖 **完整文檔**: `examples/README.md`
- 🔧 **API 文檔**: http://localhost:8000/api/docs
- 📁 **專案文檔**: `docs/` 目錄
---
**祝您使用愉快!** 🎉

View File

@@ -1,326 +0,0 @@
# TimeLine Designer - 範例檔案說明
本目錄包含標準匯入模板和示範檔案,幫助您快速上手 TimeLine Designer。
---
## 📋 檔案清單
### 1. **template.csv** - 標準匯入模板
空白模板檔案,包含所有可用欄位和一行範例資料。
**用途**: 建立自己的時間軸時,複製此檔案並填入您的事件資料。
---
### 2. **demo_project_timeline.csv** - 專案開發時間軸
展示軟體專案開發流程的完整時間軸。
**內容**:
- 專案管理 (啟動會議)
- 需求分析 (需求收集、文件撰寫)
- 研發階段 (前後端開發、資料庫)
- 測試階段 (單元測試、整合測試、UAT)
- 部署階段 (系統上線、監控)
- 里程碑標記 (Alpha、Beta、正式上線)
**事件數量**: 15 筆
**時間範圍**: 2024/01/02 - 2024/02/25
**適用場景**: 軟體開發、專案管理、團隊協作
---
### 3. **demo_life_events.csv** - 個人生活時間軸
記錄個人成長與重要生活事件。
**內容**:
- 教育經歷 (大學、進修)
- 職涯發展 (實習、工作、轉職、升遷)
- 人生大事 (結婚)
- 生活里程碑 (購車、購屋)
- 個人成就 (證照、獎項)
**事件數量**: 11 筆
**時間範圍**: 2015/09 - 2026/06
**適用場景**: 個人履歷、生涯規劃、回憶記錄
---
### 4. **demo_product_roadmap.csv** - 產品路線圖
新創公司產品發展的季度規劃。
**內容**:
- Q1 2024: MVP 開發、種子輪募資、團隊建立
- Q2 2024: v1.0 上線、用戶增長、A 輪準備
- Q3 2024: 新功能、A 輪完成、跨平台
- Q4 2024: v2.0 發布、國際擴展、目標達成
- 2025 展望: B 輪規劃、企業版
**事件數量**: 14 筆
**時間範圍**: 2024/01 - 2025/06
**適用場景**: 產品規劃、投資簡報、策略規劃
---
## 📊 CSV 欄位說明
| 欄位名稱 | 必填 | 說明 | 範例 |
|---------|------|------|------|
| **id** | ✅ | 事件唯一識別碼 | `event-001` |
| **title** | ✅ | 事件標題 | `專案啟動會議` |
| **start** | ✅ | 開始日期 | `2024-01-01` |
| **end** | ❌ | 結束日期(可選,不填則為單日事件) | `2024-01-05` |
| **group** | ❌ | 分組/分類(用於顏色區分) | `專案管理` |
| **description** | ❌ | 事件描述說明 | `確認專案目標與時程` |
| **color** | ❌ | 自訂顏色Hex 色碼) | `#3B82F6` |
---
## 🎨 色碼建議
以下是常用的色碼參考:
```
藍色系 (信任、科技)
#3B82F6 亮藍
#667EEA 柔和藍紫
綠色系 (成長、成功)
#10B981 翠綠
#22C55E 亮綠
黃色系 (警示、重要)
#F59E0B 琥珀黃
#FBBF24 金黃
紅色系 (緊急、里程碑)
#EF4444 亮紅
#DC2626 深紅
紫色系 (創新、高級)
#8B5CF6 紫羅蘭
#A78BFA 淺紫
粉色系 (溫馨、生活)
#EC4899 桃紅
#F472B6 淺粉
```
---
## 📅 日期格式支援
系統支援以下日期格式:
### ✅ 標準格式(推薦)
```
2024-01-01 ISO 8601 (YYYY-MM-DD)
2024-01-01 14:30:00 帶時間
```
### ✅ 其他支援格式
```
2024/01/01 斜線分隔
01/01/2024 月/日/年
2024-1-1 不補零
```
### ❌ 不支援格式
```
2024年1月1日 中文格式
Jan 1, 2024 英文月份
1st Jan 2024 序數日期
```
---
## 🚀 如何使用
### 方法 1: 使用模板建立新檔案
1. 複製 `template.csv` 並重新命名
2. 在 Excel 或文字編輯器中開啟
3. 刪除範例資料列
4. 填入您的事件資料
5. 儲存為 CSV 檔案
### 方法 2: 修改示範檔案
1. 選擇最接近您需求的示範檔案
2. 複製並重新命名
3. 修改事件內容、日期、群組等
4. 儲存檔案
### 方法 3: 從頭建立
建立新的 CSV 檔案,第一列必須包含欄位名稱:
```csv
id,title,start,end,group,description,color
```
---
## 💡 最佳實踐
### 1. ID 命名規則
```
✅ 推薦:
- event-001, event-002
- P001, P002 (專案)
- M001, M002 (里程碑)
❌ 避免:
- 1, 2, 3 (太簡短)
- 中文 ID
- 特殊符號
```
### 2. 分組策略
```
✅ 推薦:
- 按階段: 需求分析、開發、測試
- 按團隊: 前端組、後端組、設計組
- 按優先級: 高、中、低
❌ 避免:
- 過多分組 (建議 3-7 個)
- 分組名稱過長
```
### 3. 色彩運用
```
✅ 推薦:
- 相同分組使用相同色系
- 重要事件使用對比色
- 保持整體和諧
❌ 避免:
- 過於鮮豔刺眼
- 色彩過度混亂
- 對比度太低
```
---
## 📝 Excel 編輯注意事項
### 儲存設定
- **編碼**: 使用 UTF-8 (避免中文亂碼)
- **格式**: CSV (逗號分隔)
- **日期**: 設定為文字格式 (避免自動轉換)
### Excel 儲存步驟
1. 開啟 Excel
2. 編輯資料
3. 另存新檔 → CSV UTF-8 (逗號分隔)(*.csv)
4. 確認編碼為 UTF-8
---
## 🔍 常見問題
### Q1: 匯入後中文出現亂碼?
**A**: 檔案編碼問題,請確保使用 UTF-8 編碼儲存。
### Q2: 日期格式錯誤?
**A**: 請使用標準格式 `YYYY-MM-DD`,例如 `2024-01-01`
### Q3: 顏色沒有顯示?
**A**: 確認色碼格式為 `#` 開頭的 6 位 Hex 碼,例如 `#3B82F6`
### Q4: 單日事件如何設定?
**A**: 將 `end` 欄位留空,或設定與 `start` 相同日期。
### Q5: 可以匯入多少筆事件?
**A**: 理論上無限制,但建議單次匯入不超過 1000 筆以確保效能。
---
## 🎯 快速測試
想要快速測試系統功能?按照以下步驟:
### 步驟 1: 啟動系統
```bash
# 執行啟動腳本
start_dev.bat
# 或手動啟動
conda activate timeline_designer
uvicorn backend.main:app --reload --port 8000
# 新終端機
cd frontend-react
npm run dev
```
### 步驟 2: 開啟瀏覽器
訪問 http://localhost:12010
### 步驟 3: 匯入示範檔案
1. 拖曳 `demo_project_timeline.csv` 到上傳區
2. 點擊「生成時間軸」
3. 查看互動式圖表
4. 選擇格式與 DPI
5. 點擊「匯出」下載
---
## 📊 範例預覽
### 專案開發時間軸
- **15 個事件**,涵蓋完整開發週期
- **5 個分組**:專案管理、需求分析、研發、測試、部署
- **3 個里程碑**Alpha、Beta、正式上線
### 個人生活時間軸
- **11 個事件**,記錄 11 年生涯
- **5 個分組**:教育、職涯、旅遊、成就、人生大事
- **長時間跨度**:展示系統處理多年資料的能力
### 產品路線圖
- **14 個事件**,展示季度規劃
- **4 個分組**Q1-Q4 與未來展望
- **商業視角**:募資、產品、市場、目標
---
## 🛠️ 進階技巧
### 1. 批次建立事件
使用 Excel 公式快速生成 ID
```
=TEXT(ROW()-1,"event-000")
```
### 2. 日期序列
使用 Excel 的日期序列功能:
- 選取起始日期
- 拖曳填充把手
- Excel 會自動遞增日期
### 3. 色彩漸層
為不同階段設定漸層色彩:
```
階段 1: #3B82F6 (藍)
階段 2: #8B5CF6 (紫)
階段 3: #EC4899 (粉)
階段 4: #F59E0B (黃)
階段 5: #10B981 (綠)
```
---
## 📞 需要協助?
如有任何問題,請查閱:
- **使用手冊**: `README.md`
- **API 文檔**: http://localhost:8000/api/docs
- **技術文件**: `docs/` 目錄
---
**製作**: TimeLine Designer Team
**版本**: 1.0.0
**更新日期**: 2025-11-05

View File

@@ -1,97 +0,0 @@
# 顏色代碼參考
時間軸事件可以使用以下顏色代碼來標示不同類型的事件。
## 常用顏色代碼
### 主要顏色
| 顏色名稱 | 色碼 | 範例 | 適用情境 |
|---------|------|------|---------|
| 藍色 | `#3B82F6` | ![#3B82F6](https://via.placeholder.com/15/3B82F6/000000?text=+) | 一般事件、資訊類 |
| 綠色 | `#10B981` | ![#10B981](https://via.placeholder.com/15/10B981/000000?text=+) | 完成、成功、正面事件 |
| 黃色 | `#F59E0B` | ![#F59E0B](https://via.placeholder.com/15/F59E0B/000000?text=+) | 警告、待處理、重要提醒 |
| 紅色 | `#EF4444` | ![#EF4444](https://via.placeholder.com/15/EF4444/000000?text=+) | 緊急、錯誤、負面事件 |
| 紫色 | `#8B5CF6` | ![#8B5CF6](https://via.placeholder.com/15/8B5CF6/000000?text=+) | 特殊事件、里程碑 |
| 粉色 | `#EC4899` | ![#EC4899](https://via.placeholder.com/15/EC4899/000000?text=+) | 個人事件、慶祝活動 |
### 次要顏色
| 顏色名稱 | 色碼 | 範例 | 適用情境 |
|---------|------|------|---------|
| 靛藍色 | `#6366F1` | ![#6366F1](https://via.placeholder.com/15/6366F1/000000?text=+) | 專業、企業 |
| 青色 | `#06B6D4` | ![#06B6D4](https://via.placeholder.com/15/06B6D4/000000?text=+) | 清新、創新 |
| 橙色 | `#F97316` | ![#F97316](https://via.placeholder.com/15/F97316/000000?text=+) | 活力、創意 |
| 深灰色 | `#6B7280` | ![#6B7280](https://via.placeholder.com/15/6B7280/000000?text=+) | 中性、次要事件 |
### 淺色系(適合背景較深時使用)
| 顏色名稱 | 色碼 | 範例 | 適用情境 |
|---------|------|------|---------|
| 淺藍色 | `#93C5FD` | ![#93C5FD](https://via.placeholder.com/15/93C5FD/000000?text=+) | 柔和資訊 |
| 淺綠色 | `#6EE7B7` | ![#6EE7B7](https://via.placeholder.com/15/6EE7B7/000000?text=+) | 柔和成功 |
| 淺黃色 | `#FCD34D` | ![#FCD34D](https://via.placeholder.com/15/FCD34D/000000?text=+) | 柔和警告 |
| 淺紅色 | `#FCA5A5` | ![#FCA5A5](https://via.placeholder.com/15/FCA5A5/000000?text=+) | 柔和錯誤 |
## 使用方法
### 在 CSV 檔案中使用
在匯入的 CSV 檔案中,可以在 `color` 欄位指定顏色代碼:
```csv
id,title,start,end,description,color
1,專案啟動,2024-01-15 09:00:00,2024-01-15 10:00:00,啟動會議,#3B82F6
2,第一階段完成,2024-02-20 14:00:00,2024-02-20 15:00:00,完成開發,#10B981
3,重要里程碑,2024-03-10 10:00:00,2024-03-10 11:00:00,產品發布,#8B5CF6
4,緊急修復,2024-03-25 16:00:00,2024-03-25 17:00:00,修復重大 Bug,#EF4444
```
### 在 API 中使用
透過 API 新增事件時,在 `color` 欄位指定顏色代碼:
```json
{
"id": "event_001",
"title": "專案啟動",
"start": "2024-01-15T09:00:00",
"description": "啟動會議",
"color": "#3B82F6"
}
```
## 顏色選擇建議
### 專案時間軸
- **規劃階段**: `#6366F1` (靛藍色)
- **開發階段**: `#3B82F6` (藍色)
- **測試階段**: `#F59E0B` (黃色)
- **完成階段**: `#10B981` (綠色)
- **問題修復**: `#EF4444` (紅色)
### 個人履歷
- **教育經歷**: `#8B5CF6` (紫色)
- **工作經歷**: `#3B82F6` (藍色)
- **重要成就**: `#10B981` (綠色)
- **證書認證**: `#F59E0B` (黃色)
### 產品路線圖
- **研發中**: `#06B6D4` (青色)
- **即將發布**: `#F59E0B` (黃色)
- **已發布**: `#10B981` (綠色)
- **已棄用**: `#6B7280` (深灰色)
## 注意事項
1. **色碼格式**: 必須使用 `#` 開頭的 6 位元 16 進位色碼(如 `#3B82F6`
2. **顏色對比**: 確保文字與背景有足夠對比度,避免閱讀困難
3. **色彩意義**: 建議在同一時間軸中保持色彩意義的一致性
4. **無障礙**: 不要僅依賴顏色區分重要資訊,建議搭配文字說明
## 自訂顏色
如果需要使用其他顏色,可以使用線上工具選擇:
- [Google Color Picker](https://g.co/kgs/colorpicker)
- [Adobe Color](https://color.adobe.com/zh/create/color-wheel)
- [Coolors.co](https://coolors.co/)
選擇顏色後,複製色碼(格式:`#RRGGBB`)即可使用。

View File

@@ -1,18 +0,0 @@
# TimeLine Designer - Core Dependencies (Python 3.13 compatible)
# Web Framework
fastapi==0.115.6
uvicorn[standard]==0.34.0
python-multipart==0.0.20
# Data Validation
pydantic==2.10.5
pydantic-settings==2.7.1
# Testing
pytest==8.3.4
pytest-asyncio==0.25.2
pytest-cov==6.0.0
# Utilities
python-dateutil==2.9.0.post0

View File

@@ -1,13 +1,15 @@
# TimeLine Designer - Python Dependencies
# Version: 1.0.0
# Compatible with Python 3.8 - 3.13
# Web Framework
fastapi==0.104.1
uvicorn[standard]==0.24.0
python-multipart==0.0.6
fastapi==0.115.6
uvicorn[standard]==0.34.0
python-multipart==0.0.20
# Data Validation
pydantic==2.5.0
pydantic==2.10.5
pydantic-settings==2.7.1
# Data Processing
pandas==2.1.3
@@ -21,9 +23,9 @@ kaleido==1.2.0
pywebview==4.4.1
# Testing
pytest==7.4.3
pytest-asyncio==0.21.1
pytest-cov==4.1.0
pytest==8.3.4
pytest-asyncio==0.25.2
pytest-cov==6.0.0
pytest-benchmark==4.0.0
playwright==1.40.0
@@ -33,4 +35,4 @@ mypy==1.7.1
bandit==1.7.5
# Utilities
python-dateutil==2.8.2
python-dateutil==2.9.0.post0