2ND

README.md

@@ -1,133 +1,513 @@
-# TEMP Spec System - 暫時規範管理系統 (ONLYOFFICE-Edition)
+# 暫時規範管理系統 V3
 
-這是一個使用 Flask 開發的 Web 應用程式，旨在管理、追蹤和存檔暫時性的工程規範。此版本已整合 ONLYOFFICE Document Server，提供強大的所見即所得（WYSIWYG）線上文件編輯體驗。
+企業級暫時規範生命週期管理系統，提供完整的文件管理、LDAP整合驗證、智慧通知系統及排程提醒功能。
 
-## 核心功能
+## 🚀 系統特色
 
-- **使用者權限管理**: 內建三種角色 (`viewer`, `editor`, `admin`)，各角色擁有不同操作權限。
-- **規範生命週期**: 支援暫時規範的建立、啟用、展延、終止與刪除。
-- **線上文件編輯**: 整合 ONLYOFFICE Document Server，支援多人協作與專業級的線上 Word 文件編輯。
-- **範本自動填入**: 建立規範時，可將表單資料自動填入 Word 範本中。
-- **檔案管理**: 支援上傳簽核後的文件，並與對應的規範進行關聯。
-- **歷史紀錄**: 詳細記錄每一份規範的所有變更歷史，方便追蹤與稽核。
+- **LDAP/AD 整合驗證**：支援企業Active Directory單一登入
+- **ONLYOFFICE 線上編輯**：即時協作文件編輯功能
+- **智慧通知系統**：動態收件人選擇與自動提醒
+- **文件生命週期管理**：完整的建立、啟用、展延、終止流程
+- **多平台支援**：支援 Windows/Linux 環境部署
+- **Docker 容器化**：一鍵部署環境
 
----
+## 📋 功能模組
 
-## 環境要求
+### 核心功能
+- **文件管理**：Word範本自動化生成與PDF轉換
+- **權限控制**：三級權限管理 (Viewer/Editor/Admin)
+- **歷史追蹤**：完整的操作記錄與版本控制
+- **檔案上傳**：支援多種格式的佐證文件上傳
 
-在部署此應用程式之前，請確保您的系統已安裝以下軟體：
+### 智慧通知系統
+- **動態收件人選擇**：整合LDAP的即時用戶搜尋
+- **全流程通知**：啟用、展延、終止操作的自動郵件通知
+- **自動提醒**：3天與7天到期前的主動提醒郵件
+- **排程系統**：每日自動檢查即將到期的規範
 
-1.  **Python**: 建議使用 `Python 3.10` 或更高版本。
-2.  **MySQL**: 需要一個 MySQL 資料庫來儲存所有應用程式資料。
-3.  **Docker**: **[重要]** 本專案依賴 ONLYOFFICE Document Server，推薦使用 Docker 進行部署和管理。請確保您的伺服器已安裝並運行 Docker。
-4.  **Git**: 用於從版本控制系統下載程式碼。
+### 編輯器整合
+- **ONLYOFFICE整合**：支援Word文件的線上即時編輯
+- **Toast UI Editor**：Markdown格式的內容編輯器
+- **圖片支援**：內嵌圖片顯示與編輯功能
 
----
+## 🏗️ 系統架構
 
