# 部署指南 - 暫時規範管理系統 V4

本文件提供詳細的部署指導，涵蓋 Docker 環境部署方式及 V4 版本的新特性配置。

## 🎉 V4.0 版本優化完成

**✅ 已完成企業級生產環境優化**：
- 台灣時區 (GMT+8) 完整支援
- 展延次數限制功能（最多2次，90天上限）
- OnlyOffice 文件同步問題修正
- Redis 快取系統（提升效能）
- Nginx 反向代理（負載均衡）
- 容器間網路優化
- 時區處理模組化
- UI 樣式改進

## 📋 目錄

1. [系統需求](#1-系統需求)
2. [快速部署](#2-快速部署)
3. [生產環境配置](#3-生產環境配置)
4. [V4.0 新功能配置](#4-v40-新功能配置)
5. [監控與管理](#5-監控與管理)
6. [服務訪問](#6-服務訪問)
7. [疑難排解](#7-疑難排解)

## 1. 系統需求

### 前置需求檢查清單

- [ ] Docker 20.10+ 已安裝且運行中
- [ ] Docker Compose 2.0+ 已安裝
- [ ] 外部 MySQL 資料庫可訪問 (mysql.theaken.com:33306)
- [ ] LDAP/Active Directory 伺服器可連線 (panjit.com.tw)
- [ ] SMTP 郵件伺服器已配置 (mail.panjit.com.tw)
- [ ] 足夠的磁碟空間 (建議至少 10GB)

### 端口需求

確保以下端口未被占用：
- `12010`: Flask 應用程式（內部，可選直接訪問）
- `12013`: Nginx HTTP（反向代理，主要入口）
- `12015`: OnlyOffice 文檔服務
- `6379`: Redis 快取（容器內部）

### V4.0 網路架構

```
用戶 → Nginx (12013) → Flask App (5000) → MySQL (外部)
                     ↓                  ↓
                  Redis (6379)     OnlyOffice (80)
```

## 2. 快速部署

### 一鍵部署（推薦）

```bash
# 1. 克隆專案
git clone <repository-url>
cd TEMP_spec_system_V4

# 2. 配置環境變數（使用預設配置）
cp .env.example .env
# 編輯 .env 文件，大部分配置已預設好

# 3. 啟動所有服務（V4.0優化版本）
docker-compose up -d --build

# 4. 檢查服務狀態
docker-compose ps
```

**預期輸出應包含以下服務**：
```
NAME                        STATUS              PORTS
panjit-tempspec-redis       Up (healthy)
panjit-tempspec-onlyoffice  Up (healthy)        0.0.0.0:12015->80/tcp
panjit-tempspec-app         Up (healthy)
panjit-tempspec-nginx       Up                  0.0.0.0:12013->80/tcp
```

```bash
# 5. 查看服務日誌
docker-compose logs -f

# 6. 驗證服務可訪問性
curl -I http://localhost:12013/login    # Nginx 反向代理（推薦）
curl -I http://localhost:12015          # OnlyOffice 服務
```

### 初始化資料庫

```bash
# 初始化資料庫結構
docker-compose exec app python init_db.py

# 檢查資料庫連接
docker-compose exec app python -c "
from app import app
from models import db
with app.app_context():
    try:
        db.engine.execute('SELECT 1')
        print('✅ Database connection successful')
    except Exception as e:
        print(f'❌ Database connection failed: {e}')
"
```

## 3. 生產環境配置

### 3.1 服務架構（V4.0 優化）

```
外部用戶 → Nginx (12013) → Flask App (Gunicorn) → 外部MySQL
                         ↓                      ↓
                    Redis快取           OnlyOffice (12015)
                         ↓
                   台灣時區處理模組
```

**V4.0 服務組件**：
- **Nginx**: 反向代理 + 靜態檔案（端口 12013）
- **Flask 應用**: Gunicorn WSGI 伺服器（內部端口 5000）
- **Redis**: 快取系統（內部端口 6379）
- **OnlyOffice**: 文檔編輯服務（端口 12015）
- **MySQL**: 外部資料庫服務（mysql.theaken.com:33306）

### 3.2 V4.0 效能規格

- **時區支援**: 全系統台灣時區 (GMT+8) 處理
- **展延控制**: 最多2次展延，90天效期上限
- **文件同步**: 增強的 OnlyOffice 回調處理
- **快取優化**: Redis 減少資料庫查詢負載
- **網路優化**: 容器間通信使用服務名稱
- **響應時間**: < 200ms（快取命中時）

### 3.3 環境變數配置

編輯 `.env` 檔案：

```env
# V4.0 基本設定
SECRET_KEY=your_super_secret_production_key_here
FLASK_ENV=production

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

# Redis 快取
REDIS_URL=redis://redis:6379/0

# LDAP 設定（V4.0預設配置）
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 設定（V4.0預設配置）
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

# 服務端口設定
ONLYOFFICE_PORT=12015
```

## 4. V4.0 新功能配置

### 4.1 台灣時區支援

**自動配置**：
- Docker 容器環境變數：`TZ: Asia/Taipei`
- Python 時區模組：`utils/timezone.py`
- 資料庫時間自動轉換為台灣時區

**驗證時區設定**：
```bash
# 檢查容器時區
docker exec panjit-tempspec-app date

# 測試 Python 時區功能
docker exec panjit-tempspec-app python -c "
from utils.timezone import taiwan_now, format_taiwan_time
print('Current Taiwan time:', format_taiwan_time(taiwan_now()))
"
```

### 4.2 展延次數限制

**功能說明**：
- 每個暫時規範最多展延2次
- 總效期上限90天
- 前端按鈕自動禁用
- 後端邏輯驗證

**配置驗證**：
```bash
# 檢查展延限制邏輯
docker exec panjit-tempspec-app python -c "
from app import app
with app.app_context():
    print('Extension limit logic loaded successfully')
"
```

### 4.3 OnlyOffice 文件同步

**V4.0 改進**：
- 支援多種儲存狀態（status=2, status=6）
- 增強回調 URL 處理
- 修正容器間網路通信

**同步測試**：
```bash
# 測試 OnlyOffice 網路連接
docker exec panjit-tempspec-onlyoffice curl -I http://panjit-tempspec-nginx:80/

# 檢查回調處理日誌
docker-compose logs app | grep "OnlyOffice callback"
```

### 4.4 Redis 快取系統

**配置檢查**：
```bash
# 檢查 Redis 連接
docker-compose exec redis redis-cli ping

# 查看快取統計
docker-compose exec redis redis-cli info stats

# 監控快取使用
docker-compose exec redis redis-cli monitor
```

## 5. 監控與管理

### 5.1 系統監控

```bash
# V4.0 系統監控（如有 monitor.py）
python monitor.py --watch 5

# Docker 容器監控
docker-compose ps
docker stats

# 服務健康檢查
docker-compose logs --tail=50 app
docker-compose logs --tail=50 nginx
docker-compose logs --tail=50 redis
docker-compose logs --tail=50 onlyoffice
```

### 5.2 V4.0 特定檢查

```bash
# 時區功能檢查
docker exec panjit-tempspec-app python -c "
from utils.timezone import taiwan_now, to_taiwan_time
from datetime import datetime
print('Taiwan now:', taiwan_now())
print('UTC to Taiwan:', to_taiwan_time(datetime.utcnow()))
"

# 展延限制檢查
docker exec panjit-tempspec-app python -c "
from models import TempSpec
from app import app
with app.app_context():
    specs = TempSpec.query.filter(TempSpec.extension_count >= 2).count()
    print(f'Specs at extension limit: {specs}')
"

# OnlyOffice 同步檢查
docker-compose logs app | grep -E "(callback|sync|save)" | tail -10
```

### 5.3 Redis 快取管理

```bash
# 快取狀態檢查
docker-compose exec redis redis-cli info memory
docker-compose exec redis redis-cli dbsize

# 清空快取（如需要）
docker-compose exec redis redis-cli flushall

# 監控快取命中率
docker-compose exec redis redis-cli info stats | grep hit
```

## 6. 服務訪問

### 6.1 V4.0 服務入口

**主要服務**：
- **主應用程式 (Nginx)**: http://localhost:12013 🌟 **推薦**
- **OnlyOffice 服務**: http://localhost:12015

**V4.0 登入資訊**：
- **認證方式**: LDAP/Active Directory
- **登入格式**: `username@panjit.com.tw`
- **時區顯示**: 所有時間使用台灣時區 (GMT+8)

### 6.2 V4.0 新功能驗證

登入後驗證以下新功能：

1. **時區顯示**: 檢查所有時間是否使用台灣時區
2. **展延限制**: 查看已展延2次的規範是否正確顯示限制
3. **文件同步**: 測試 OnlyOffice 編輯和儲存功能
4. **UI 改進**: 檢查展延狀態在深色背景下的可讀性

## 7. 疑難排解

### 7.1 V4.0 特定問題

**時區顯示錯誤**
```bash
# 檢查容器時區設定
docker exec panjit-tempspec-app date
docker exec panjit-tempspec-app python -c "
import os
print('TZ:', os.environ.get('TZ', 'Not set'))
"

# 重新啟動應用容器
docker-compose restart app
```

**展延限制未生效**
```bash
# 檢查展延邏輯
docker-compose logs app | grep -i extension

# 測試展延限制邏輯
docker exec panjit-tempspec-app python -c "
from routes.temp_spec import check_extension_limit
print('Extension limit logic available')
"
```

**OnlyOffice 文件同步問題**
```bash
# 檢查 OnlyOffice 回調
docker-compose logs app | grep "OnlyOffice callback"

# 檢查容器間網路
docker exec panjit-tempspec-onlyoffice ping panjit-tempspec-nginx

# 檢查 OnlyOffice 健康狀態
curl -I http://localhost:12015/healthcheck
```

**Redis 快取問題**
```bash
# 檢查 Redis 連接
docker-compose exec app python -c "
import redis
r = redis.Redis(host='redis', port=6379, db=0)
print('Redis ping:', r.ping())
"

# 重啟 Redis
docker-compose restart redis
```

### 7.2 容器網路問題

**容器間通信失敗**
```bash
# 檢查網路配置
docker network ls | grep tempspec
docker network inspect tempspec-network

# 測試容器間連接
docker exec panjit-tempspec-app ping panjit-tempspec-redis
docker exec panjit-tempspec-app ping panjit-tempspec-onlyoffice
docker exec panjit-tempspec-app ping panjit-tempspec-nginx
```

**端口衝突解決**
```bash
# 檢查端口占用
netstat -tulpn | grep -E "(12013|12015)"

# 修改端口配置（編輯 docker-compose.yml）
# 將衝突端口改為其他可用端口
```

### 7.3 資料庫連接問題

**MySQL 連接測試**
```bash
# 測試外部資料庫連接
docker-compose exec app python -c "
import pymysql
try:
    conn = pymysql.connect(
        host='mysql.theaken.com',
        port=33306,
        user='A060',
        password='WLeSCi0yhtc7',
        database='db_A060'
    )
    print('✅ Database connection successful')
    conn.close()
except Exception as e:
    print(f'❌ Database connection failed: {e}')
"
```

### 7.4 V4.0 維護命令

```bash
# 完全重建 V4.0 服務
docker-compose down
docker-compose build --no-cache
docker-compose up -d

# 更新單一服務
docker-compose up -d --force-recreate app

# 清理 Docker 資源
docker system prune -a

# 備份重要資料
docker exec panjit-tempspec-app tar -czf /tmp/uploads_backup.tar.gz uploads/
docker cp panjit-tempspec-app:/tmp/uploads_backup.tar.gz ./uploads_backup.tar.gz
```

### 7.5 V4.0 效能監控

```bash
# 監控容器資源使用
docker stats panjit-tempspec-app panjit-tempspec-redis panjit-tempspec-nginx

# 檢查應用效能
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:12013/login

# Redis 效能監控
docker-compose exec redis redis-cli info stats | grep -E "(hits|misses|ops)"
```

---

## 🎉 V4.0 部署完成檢查清單

- [ ] 所有容器運行正常 (`docker-compose ps`)
- [ ] 時區顯示為台灣時區 (GMT+8)
- [ ] 展延限制功能正常 (最多2次)
- [ ] OnlyOffice 文件同步正常
- [ ] Redis 快取服務運行
- [ ] Nginx 反向代理正常
- [ ] LDAP 認證功能正常
- [ ] 郵件通知功能正常
- [ ] UI 樣式顯示正確

**快速啟動**: `docker-compose up -d --build`
**服務訪問**: http://localhost:12013
**健康檢查**: `docker-compose ps && docker-compose logs --tail=10`

---

**🚀 暫時規範管理系統 V4.0 部署完成！**

系統已具備完整的台灣時區支援、展延限制控制、優化的文件同步機制以及增強的用戶體驗。