# 主機維護報告功能使用指南

## 功能概述

本功能提供完整的主機維護報告生成和發送系統，包括：

1. ✅ 自動從主機 API 取得系統資訊
2. ✅ 數據驗證和結構化處理
3. ✅ 定期主機維護報告生成和郵件發送
4. ✅ 多種報告導出格式（Word、Excel）
5. ✅ 報告完成度追蹤

---

## 核心改進

### 1. 增強的 API 連線服務 (\`SystemReportService\`)

**位置**: [app/Services/SystemReportService.php](app/Services/SystemReportService.php)

**改進內容**:
- ✨ 重試機制（最多 3 次重試，延遲 1 秒）
- ✨ 認證支援（Basic Auth + Token）
- ✨ 完整的數據驗證和結構化
- ✨ 報告完成度計算
- ✨ 詳細的日誌記錄

**使用方式**:
```php
$service = new SystemReportService();
$reportData = $service->fetch($host->api_url, [
    'username' => $host->username,
    'password' => $host->password,
]);

// 計算報告完成度
$completionRate = $service->getCompletionPercentage($reportData);
```

### 2. 定期報告生成任務 (\`GenerateMaintenanceReportJob\`)

**位置**: [app/Jobs/GenerateMaintenanceReportJob.php](app/Jobs/GenerateMaintenanceReportJob.php)

**功能**:
- 自動取得項目下所有主機的系統報告
- 計算每個主機的報告完成度
- 生成格式化的郵件報告
- 發送給指定的收件人

**使用方式**:
```php
// 手動分派任務
GenerateMaintenanceReportJob::dispatch($project);

// 或使用命令行
php artisan maintenance:generate --project-id=1
php artisan maintenance:generate --force  // 忽略週期限制
```

### 3. 報告調度器服務 (\`MaintenanceReportScheduleService\`)

**位置**: [app/Services/MaintenanceReportScheduleService.php](app/Services/MaintenanceReportScheduleService.php)

**功能**:
- 根據報告週期判斷是否應該生成報告
- 支援月度 (monthly)、季度 (quarterly)、半年度 (semiannually) 週期
- 追蹤上次報告生成時間
- 批量查詢需要生成報告的項目

**使用方式**:
```php
// 判斷項目是否應該生成報告
if (MaintenanceReportScheduleService::shouldGenerateReport($project)) {
    GenerateMaintenanceReportJob::dispatch($project);
}

// 取得所有需要生成報告的項目
$projects = MaintenanceReportScheduleService::getProjectsForReportGeneration();

// 標記報告已生成
MaintenanceReportScheduleService::markReportGenerated($project);
```

---

## 使用方式

### 方式 1：Web 介面

#### 查看主機報告

1. 進入 **主機管理** > **主機列表**
2. 點擊要查看的主機
3. 查看報告完成度進度條和所有系統資訊

#### 導出報告

1. 在主機報告頁面
2. 選擇匯出格式：
   - **📄 匯出 Word**: 生成完整的 Word 文檔（包含 SSL 分析）
   - **📊 匯出 Excel**: 生成 Excel 電子表格

### 方式 2：命令行

#### 生成單個項目的報告

```bash
# 根據週期判斷是否生成
php artisan maintenance:generate --project-id=1

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

#### 生成所有需要的報告

```bash
# 檢查並生成所有需要發送報告的項目
php artisan maintenance:generate

# 強制生成所有項目的報告
php artisan maintenance:generate --force
```

#### 查看幫助

```bash
php artisan maintenance:generate --help
```

### 方式 3：自動調度

定時任務會在每天凌晨 1 點自動檢查並生成需要發送的報告。

設定位置: [app/Console/Kernel.php](app/Console/Kernel.php)

```php
$schedule->command('maintenance:generate')
    ->dailyAt('01:00')
    ->name('maintenance-daily-report')
    ->withoutOverlapping();
