暫時規範管理系統 V4

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

🚀 系統特色

• LDAP/AD 整合驗證：支援企業Active Directory單一登入
• ONLYOFFICE 線上編輯：即時協作文件編輯功能
• 智慧通知系統：動態收件人選擇與自動提醒
• 文件生命週期管理：完整的建立、啟用、展延、終止流程
• 時區完整支援：台灣時區 (GMT+8) 全系統支援
• 展延次數控制：最多2次展延，總效期限制90天
• Docker 容器化：一鍵部署環境

📋 功能模組

核心功能

• 文件管理：Word範本自動化生成與PDF轉換
• 權限控制：三級權限管理 (Viewer/Editor/Admin)
• 歷史追蹤：完整的操作記錄與版本控制
• 檔案上傳：支援多種格式的佐證文件上傳
• 展延限制：最多展延2次，總效期上限90天，防止無限延期

權限說明

• Viewer（檢視者）：檢視所有規範、下載PDF檔案、檢視歷史紀錄
• Editor（編輯者）：建立新規範、編輯內容、展延/終止規範、下載檔案
• Admin（管理員）：所有Editor權限 + 啟用規範 + 刪除規範

智慧通知系統

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

編輯器整合

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

🏗️ 系統架構

暫時規範系統 V4
├── 前端介面 (Flask + Bootstrap 5)
├── 後端邏輯 (Python Flask)
├── 資料庫 (MySQL 外部)
├── LDAP整合 (Active Directory)
├── 文件引擎 (ONLYOFFICE)
├── 快取服務 (Redis)
├── 排程服務 (APScheduler)
├── 反向代理 (Nginx)
└── 郵件系統 (SMTP)

🛠️ 技術棧

• 後端框架：Python Flask 3.x
• 資料庫ORM：SQLAlchemy
• 前端UI：Bootstrap 5 + Tom Select
• 文件處理：python-docx, docx2pdf
• 認證系統：Flask-Login + LDAP3
• 排程系統：Flask-APScheduler
• 快取服務：Redis
• 反向代理：Nginx
• 容器化：Docker + Docker Compose

📦 安裝部署

前置需求

• Docker & Docker Compose
• 外部 MySQL 8.0+ 資料庫
• LDAP/Active Directory 伺服器
• SMTP 郵件伺服器

快速開始 (Docker)

1. 克隆專案

git clone <repository-url>
cd TEMP_spec_system_V4

2. 設定環境變數

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

3. 使用Docker Compose啟動

# 建置並啟動所有服務（強制重建以確保使用最新代碼）
docker-compose up -d --build

# 檢查服務狀態
docker-compose ps

# 停止服務
docker-compose down

# 查看日誌
docker-compose logs -f

4. 初始化資料庫

docker-compose exec app python init_db.py

5. 系統訪問

啟動完成後，您可以通過以下地址訪問系統：

• 主系統入口：http://localhost:12013 (推薦使用，通過 Nginx 代理)
• ONLYOFFICE 文件服務器：http://localhost:12015

注意：

• 建議使用 Nginx 代理入口 (12013) 訪問系統，具有更好的性能和安全性
• 首次啟動 ONLYOFFICE 可能需要 2-3 分鐘初始化，請等待容器狀態變為 healthy

⚙️ 組態設定

環境變數 (.env)

# Flask 設定
SECRET_KEY=your_secret_key_here
FLASK_ENV=production

# 資料庫設定 (外部 MySQL)
DATABASE_URL=mysql+pymysql://A060:WLeSCi0yhtc7@mysql.theaken.com:33306/db_A060

# LDAP 設定 (預設配置)
LDAP_SERVER=panjit.com.tw
LDAP_PORT=389
LDAP_USE_SSL=false
LDAP_SEARCH_BASE=DC=panjit,DC=com,DC=tw
LDAP_BIND_USER_DN=CN=LdapBind,CN=Users,DC=PANJIT,DC=COM,DC=TW
LDAP_BIND_USER_PASSWORD=panjit2481
LDAP_USER_LOGIN_ATTR=userPrincipalName

