# 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