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. 克隆專案

git clone <repository-url>
cd TEMP_spec_system_V3

2. 設定環境變數

cp .env.example .env
# 編輯 .env 檔案設定資料庫、LDAP、SMTP 等參數

3. 使用Docker Compose啟動

docker-compose up -d

4. 初始化資料庫

docker-compose exec app python init_db.py

手動安裝

Windows 環境

1. 安裝Python依賴

pip install -r requirements.txt

2. 設定環境變數

copy .env.example .env
REM 編輯 .env 檔案

3. 初始化資料庫

python init_db.py

4. 啟動 ONLYOFFICE Document Server

docker run -d -p 8080:80 --restart=always ^
    -e JWT_ENABLED=true ^
    -e JWT_SECRET=your-onlyoffice-jwt-secret-string ^
    onlyoffice/documentserver

5. 啟動應用程式

REM 開發環境
python app.py

REM 生產環境 (Windows 建議使用 Waitress)
pip install waitress
waitress-serve --host=0.0.0.0 --port=5000 app:app

Linux 環境

1. 安裝Python依賴

pip install -r requirements.txt

2. 設定環境變數

cp .env.example .env
# 編輯 .env 檔案

3. 初始化資料庫

python init_db.py

4. 啟動 ONLYOFFICE Document Server

docker run -d -p 8080:80 --restart=always \
    -e JWT_ENABLED=true \
    -e JWT_SECRET=your-onlyoffice-jwt-secret-string \
    onlyoffice/documentserver

5. 啟動應用程式

# 開發環境
python app.py

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

生產環境部署

使用 Nginx + Gunicorn (Linux)

1. 安裝 Gunicorn

pip install gunicorn

2. 建立 Gunicorn 服務檔案

sudo nano /etc/systemd/system/tempspec.service

內容：

[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 設定

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. 啟動服務

sudo systemctl enable tempspec
sudo systemctl start tempspec

Windows IIS 部署

1. 安裝 IIS 與 Python
2. 安裝 HttpPlatformHandler
3. 設定 Web.config

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

# 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，需要額外設定：

   # Windows 環境需要使用 eventlet 或 solo 執行器
   celery -A app.celery worker --loglevel=info --pool=solo
   

2. 路徑設定

   # Windows 環境請使用絕對路徑或適當的路徑分隔符
   UPLOAD_FOLDER = r'C:\path\to\uploads'
   

3. 服務安裝

   # 使用 NSSM 將 Python 應用程式安裝為 Windows 服務
   nssm install TempSpecSystem python.exe app.py
   

Linux 環境最佳化

1. 系統服務設定

   # 設定系統服務自動啟動
   sudo systemctl enable tempspec.service
   

2. 日誌管理

   # 使用 logrotate 管理日誌檔案
   sudo nano /etc/logrotate.d/tempspec
   

3. 效能調校

   # 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. 手動設定：在資料庫中更新用戶權限：

UPDATE ts_user SET role='admin' WHERE username='user@domain.com';

3. 程式設定：修改 routes/auth.py 中的管理員帳號列表：

# 將特定用戶設為管理員
if user_info['username'].lower() == 'your_admin@domain.com':
    default_role = 'admin'

排程任務說明

系統預設每天凌晨 2:00 執行到期檢查任務，可在 app.py 中調整：

@scheduler.task('cron', id='check_expiring_specs_job', hour=2, minute=0)
def scheduled_job():
    check_expiring_specs(app)

自訂提醒天數

在 tasks.py 中修改提醒時程：

seven_days_later = today + timedelta(days=7)  # 7天前提醒
three_days_later = today + timedelta(days=3)  # 3天前提醒

預設收件人群組設定

在 tasks.py 中設定自動提醒的收件人：

# 修改為實際的 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. 檔案上傳失敗

   • 檢查上傳目錄權限
   • 確認檔案大小限制設定
   • 驗證磁碟空間是否足夠

日誌查看

# Docker 環境
docker-compose logs -f app

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

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

效能監控

# 監控資源使用
htop
docker stats

# 檢查資料庫效能
SHOW PROCESSLIST;
SHOW ENGINE INNODB STATUS;

🤝 開發指南

開發環境設定

1. 虛擬環境建立

python -m venv venv
source venv/bin/activate  # Linux
venv\Scripts\activate     # Windows

2. 安裝開發依賴

pip install -r requirements.txt
pip install -r requirements-dev.txt  # 如果有開發專用依賴

3. 資料庫遷移

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 檔案。

🆕 版本歷程

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

---

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