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. 專案複製

git clone <repository-url>
cd TODOLIST

2. 後端設置

# 進入後端目錄
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. 前端設置

# 進入前端目錄
cd frontend

# 安裝依賴
npm install

# 設置環境變數
copy .env.example .env.local
# 編輯 .env.local 文件

# 啟動開發服務器 (現使用 port 12012)
npm run dev

# 生產環境部署
npm run build
npm run start

4. 背景任務 (可選)

# 在另一個終端啟動 Celery Worker
cd backend
celery -A celery_app worker --loglevel=info

# 啟動任務調度器
celery -A celery_app beat --loglevel=info

⚙️ 設定說明

環境變數配置

後端設定 (backend/.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)

# 後端 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 部署 (建議)

# 建置 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 提示

🔐 權限矩陣

待辦事項權限控制

操作/角色	建立者	負責人	追蹤者	其他使用者
查看（非公開）	✅	✅	❌	❌
查看（公開）	✅	✅	✅	✅
編輯	✅	❌	❌	❌
刪除	✅	❌	❌	❌
更改狀態	✅	❌	❌	❌
指派負責人	✅	❌	❌	❌
設為公開/私人	✅	❌	❌	❌
追蹤（公開）	✅	✅	✅	✅
追蹤（非公開）	❌	❌	❌	❌

權限說明

可見性規則

• 公開待辦事項：所有使用者皆可查看
• 非公開待辦事項：僅建立者和負責人可查看
• 追蹤者只能存在於公開的待辦事項

編輯權限

• 完全控制：僅建立者擁有編輯、刪除、狀態變更等所有權限
• 唯讀權限：負責人、追蹤者及其他使用者僅能查看，無法編輯

追蹤功能

• 只有公開的待辦事項才能被追蹤
• 任何人都可以追蹤公開的待辦事項
• 非公開的待辦事項不支援追蹤功能

🧪 測試

單元測試

# 後端測試
cd backend
pytest tests/ -v

# 前端測試
cd frontend
npm run test

類型檢查

# 前端類型檢查
cd frontend
npm run type-check

代碼規範檢查

# 前端 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: 檢查文件格式和欄位映射，參考匯入模板