```

---

## 項目配置

### 啟用主機維護報告

在 **項目設定** 頁面配置：

| 欄位 | 說明 | 範例 |
|------|------|------|
| 寄送維護報告 | 是否啟用此功能 | ✓ 啟用 |
| 報告週期 | 生成報告的間隔 | 每月 (monthly) |
| 通知人信箱 | 報告接收者（支援多個，逗號分隔） | user@domain.com, admin@domain.com |

### 主機配置

在 **主機設定** 頁面配置：

| 欄位 | 說明 | 備註 |
|------|------|------|
| API URL | 主機系統報告 API 端點 | 如 http://host:8080/api/system |
| 使用者名稱 | API 認證用戶名 | 可選，若 API 需認證 |
| 密碼 | API 認證密碼 | 可選，若 API 需認證 |
| 連接埠 | 主機服務連接埠 | 可選 |

---

## 報告數據欄位

報告包含以下主要類別：

### 基本系統資訊
- 作業系統、核心版本、時區、IP 位址、主機名稱

### 硬體資訊
- CPU 型號和核心數
- 記憶體使用情況
- 硬碟使用情況

### 軟體版本
- Apache, PHP, MySQL, OpenSSL, OpenSSH

### 系統配置
- NTP 時間同步狀態和伺服器
- 特權帳號清單
- 帳號到期相關設定

### 安全設定
- 防毒軟體狀態
- 防火牆設定
- SELinux 狀態
- 日誌旋轉設定
- 螢幕保護設定

---

## 郵件報告格式

收到的郵件包含：

1. **統計摘要**
   - 總主機數
   - 成功取得報告的主機數量
   - 失敗數量

2. **主機詳細報告**
   - 每個主機的系統資訊摘要
   - 報告完成度百分比
   - 關鍵項目（OS、CPU、記憶體、軟體版本等）

3. **快速連結**
   - 查看完整報告的連結

---

## 故障排除

### 報告資訊為空

**可能原因**:
1. API 端點無法響應
2. API 返回無效的 JSON
3. API 認證信息不正確

**解決方案**:
- 檢查主機 API URL 是否正確
- 確認 API 認證信息（用戶名和密碼）
- 查看應用日誌：`storage/logs/laravel.log`

### 郵件未收到

**可能原因**:
1. 郵件隊列未運行
2. 收件人信箱設定錯誤
3. 郵件服務配置有誤

**解決方案**:
1. 確保隊列工作進程運行：`php artisan queue:work`
2. 檢查項目配置中的收件人信箱
3. 驗證郵件服務配置（`.env` 文件）

### 命令執行失敗

**檢查日誌**:
```bash
tail -f storage/logs/laravel.log
```

**測試 API 連線**:
```bash
# 使用 curl 測試
curl -u "username:password" http://host:api_url
```

---

## 數據流程圖

```
主機維護報告流程
├─ 項目配置
│  ├─ 啟用報告發送
│  ├─ 設定報告週期（月/季/半年）
│  └─ 設定收件人郵箱
├─ 定時觸發（每日凌晨 1 點）或手動觸發
│  └─ maintenance:generate 命令
├─ 報告生成流程
│  ├─ 查詢所需生成報告的項目
│  ├─ 遍歷項目下的所有主機
│  ├─ 調用 API 取得系統資訊
│  ├─ 驗證和結構化數據
│  └─ 分派到後台隊列任務
├─ 後台任務處理
│  ├─ 生成郵件內容
│  ├─ 發送郵件給收件人
│  └─ 記錄操作日誌
└─ Web 介面展示
   ├─ 顯示報告完成度
   ├─ 支援導出 Word 格式
   └─ 支援導出 Excel 格式
```

---

## API 要求

主機 API 應返回以下 JSON 格式的數據（至少包含必須字段）：

```json
{
  "hostname": "server-01",
  "os_release": {
    "PRETTY_NAME": "Ubuntu 22.04.1 LTS"
  },
  "kernel_version": "5.15.0-56-generic",
  "ip": "192.168.1.10",
  "cpu_model": "Intel(R) Xeon(R) CPU E5-2680 v3 @ 2.50GHz",
  "cpu_count": 8,
  "memory": {
    "total_gb": 32,
    "used_gb": 16,
    "free_gb": 16,
    "percent": 50
  },
  "disk_info": [
    {
      "mounted_on": "/",
      "filesystem": "ext4",
      "size": "100G",
      "used": "50G",
      "avail": "50G",
      "percent": "50%"
    }
  ],
  "apache_version": "Apache/2.4.41",
  "php_version": "7.4.26",
  "mysql_version": "MySQL 8.0.28",
  "openssl_version": "OpenSSL 1.1.1f",
  "openssh_version": "OpenSSH_8.2",
  "ntp_status": "synchronized",
  "ntp_servers": ["time1.google.com", "time2.google.com"],
  "privileged_accounts": ["root"],
  "antivirus_installed": true,
  "antivirus_version": "2.5.1",
  "firewall_status": "active",
  "selinux_status": "enforcing",
  "log_rotate_180days": true,
  "apache_logrotate_180days": true,
  "screensaver_configured": true,
  "screensaver_timeout": 300
}
```

---

## 相關文件

- [HostController](app/Http/Controllers/HostController.php) - 主機控制器
- [Host Model](app/Models/Host.php) - 主機模型
- [Project Model](app/Models/Project.php) - 項目模型
- [GenerateMaintenanceReportJob](app/Jobs/GenerateMaintenanceReportJob.php) - 報告生成任務
- [MaintenanceReportScheduleService](app/Services/MaintenanceReportScheduleService.php) - 調度器服務
- [SystemReportService](app/Services/SystemReportService.php) - API 連線服務
- [主機報告視圖](resources/views/hosts/show.blade.php) - 前端展示
- [郵件模板](resources/views/mails/maintenance-report.blade.php) - 郵件格式

---

## 更新日誌

### 版本 2.0（2026-03-23）

✨ **新功能**:
- 增強的 API 連線邏輯（重試、認證、數據驗證）
- 完整的定期報告生成系統
- 自動郵件發送功能
- Excel 報告導出
- 報告完成度追蹤和顯示
- 命令行工具支援

🔧 **改進**:
- 改進的錯誤處理和日誌記錄
- 更完善的數據結構化
- 更好的用戶界面反饋
- 支援多收件人

---

## 技術詳情

### 隊列設定

確保以下隊列工作進程運行以處理報告生成：

```bash
# 開發環境
php artisan queue:work

# 生產環境（建議使用 Supervisor）
supervisorctl start laravel-worker
```

### 時區設定

確保應用的時區設定正確：

```env
# .env
APP_TIMEZONE=Asia/Taipei
```

### 郵件設定

配置郵件服務（`.env`）：

```env
MAIL_DRIVER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_ENCRYPTION=tls
MAIL_FROM_NAME="VPN 工作平台"
```

---

## 許可證

本功能作為 VPN 工作平台的一部分發佈。