backup
This commit is contained in:
beabigegg
356
README.md
Normal file
356
README.md
Normal file
@@ -0,0 +1,356 @@
|
||||
# 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
|
||||
docker-compose up -d
|
||||
|
||||
# 使用管理腳本 (Windows)
|
||||
manage.bat
|
||||
```
|
||||
|
||||
### 生產環境部署
|
||||
|
||||
1. **資料庫準備**
|
||||
- 建立 MySQL 資料庫 (Port 33306)
|
||||
- 執行資料庫遷移腳本
|
||||
- 設定資料庫備份策略
|
||||
|
||||
2. **應用程式部署**
|
||||
- 設定反向代理 (Nginx/IIS)
|
||||
- 應用服務: Port 12011 → 對外 Port 80/443
|
||||
- 配置 SSL 證書
|
||||
- 設定生產環境變數
|
||||
|
||||
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: 檢查文件格式和欄位映射，參考匯入模板
|
||||
|
||||
Reference in New Issue
Block a user