diff --git a/README.md b/README.md new file mode 100644 index 0000000..917c980 --- /dev/null +++ b/README.md @@ -0,0 +1,171 @@ +# PROJECT CONTROL + +跨部門專案管理系統 - 支援多維度任務追蹤、資源負載管理與即時協作。 + +## 功能特色 + +### 任務管理 +- **多層級架構**: 空間 (Space) → 專案 (Project) → 任務 (Task) → 子任務 (SubTask) +- **多維視角**: 看板 (Kanban)、甘特圖 (Gantt)、行事曆 (Calendar)、列表 (List) +- **自訂欄位**: 下拉選單、公式計算、人員標籤、日期欄位 +- **任務依賴**: 支援 FS/SS/FF/SF 四種依賴類型，自動循環檢測 + +### 資源管理 +- **工作負載熱力圖**: 視覺化團隊工作分配 +- **容量規劃**: 個人週時數設定與超載警示 +- **專案健康度**: 風險評分與預警機制 + +### 協作功能 +- **即時同步**: WebSocket 實現多人即時協作 +- **評論系統**: 支援 @mention 通知 +- **阻礙追蹤**: 任務阻礙管理與通知 + +### 安全與合規 +- **稽核日誌**: 完整操作歷史追蹤 +- **檔案加密**: AES-256 加密機密專案附件 +- **CSRF 保護**: 跨站請求偽造防護 +- **RBAC**: 角色權限控制 + +## 系統架構 + +``` +┌─────────────────┐ ┌─────────────────┐ +│ Frontend │────▶│ Backend │ +│ React + TS │ │ FastAPI │ +│ Port: 5173 │ │ Port: 8000 │ +└─────────────────┘ └────────┬────────┘ + │ + ┌────────────┼────────────┐ + ▼ ▼ ▼ + ┌─────────┐ ┌─────────┐ ┌─────────┐ + │ MySQL │ │ Redis │ │ Files │ + │ DB │ │ Cache │ │ Storage │ + └─────────┘ └─────────┘ └─────────┘ +``` + +## 快速開始 + +### 系統需求 + +| 軟體 | 版本 | +|------|------| +| Node.js | 18+ | +| Python | 3.11+ | +| MySQL | 8.0+ | +| Redis | 6.0+ | + +### 安裝步驟 + +```bash +# 1. 複製專案 +git clone +cd PROJECT\ CONTORL + +# 2. 後端設定 +cd backend +cp .env.example .env +# 編輯 .env 設定資料庫連線 +pip install -r requirements.txt +alembic upgrade head +uvicorn app.main:app --reload --port 8000 + +# 3. 前端設定 (另開終端) +cd frontend +npm install +npm run dev +``` + +### 存取服務 + +| 服務 | 網址 | +|------|------| +| 前端應用 | http://localhost:5173 | +| 後端 API | http://localhost:8000 | +| API 文件 | http://localhost:8000/docs | + +## 專案結構 + +``` +PROJECT CONTORL/ +├── backend/ # FastAPI 後端 +│ ├── app/ # 應用程式碼 +│ ├── migrations/ # 資料庫遷移 +│ └── tests/ # 測試檔案 +├── frontend/ # React 前端 +│ ├── src/ # 原始碼 +│ └── public/ # 靜態資源 +├── openspec/ # OpenSpec 規格文件 +│ ├── specs/ # 功能規格 +│ └── changes/ # 變更提案 +├── DEPLOYMENT.md # 部署指南 +├── USER_MANUAL.md # 使用者手冊 +└── README.md # 本文件 +``` + +## 文件索引 + +| 文件 | 說明 | +|------|------| +| [backend/README.md](backend/README.md) | 後端開發指南 | +| [frontend/README.md](frontend/README.md) | 前端開發指南 | +| [DEPLOYMENT.md](DEPLOYMENT.md) | 生產環境部署 | +| [USER_MANUAL.md](USER_MANUAL.md) | 使用者操作手冊 | + +## 技術棧 + +### 前端 +- React 18 + TypeScript +- Vite (建置工具) +- react-i18next (國際化) +- WebSocket (即時同步) + +### 後端 +- FastAPI (Web 框架) +- SQLAlchemy 2.0 (ORM) +- Alembic (資料庫遷移) +- Redis (快取/Session) + +### 基礎設施 +- MySQL 8.0 (主資料庫) +- Redis 6.0 (快取層) +- JWT (認證) + +## 開發指令 + +### 後端 + +```bash +cd backend + +# 執行測試 +pytest -v + +# 執行開發伺服器 +uvicorn app.main:app --reload + +# 資料庫遷移 +alembic upgrade head +``` + +### 前端 + +```bash +cd frontend + +# 開發模式 +npm run dev + +# 建置生產版本 +npm run build + +# 程式碼檢查 +npm run lint +``` + +## 授權 + +此專案為私有專案，未經授權禁止使用。 + +## 聯絡資訊 + +如有問題，請聯繫系統管理員。 diff --git a/USER_MANUAL.md b/USER_MANUAL.md new file mode 100644 index 0000000..1811ee4 --- /dev/null +++ b/USER_MANUAL.md @@ -0,0 +1,420 @@ +# PROJECT CONTROL 使用者手冊 + +## 目錄 + +1. [系統概述](#系統概述) +2. [登入與帳戶](#登入與帳戶) +3. [儀表板](#儀表板) +4. [空間與專案管理](#空間與專案管理) +5. [任務管理](#任務管理) +6. [工作負載管理](#工作負載管理) +7. [稽核日誌](#稽核日誌) +8. [個人設定](#個人設定) +9. [常見問題](#常見問題) + +--- + +## 系統概述 + +PROJECT CONTROL 是一個跨部門專案管理系統，提供以下核心功能： + +- **專案組織**: 透過空間和專案層級管理工作 +- **任務追蹤**: 多種視角管理任務 (看板、甘特圖、行事曆、列表) +- **團隊協作**: 即時同步、評論、@mention 通知 +- **資源規劃**: 工作負載視覺化與容量管理 +- **合規追蹤**: 完整稽核日誌 + +--- + +## 登入與帳戶 + +### 登入系統 + +1. 開啟瀏覽器，前往系統網址 +2. 輸入您的公司郵箱和密碼 +3. 點擊「登入」按鈕 + +### 登出系統 + +點擊右上角的使用者圖示，選擇「登出」 + +### Session 管理 + +- 系統會自動保持登入狀態 +- Token 每 60 分鐘自動刷新 +- 長時間不活動後需重新登入 + +--- + +## 儀表板 + +登入後首先看到的是儀表板頁面，顯示您的工作概覽。 + +### 統計卡片 + +| 卡片 | 說明 | +|------|------| +| 總任務數 | 指派給您的所有任務 | +| 本週到期 | 本週內需完成的任務 | +| 已逾期 | 超過截止日期的任務 | +| 完成率 | 已完成任務的百分比 | + +### 我的工作負載 + +顯示您本週的工時分配： +- **分配時數**: 已安排的工作時數 +- **容量時數**: 您的週工時上限 +- **負載百分比**: 工作量佔比 +- **狀態**: 正常 / 警告 / 超載 + +### 專案健康摘要 + +顯示您參與專案的健康狀況： +- 健康 (綠色) +- 風險中 (黃色) +- 危機 (紅色) + +### 快速操作 + +提供常用功能的快速連結： +- 前往空間頁面 +- 查看工作負載 +- 查看專案健康度 +- 稽核日誌 (僅管理員) + +--- + +## 空間與專案管理 + +### 空間 (Space) + +空間是最高層級的組織單位，通常代表一個部門或業務線。 + +#### 建立空間 + +1. 前往「空間」頁面 +2. 點擊「新增空間」按鈕 +3. 輸入空間名稱和描述 +4. 點擊「建立」 + +#### 管理空間 + +- **編輯**: 點擊空間卡片上的編輯圖示 +- **刪除**: 點擊刪除圖示 (需確認，會刪除所有內含專案) + +### 專案 (Project) + +專案存在於空間之下，代表一個具體的工作項目。 + +#### 建立專案 + +1. 進入目標空間 +2. 點擊「新增專案」 +3. 填寫專案資訊： + - 名稱 (必填) + - 描述 + - 開始日期 + - 結束日期 + - 安全等級 +4. 點擊「建立」 + +#### 專案設定 + +點擊專案後，可進入專案設定頁面： + +##### 任務狀態 + +自訂任務流程狀態： +1. 點擊「任務狀態」標籤 +2. 新增/編輯/刪除狀態 +3. 拖曳調整狀態順序 + +##### 自訂欄位 + +為任務新增額外欄位： + +| 類型 | 說明 | 範例 | +|------|------|------| +| 文字 | 單行文字輸入 | 備註 | +| 數字 | 數值輸入 | 預估工時 | +| 日期 | 日期選擇 | 實際完成日 | +| 下拉選單 | 預設選項 | 優先級、類別 | +| 人員 | 選擇團隊成員 | 審核人 | +| 公式 | 自動計算 | 完成率 | + +##### 專案成員 + +管理專案成員： +1. 點擊「成員」標籤 +2. 點擊「新增成員」 +3. 搜尋並選擇使用者 +4. 設定角色 (Owner/Manager/Member) + +--- + +## 任務管理 + +### 任務視角 + +系統提供四種任務視角，可透過頁面上方的切換按鈕選擇： + +#### 看板視角 (Kanban) + +- 任務以卡片形式顯示 +- 依狀態分欄 +- **拖曳** 卡片可改變狀態 +- 適合敏捷開發流程 + +#### 甘特圖視角 (Gantt) + +- 時間軸視覺化 +- 顯示任務依賴關係 +- **拖曳** 可調整日期 +- 適合專案時程規劃 + +#### 行事曆視角 (Calendar) + +- 月曆格式顯示 +- 依到期日安排 +- 點擊日期可新增任務 +- 適合日程管理 + +#### 列表視角 (List) + +- 表格格式顯示 +- 支援排序和篩選 +- 可自訂顯示欄位 +- 適合大量任務管理 + +### 建立任務 + +1. 點擊「新增任務」按鈕 +2. 填寫任務資訊： + - **標題** (必填，最多 500 字) + - **描述** (最多 10,000 字) + - **負責人** + - **狀態** + - **優先級**: 低/中/高/緊急 + - **開始日期** + - **到期日期** + - **預估工時** +3. 點擊「建立」 + +### 編輯任務 + +1. 點擊任務開啟詳細視窗 +2. 修改所需欄位 +3. 變更會自動儲存 + +### 任務詳細視窗 + +#### 基本資訊 + +- 標題、描述、狀態、負責人等 + +#### 子任務 + +建立更細緻的工作拆分： +1. 在詳細視窗中展開「子任務」區塊 +2. 點擊「新增子任務」 +3. 輸入子任務標題 +4. 子任務完成會自動更新父任務進度 + +#### 評論 + +與團隊成員溝通： +1. 在「評論」區塊輸入訊息 +2. 使用 `@使用者名稱` 標記特定人員 +3. 被標記者會收到通知 + +#### 附件 + +上傳相關檔案： +1. 點擊「上傳附件」 +2. 選擇檔案 (最大 50MB) +3. 支援版本控制 +4. 機密專案附件會自動加密 + +#### 阻礙管理 + +當任務遭遇阻礙時： +1. 點擊「標記為阻礙」 +2. 輸入阻礙原因 +3. 主管會收到通知 +4. 解決後點擊「解除阻礙」 + +### 任務依賴 + +設定任務間的依賴關係： + +1. 在甘特圖視角中選擇任務 +2. 點擊「新增依賴」 +3. 選擇前置任務 +4. 選擇依賴類型： + - **FS (Finish-to-Start)**: 前置完成後才能開始 + - **SS (Start-to-Start)**: 同時開始 + - **FF (Finish-to-Finish)**: 同時完成 + - **SF (Start-to-Finish)**: 前置開始後才能完成 + +> ⚠️ 系統會自動檢測循環依賴並阻止建立 + +--- + +## 工作負載管理 + +### 工作負載熱力圖 + +視覺化顯示團隊成員的工作分配： + +#### 顏色說明 + +| 顏色 | 負載範圍 | 狀態 | +|------|----------|------| +| 綠色 | 0-80% | 正常 | +| 黃色 | 80-100% | 警告 | +| 紅色 | >100% | 超載 | + +#### 週導航 + +- 使用左右箭頭切換週次 +- 點擊「今天」回到當前週 + +#### 部門篩選 + +- 管理員可查看所有部門 +- 一般使用者僅能查看自己部門 + +### 容量設定 + +設定個人週工時上限： + +1. 前往「個人設定」 +2. 找到「週工時容量」 +3. 輸入每週可用工時 (預設 40 小時) +4. 點擊「儲存」 + +--- + +## 稽核日誌 + +> 此功能僅限系統管理員使用 + +### 查看稽核日誌 + +1. 從儀表板點擊「稽核日誌」 +2. 或從側邊欄選擇「稽核」 + +### 篩選條件 + +| 篩選項 | 說明 | +|--------|------| +| 日期範圍 | 選擇開始和結束日期 | +| 事件類型 | 建立/更新/刪除/登入等 | +| 資源類型 | 任務/專案/使用者等 | +| 使用者 | 特定操作者 | +| 敏感度 | 低/中/高 | + +### 匯出報告 + +1. 設定篩選條件 +2. 點擊「匯出 PDF」 +3. 系統會產生可列印的報告 + +### 完整性驗證 + +驗證稽核日誌是否被竄改： + +1. 點擊「驗證完整性」 +2. 選擇日期範圍 +3. 系統會檢查所有日誌的校驗碼 +4. 顯示驗證結果 + +--- + +## 個人設定 + +### 存取設定 + +1. 點擊右上角使用者圖示 +2. 選擇「設定」 + +### 可設定項目 + +#### 基本資料 + +- 顯示名稱 (唯讀) +- 電子郵件 (唯讀) +- 部門 (唯讀) + +#### 工作設定 + +- **週工時容量**: 每週可用工時 +- **週報訂閱**: 是否接收每週工作報告 + +#### 語言設定 + +切換系統語言： +- English (英文) +- 繁體中文 + +--- + +## 常見問題 + +### Q: 忘記密碼怎麼辦？ + +請聯繫系統管理員重設密碼。 + +### Q: 為什麼我看不到某些專案？ + +專案的可見性受以下因素影響： +- 您的部門 +- 專案的安全等級設定 +- 您是否為專案成員 + +請聯繫專案負責人將您加入專案。 + +### Q: 任務狀態無法拖曳？ + +請確認： +1. 您有該任務的編輯權限 +2. 網路連線正常 +3. 嘗試重新整理頁面 + +### Q: 附件上傳失敗？ + +請確認： +1. 檔案大小不超過 50MB +2. 檔案類型未被系統封鎖 (如 .exe) +3. 網路連線穩定 + +### Q: 即時同步不工作？ + +1. 檢查網路連線 +2. 重新整理頁面 +3. 檢查瀏覽器是否支援 WebSocket +4. 清除瀏覽器快取 + +### Q: 如何聯繫技術支援？ + +請聯繫您的系統管理員或 IT 部門。 + +--- + +## 快捷鍵 + +| 快捷鍵 | 功能 | +|--------|------| +| `Esc` | 關閉彈窗/取消操作 | +| `Enter` | 確認/提交 | + +--- + +## 版本資訊 + +- **版本**: 1.0.0 +- **最後更新**: 2024 年 1 月 + +--- + +*此手冊會隨系統更新而更新，請定期查閱最新版本。* diff --git a/backend/README.md b/backend/README.md index 3da950e..c2fcc1d 100644 --- a/backend/README.md +++ b/backend/README.md @@ -1,6 +1,16 @@ -# PROJECT CONTROL Backend +# PROJECT CONTROL - Backend -FastAPI 後端服務 +FastAPI 後端服務，提供跨部門專案管理系統的 RESTful API。 + +## 技術架構 + +| 技術 | 版本 | 用途 | +|------|------|------| +| FastAPI | 0.109+ | Web 框架 | +| SQLAlchemy | 2.0+ | ORM | +| Alembic | 1.13+ | 資料庫遷移 | +| Redis | 6.0+ | 快取與 Session | +| MySQL | 8.0+ | 主資料庫 | ## 系統需求 @@ -10,35 +20,53 @@ FastAPI 後端服務 |-----|------|-----| | Python | 3.11+ | 執行環境 | | MySQL | 8.0+ | 主要資料庫 | -| Redis | 6.0+ | Session 存儲 | +| Redis | 6.0+ | Session 與快取 | ### Redis Server 安裝 -Redis Python 套件 (`redis==5.0.1`) 僅為客戶端，需另外安裝 Redis Server： - -**macOS (Homebrew):** ```bash +# macOS (Homebrew) brew install redis brew services start redis -``` -**Ubuntu/Debian:** -```bash -sudo apt update -sudo apt install redis-server +# Ubuntu/Debian +sudo apt update && sudo apt install redis-server sudo systemctl start redis-server -sudo systemctl enable redis-server -``` -**Docker:** -```bash +# Docker docker run -d --name redis -p 6379:6379 redis:alpine + +# 驗證安裝 +redis-cli ping # 應回傳 PONG ``` -**驗證安裝:** -```bash -redis-cli ping -# 應回傳 PONG +## 專案結構 + +``` +backend/ +├── app/ +│ ├── api/ # API 路由 +│ │ ├── auth/ # 認證 (登入/登出/JWT) +│ │ ├── tasks/ # 任務管理 +│ │ ├── projects/ # 專案管理 +│ │ ├── workload/ # 工作負載 +│ │ ├── audit/ # 稽核日誌 +│ │ ├── websocket/ # WebSocket 即時同步 +│ │ └── ... +│ ├── core/ # 核心配置 +│ │ ├── config.py # 環境設定 +│ │ ├── security.py # 安全性 (JWT/CSRF) +│ │ └── database.py # 資料庫連線 +│ ├── middleware/ # 中間件 +│ │ ├── csrf.py # CSRF 保護 +│ │ ├── security_audit.py # 安全稽核 +│ │ └── error_sanitizer.py # 錯誤訊息淨化 +│ ├── models/ # SQLAlchemy 模型 +│ ├── schemas/ # Pydantic 結構 +│ └── services/ # 業務邏輯 +├── migrations/ # Alembic 遷移檔 +├── tests/ # 測試檔案 +└── uploads/ # 附件上傳目錄 ``` ## 環境建置 @@ -60,19 +88,23 @@ cp .env.example .env ``` 主要設定項目： -- `MYSQL_*` - 資料庫連線 -- `REDIS_*` - Redis 連線 -- `JWT_SECRET_KEY` - JWT 簽名密鑰 (生產環境必須更換) -- `AUTH_API_URL` - 外部認證 API +| 變數 | 說明 | +|------|------| +| `MYSQL_*` | 資料庫連線設定 | +| `REDIS_*` | Redis 連線設定 | +| `JWT_SECRET_KEY` | JWT 簽名密鑰 (生產環境必須更換) | +| `JWT_EXPIRE_MINUTES` | JWT 過期時間 (預設 60 分鐘) | +| `AUTH_API_URL` | 外部認證 API | +| `ENVIRONMENT` | 環境 (development/production) | ## 執行 ```bash -# 開發模式 +# 開發模式 (自動重載) uvicorn app.main:app --reload --port 8000 # 生產模式 -uvicorn app.main:app --host 0.0.0.0 --port 8000 +gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 ``` ## 資料庫遷移 @@ -83,10 +115,62 @@ alembic upgrade head # 回滾一個版本 alembic downgrade -1 + +# 產生新遷移 +alembic revision --autogenerate -m "描述" ``` +## API 文件 + +啟動服務後可存取： +- **Swagger UI**: http://localhost:8000/docs +- **ReDoc**: http://localhost:8000/redoc + ## 測試 ```bash +# 執行所有測試 pytest -v + +# 執行特定測試 +pytest tests/test_auth.py -v + +# 查看測試覆蓋率 +pytest --cov=app tests/ ``` + +## 主要功能模組 + +### 認證與授權 +- JWT Token 認證 (60 分鐘過期) +- Refresh Token 支援 (7 天過期) +- CSRF 保護 (POST/PUT/PATCH/DELETE) +- 速率限制 (標準 60/分鐘) + +### 任務管理 +- 多層級架構 (Space > Project > Task > SubTask) +- 自訂欄位 (下拉、公式、人員、日期) +- 任務依賴與循環檢測 +- 軟刪除與級聯還原 +- 樂觀鎖定並發控制 + +### 即時協作 +- WebSocket 專案頻道 +- 任務狀態即時同步 +- 通知推播 + +### 安全性 +- 輸入長度驗證 +- SQL 注入防護 +- XSS 防護 +- 錯誤訊息淨化 (生產環境) +- 安全事件稽核日誌 + +## 健康檢查端點 + +| 端點 | 認證 | 說明 | +|------|------|------| +| `GET /health` | 否 | 基本健康狀態 | +| `GET /health/live` | 否 | 存活探針 | +| `GET /health/ready` | 否 | 就緒探針 | +| `GET /health/detailed` | 管理員 | 詳細系統狀態 |