364 lines
8.8 KiB
Markdown
364 lines
8.8 KiB
Markdown
# PANJIT To-Do 專案管理系統
|
||
|
||
一套完整的企業級待辦事項管理系統，支援AD認證、郵件通知、Excel匯入匯出等功能。
|
||
|
||
## 🚀 功能特色
|
||
|
||
### 核心功能
|
||
- **待辦事項管理**：新增、編輯、刪除、狀態管理
|
||
- **多重視圖**：列表視圖、日曆視圖、看板視圖
|
||
- **權限控制**：創建者、負責人、追蹤者角色管理
|
||
- **狀態追蹤**：新建立、進行中、已阻塞、已完成
|
||
|
||
### 身份認證
|
||
- **AD 整合**：支援Active Directory單一登入
|
||
- **角色權限**：管理員、一般使用者權限管控
|
||
- **安全防護**：JWT Token認證機制
|
||
|
||
### 通知系統
|
||
- **郵件通知**：狀態變更、到期提醒自動通知
|
||
- **即時推播**：系統內通知面板
|
||
- **自定義設定**：個人化通知偏好
|
||
|
||
### 資料處理
|
||
- **Excel 匯入**：批量匯入待辦事項
|
||
- **Excel 匯出**：支援多種匯出格式
|
||
- **報表功能**：統計分析報表
|
||
|
||
### 使用者介面
|
||
- **響應式設計**：支援桌面、平板、手機
|
||
- **深色模式**：亮色/暗色/自動切換
|
||
- **多語言支援**：繁體中文介面
|
||
- **動畫效果**：流暢的使用者體驗
|
||
|
||
## 🛠 技術架構
|
||
|
||
### 端口配置
|
||
|
||
#### 主要服務端口
|
||
- **前端服務**：Port 12012 (Next.js)
|
||
- **後端 API**：Port 12011 (Flask)
|
||
- **資料庫**：Port 33306 (MySQL)
|
||
|
||
#### 外部依賴端口
|
||
- **快取系統**：Port 6379 (Redis)
|
||
- **LDAP 服務**：Port 389
|
||
- **郵件服務**：Port 25 (SMTP)
|
||
|
||
> 📝 **註意**：所有主要服務端口已調整到 12010-12019 範圍內，符合企業環境統一規範。
|
||
|
||
### 前端技術棧
|
||
- **框架**：Next.js 14 (React 18)
|
||
- **UI 庫**：Material-UI (MUI) 5
|
||
- **狀態管理**：Redux Toolkit + React Query
|
||
- **樣式方案**：Emotion + CSS-in-JS
|
||
- **動畫庫**：Framer Motion
|
||
- **類型檢查**：TypeScript
|
||
- **構建工具**：Next.js + SWC
|
||
|
||
### 後端技術棧
|
||
- **框架**：Flask 2.3
|
||
- **資料庫**：MySQL + SQLAlchemy ORM
|
||
- **認證系統**：Flask-JWT-Extended
|
||
- **LDAP 整合**：ldap3 (Windows 相容)
|
||
- **任務佇列**：Celery + Redis
|
||
- **郵件服務**：Flask-Mail + SMTP
|
||
- **檔案處理**：pandas + openpyxl
|
||
- **API 文檔**：Flask-RESTful
|
||
|
||
### 基礎設施
|
||
- **資料庫**：MySQL 8.0
|
||
- **快取系統**：Redis
|
||
- **檔案儲存**：本地檔案系統
|
||
- **日誌管理**：colorlog
|
||
- **部署環境**：Windows Server
|
||
|
||
## 📋 系統需求
|
||
|
||
### 開發環境
|
||
- **Node.js**：16.x 或以上版本
|
||
- **Python**：3.10 或以上版本
|
||
- **MySQL**：8.0 或以上版本
|
||
- **Redis**：6.0 或以上版本
|
||
|
||
### 生產環境
|
||
- **作業系統**：Windows Server 2016+ 或 Linux
|
||
- **記憶體**：最低 4GB，建議 8GB
|
||
- **磁碟空間**：最低 10GB
|
||
- **網路**：可連接 SMTP 和 LDAP 伺服器
|
||
|
||
## 🚀 快速開始
|
||
|
||
### 1. 專案複製
|
||
```bash
|
||
git clone <repository-url>
|
||
cd TODOLIST
|
||
```
|
||
|
||
### 2. 後端設置
|
||
```bash
|
||
# 進入後端目錄
|
||
cd backend
|
||
|
||
# 建立虛擬環境 (Windows)
|
||
python -m venv venv
|
||
venv\Scripts\activate
|
||
|
||
# 安裝依賴
|
||
pip install -r requirements.txt
|
||
|
||
# 設置環境變數
|
||
copy .env.example .env
|
||
# 編輯 .env 文件，填入正確的設定值
|
||
|
||
# 初始化資料庫
|
||
python init_db.py
|
||
|
||
# 啟動後端服務 (現使用 port 12011)
|
||
python app.py
|
||
```
|
||
|
||
### 3. 前端設置
|
||
```bash
|
||
# 進入前端目錄
|
||
cd frontend
|
||
|
||
# 安裝依賴
|
||
npm install
|
||
|
||
# 設置環境變數
|
||
copy .env.example .env.local
|
||
# 編輯 .env.local 文件
|
||
|
||
# 啟動開發服務器 (現使用 port 12012)
|
||
npm run dev
|
||
|
||
# 生產環境部署
|
||
npm run build
|
||
npm run start
|
||
```
|
||
|
||
### 4. 背景任務 (可選)
|
||
```bash
|
||
# 在另一個終端啟動 Celery Worker
|
||
cd backend
|
||
celery -A celery_app worker --loglevel=info
|
||
|
||
# 啟動任務調度器
|
||
celery -A celery_app beat --loglevel=info
|
||
```
|
||
|
||
## ⚙️ 設定說明
|
||
|
||
### 環境變數配置
|
||
|
||
#### 後端設定 (backend/.env)
|
||
```env
|
||
# 資料庫連線
|
||
DATABASE_URL=mysql+pymysql://username:password@host:port/database
|
||
MYSQL_HOST=mysql.example.com
|
||
MYSQL_PORT=33306
|
||
MYSQL_USER=your_user
|
||
MYSQL_PASSWORD=your_password
|
||
MYSQL_DATABASE=your_database
|
||
|
||
# JWT 設定
|
||
JWT_SECRET_KEY=your-super-secret-key
|
||
JWT_ACCESS_TOKEN_EXPIRES=86400
|
||
|
||
# LDAP 設定
|
||
LDAP_SERVER=your-ldap-server.com
|
||
LDAP_PORT=389
|
||
LDAP_BIND_USER_DN=CN=ServiceAccount,CN=Users,DC=example,DC=com
|
||
LDAP_BIND_USER_PASSWORD=service_password
|
||
LDAP_SEARCH_BASE=OU=Users,DC=example,DC=com
|
||
|
||
# SMTP 設定
|
||
SMTP_SERVER=smtp.example.com
|
||
SMTP_PORT=25
|
||
SMTP_SENDER_EMAIL=noreply@example.com
|
||
|
||
# Redis 設定
|
||
REDIS_URL=redis://localhost:6379/0
|
||
|
||
# CORS 設定
|
||
CORS_ORIGINS=http://localhost:12012
|
||
```
|
||
|
||
#### 前端設定 (frontend/.env.local)
|
||
```env
|
||
# 後端 API 設定
|
||
NEXT_PUBLIC_API_URL=http://localhost:12011
|
||
NEXT_PUBLIC_BACKEND_URL=http://localhost:12011
|
||
|
||
# 應用基本設定
|
||
NEXT_PUBLIC_APP_NAME=PANJIT To-Do System
|
||
NODE_ENV=development
|
||
|
||
# CORS 設定
|
||
NEXT_PUBLIC_ALLOWED_ORIGINS=http://localhost:12012,http://localhost:12011
|
||
```
|
||
|
||
## 📝 部署指南
|
||
|
||
### Docker 部署 (建議)
|
||
|
||
```bash
|
||
# 建置 Docker 鏡像
|
||
# 後端
|
||
cd backend
|
||
docker build -t todolist-backend .
|
||
|
||
# 前端
|
||
cd frontend
|
||
docker build -t todolist-frontend .
|
||
|
||
# 啟動容器
|
||
docker run -d -p 12011:12011 --name backend todolist-backend
|
||
docker run -d -p 12012:12012 --name frontend todolist-frontend
|
||
```
|
||
|
||
### 生產環境部署
|
||
|
||
1. **資料庫準備**
|
||
- 建立 MySQL 資料庫 (Port 33306)
|
||
- 執行資料庫遷移腳本
|
||
- 設定資料庫備份策略
|
||
|
||
2. **應用程式部署**
|
||
- 設定反向代理 (Nginx/IIS)
|
||
- 前端: Port 12012 → 對外 Port 80/443
|
||
- 後端 API: Port 12011 → 對外 API 路徑
|
||
- 配置 SSL 證書
|
||
- 設定生產環境變數
|
||
|
||
3. **背景服務設定**
|
||
- 配置 Celery Windows Service
|
||
- 設定 Redis 服務自動啟動 (Port 6379)
|
||
- 配置日誌輪轉
|
||
|
||
4. **環境判斷保護**
|
||
- 生產環境使用 `NODE_ENV=production`
|
||
- 自動禁用 HMR WebSocket 連接
|
||
- 禁用 React DevTools 提示
|
||
|
||
## 🔐 權限矩陣
|
||
|
||
### 待辦事項權限控制
|
||
|
||
| 操作/角色 | 建立者 | 負責人 | 追蹤者 | 其他使用者 |
|
||
|----------|--------|--------|--------|------------|
|
||
| **查看（非公開）** | ✅ | ✅ | ❌ | ❌ |
|
||
| **查看（公開）** | ✅ | ✅ | ✅ | ✅ |
|
||
| **編輯** | ✅ | ❌ | ❌ | ❌ |
|
||
| **刪除** | ✅ | ❌ | ❌ | ❌ |
|
||
| **更改狀態** | ✅ | ❌ | ❌ | ❌ |
|
||
| **指派負責人** | ✅ | ❌ | ❌ | ❌ |
|
||
| **設為公開/私人** | ✅ | ❌ | ❌ | ❌ |
|
||
| **追蹤（公開）** | ✅ | ✅ | ✅ | ✅ |
|
||
| **追蹤（非公開）** | ❌ | ❌ | ❌ | ❌ |
|
||
|
||
### 權限說明
|
||
|
||
#### 可見性規則
|
||
- **公開待辦事項**：所有使用者皆可查看
|
||
- **非公開待辦事項**：僅建立者和負責人可查看
|
||
- 追蹤者只能存在於公開的待辦事項
|
||
|
||
#### 編輯權限
|
||
- **完全控制**：僅建立者擁有編輯、刪除、狀態變更等所有權限
|
||
- **唯讀權限**：負責人、追蹤者及其他使用者僅能查看，無法編輯
|
||
|
||
#### 追蹤功能
|
||
- 只有公開的待辦事項才能被追蹤
|
||
- 任何人都可以追蹤公開的待辦事項
|
||
- 非公開的待辦事項不支援追蹤功能
|
||
|
||
## 🧪 測試
|
||
|
||
### 單元測試
|
||
```bash
|
||
# 後端測試
|
||
cd backend
|
||
pytest tests/ -v
|
||
|
||
# 前端測試
|
||
cd frontend
|
||
npm run test
|
||
```
|
||
|
||
### 類型檢查
|
||
```bash
|
||
# 前端類型檢查
|
||
cd frontend
|
||
npm run type-check
|
||
```
|
||
|
||
### 代碼規範檢查
|
||
```bash
|
||
# 前端 ESLint 檢查
|
||
cd frontend
|
||
npm run lint
|
||
```
|
||
|
||
## 📚 API 文檔
|
||
|
||
主要 API 端點：
|
||
|
||
### 認證相關
|
||
- `POST /api/auth/login` - 使用者登入
|
||
- `POST /api/auth/logout` - 使用者登出
|
||
- `GET /api/auth/me` - 取得當前使用者資訊
|
||
|
||
### 待辦事項
|
||
- `GET /api/todos` - 取得待辦清單
|
||
- `POST /api/todos` - 建立新待辦事項
|
||
- `PUT /api/todos/{id}` - 更新待辦事項
|
||
- `DELETE /api/todos/{id}` - 刪除待辦事項
|
||
|
||
### Excel 功能
|
||
- `POST /api/excel/import` - Excel 匯入
|
||
- `GET /api/excel/export` - Excel 匯出
|
||
- `GET /api/excel/template` - 下載匯入模板
|
||
|
||
## 🤝 開發貢獻
|
||
|
||
### 代碼規範
|
||
- 使用 TypeScript 進行前端開發
|
||
- 遵循 ESLint 和 Prettier 設定
|
||
- 後端使用 Python Type Hints
|
||
- 提交前執行測試
|
||
|
||
### Git 工作流程
|
||
1. 建立功能分支
|
||
2. 開發並測試功能
|
||
3. 提交 Pull Request
|
||
4. 代碼審查
|
||
5. 合併到主分支
|
||
|
||
## 🐛 問題排解
|
||
|
||
### 常見問題
|
||
|
||
**Q: 登入失敗，顯示 LDAP 連線錯誤**
|
||
A: 檢查 LDAP 設定和網路連線，確認服務帳號權限
|
||
|
||
**Q: 郵件通知無法發送**
|
||
A: 驗證 SMTP 設定，檢查防火牆和郵件伺服器設定
|
||
|
||
**Q: 前端無法連接後端 API**
|
||
A: 確認 CORS 設定和 API 基礎 URL 配置，檢查端口 12011 (後端) 和 12012 (前端) 是否正確設定
|
||
|
||
**Q: 生產環境出現 WebSocket HMR 錯誤**
|
||
A: 系統已加入環境判斷保護，確保使用 `npm run build && npm run start` 而非 `npm run dev` 進行生產部署
|
||
|
||
**Q: 端口衝突問題**
|
||
A: 系統使用 12010-12019 範圍的端口，如遇衝突請修改環境變數中的端口設定
|
||
|
||
**Q: CORS 錯誤**
|
||
A: 確認後端 .env 文件中 CORS_ORIGINS 包含正確的前端 URL (http://localhost:12012)
|
||
|
||
**Q: Excel 匯入失敗**
|
||
A: 檢查文件格式和欄位映射，參考匯入模板
|
||
|