docs: add root README and user manual, update backend docs
- 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
171
README.md
Normal file
171
README.md
Normal 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
420
USER_MANUAL.md
Normal 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 月
|
||||
|
||||
---
|
||||
|
||||
*此手冊會隨系統更新而更新，請定期查閱最新版本。*
|
||||
@@ -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` | 管理員 | 詳細系統狀態 |
|
||||
|
||||
Reference in New Issue
Block a user