From dc01655c9ef1afeff876930140854cbd05945046 Mon Sep 17 00:00:00 2001 From: beabigegg Date: Thu, 6 Nov 2025 12:12:49 +0800 Subject: [PATCH] =?UTF-8?q?=E7=B0=A1=E5=8C=96=20README.md=EF=BC=9A?= =?UTF-8?q?=E7=A7=BB=E9=99=A4=E9=96=8B=E7=99=BC=E7=9B=B8=E9=97=9C=E5=85=A7?= =?UTF-8?q?=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 主要變更： - 移除開發相關章節 - 刪除「專案架構」說明 - 刪除「執行測試」指南 - 刪除「API 文檔」章節 - 刪除「主題系統」說明（前端未實現切換） - 刪除「開發指南」（VIBE、TDD等） - 刪除「程式碼檢查」工具說明 - 刪除「效能指標」KPI - 刪除「致謝」套件列表 - 簡化使用者導向內容 - 更新主要特性說明，移除未實現功能 - 簡化啟動方式，提供腳本啟動教學 - 保留核心使用說明和示範檔案資訊 - 簡化問題回報資訊 - 最終結果 - README 僅保留使用者需要的資訊 - 移除所有開發者專用內容 - 文檔更加簡潔易懂 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- README.md | 173 ++++++++---------------------------------------------- 1 file changed, 23 insertions(+), 150 deletions(-) diff --git a/README.md b/README.md index 752d694..f7b2a77 100644 --- a/README.md +++ b/README.md @@ -2,53 +2,51 @@ > 輕鬆建立專業的時間軸圖表 -TimeLine Designer 是一款桌面應用程式，讓您能夠輕鬆匯入事件資料並生成高品質的時間軸圖表。支援 CSV/XLSX 匯入，可匯出為 PNG、PDF、SVG 等多種格式。 +TimeLine Designer 是一款時間軸生成工具，讓您能夠輕鬆匯入事件資料並生成高品質的時間軸圖表。支援 CSV/XLSX 匯入，可匯出為 PNG、PDF、SVG 等多種格式。 ## ✨ 主要特性 -- **零程式門檻** - 直覺的 GUI 操作介面 -- **快速渲染** - 100 筆事件 < 2 秒 +- **零程式門檻** - 直覺的 Web 操作介面 +- **快速渲染** - 快速生成時間軸圖表 - **高解析輸出** - 支援 300 DPI 印刷品質 - **多格式匯出** - PNG / PDF / SVG -- **跨平台支援** - Windows / macOS -- **主題系統** - 多種視覺主題可選 -- **智能刻度** - 自動調整時間刻度單位 +- **互動式操作** - 支援縮放、拖曳、懸停查看詳情 ## 🚀 快速開始 ### 環境需求 - Python 3.8 或以上版本 +- Node.js 16 或以上版本（前端需要） - Windows 10/11 或 macOS 10.14+ -### 安裝步驟 +### 啟動應用程式 -1. **克隆專案** +**方法 1：使用啟動腳本（推薦）** ```bash -git clone -cd Timeline_Generator -``` - -2. **建立虛擬環境** -```bash -python -m venv venv - # Windows -venv\Scripts\activate +start_dev.bat -# macOS/Linux -source venv/bin/activate +# 系統會自動啟動： +# - 後端 API: http://localhost:8000 +# - 前端介面: http://localhost:12010 ``` -3. **安裝依賴** +**方法 2：手動啟動** ```bash +# 1. 安裝 Python 依賴 pip install -r requirements.txt + +# 2. 啟動後端 (終端 1) +uvicorn backend.main:app --reload --port 8000 + +# 3. 啟動前端 (終端 2) +cd frontend-react +npm install +npm run dev ``` -4. **啟動應用程式** -```bash -python app.py -``` +啟動後，在瀏覽器打開 `http://localhost:12010` 即可使用 ## 📖 使用說明 @@ -125,141 +123,16 @@ evt-002,需求分析,2024-01-02 09:00:00,2024-01-05 18:00:00,Phase 1,收集並 - **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 版本 +2. Python 與 Node.js 版本 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