TEMP_spec_system_V3/DEMO_GUIDE.md

# 暫時規範管理系統 V3 - 測試/Demo 啟動指南

本指南專門用於快速啟動系統進行測試或演示。

## 🚀 快速啟動 (建議用於Demo)

### 選項1：Docker 一鍵啟動 (最簡單)

```bash
# 1. 複製並設定環境變數
cp .env.example .env

# 2. 編輯 .env 檔案 (重要！)
# 設定以下關鍵參數：
# - LDAP_SERVER=ldap://your-dc.company.com
# - LDAP_BIND_USER_DN=CN=service,DC=company,DC=com
# - LDAP_BIND_USER_PASSWORD=your_service_password

# 3. 啟動所有服務
docker-compose up -d

# 4. 等待服務啟動 (約30-60秒)
docker-compose logs -f

# 5. 初始化資料庫
docker-compose exec app python init_db.py

# 6. 訪問系統
# http://localhost:5000
```

### 選項2：本機開發模式

```bash
# Windows
start-windows.bat

# Linux
./start-linux.sh
```

## 📋 Demo 前檢查清單

### 必要服務檢查
- [ ] **MySQL**: `docker ps` 確認 tempspec-mysql 運行中
- [ ] **ONLYOFFICE**: 訪問 http://localhost:8080 確認運行正常
- [ ] **Flask App**: 訪問 http://localhost:5000 確認可登入
- [ ] **LDAP連線**: 使用AD帳號測試登入

### 權限設定確認
- [ ] **admin@company.com**: 已設定為管理員權限
- [ ] **權限管理頁面**: 可透過選單訪問
- [ ] **角色功能**: admin/editor/viewer 功能正常

## 🔧 資料庫架構變更說明

### ⚠️ 重要：資料表名稱變更

如果您有現有的資料庫，請注意以下變更：

**舊版本 → V3 變更**:
```
user → ts_user
temp_spec → ts_temp_spec  
upload → ts_upload
spec_history → ts_spec_history
```

### 資料移轉腳本 (如果需要)

如果需要從舊版本遷移資料：

```sql
-- 備份現有資料
CREATE TABLE user_backup AS SELECT * FROM user;
CREATE TABLE temp_spec_backup AS SELECT * FROM temp_spec;
-- 其他表的備份...

-- 重命名資料表 (謹慎操作！)
RENAME TABLE user TO ts_user;
RENAME TABLE temp_spec TO ts_temp_spec;
RENAME TABLE upload TO ts_upload;
RENAME TABLE spec_history TO ts_spec_history;
```

**建議**: 如果是演示環境，直接重新初始化資料庫即可：

```bash
# 清除舊資料並重新初始化
docker-compose down -v  # 刪除所有卷
docker-compose up -d
docker-compose exec app python init_db.py
```

## 🧪 Demo 測試流程

### 基本功能測試

1. **登入測試**
```bash
# 測試AD帳號登入
用戶: admin@company.com
密碼: [AD密碼]
```

2. **權限管理測試**
   - 登入後訪問 "權限管理" 選單
   - 確認可以看到使用者列表
   - 測試權限變更功能

3. **規範建立流程**
   - 建立新的暫時規範
   - 測試 ONLYOFFICE 編輯功能
   - 下載 Word 文件

4. **智慧通知測試**
   - 測試啟用規範時的收件人選擇
   - 確認 LDAP 搜尋功能運作
   - 驗證郵件發送 (如果SMTP已設定)

5. **排程任務測試**
   - 檢查排程任務是否已註冊
   - 模擬到期提醒功能

### Demo 劇本建議

```
1. 開場 - 系統介紹 (2分鐘)
   "這是企業級暫時規範管理系統V3，集成了AD認證和智慧通知"

2. 登入演示 (1分鐘)
   展示AD單一登入功能

3. 權限管理 (2分鐘)
   展示LDAP整合的權限管理界面

4. 規範建立 (3分鐘)
   展示從建立到線上編輯的完整流程

5. 智慧通知 (2分鐘)
   展示動態收件人選擇和自動提醒功能

6. 總結 (1分鐘)
   強調V3的主要改進和企業級特性
```

## 🛠️ 疑難排解

### 常見問題

1. **LDAP連線失敗**
```bash
# 檢查LDAP設定
docker-compose exec app python -c "
from ldap_utils import authenticate_ldap_user
print(authenticate_ldap_user('testuser', 'testpass'))
"
```

2. **ONLYOFFICE無法載入**
```bash
# 檢查Document Server狀態
curl http://localhost:8080/healthcheck
docker logs tempspec-onlyoffice
```

3. **資料庫連線問題**
```bash
# 檢查MySQL狀態
docker-compose exec mysql mysql -u root -p -e "SHOW DATABASES;"
```

4. **權限設定問題**
```sql
-- 直接在資料庫中設定管理員
USE tempspec_db;
UPDATE ts_user SET role='admin' WHERE username='admin@company.com';
```

### 快速重置

如果需要完全重置系統：

```bash
# 停止並刪除所有容器和資料
docker-compose down -v --remove-orphans

# 清理Docker資源
docker system prune -f

# 重新啟動
docker-compose up -d
sleep 30
docker-compose exec app python init_db.py

echo "系統已完全重置！"
```

## 📊 系統狀態監控

### 檢查系統健康狀態

```bash
#!/bin/bash
# health-check.sh

echo "=== 系統狀態檢查 ==="

echo "1. Docker 服務狀態:"
docker-compose ps

echo -e "\n2. 應用程式可訪問性:"
curl -s -o /dev/null -w "%{http_code}" http://localhost:5000 && echo " ✓ Flask App: 正常" || echo " ✗ Flask App: 異常"

echo -e "\n3. ONLYOFFICE 狀態:"
curl -s -o /dev/null -w "%{http_code}" http://localhost:8080 && echo " ✓ ONLYOFFICE: 正常" || echo " ✗ ONLYOFFICE: 異常"

echo -e "\n4. MySQL 狀態:"
docker-compose exec mysql mysqladmin ping -h localhost -u root -p$DB_ROOT_PASSWORD --silent && echo " ✓ MySQL: 正常" || echo " ✗ MySQL: 異常"

echo -e "\n5. 磁碟空間:"
df -h | grep -E "(Filesystem|/dev/)"

echo -e "\n6. 記憶體使用:"
free -h

echo -e "\n=== 檢查完成 ==="
```

## 📝 Demo 注意事項

1. **網路環境**: 確保Demo環境可以連接到公司的LDAP伺服器
2. **防火牆**: 開放必要的端口 (389/636 for LDAP, 25/587 for SMTP)
3. **測試資料**: 準備一些測試用的暫時規範範例
4. **備案計畫**: 準備離線Demo資料以防網路問題
5. **效能考量**: Demo環境建議至少4GB RAM，確保ONLYOFFICE穩定運行

## 🎯 成功標準

Demo成功的標誌：
- ✅ AD帳號可以正常登入
- ✅ 權限管理功能運作正常
- ✅ ONLYOFFICE編輯器可以載入和編輯
- ✅ 智慧通知功能可以搜尋LDAP用戶
- ✅ 排程任務已正確註冊
- ✅ 所有核心功能響應時間 < 3秒

---

**祝您Demo順利！** 如有任何問題，請參考系統日誌。