# PANJIT To-Do System

一個功能完整的企業級待辦事項管理系統，支援 LDAP 認證、郵件通知、Excel 匯入匯出，以及豐富的協作功能。

## 🚀 功能特色

### 核心功能
- **待辦事項管理**：建立、編輯、刪除、狀態管理
- **多人協作**：負責人指派、追蹤人員、權限控制
- **狀態管理**：新建立 → 進行中 → 已阻礙 → 已完成
- **優先級分類**：低、中、高、緊急
- **到期日管理**：日期設定、逾期提醒

### 高級功能
- **LDAP/Active Directory 整合**：企業帳號統一認證
- **智能搜尋**：模糊搜尋、多條件篩選
- **Excel 匯入匯出**：批量資料處理
- **郵件通知系統**：自動提醒、狀態變更通知
- **行事曆檢視**：時間軸管理
- **批量操作**：多項目同時處理
- **公開/私人模式**：靈活的可見性控制

### 技術特色
- **現代化架構**：前後端分離設計
- **響應式設計**：支援桌面和行動裝置
- **深色/淺色主題**：使用者體驗優化
- **即時更新**：React Query 資料同步
- **任務排程**：Celery 背景處理
- **健康檢查**：系統狀態監控

## 🏗️ 技術架構

### 前端 (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 部門或查看相關文檔。