-## 安裝與設定步驟
-
-請依照以下步驟來設定您的開發或生產環境：
-
-### 1. 下載程式碼
-
-```bash
-git clone <your-repository-url>
-cd TEMP_spec_system_V2
+```
+暫時規範系統 V3
+├── 前端介面 (Flask + Bootstrap 5)
+├── 後端邏輯 (Python Flask)
+├── 資料庫 (MySQL/SQLite)
+├── LDAP整合 (Active Directory)
+├── 文件引擎 (ONLYOFFICE)
+├── 排程服務 (APScheduler)
+└── 郵件系統 (SMTP)
 ```
 
-### 2. 建立並啟用虛擬環境
+## 🛠️ 技術棧
 
+- **後端框架**：Python Flask 3.x
+- **資料庫ORM**：SQLAlchemy
+- **前端UI**：Bootstrap 5 + Tom Select
+- **文件處理**：python-docx, docx2pdf
+- **認證系統**：Flask-Login + LDAP3
+- **排程系統**：Flask-APScheduler
+- **容器化**：Docker + Docker Compose
+
+## 📦 安裝部署
+
+### 前置需求
+
+- Python 3.8+
+- MySQL 8.0+ 或 SQLite
+- ONLYOFFICE Document Server
+- LDAP/Active Directory 伺服器
+- SMTP 郵件伺服器
+
+### 快速開始 (Docker)
+
+1. **克隆專案**
 ```bash
-# Windows
-python -m venv .venv
-.\.venv\Scripts\activate
-
-# macOS / Linux
-python3 -m venv .venv
-source .venv/bin/activate
+git clone <repository-url>
+cd TEMP_spec_system_V3
 ```
 
-### 3. 安裝相依套件
+2. **設定環境變數**
+```bash
+cp .env.example .env
+# 編輯 .env 檔案設定資料庫、LDAP、SMTP 等參數
+```
 
+3. **使用Docker Compose啟動**
+```bash
+docker-compose up -d
+```
+
+4. **初始化資料庫**
+```bash
+docker-compose exec app python init_db.py
+```
+
+### 手動安裝
+
+#### Windows 環境
+
+1. **安裝Python依賴**
+```cmd
+pip install -r requirements.txt
+```
+
+2. **設定環境變數**
+```cmd
+copy .env.example .env
+REM 編輯 .env 檔案
+```
+
+3. **初始化資料庫**
+```cmd
+python init_db.py
+```
+
+4. **啟動 ONLYOFFICE Document Server**
+```cmd
+docker run -d -p 8080:80 --restart=always ^
+    -e JWT_ENABLED=true ^
+    -e JWT_SECRET=your-onlyoffice-jwt-secret-string ^
+    onlyoffice/documentserver
+```
+
+5. **啟動應用程式**
+```cmd
+REM 開發環境
+python app.py
+
+REM 生產環境 (Windows 建議使用 Waitress)
+pip install waitress
+waitress-serve --host=0.0.0.0 --port=5000 app:app
+```
+
+#### Linux 環境
+
+1. **安裝Python依賴**
 ```bash
 pip install -r requirements.txt
 ```
 
-### 4. 設定環境變數
-
-複製範例檔案，並填入您的實際設定：
-
+2. **設定環境變數**
 ```bash
-# Windows
-copy .env.example .env
-
-# macOS / Linux
 cp .env.example .env
