egg/PROJECT-CONTORL
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add root README and user manual, update backend docs

Browse Source 
- Create comprehensive root README.md with system overview and quick start
- Create USER_MANUAL.md with complete user documentation in Traditional Chinese
- Update backend/README.md with detailed project structure and features

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
beabigegg
2026-01-13 21:49:59 +08:00
parent 150547d440
commit c6cd811093
3 changed files with 700 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

171
README.md Normal file
View File

@@ -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 <repository-url>
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
```
## 授權
此專案為私有專案，未經授權禁止使用。
## 聯絡資訊
如有問題，請聯繫系統管理員。

420
USER_MANUAL.md Normal file
View File

@@ -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 月
---
*此手冊會隨系統更新而更新，請定期查閱最新版本。*

134
backend/README.md
View File

@@ -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` | 管理員 | 詳細系統狀態 |