# SMTP 郵件設定
SMTP_SERVER=mail.panjit.com.tw
SMTP_PORT=25
SMTP_USE_TLS=false
SMTP_USE_SSL=false
SMTP_AUTH_REQUIRED=false
SMTP_SENDER_EMAIL=temp-spec-system@panjit.com.tw
SMTP_SENDER_PASSWORD=

# ONLYOFFICE 設定
ONLYOFFICE_URL=http://localhost:12015/
ONLYOFFICE_INTERNAL_URL=http://onlyoffice:80
ONLYOFFICE_JWT_SECRET=your_jwt_secret_key_here

# Redis 設定
REDIS_URL=redis://redis:6379/0

# 服務端口設定
ONLYOFFICE_PORT=12015

📚 使用說明

登入規範

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

✅ 正確格式：user@panjit.com.tw ❌ 錯誤格式：user

初次設定管理員

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

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

2. 手動設定：在資料庫中更新用戶權限：

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

展延次數限制

系統實作嚴格的展延控制機制：

• 初次生效：30天效期
• 第一次展延：效期變為60天
• 第二次展延：效期變為90天（達到上限）
• 第三次展延：系統拒絕並顯示錯誤訊息

郵件通知功能

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

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
   • 檢查容器間網路連線：docker exec panjit-tempspec-onlyoffice curl -s http://panjit-tempspec-nginx:80/health
   • 驗證 JWT Secret 設定是否一致
   • 檢查日誌中的網路錯誤：docker-compose logs onlyoffice | grep ERROR

   常見錯誤：

   • ECONNREFUSED 錯誤：通常是容器間網路配置問題
   • host.docker.internal 無法連接：應使用容器名稱而非 host.docker.internal
   • 文件下載失敗：檢查靜態檔案路徑和 nginx 代理設定

3. ONLYOFFICE 文件同步問題

   • 問題描述：在 OnlyOffice 編輯器中編輯並儲存文件後，下載的 Word 文件沒有包含最新的編輯內容

   解決方案：

   • 系統已增強 OnlyOffice 回調處理機制，支援多種儲存狀態
   • 改善了文件同步邏輯，確保編輯內容正確儲存到伺服器
   • 新增詳細的回調日誌記錄，便於問題診斷

   檢查方法：

   # 查看 OnlyOffice 回調日誌
   docker-compose logs -f app | grep "OnlyOffice callback"
   
   # 檢查文件儲存狀態
   docker-compose logs -f app | grep "Document saved successfully"
   
   # 驗證文件更新時間
   docker exec panjit-tempspec-app ls -la uploads/
   

   技術細節：

   • 回調處理現在支援 status=2 (自動儲存) 和 status=6 (強制儲存)
   • 增加了 JWT Token 驗證以確保回調安全性
   • 改善錯誤處理和檔案下載邏輯
   • 修正回調中的 URL 路由，將 localhost:12015 轉換為容器間通信地址 panjit-tempspec-onlyoffice:80

4. 時區設定問題

   • 問題描述：系統時間顯示為 GMT+0，但正確時區應該是 GMT+8（台灣時區）

   解決方案：

   • 建立完整的時區處理模組 utils/timezone.py
   • 修正所有資料庫時間欄位使用台灣時區
   • 更新前端模板使用時區轉換 filter
   • 設定 Docker 容器環境變數 TZ: Asia/Taipei

   檢查方法：

   # 檢查容器時區設定
   docker exec panjit-tempspec-app date
   
   # 測試時區轉換功能
   docker exec panjit-tempspec-app python -c "from utils.timezone import taiwan_now, format_taiwan_time; print(format_taiwan_time(taiwan_now()))"
   

   技術細節：

   • 新增 taiwan_now() 函數替代 datetime.utcnow()
   • 支援 date 和 datetime 物件的時區轉換
   • 前端模板 filter：|taiwan_time 和 |taiwan_date
   • 自動處理 naive datetime 和 timezone-aware datetime

5. 展延次數限制功能

   • 功能說明：防止暫時規範無限延期，確保企業治理合規

   限制規則：

   • 初次生效：30天效期
   • 第一次展延：效期變為60天
   • 第二次展延：效期變為90天（達到上限）
   • 第三次展延：系統拒絕並顯示錯誤訊息

   實作功能：

   • 後端邏輯檢查：當 extension_count >= 2 時拒絕展延
   • 前端介面優化：超過限制時展延按鈕變為不可用
   • 視覺化顯示：展延次數進度和剩餘次數
   • 樣式改進：深色背景下清楚可見的展延狀態顯示

