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. 克隆專案
git clone <repository-url>
cd TODOLIST
2. 資料庫準備
方式一：使用 Docker (推薦)
# 啟動 MySQL 和 Redis
docker-compose up mysql redis -d
# 等待資料庫啟動完成 (大約30秒)
docker-compose logs mysql
方式二：本地 MySQL
# 建立資料庫
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. 後端設定
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 檔案：
# 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. 前端設定
cd frontend
# 安裝依賴
npm install
# 複製環境設定檔
copy .env.example .env.local # Windows
# cp .env.example .env.local # Linux/macOS
# 編輯 .env.local 設定 API URL
編輯 frontend/.env.local：
NEXT_PUBLIC_API_URL=http://localhost:5000
NEXT_PUBLIC_AD_DOMAIN=your-company.com.tw
NEXT_PUBLIC_EMAIL_DOMAIN=your-company.com.tw
5. 啟動應用程式
後端啟動
cd backend
# 啟動 Flask 應用程式
python app.py
# 後端將在 http://localhost:5000 啟動
前端啟動 (另開終端)
cd frontend
# 啟動開發服務器
npm run dev
# 前端將在 http://localhost:3000 啟動
Celery 背景任務 (另開終端)
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 # 產品需求文件
🔧 開發指令
後端開發
cd backend
# 啟動開發服務器 (自動重載)
flask run --debug
# 資料庫遷移
flask db upgrade
# 執行 Python 腳本
python -m scripts.init_admin_user
前端開發
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
# 建置並啟動所有服務
docker-compose up -d
# 檢查服務狀態
docker-compose ps
# 查看日誌
docker-compose logs -f backend frontend
環境變數設定
生產環境請務必修改：
SECRET_KEY- Flask 密鑰JWT_SECRET_KEY- JWT 密鑰- 資料庫密碼
- SMTP 設定
- LDAP 設定
🔍 故障排除
常見問題
-
資料庫連線失敗
# 檢查 MySQL 是否啟動 docker-compose ps mysql # 檢查連線設定 mysql -h localhost -u todouser -p todo_system -
LDAP 連線失敗
- 檢查 LDAP 服務器設定
- 確認網路連線
- 驗證搜尋基底 DN 設定
-
郵件發送失敗
- 檢查 SMTP 服務器設定
- 確認防火牆設定
- 驗證寄件者郵箱權限
-
前端無法連接後端
- 檢查
NEXT_PUBLIC_API_URL設定 - 確認 CORS 設定
- 檢查後端服務是否正常啟動
- 檢查
日誌檢查
# 後端日誌
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 部門或查看相關文檔。