TODOLIST/README.md

# PANJIT To-Do 專案管理系統

一套完整的企業級待辦事項管理系統，支援AD認證、郵件通知、Excel匯入匯出等功能。

## 🚀 功能特色

### 核心功能
- **待辦事項管理**：新增、編輯、刪除、狀態管理
- **多重視圖**：列表視圖、日曆視圖、看板視圖
- **權限控制**：創建者、負責人、追蹤者角色管理
- **狀態追蹤**：新建立、進行中、已阻塞、已完成

### 身份認證
- **AD 整合**：支援Active Directory單一登入
- **角色權限**：管理員、一般使用者權限管控
- **安全防護**：JWT Token認證機制

### 通知系統  
- **郵件通知**：狀態變更、到期提醒自動通知
- **即時推播**：系統內通知面板
- **自定義設定**：個人化通知偏好

### 資料處理
- **Excel 匯入**：批量匯入待辦事項
- **Excel 匯出**：支援多種匯出格式
- **報表功能**：統計分析報表

### 使用者介面
- **響應式設計**：支援桌面、平板、手機
- **深色模式**：亮色/暗色/自動切換
- **多語言支援**：繁體中文介面
- **動畫效果**：流暢的使用者體驗

## 🛠 技術架構

### 端口配置

#### 單一容器架構
- **應用服務**：Port 12011 (前端 + 後端 API)
- **資料庫**：Port 33306 (MySQL)

#### 外部依賴端口
- **LDAP 服務**：Port 389
- **郵件服務**：Port 25 (SMTP)

> 📝 **架構升級**：已從分離式容器升級為單一容器部署，簡化端口管理和部署流程。

### 前端技術棧
- **框架**：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. 專案複製
```bash
git clone <repository-url>
cd TODOLIST
```

### 2. 後端設置
```bash
# 進入後端目錄
cd backend

# 建立虛擬環境 (Windows)
python -m venv venv
venv\Scripts\activate

# 安裝依賴
pip install -r requirements.txt

# 設置環境變數
copy .env.example .env
# 編輯 .env 文件，填入正確的設定值

# 初始化資料庫
python init_db.py

# 啟動後端服務 (整合前端靜態文件服務)
python app.py
```

### 3. 前端設置
```bash
# 進入前端目錄
cd frontend

# 安裝依賴
npm install

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

# 開發環境
npm run dev

# 生產環境構建 (將與後端整合)
npm run build
```

### 4. 背景任務 (可選)
```bash
# 在另一個終端啟動 Celery Worker
cd backend
celery -A celery_app worker --loglevel=info

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

## ⚙️ 設定說明

### 環境變數配置

#### 後端設定 (backend/.env)
```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:12011
```

#### 前端設定 (frontend/.env.local)
```env
# 後端 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
```

## 📝 部署指南

### Docker 部署 (建議)

```bash
# 快速部署 - 單一容器架構
# Windows
deploy.bat

# Linux/macOS  
./deploy.sh

# 或使用 Docker Compose（包含 Nginx 反向代理，對外開放 12011）
docker-compose up -d

# 使用管理腳本 (Windows)
manage.bat
```

### 生產環境部署

1. **資料庫準備**
   - 建立 MySQL 資料庫 (Port 33306)
   - 執行資料庫遷移腳本
   - 設定資料庫備份策略

2. **應用程式部署**
   - 設定反向代理 (Nginx/IIS)
      - 應用服務: Port 12011 → 對外 Port 12011（由 Nginx 監聽）
   - 配置 SSL 證書（若需 443 可另行設定）
   - 設定生產環境變數

3. **背景服務設定**
   - 配置 Celery Windows Service  
   - 設定 Redis 服務自動啟動 (Port 6379)
   - 配置日誌輪轉

4. **環境判斷保護**
   - 生產環境使用 `NODE_ENV=production`
   - 自動禁用 HMR WebSocket 連接
   - 禁用 React DevTools 提示

## 🔐 權限矩陣

### 待辦事項權限控制

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

### 權限說明

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

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

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

## 🧪 測試

### 單元測試
```bash
# 後端測試
cd backend
pytest tests/ -v

# 前端測試
cd frontend
npm run test
```

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

### 代碼規範檢查
```bash
# 前端 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: 應用無法正常訪問**
A: 確認單一容器服務正常運行，檢查端口 12011 是否可訪問，確認靜態文件正確構建

**Q: 生產環境出現 WebSocket HMR 錯誤**
A: 系統已加入環境判斷保護，確保使用 `npm run build && npm run start` 而非 `npm run dev` 進行生產部署

**Q: 端口衝突問題**
A: 系統使用 12010-12019 範圍的端口，如遇衝突請修改環境變數中的端口設定

**Q: 靜態文件載入失敗**
A: 確認 Next.js 構建正確完成，檢查 /app/frontend/out 目錄是否存在於容器中

**Q: Excel 匯入失敗**
A: 檢查文件格式和欄位映射，參考匯入模板