egg/TODO_list_system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

6th

Browse Source
This commit is contained in:
beabigegg
2025-09-01 16:42:41 +08:00
parent 22a231d78c
commit 00061adeb7
23 changed files with 858 additions and 3584 deletions
Download Patch File Download Diff File Expand all files Collapse all files

556
README.md
View File

@@ -1,401 +1,301 @@
# PANJIT To-Do System
# PANJIT To-Do 專案管理系統
一個功能完整的企業級待辦事項管理系統，支援 LDAP 認證、郵件通知、Excel 匯入匯出，以及豐富的協作功能。
一套完整的企業級待辦事項管理系統，支援AD認證、郵件通知、Excel匯入匯出等功能。
## 🚀 功能特色
### 核心功能
- **待辦事項管理**：建立、編輯、刪除、狀態管理
- **多人協作**：負責人指派、追蹤人員、權限控制
- **狀態管理**：新建立 → 進行中 → 已阻礙 → 已完成
- **優先級分類**：低、中、高、緊急
- **到期日管理**：日期設定、逾期提醒
- **待辦事項管理**：新增、編輯、刪除、狀態管理
- **多重視圖**：列表視圖、日曆視圖、看板視圖
- **權限控制**：創建者、負責人、追蹤者角色管理
- **狀態追蹤**：新建立、進行中、已阻塞、已完成
### 高級功能
- **LDAP/Active Directory 整合**：企業帳號統一認證
- **智能搜尋**：模糊搜尋、多條件篩選
- **Excel 匯入匯出**：批量資料處理
- **郵件通知系統**：自動提醒、狀態變更通知
- **行事曆檢視**：時間軸管理
- **批量操作**：多項目同時處理
- **公開/私人模式**：靈活的可見性控制
### 身份認證
- **AD 整合**：支援Active Directory單一登入
- **角色權限**：管理員、一般使用者權限管控
- **安全防護**：JWT Token認證機制
### 技術特色
- **現代化架構**：前後端分離設計
- **響應式設計**：支援桌面和行動裝置
- **深色/淺色主題**：使用者體驗優化
- **即時更新**：React Query 資料同步
- **任務排程**：Celery 背景處理
- **健康檢查**：系統狀態監控
### 通知系統
- **郵件通知**：狀態變更、到期提醒自動通知
- **即時推播**：系統內通知面板
- **自定義設定**：個人化通知偏好
## 🏗️ 技術架構
### 資料處理
- **Excel 匯入**：批量匯入待辦事項
- **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** - 快取與任務佇列
### 前端技術棧
- **框架**：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** >= 18.0
- **Python** >= 3.11
- **MySQL** >= 8.0
- **Redis** >= 6.0
### 開發環境
- **Node.js**：16.x 或以上版本
- **Python**：3.10 或以上版本
- **MySQL**：8.0 或以上版本
- **Redis**：6.0 或以上版本
## 🛠️ 本地開發安裝
### 生產環境
- **作業系統**：Windows Server 2016+ 或 Linux
- **記憶體**：最低 4GB，建議 8GB
- **磁碟空間**：最低 10GB
- **網路**：可連接 SMTP 和 LDAP 伺服器
### 1. 克隆專案
## 🚀 快速開始
### 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. 後端設定
### 2. 後端設置
```bash
# 進入後端目錄
cd backend
# 建立虛擬環境
# 建立虛擬環境 (Windows)
python -m venv venv
venv\Scripts\activate # Windows
# source venv/bin/activate # Linux/macOS
venv\Scripts\activate
# 安裝依賴
pip install -r requirements.txt
# 複製環境設定檔並修改
copy .env.example .env # Windows
# cp .env.example .env # Linux/macOS
# 設置環境變數
copy .env.example .env
# 編輯 .env 文件，填入正確的設定值
# 編輯 .env 檔案，設定資料庫連線資訊
# 初始化資料庫
python init_db.py
# 啟動後端服務
python app.py
```
#### 重要環境變數設定
編輯 `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. 前端設定
### 3. 前端設置
```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
# 設置環境變數
copy .env.example .env.local
# 編輯 .env.local 文件
# 啟動開發服務器
npm run dev
# 前端將在 http://localhost:3000 啟動
```
#### Celery 背景任務 (另開終端)
### 4. 背景任務 (可選)
```bash
# 在另一個終端啟動 Celery Worker
cd backend
celery -A celery_app worker --loglevel=info
# 啟動 Celery Worker
celery -A celery_app.celery worker --loglevel=info
# 啟動 Celery Beat (排程任務)
celery -A celery_app.celery beat --loglevel=info
# 啟動任務調度器
celery -A celery_app beat --loglevel=info
```
## 🌐 訪問應用程式
## ⚙️ 設定說明
- **前端界面**: http://localhost:3000
- **後端 API**: http://localhost:5000
- **API 文檔**: http://localhost:5000/api (Swagger UI)
- **健康檢查**: http://localhost:5000/api/health/healthz
### 環境變數配置
## 📁 專案結構
#### 後端設定 (backend/.env)
```env
# 資料庫連線
DATABASE_URL=mysql+pymysql://username:password@host:port/database
MYSQL_HOST=mysql.example.com
MYSQL_PORT=3306
MYSQL_USER=your_user
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database
```
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 # 產品需求文件
# 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
```
## 🔧 開發指令
#### 前端設定 (frontend/.env.local)
```env
NEXT_PUBLIC_API_BASE_URL=http://localhost:5000/api
NEXT_PUBLIC_APP_NAME=PANJIT To-Do System
```
### 後端開發
## 📝 部署指南
### 生產環境部署
1. **資料庫準備**
- 建立 MySQL 資料庫
- 執行資料庫遷移腳本
- 設定資料庫備份策略
2. **應用程式部署**
- 設定 IIS 或 Apache 反向代理
- 配置 SSL 證書
- 設定環境變數
3. **背景服務設定**
- 配置 Celery Windows Service
- 設定 Redis 服務自動啟動
- 配置日誌輪轉
## 🔐 權限矩陣
### 待辦事項權限控制
| 操作/角色 | 建立者 | 負責人 | 追蹤者 | 其他使用者 |
|----------|--------|--------|--------|------------|
| **查看（非公開）** | ✅ | ✅ | ❌ | ❌ |
| **查看（公開）** | ✅ | ✅ | ✅ | ✅ |
| **編輯** | ✅ | ❌ | ❌ | ❌ |
| **刪除** | ✅ | ❌ | ❌ | ❌ |
| **更改狀態** | ✅ | ❌ | ❌ | ❌ |
| **指派負責人** | ✅ | ❌ | ❌ | ❌ |
| **設為公開/私人** | ✅ | ❌ | ❌ | ❌ |
| **追蹤（公開）** | ✅ | ✅ | ✅ | ✅ |
| **追蹤（非公開）** | ❌ | ❌ | ❌ | ❌ |
### 權限說明
#### 可見性規則
- **公開待辦事項**：所有使用者皆可查看
- **非公開待辦事項**：僅建立者和負責人可查看
- 追蹤者只能存在於公開的待辦事項
#### 編輯權限
- **完全控制**：僅建立者擁有編輯、刪除、狀態變更等所有權限
- **唯讀權限**：負責人、追蹤者及其他使用者僅能查看，無法編輯
#### 追蹤功能
- 只有公開的待辦事項才能被追蹤
- 任何人都可以追蹤公開的待辦事項
- 非公開的待辦事項不支援追蹤功能
## 🧪 測試
### 單元測試
```bash
# 後端測試
cd backend
pytest tests/ -v
# 啟動開發服務器 (自動重載)
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
npm run test
```
## 📊 功能說明
### 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
# 前端類型檢查
cd frontend
npm run type-check
```
### 環境變數設定
### 代碼規範檢查
```bash
# 前端 ESLint 檢查
cd frontend
npm run lint
```
生產環境請務必修改：
- `SECRET_KEY` - Flask 密鑰
- `JWT_SECRET_KEY` - JWT 密鑰
- 資料庫密碼
- SMTP 設定
- LDAP 設定
## 📚 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. 合併到主分支
## 🐛 問題排解
### 常見問題
1. **資料庫連線失敗**
```bash
# 檢查 MySQL 是否啟動
docker-compose ps mysql
# 檢查連線設定
mysql -h localhost -u todouser -p todo_system
```
**Q: 登入失敗，顯示 LDAP 連線錯誤**
A: 檢查 LDAP 設定和網路連線，確認服務帳號權限
2. **LDAP 連線失敗**
- 檢查 LDAP 服務器設定
- 確認網路連線
- 驗證搜尋基底 DN 設定
**Q: 郵件通知無法發送**
A: 驗證 SMTP 設定，檢查防火牆和郵件伺服器設定
3. **郵件發送失敗**
- 檢查 SMTP 服務器設定
- 確認防火牆設定
- 驗證寄件者郵箱權限
**Q: 前端無法連接後端 API**
A: 確認 CORS 設定和 API 基礎 URL 配置
4. **前端無法連接後端**
- 檢查 `NEXT_PUBLIC_API_URL` 設定
- 確認 CORS 設定
- 檢查後端服務是否正常啟動
**Q: Excel 匯入失敗**
A: 檢查文件格式和欄位映射，參考匯入模板
### 日誌檢查
```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 部門或查看相關文檔。