# 主機維護報告 - 快速啟動指南

## 📋 功能總覽

優化後的主機維護功能包含：

✅ **完整的 API 連線邏輯**
- 自動重試（最多 3 次）
- 認證支援（Basic Auth + Token）
- 完整的數據驗證

✅ **定期報告生成系統**
- 支援按月度、季度、半年度生成
- 自動郵件發送
- 批量處理多個項目

✅ **報告完成度追蹤**
- 實時完成度百分比
- 進度條可視化
- 詳細的字段映射

✅ **多種導出格式**
- Word 文檔（支援 SSL 分析）
- Excel 電子表格
- Web 頁面展示

---

## 🚀 快速開始

### 第 1 步：配置項目

進入 **項目設定**：

1. 勾選 ✓ **寄送維護報告**
2. 選擇 **報告週期**：
   - 每月 (monthly)
   - 每季 (quarterly)  
   - 每半年 (semiannually)
3. 設定 **通知人信箱**（支援多個，逗號分隔）：
   ```
   user1@company.com, user2@company.com
   ```

### 第 2 步：配置主機

進入 **主機設定**：

1. 設定 **API URL**：
   ```
   http://192.168.1.100:8080/api/system-report
   ```

2. 如果 API 需要認證，填入：
   - **使用者名稱**
   - **密碼**

3. 保存設定

### 第 3 步：測試 API

進入主機詳情頁面，確認：

- ✓ 能夠取得報告資訊
- ✓ 完成度顯示 > 0%
- ✓ 系統資訊正常顯示

---

## 📊 查看報告

### 方式 1：Web 介面

```
主機管理 → 主機列表 → 選擇主機
```

查看內容：
- 📈 報告完成度進度條
- 📋 所有系統資訊
- 🔗 快速導出按鈕

### 方式 2：導出報告

**匯出 Word**:
```
按鈕 → 📄 匯出 Word
生成包含所有系統資訊和 SSL 分析的 Word 文檔
```

**匯出 Excel**:
```
按鈕 → 📊 匯出 Excel  
結構化的 Excel 報告，便於數據分析
```

---

## 🔧 命令行操作

### 手動生成報告

```bash
# 生成特定項目的報告
php artisan maintenance:generate --project-id=1

# 強制生成（忽略週期）
php artisan maintenance:generate --project-id=1 --force

# 生成所有需要的報告
php artisan maintenance:generate

# 查看幫助
php artisan maintenance:generate --help
```

### 檢查隊列狀態

```bash
# 開始處理隊列任務
php artisan queue:work

# 監控隊列狀態  
php artisan queue:monitor

# 查看失敗任務
php artisan queue:failed
```

---

## 📧 郵件報告

**收件人會收到**：

1. **郵件主題**:
   ```
   【工作平台】主機維護報告 - 項目名稱 (2026-03-23 01:00:00)
   ```

2. **郵件內容**:
   - 項目基本信息
   - 主機數量統計
   - 每個主機的系統資訊摘要
   - 報告完成度
   - 查看完整報告的連結

3. **自動發送時間**:
   - 每天凌晨 1:00（UTC+8）
   - 或手動觸發時立即發送

---

## 🔍 故障診斷

### ❌ 報告信息為空或 N/A

**可能原因**：API 無法連線或返回不完整的數據

**檢查步驟**：
```bash
# 1. 測試 API 連線
curl -u "username:password" http://192.168.1.100:8080/api/system-report

# 2. 查看應用日誌
tail -f storage/logs/laravel.log

# 3. 檢查主機配置
# 進入：主機管理 → 編輯主機 → 檢查 API URL 和認證信息
```

### ❌ 郵件未收到

**檢查步驟**：
```bash
# 1. 確保隊列在運行
ps aux | grep "queue:work"

# 2. 檢查郵件配置
cat .env | grep MAIL_

# 3. 查看失敗任務
php artisan queue:failed

# 4. 重試失敗任務
php artisan queue:retry all
```

### ❌ 命令執行失敗

**檢查步驟**：
```bash
# 1. 測試數據庫連線
php artisan tinker
>>> DB::connection()->getPdo();

# 2. 檢查項目配置
php artisan tinker
>>> Project::where('send_maintenance_report', true)->count();

# 3. 查看詳細日誌
php artisan maintenance:generate -v
```

---

## 📈 性能優化建議

### 1. 使用後台隊列

**差**：等待 API 響應（可能 5-30 秒）
```bash
php artisan maintenance:generate  # 同步執行
```

**好**：異步處理（立即返回）
```bash
php artisan maintenance:generate  # 發到隊列
php artisan queue:work  # 後台處理
```

### 2. 合理設定報告週期

- **日常監控**：使用 Web 介面查看
- **月度匯總**：maintenance_report_cycle = 'monthly'
- **業務報告**：maintenance_report_cycle = 'quarterly'

### 3. 監控隊列性能

```bash
# 監控隊列延遲
php artisan queue:monitor --longwait=60

# 設定自動重試
# .env: QUEUE_TIMEOUT=300
```

---

## 🔐 安全建議

### 認證信息管理

```php
// .env 中存儲敏感信息
HOST_API_USERNAME=your_username
HOST_API_PASSWORD=your_password
```

### API 訪問控制

```php
// 限制 API 訪問
Route::middleware('throttle:60,1')->group(function () {
    Route::get('hosts/{host}', [HostController::class, 'show']);
});
```

### 審計日誌

所有報告生成事件都會被記錄：
```
storage/logs/laravel.log
```

---

## 📞 常見問題

### Q: 為什麼報告沒有實時更新？

A: API 通常需要 5-30 秒取得數據。可以：
- 重新整理頁面
- 檢查 `storage/logs/laravel.log`
- 確認 API 服務正常

### Q: 如何修改報告發送時間？

A: 編輯 `app/Console/Kernel.php`：
```php
$schedule->command('maintenance:generate')
    ->dailyAt('02:00')  // 改為凌晨 2 點
    ->name('maintenance-daily-report')
    ->withoutOverlapping();
```

### Q: 如何手動立即發送報告？

A: 使用命令行：
```bash
php artisan maintenance:generate --project-id=1 --force
```

### Q: 支援多少個主機？

A: 理論上無限制，但建議：
- 單個項目 ≤ 100 個主機
- 單次批處理 ≤ 50 個項目

### Q: 如何禁用某個項目的報告？

A: 進入項目設定，取消勾選 ✓ **寄送維護報告**

---

## 📚 相關文檔

- [完整使用指南](./MAINTENANCE_REPORT_README.md)
- [API 規範](./MAINTENANCE_REPORT_README.md#api-要求)
- [故障排除](./MAINTENANCE_REPORT_README.md#故障排除)

---

## 🎯 後續優化方案

- [ ] 支援 Webhook 外部通知
- [ ] 自定義報告模板
- [ ] 數據對比分析（與歷史記錄比較）
- [ ] 告警規則設定（如內存超過 80%）
- [ ] 報告歷史存檔
- [ ] 多語言支援

---

**最後更新**：2026-03-23
**版本**：2.0