6. 郵件發送失敗

   • 確認 SMTP 設定正確
   • 檢查郵件伺服器認證設定
   • 驗證防火牆規則 (Port 25/587/465)

7. 排程任務未執行

   • 檢查 APScheduler 初始化
   • 確認應用程式持續運行
   • 查看系統日誌

8. 容器間網路通訊問題

   • 檢查所有容器是否在同一網路：docker network ls
   • 驗證容器名稱解析：docker exec container1 ping container2
   • 確認端口映射：docker-compose ps

   OnlyOffice 網路問題修正：

   # 檢查 OnlyOffice 能否連接到 Flask 應用
   docker exec panjit-tempspec-onlyoffice curl -I http://panjit-tempspec-nginx:80/static/
   
   # 檢查 Flask 應用日誌
   docker-compose logs -f app
   
   # 重新構建有網路修正的應用
   docker-compose up -d --build app
   

日誌查看

# Docker 環境
docker-compose logs -f app

# OnlyOffice 相關日誌
docker-compose logs -f onlyoffice
docker exec panjit-tempspec-onlyoffice tail -f /var/log/onlyoffice/documentserver/docservice/out.log

# Redis 日誌
docker-compose logs -f redis

# Nginx 日誌
docker-compose logs -f nginx

🤝 開發指南

程式碼結構

├── app.py              # 主應用程式
├── config.py           # 組態設定
├── models.py           # 資料模型
├── tasks.py            # 排程任務
├── wsgi.py             # WSGI 入口點
├── gunicorn.conf.py    # Gunicorn 配置
├── routes/             # 路由模組
│   ├── __init__.py
│   ├── auth.py         # 認證相關
│   ├── temp_spec.py    # 暫規管理
│   ├── upload.py       # 檔案上傳
│   ├── admin.py        # 管理功能
│   └── api.py          # API介面
├── templates/          # 前端範本
├── static/             # 靜態檔案
├── utils/              # 工具模組
│   ├── __init__.py     # 工具函式
│   └── timezone.py     # 時區處理
├── ldap_utils.py       # LDAP 工具
├── cache_utils.py      # 快取工具
├── cdn_utils.py        # CDN 工具
├── monitor.py          # 監控工具
└── nginx/              # Nginx 配置
    ├── Dockerfile
    ├── nginx.conf
    └── conf.d/

容器架構

• panjit-tempspec-app: Flask 應用程式容器
• panjit-tempspec-nginx: Nginx 反向代理容器
• panjit-tempspec-onlyoffice: OnlyOffice 文件服務器容器
• panjit-tempspec-redis: Redis 快取服務容器

網路配置

所有容器運行在 tempspec-network 橋接網路中，確保容器間通信：

• 外部訪問：通過 Nginx (port 12013) 和 OnlyOffice (port 12015)
• 內部通信：使用容器名稱作為主機名

📄 授權條款

本專案採用 MIT 授權條款。

🆕 版本歷程

v4.0.0 (最新版本)

• 🆕 新增台灣時區 (GMT+8) 完整支援
• 🆕 實作展延次數限制功能（最多2次，總效期90天）
• 🆕 修正 OnlyOffice 文件同步問題
• 🎨 改進規範列表頁面樣式和用戶體驗
• 🔧 修正時區 filter 支援 date 物件處理
• 🗑️ 移除舊版 utils.py，改用模組化架構
• 🔧 修正容器間網路通信問題
• 🆕 新增 Redis 快取服務
• 🆕 新增 Nginx 反向代理

v3.2.0

• 🆕 新增郵件通知記憶功能
• 🆕 支援 Port 25 無認證 SMTP
• ♻️ 優化郵件管理邏輯
• 🗑️ 移除測試檔案和調試代碼

v3.1.0

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

v3.0.0

• ♻️ 重構權限管理系統
• 🗑️ 移除本地帳號管理功能

---

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