TEMP_spec_system_V3/README.md

# 暫時規範管理系統 V3

企業級暫時規範生命週期管理系統，提供完整的文件管理、LDAP整合驗證、智慧通知系統及排程提醒功能。

## 🚀 系統特色

- **LDAP/AD 整合驗證**：支援企業Active Directory單一登入
- **ONLYOFFICE 線上編輯**：即時協作文件編輯功能
- **智慧通知系統**：動態收件人選擇與自動提醒
- **文件生命週期管理**：完整的建立、啟用、展延、終止流程
- **多平台支援**：支援 Windows/Linux 環境部署
- **Docker 容器化**：一鍵部署環境

## 📋 功能模組

### 核心功能
- **文件管理**：Word範本自動化生成與PDF轉換
- **權限控制**：三級權限管理 (Viewer/Editor/Admin)
- **歷史追蹤**：完整的操作記錄與版本控制
- **檔案上傳**：支援多種格式的佐證文件上傳

### 智慧通知系統
- **動態收件人選擇**：整合LDAP的即時用戶搜尋
- **郵件記憶功能**：自動記憶並帶出之前使用的通知對象
- **全流程通知**：啟用、展延、終止操作的自動郵件通知
- **自動提醒**：3天與7天到期前的主動提醒郵件
- **排程系統**：每日自動檢查即將到期的規範

### 編輯器整合
- **ONLYOFFICE整合**：支援Word文件的線上即時編輯
- **Toast UI Editor**：Markdown格式的內容編輯器
- **圖片支援**：內嵌圖片顯示與編輯功能

## 🏗️ 系統架構

```
暫時規範系統 V3
├── 前端介面 (Flask + Bootstrap 5)
├── 後端邏輯 (Python Flask)
├── 資料庫 (MySQL/SQLite)
├── LDAP整合 (Active Directory)
├── 文件引擎 (ONLYOFFICE)
├── 排程服務 (APScheduler)
└── 郵件系統 (SMTP)
```

## 🛠️ 技術棧

- **後端框架**：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
git clone <repository-url>
cd TEMP_spec_system_V3
```

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
```

5. **資料庫遷移（如果需要）**
```bash
# 新增郵件功能欄位
docker-compose exec app python migrate_add_email_column.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. **資料庫遷移（如果需要）**
```cmd
python migrate_add_email_column.py
```

5. **啟動 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
```

6. **啟動應用程式**
```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
```

2. **設定環境變數**
```bash
cp .env.example .env
# 編輯 .env 檔案
```

3. **初始化資料庫**
```bash
python init_db.py
```

4. **資料庫遷移（如果需要）**
```bash
python migrate_add_email_column.py
```

5. **啟動 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
```

6. **啟動應用程式**
```bash
# 開發環境
python app.py

# 生產環境 (使用 Gunicorn)
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 app:app
```

## ⚙️ 組態設定

### 環境變數 (.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 郵件設定 (Port 25 無認證方式)
SMTP_SERVER=mail.company.com
SMTP_PORT=25
SMTP_USE_TLS=false
SMTP_USE_SSL=false
SMTP_AUTH_REQUIRED=false
SMTP_SENDER_EMAIL=temp-spec-system@company.com
SMTP_SENDER_PASSWORD=

# ONLYOFFICE 設定
ONLYOFFICE_URL=http://onlyoffice:8080
ONLYOFFICE_JWT_SECRET=your_jwt_secret
```

### SMTP 配置說明

系統支援多種 SMTP 配置方式：

- **Port 25（推薦）**：內部郵件伺服器，無需認證
- **Port 587**：STARTTLS + 認證
- **Port 465**：SSL + 認證

詳細設定請參考 `SMTP_CONFIGURATION_UPDATE.md`

## 📚 使用說明

### 登入規範

**重要**：系統要求使用完整的UPN格式帳號登入

✅ **正確格式**：`user@domain.com`
❌ **錯誤格式**：`user`

### 初次設定管理員

系統預設所有使用者為 `viewer` 權限。設定管理員的方式：

1. **程式設定**：修改 `routes/auth.py` 中的預設管理員帳號

2. **手動設定**：在資料庫中更新用戶權限：
```sql
UPDATE ts_user SET role='admin' WHERE username='user@domain.com';
```

### 郵件通知功能

系統具備智慧郵件管理功能：

1. **規範生效時**：輸入通知郵件對象，系統自動記憶
2. **規範終止時**：自動帶出生效時使用的郵件清單，可編輯後發送
3. **規範展延時**：自動帶出郵件清單，修改後更新記錄

### 排程任務

系統預設每天凌晨 2:00 執行到期檢查任務：

- 7天到期提醒
- 3天到期提醒
- 自動發送提醒郵件

## 🔐 安全性設定

### LDAP 整合
- 支援 SSL/TLS 加密連線
- 服務帳號權限最小化原則
- 自動用戶同步與權限管控

### 資料保護
- JWT Token 驗證
- 檔案存取權限控制
- SQL Injection 防護
- XSS 攻擊防護

## 🐛 疑難排解

### 常見問題

1. **LDAP 連線失敗**
   - 檢查防火牆設定 (通常是 389/636 port)
   - 確認服務帳號權限
   - 驗證 LDAP 伺服器位址和搜尋基底

2. **ONLYOFFICE 無法載入**
   - 確認 Document Server 運行狀態：`docker ps`
   - 檢查網路連線設定
   - 驗證 JWT Secret 設定是否一致

3. **郵件發送失敗**
   - 確認 SMTP 設定正確
   - 檢查郵件伺服器認證設定
   - 驗證防火牆規則 (Port 25/587/465)

4. **排程任務未執行**
   - 檢查 APScheduler 初始化
   - 確認應用程式持續運行
   - 查看系統日誌

### 日誌查看

```bash
# Docker 環境
docker-compose logs -f app

# 一般環境
tail -f logs/app.log

# Windows 環境
Get-Content logs/app.log -Tail 10 -Wait
```

## 🤝 開發指南

### 程式碼結構

```
├── 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 工具
```

### 資料庫遷移

當系統需要資料庫結構更新時：

```bash
# 執行遷移腳本
python migrate_add_email_column.py
```

## 📄 授權條款

本專案採用 MIT 授權條款。

## 🆕 版本歷程

### v3.2.0 (最新版本)
- 🆕 新增郵件通知記憶功能
- 🆕 支援 Port 25 無認證 SMTP
- ♻️ 優化郵件管理邏輯
- 🗑️ 移除測試檔案和調試代碼

### v3.1.0
- 🆕 新增 LDAP/AD 整合驗證
- 🆕 整合 ONLYOFFICE 線上編輯器
- 🆕 實作智慧通知系統
- 🆕 新增自動排程提醒功能
- 🆕 支援 Docker 容器化部署

### v3.0.0
- ♻️ 重構權限管理系統
- 🗑️ 移除本地帳號管理功能

---

**暫時規範管理系統 V3** - 讓企業文件管理更智慧、更高效！