385 lines
8.4 KiB
Markdown
385 lines
8.4 KiB
Markdown
# PANJIT To-Do List System V1
|
||
|
||
一個基於 Next.js + Flask 的企業級待辦事項管理系統，支援 AD/LDAP 登入、多人協作、Email 提醒等功能。
|
||
|
||
## 🚀 系統特色
|
||
|
||
- ✅ **AD/LDAP 登入** - 企業級身份驗證
|
||
- ✅ **多人協作** - 支援多負責人/多追蹤者
|
||
- ✅ **Fire 一鍵提醒** - 立即郵件提醒功能 (2分鐘冷卻 + 每日20封限額)
|
||
- ✅ **排程提醒** - 到期前/當天/逾期自動提醒 + 週摘要
|
||
- ✅ **Excel 匯入** - 完整模板驗證與錯誤處理
|
||
- ✅ **完整稽核** - 所有操作記錄追蹤
|
||
- ✅ **響應式設計** - 支援桌面與行動裝置
|
||
|
||
## 🏗️ 技術架構
|
||
|
||
### 前端 (Frontend)
|
||
- **Next.js 14** - React 全端框架
|
||
- **TypeScript** - 類型安全開發
|
||
- **Material-UI** - 企業級 UI 組件
|
||
- **Redux Toolkit** - 狀態管理
|
||
- **TanStack Query** - 服務端狀態管理
|
||
|
||
### 後端 (Backend)
|
||
- **Flask** - Python Web 框架
|
||
- **SQLAlchemy** - ORM 資料庫管理
|
||
- **MySQL** - 主要資料庫
|
||
- **Celery + Redis** - 背景任務處理
|
||
- **JWT** - 身份驗證
|
||
- **python-ldap** - AD/LDAP 整合
|
||
|
||
### 部署 (Deployment)
|
||
- **Docker** - 容器化部署
|
||
- **Nginx** - 反向代理
|
||
- **MySQL 8.0** - 資料庫服務
|
||
- **Redis** - 快取與任務佇列
|
||
|
||
## 📋 系統需求
|
||
|
||
- **Node.js** >= 18.0
|
||
- **Python** >= 3.11
|
||
- **MySQL** >= 8.0
|
||
- **Redis** >= 6.0
|
||
|
||
## 🛠️ 本地開發安裝
|
||
|
||
### 1. 克隆專案
|
||
|
||
```bash
|
||
git clone <repository-url>
|
||
cd TODOLIST
|
||
```
|
||
|
||
### 2. 資料庫準備
|
||
|
||
#### 方式一：使用 Docker (推薦)
|
||
```bash
|
||
# 啟動 MySQL 和 Redis
|
||
docker-compose up mysql redis -d
|
||
|
||
# 等待資料庫啟動完成 (大約30秒)
|
||
docker-compose logs mysql
|
||
```
|
||
|
||
#### 方式二：本地 MySQL
|
||
```bash
|
||
# 建立資料庫
|
||
mysql -u root -p
|
||
CREATE DATABASE todo_system CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||
CREATE USER 'todouser'@'localhost' IDENTIFIED BY 'todopass';
|
||
GRANT ALL PRIVILEGES ON todo_system.* TO 'todouser'@'localhost';
|
||
FLUSH PRIVILEGES;
|
||
EXIT;
|
||
|
||
# 初始化資料庫結構
|
||
mysql -u todouser -p todo_system < mysql/init/01-init.sql
|
||
```
|
||
|
||
### 3. 後端設定
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# 建立虛擬環境
|
||
python -m venv venv
|
||
venv\Scripts\activate # Windows
|
||
# source venv/bin/activate # Linux/macOS
|
||
|
||
# 安裝依賴
|
||
pip install -r requirements.txt
|
||
|
||
# 複製環境設定檔並修改
|
||
copy .env.example .env # Windows
|
||
# cp .env.example .env # Linux/macOS
|
||
|
||
# 編輯 .env 檔案，設定資料庫連線資訊
|
||
```
|
||
|
||
#### 重要環境變數設定
|
||
|
||
編輯 `backend/.env` 檔案：
|
||
|
||
```env
|
||
# MySQL 連線 (如使用Docker，保持預設值即可)
|
||
MYSQL_HOST=localhost
|
||
MYSQL_PORT=3306
|
||
MYSQL_USER=todouser
|
||
MYSQL_PASSWORD=todopass
|
||
MYSQL_DATABASE=todo_system
|
||
|
||
# SMTP 設定 (依照公司環境設定)
|
||
SMTP_SERVER=mail.your-company.com
|
||
SMTP_PORT=25
|
||
SMTP_SENDER_EMAIL=todo-system@your-company.com
|
||
|
||
# AD/LDAP 設定 (依照公司環境設定)
|
||
LDAP_SERVER=ldap://dc.your-company.com
|
||
LDAP_SEARCH_BASE=DC=your-company,DC=com
|
||
```
|
||
|
||
### 4. 前端設定
|
||
|
||
```bash
|
||
cd frontend
|
||
|
||
# 安裝依賴
|
||
npm install
|
||
|
||
# 複製環境設定檔
|
||
copy .env.example .env.local # Windows
|
||
# cp .env.example .env.local # Linux/macOS
|
||
|
||
# 編輯 .env.local 設定 API URL
|
||
```
|
||
|
||
編輯 `frontend/.env.local`：
|
||
```env
|
||
NEXT_PUBLIC_API_URL=http://localhost:5000
|
||
NEXT_PUBLIC_AD_DOMAIN=your-company.com.tw
|
||
NEXT_PUBLIC_EMAIL_DOMAIN=your-company.com.tw
|
||
```
|
||
|
||
### 5. 啟動應用程式
|
||
|
||
#### 後端啟動
|
||
```bash
|
||
cd backend
|
||
|
||
# 啟動 Flask 應用程式
|
||
python app.py
|
||
|
||
# 後端將在 http://localhost:5000 啟動
|
||
```
|
||
|
||
#### 前端啟動 (另開終端)
|
||
```bash
|
||
cd frontend
|
||
|
||
# 啟動開發服務器
|
||
npm run dev
|
||
|
||
# 前端將在 http://localhost:3000 啟動
|
||
```
|
||
|
||
#### Celery 背景任務 (另開終端)
|
||
```bash
|
||
cd backend
|
||
|
||
# 啟動 Celery Worker
|
||
celery -A celery_app.celery worker --loglevel=info
|
||
|
||
# 啟動 Celery Beat (排程任務)
|
||
celery -A celery_app.celery beat --loglevel=info
|
||
```
|
||
|
||
## 🌐 訪問應用程式
|
||
|
||
- **前端界面**: http://localhost:3000
|
||
- **後端 API**: http://localhost:5000
|
||
- **API 文檔**: http://localhost:5000/api (Swagger UI)
|
||
- **健康檢查**: http://localhost:5000/api/health/healthz
|
||
|
||
## 📁 專案結構
|
||
|
||
```
|
||
TODOLIST/
|
||
├── backend/ # Flask 後端
|
||
│ ├── routes/ # API 路由
|
||
│ ├── models.py # 資料模型
|
||
│ ├── config.py # 設定檔
|
||
│ ├── app.py # Flask 應用程式入口
|
||
│ ├── tasks.py # Celery 背景任務
|
||
│ └── utils/ # 工具函數
|
||
├── frontend/ # Next.js 前端
|
||
│ ├── src/
|
||
│ │ ├── app/ # Next.js 應用程式路由
|
||
│ │ ├── components/ # React 組件
|
||
│ │ ├── store/ # Redux 狀態管理
|
||
│ │ ├── lib/ # API 客戶端
|
||
│ │ └── types/ # TypeScript 類型定義
|
||
├── mysql/
|
||
│ └── init/ # 資料庫初始化 SQL
|
||
├── nginx/ # Nginx 設定
|
||
├── docker-compose.yml # Docker 編排設定
|
||
└── PRD.md # 產品需求文件
|
||
```
|
||
|
||
## 🔧 開發指令
|
||
|
||
### 後端開發
|
||
```bash
|
||
cd backend
|
||
|
||
# 啟動開發服務器 (自動重載)
|
||
flask run --debug
|
||
|
||
# 資料庫遷移
|
||
flask db upgrade
|
||
|
||
# 執行 Python 腳本
|
||
python -m scripts.init_admin_user
|
||
```
|
||
|
||
### 前端開發
|
||
```bash
|
||
cd frontend
|
||
|
||
# 開發模式
|
||
npm run dev
|
||
|
||
# 類型檢查
|
||
npm run type-check
|
||
|
||
# 程式碼檢查
|
||
npm run lint
|
||
|
||
# 建置生產版本
|
||
npm run build
|
||
|
||
# 啟動生產服務器
|
||
npm start
|
||
```
|
||
|
||
## 📊 功能說明
|
||
|
||
### 1. 使用者登入
|
||
- 使用 AD/LDAP 帳號登入
|
||
- 首次登入自動建立使用者偏好設定
|
||
- JWT Token 驗證機制
|
||
|
||
### 2. 待辦管理
|
||
- 建立/編輯/刪除待辦事項
|
||
- 支援多負責人與多追蹤者
|
||
- 狀態管理：NEW/DOING/BLOCKED/DONE
|
||
- 優先級：LOW/MEDIUM/HIGH/URGENT
|
||
- 到期日設定與星號標記
|
||
|
||
### 3. 通知系統
|
||
- **Fire 一鍵提醒**：立即發送郵件，2分鐘冷卻，每日20封限制
|
||
- **排程提醒**：到期前3天、當天、逾期1天自動提醒
|
||
- **週摘要**：每週一早上9點發送個人待辦摘要
|
||
|
||
### 4. Excel 匯入
|
||
- 下載正式模板檔案
|
||
- 逐列錯誤驗證與報告
|
||
- AD 帳號存在性檢查
|
||
- 重複項目檢測
|
||
|
||
### 5. 權限控制
|
||
- **建立者**：完整編輯權限
|
||
- **負責人**：完整編輯權限
|
||
- **追蹤者**：僅檢視權限，可接收通知
|
||
|
||
## 🛡️ 安全性
|
||
|
||
- JWT Token 身份驗證
|
||
- CORS 跨域保護
|
||
- SQL Injection 防護 (SQLAlchemy)
|
||
- XSS 防護 (React)
|
||
- LDAP 注入防護
|
||
- API Rate Limiting (建議生產環境啟用)
|
||
|
||
## 📝 API 文檔
|
||
|
||
### 主要 API 端點
|
||
|
||
- `POST /api/auth/login` - 使用者登入
|
||
- `GET /api/todos` - 取得待辦清單
|
||
- `POST /api/todos` - 建立待辦事項
|
||
- `PATCH /api/todos/{id}` - 更新待辦事項
|
||
- `DELETE /api/todos/{id}` - 刪除待辦事項
|
||
- `POST /api/todos/{id}/fire-email` - Fire 一鍵提醒
|
||
- `GET /api/imports/template` - 下載 Excel 模板
|
||
- `POST /api/imports` - 上傳 Excel 檔案
|
||
|
||
完整 API 文檔請查看：http://localhost:5000/api/docs
|
||
|
||
## 🚀 生產部署
|
||
|
||
### 使用 Docker Compose
|
||
|
||
```bash
|
||
# 建置並啟動所有服務
|
||
docker-compose up -d
|
||
|
||
# 檢查服務狀態
|
||
docker-compose ps
|
||
|
||
# 查看日誌
|
||
docker-compose logs -f backend frontend
|
||
```
|
||
|
||
### 環境變數設定
|
||
|
||
生產環境請務必修改：
|
||
- `SECRET_KEY` - Flask 密鑰
|
||
- `JWT_SECRET_KEY` - JWT 密鑰
|
||
- 資料庫密碼
|
||
- SMTP 設定
|
||
- LDAP 設定
|
||
|
||
## 🔍 故障排除
|
||
|
||
### 常見問題
|
||
|
||
1. **資料庫連線失敗**
|
||
```bash
|
||
# 檢查 MySQL 是否啟動
|
||
docker-compose ps mysql
|
||
|
||
# 檢查連線設定
|
||
mysql -h localhost -u todouser -p todo_system
|
||
```
|
||
|
||
2. **LDAP 連線失敗**
|
||
- 檢查 LDAP 服務器設定
|
||
- 確認網路連線
|
||
- 驗證搜尋基底 DN 設定
|
||
|
||
3. **郵件發送失敗**
|
||
- 檢查 SMTP 服務器設定
|
||
- 確認防火牆設定
|
||
- 驗證寄件者郵箱權限
|
||
|
||
4. **前端無法連接後端**
|
||
- 檢查 `NEXT_PUBLIC_API_URL` 設定
|
||
- 確認 CORS 設定
|
||
- 檢查後端服務是否正常啟動
|
||
|
||
### 日誌檢查
|
||
|
||
```bash
|
||
# 後端日誌
|
||
tail -f backend/logs/app.log
|
||
|
||
# Docker 日誌
|
||
docker-compose logs -f backend
|
||
docker-compose logs -f frontend
|
||
|
||
# Celery 任務日誌
|
||
docker-compose logs -f celery-worker
|
||
```
|
||
|
||
## 👥 開發團隊
|
||
|
||
- **產品設計**: PANJIT IT Team
|
||
- **後端開發**: Flask + SQLAlchemy
|
||
- **前端開發**: Next.js + TypeScript
|
||
- **系統架構**: Docker + Nginx
|
||
|
||
## 📄 授權
|
||
|
||
本專案為 PANJIT 內部使用，請勿外傳。
|
||
|
||
---
|
||
|
||
## 🔖 版本資訊
|
||
|
||
- **版本**: V1.0
|
||
- **更新日期**: 2025-08-28
|
||
- **Python**: 3.11+
|
||
- **Node.js**: 18.0+
|
||
- **資料庫**: MySQL 8.0
|
||
|
||
如有問題請聯繫 IT 部門或查看相關文檔。 |