+# 編輯 .env 檔案
 ```
 
-編輯 `.env` 檔案，確保包含以下所有欄位：
-
-```dotenv
-# Flask 應用程式的密鑰，用於保護 session
-SECRET_KEY="your-super-secret-and-random-string"
-
-# 資料庫連線 URL
-DATABASE_URL="mysql+pymysql://user:password@host:port/dbname"
-
-# --- ONLYOFFICE 設定 ---
-# 您 ONLYOFFICE Document Server 的公開存取位址
-ONLYOFFICE_URL="http://localhost:8080/"
-
-# 用於保護 ONLYOFFICE 通訊的 JWT 密鑰 (請務必修改為一個新的隨機長字串)
-ONLYOFFICE_JWT_SECRET="your-onlyoffice-jwt-secret-string"
-```
-
-**注意**: 請先在您的 MySQL 中手動建立一個資料庫。
-
-### 5. 啟動 ONLYOFFICE Document Server
-
-使用 Docker 啟動 ONLYOFFICE Document Server，並啟用 JWT 驗證。
-
-```bash
-docker run -i -t -d -p 8080:80 --restart=always \
-    -e JWT_ENABLED=true \
-    -e JWT_SECRET="your-onlyoffice-jwt-secret-string" \
-    onlyoffice/documentserver
-```
-
-**[重要]**：指令中的 `JWT_SECRET` 值，必須和您在 `.env` 檔案中設定的 `ONLYOFFICE_JWT_SECRET` **完全一致**。
-
-### 6. 初始化資料庫
-
-執行初始化腳本來建立所有需要的資料表，並產生一個預設的管理員帳號。
-
+3. **初始化資料庫**
 ```bash
 python init_db.py
 ```
 
-腳本會提示您確認操作。輸入 `yes` 後，它會建立資料表並在終端機中顯示預設 `admin` 帳號的隨機密碼。**請務必記下此密碼**。
+4. **啟動 ONLYOFFICE Document Server**
+```bash
+docker run -d -p 8080:80 --restart=always \
+    -e JWT_ENABLED=true \
+    -e JWT_SECRET=your-onlyoffice-jwt-secret-string \
+    onlyoffice/documentserver
+```
+
+5. **啟動應用程式**
+```bash
+# 開發環境
+python app.py
+
+# 生產環境 (使用 Gunicorn)
+pip install gunicorn
+gunicorn -w 4 -b 0.0.0.0:5000 app:app
+```
+
+### 生產環境部署
+
+#### 使用 Nginx + Gunicorn (Linux)
+
+1. **安裝 Gunicorn**
+```bash
+pip install gunicorn
+```
+
+2. **建立 Gunicorn 服務檔案**
+```bash
+sudo nano /etc/systemd/system/tempspec.service
+```
+
+內容：
+```ini
+[Unit]
+Description=Temp Spec System
+After=network.target
+
+[Service]
+User=www-data
+Group=www-data
+WorkingDirectory=/path/to/your/app
+Environment="PATH=/path/to/your/app/venv/bin"
+ExecStart=/path/to/your/app/venv/bin/gunicorn -w 4 -b 127.0.0.1:5000 app:app
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+3. **Nginx 設定**
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+    
+    location / {
+        proxy_pass http://127.0.0.1:5000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+}
+```
+
+4. **啟動服務**
+```bash
+sudo systemctl enable tempspec
+sudo systemctl start tempspec
+```
+
+#### Windows IIS 部署
+
+1. **安裝 IIS 與 Python**
+2. **安裝 HttpPlatformHandler**
+3. **設定 Web.config**
+```xml
+<configuration>
+  <system.webServer>
+    <handlers>
+      <add name="PythonHandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified"/>
+    </handlers>
+    <httpPlatform processPath="C:\path\to\python.exe"
+                  arguments="app.py"
+                  startupTimeLimit="60"
+                  startupRetryCount="3">
+    </httpPlatform>
+  </system.webServer>
+</configuration>
+```
+
+## ⚙️ 組態設定
+
+### 環境變數 (.env)
+
+```env
+# Flask 設定
+SECRET_KEY=your_secret_key_here
+UPLOAD_FOLDER=uploads
+
+# 資料庫設定
+DATABASE_URL=mysql+pymysql://user:password@localhost/tempspec_db
+
+# LDAP 設定
+LDAP_SERVER=ldap://your-dc.company.com
+LDAP_PORT=389
+LDAP_USE_SSL=False
+LDAP_SEARCH_BASE=DC=company,DC=com
+LDAP_BIND_USER_DN=CN=service,DC=company,DC=com
+LDAP_BIND_USER_PASSWORD=service_password
+LDAP_USER_LOGIN_ATTR=userPrincipalName
+
+# SMTP 郵件設定
+SMTP_SERVER=smtp.company.com
+SMTP_PORT=587
+SMTP_USE_TLS=True
+SMTP_SENDER_EMAIL=noreply@company.com
+SMTP_SENDER_PASSWORD=smtp_password
+
+# ONLYOFFICE 設定
+ONLYOFFICE_URL=http://onlyoffice:8080
+ONLYOFFICE_JWT_SECRET=your_jwt_secret
+```
+
+### 特殊注意事項
+
+#### Windows 環境差異
+
+1. **排程服務限制**
+   - APScheduler 在 Windows 上運行正常
+   - 若使用 Celery，需要額外設定：
+   ```bash
+   # Windows 環境需要使用 eventlet 或 solo 執行器
+   celery -A app.celery worker --loglevel=info --pool=solo
+   ```
+
+2. **路徑設定**
+   ```python
+   # Windows 環境請使用絕對路徑或適當的路徑分隔符
+   UPLOAD_FOLDER = r'C:\path\to\uploads'
+   ```
+
+3. **服務安裝**
+   ```bash
+   # 使用 NSSM 將 Python 應用程式安裝為 Windows 服務
+   nssm install TempSpecSystem python.exe app.py
+   ```
+
+#### Linux 環境最佳化
+
+1. **系統服務設定**
+   ```bash
+   # 設定系統服務自動啟動
+   sudo systemctl enable tempspec.service
+   ```
+
+2. **日誌管理**
+   ```bash
+   # 使用 logrotate 管理日誌檔案
+   sudo nano /etc/logrotate.d/tempspec
+   ```
+
+3. **效能調校**
+   ```bash
+   # Gunicorn 推薦設定
+   gunicorn -w 4 -k gevent --worker-connections 1000 -b 0.0.0.0:5000 app:app
+   ```
+
+## 🔐 安全性設定
+
+### LDAP 整合
+- 支援 SSL/TLS 加密連線
+- 服務帳號權限最小化原則
+- 自動用戶同步與權限管控
+
+### 資料保護
+- JWT Token 驗證
+- 檔案存取權限控制
+- SQL Injection 防護
+- XSS 攻擊防護
+
+## 📚 使用說明
+
+### 登入規範
+
+**重要**：系統要求使用完整的UPN格式帳號登入
+
+✅ **正確格式**：`user@domain.com`
+❌ **錯誤格式**：`user`
+
+### 初次設定管理員
+
+系統預設所有使用者為 `viewer` 權限。設定管理員的方式：
+
+1. **程式設定**：修改 `routes/auth.py` 中的預設管理員帳號
+
+2. **手動設定**：在資料庫中更新用戶權限：
+```sql
+UPDATE ts_user SET role='admin' WHERE username='user@domain.com';
+```
+
+3. **程式設定**：修改 `routes/auth.py` 中的管理員帳號列表：
+```python
+# 將特定用戶設為管理員
+if user_info['username'].lower() == 'your_admin@domain.com':
+    default_role = 'admin'
+```
+
+### 排程任務說明
+
+系統預設每天凌晨 2:00 執行到期檢查任務，可在 `app.py` 中調整：
+
+```python
+@scheduler.task('cron', id='check_expiring_specs_job', hour=2, minute=0)
+def scheduled_job():
+    check_expiring_specs(app)
+```
+
+### 自訂提醒天數
+
+在 `tasks.py` 中修改提醒時程：
+
+```python
+seven_days_later = today + timedelta(days=7)  # 7天前提醒
+three_days_later = today + timedelta(days=3)  # 3天前提醒
+```
+
+### 預設收件人群組設定
+
+在 `tasks.py` 中設定自動提醒的收件人：
+
+```python
+# 修改為實際的 AD 群組名稱
+default_recipients = get_ldap_group_members('TempSpec_Admins')
+```
+
+## 🐛 疑難排解
+
+### 常見問題
+
+1. **LDAP 連線失敗**
+   - 檢查防火牆設定 (通常是 389/636 port)
+   - 確認服務帳號權限
+   - 驗證 LDAP 伺服器位址和搜尋基底
+
+2. **ONLYOFFICE 無法載入**
+   - 確認 Document Server 運行狀態：`docker ps`
+   - 檢查網路連線設定
+   - 驗證 JWT Secret 設定是否一致
+
+3. **郵件發送失敗**
+   - 確認 SMTP 設定正確
+   - 檢查郵件伺服器認證
+   - 驗證防火牆規則 (通常是 25/587/465 port)
+
+4. **排程任務未執行**
+   - 檢查 APScheduler 初始化
+   - 確認應用程式持續運行
+   - 查看系統日誌
+
+5. **檔案上傳失敗**
+   - 檢查上傳目錄權限
+   - 確認檔案大小限制設定
+   - 驗證磁碟空間是否足夠
+
+### 日誌查看
+
+```bash
+# Docker 環境
+docker-compose logs -f app
+
+# 一般環境
+tail -f logs/app.log
+
+# Windows 環境
+Get-Content logs/app.log -Tail 10 -Wait
+```
+
+### 效能監控
+
+```bash
+# 監控資源使用
+htop
+docker stats
+
+# 檢查資料庫效能
+SHOW PROCESSLIST;
+SHOW ENGINE INNODB STATUS;
+```
+
+## 🤝 開發指南
+
+### 開發環境設定
+
+1. **虛擬環境建立**
+```bash
+python -m venv venv
+source venv/bin/activate  # Linux
+venv\Scripts\activate     # Windows
+```
+
+2. **安裝開發依賴**
+```bash
+pip install -r requirements.txt
+pip install -r requirements-dev.txt  # 如果有開發專用依賴
+```
+
+3. **資料庫遷移**
+```bash
+python init_db.py
+```
+
+### 程式碼結構
+
+```
+├── app.py              # 主應用程式
+├── config.py           # 組態設定
+├── models.py           # 資料模型
+├── tasks.py            # 排程任務
+├── routes/             # 路由模組
+│   ├── auth.py         # 認證相關
+│   ├── temp_spec.py    # 暫規管理
+│   ├── upload.py       # 檔案上傳
+│   └── api.py          # API介面
+├── templates/          # 前端範本
+├── static/             # 靜態檔案
+├── utils.py            # 工具函式
+└── ldap_utils.py       # LDAP 工具
+```
+
+### 新增功能開發
+
+1. **建立新的路由模組**
+2. **新增對應的資料模型**
+3. **建立前端範本**
+4. **撰寫單元測試**
+
+## 📄 授權條款
+
+本專案採用 MIT 授權條款，詳見 [LICENSE](LICENSE) 檔案。
+
+## 🆕 版本歷程
+
+### v3.0.0 (2024-01-XX)
+- 🆕 新增 LDAP/AD 整合驗證
+- 🆕 整合 ONLYOFFICE 線上編輯器  
+- 🆕 實作智慧通知系統
+- 🆕 新增自動排程提醒功能
+- 🆕 支援 Docker 容器化部署
+- ♻️ 重構權限管理系統
+- 🗑️ 移除本地帳號管理功能
+
+### v2.x.x
+- Toast UI Editor 整合
+- 基本文件管理功能
+- 本地帳號系統
+
+## 📞 技術支援
+
+如有問題或建議，請透過以下方式聯繫：
+
+- 📧 Email: support@company.com
+- 📋 Issue Tracker: GitHub Issues
+- 📖 文件wiki: GitHub Wiki
 
 ---
 
-## 執行應用程式
-
-### 開發模式
-
-**請確保您的 ONLYOFFICE Docker 容器已在運行中**，然後在另一個終端機視窗執行 `app.py`：
-
-```bash
-python app.py
-```
-
-應用程式預設會在 `http://127.0.0.1:5000` 上執行。
-
-### 生產環境
-
-在生產環境中，建議使用生產級的 WSGI 伺服器，例如 `Gunicorn` (Linux) 或 `Waitress` (Windows)。
-
-**使用 Waitress (Windows) 的範例:**
-
-```bash
-pip install waitress
-waitress-serve --host=0.0.0.0 --port=8000 app:app
-```
+**暫時規範管理系統 V3** - 讓企業文件管理更智慧、更高效！