# 風險報告生成功能 - 完成報告

**完成日期：** 2025-10-31  
**實作人員：** AI Assistant  
**功能編號：** 2.1.3

---

## ✅ 完成項目概覽

本次開發完成了 **風險報告生成** 功能，這是階段二「資產風險評估與分析」的第三個大任務。該功能提供了完整的風險報告解決方案，包括個別風險報告、整體風險評估報告、趨勢分析圖表以及報告匯出功能。

---

## 📋 功能清單

### 1. 後端 API 實作

#### 1.1 風險趨勢分析 API
- **路徑：** `GET /api/risks/risks/risk_trend_analysis/`
- **功能：** 提供過去12個月的風險趨勢數據
- **返回數據：**
  - 每月風險總數
  - 各等級風險數量（極高/高/中/低）
  - 平均風險值
- **用途：** 用於生成趨勢圖表

#### 1.2 個別資產風險報告 API
- **路徑：** `GET /api/risks/risks/{id}/asset_risk_report/`
- **功能：** 生成特定風險的詳細報告
- **包含內容：**
  - 風險基本資訊
  - 受影響資產列表
  - 處理行動記錄
  - 審查歷史記錄
  - 威脅來源與脆弱性資訊
- **用途：** 個別風險的完整報告

#### 1.3 整體風險評估報告 API
- **路徑：** `GET /api/risks/risks/overall_risk_report/`
- **功能：** 生成組織整體風險狀況報告
- **包含內容：**
  - 風險統計摘要
  - 按類別分析
  - 高風險項目列表（Top 10）
  - 處理行動統計
  - 風險降低效果分析
- **用途：** 管理階層審查用報告

#### 1.4 PDF 報告匯出 API
- **路徑：** `GET /api/risks/risks/{id}/export_pdf/`
- **功能：** 匯出個別風險報告為 HTML 格式
- **特點：**
  - 精美的 HTML 報告模板
  - 包含完整風險資訊
  - 支援瀏覽器列印為 PDF
  - 響應式設計
- **用途：** 報告存檔與分享

---

### 2. 前端頁面實作

#### 2.1 個別風險報告頁面 (RiskReport.tsx)

**路徑：** `/risks/{id}`

**主要功能：**
- 風險概覽卡片
  - 顯示風險等級、風險值、可能性、影響度
  - 展示殘餘風險資訊（如有）
  - 風險降低率計算與視覺化
  
- 詳細資訊標籤頁
  - **基本資訊：** 風險描述、分類、狀態、處理方式、威脅與脆弱性
  - **受影響資產：** 資產列表表格（編號、名稱、類型、狀態、擁有者、部門）
  - **處理行動：** 處理措施表格（措施、狀態、進度條、負責人、日期）
  - **審查記錄：** 時間軸展示（審查人員、發現、建議、風險變更標記）

- 操作功能
  - 返回按鈕
  - 匯出 PDF 按鈕
  - 列印按鈕
  - 列印友善 CSS（隱藏導航元素）

**UI 特點：**
- 使用 Ant Design 元件庫
- 響應式設計
- 視覺化風險等級（顏色標籤）
- 進度條顯示處理進度
- 統計卡片展示關鍵指標

#### 2.2 整體風險評估報告頁面 (RiskOverallReport.tsx)

**路徑：** `/risks/reports/overall`

**主要功能：**
- 關鍵指標卡片
  - 總風險數
  - 極高+高風險數
  - 待處理風險
  - 逾期審查數

- 風險降低效果分析
  - 平均初始風險值
  - 平均殘餘風險值
  - 風險降低率
  - 已處理風險數
  - 進度條視覺化

- 圖表視覺化
  - **風險等級分布：** 圓餅圖（極高/高/中/低）
  - **風險類別分析：** 柱狀圖（數量 + 平均風險值）
  - **風險趨勢分析：** 折線圖（過去12個月，按等級分類）

- 高風險項目列表
  - Top 10 高風險項目
  - 可排序表格
  - 包含編號、標題、等級、風險值、處理方式、負責人

- 處理行動統計
  - 已規劃/進行中/已完成數量
  - 逾期行動數

**UI 特點：**
- 使用 Recharts 圖表庫
- 多種圖表類型（折線圖、圓餅圖、柱狀圖）
- 響應式圖表布局
- 列印友善設計
- 數據視覺化與色彩編碼

---

### 3. API 介面更新

更新 `frontend/src/api/risks.ts`，新增以下函數：

```typescript
// 風險趨勢分析
export const getRiskTrendAnalysis = () => {
  return axiosInstance.get('/api/risks/risks/risk_trend_analysis/');
};

// 個別資產風險報告
export const getAssetRiskReport = (id: string) => {
  return axiosInstance.get(`/api/risks/risks/${id}/asset_risk_report/`);
};

// 整體風險評估報告
export const getOverallRiskReport = () => {
  return axiosInstance.get('/api/risks/risks/overall_risk_report/');
};

// 匯出風險 PDF 報告
export const exportRiskPDF = (id: string) => {
  return axiosInstance.get(`/api/risks/risks/${id}/export_pdf/`, {
    responseType: 'text',
  });
};
```

---

### 4. 路由配置更新

在 `App.tsx` 中新增路由：

```typescript
<Route path="risks/:id" element={<RiskReport />} />
<Route path="risks/reports/overall" element={<RiskOverallReport />} />
```

---

### 5. 使用者介面整合

在 `RiskList.tsx` 中新增「整體報告」按鈕：

```typescript
<Button
  icon={<FileTextOutlined />}
  onClick={() => navigate('/risks/reports/overall')}
>
  整體報告
</Button>
```

---

## 🎨 技術實作細節

### 資料處理與計算

1. **風險趨勢計算：**
   - 遍歷過去12個月
   - 統計每月各等級風險數量
   - 計算平均風險值
   - 返回時間序列數據

2. **風險降低率計算：**
   ```python
   reduction_rate = ((initial_score - residual_score) / initial_score) * 100
   ```

3. **殘餘風險自動判定：**
   - 根據殘餘可能性 × 殘餘影響度
   - 自動分配風險等級

### 圖表實作

使用 Recharts 庫實作多種圖表：

1. **折線圖 (LineChart)：** 風險趨勢
2. **圓餅圖 (PieChart)：** 風險等級分布
3. **柱狀圖 (BarChart)：** 類別分析（雙軸）

### 列印樣式

使用 CSS `@media print` 優化列印輸出：

```css
@media print {
  .no-print {
    display: none !important;
  }
  body {
    background: white !important;
  }
  .ant-card {
    box-shadow: none !important;
    border: 1px solid #d9d9d9;
    page-break-inside: avoid;
  }
}
```

---

## 📦 安裝的套件

```bash
npm install recharts --save
```

**Recharts 特點：**
- 基於 React 和 D3
- 聲明式 API
- 響應式圖表
- 豐富的圖表類型
- 易於自訂

---

## 🧪 測試腳本

創建 `test_risk_reports.sh` 測試腳本：

**測試項目：**
1. 檢查後端服務狀態
2. 測試風險趨勢分析 API
3. 測試整體風險評估報告 API
4. 測試個別資產風險報告 API
5. 測試 PDF 匯出 API
6. 檢查前端開發服務器

**執行方式：**
```bash
./test_risk_reports.sh
```

---

## 📊 功能展示

### 個別風險報告頁面

```
┌─────────────────────────────────────────────────┐
│ 風險評估報告                    [返回] [匯出] [列印] │
├─────────────────────────────────────────────────┤
│                                                  │
│ 風險概覽                                         │
│ ┌───────┬───────┬───────┬───────┐              │
│ │風險等級│風險值 │可能性 │影響度 │              │
│ │  高   │ 15/25 │ 3/5  │ 5/5  │              │
│ └───────┴───────┴───────┴───────┘              │
│                                                  │
│ 殘餘風險：中 (9/25) ▼降低率 40%                 │
│                                                  │
│ [基本資訊] [資產] [處理行動] [審查記錄]          │
│ ─────────────────────────────────              │
│ 風險編號：RSK-001                                │
│ 標題：Web Server 遭受 DDoS 攻擊                  │
│ 類別：技術風險                                   │
│ 狀態：已處理                                     │
│ ...                                              │
└─────────────────────────────────────────────────┘
```

### 整體風險評估報告頁面

```
┌─────────────────────────────────────────────────┐
│ 整體風險評估報告                        [返回] [列印] │
├─────────────────────────────────────────────────┤
│                                                  │
│ ┌──────┬──────┬──────┬──────┐                  │
│ │總風險 │高風險 │待處理 │逾期  │                  │
│ │ 156  │  23  │  15  │  3   │                  │
│ └──────┴──────┴──────┴──────┘                  │
│                                                  │
│ 風險降低效果分析                                  │
│ 初始風險：18.5 → 殘餘風險：11.2 (降低 39.5%)      │
│ ████████████████████░░░░░░░░░░                  │
│                                                  │
│ ┌─────────────┬─────────────┐                  │
│ │風險等級分布  │風險類別分析  │                  │
│ │  (圓餅圖)   │  (柱狀圖)   │                  │
│ └─────────────┴─────────────┘                  │
│                                                  │
│ 風險趨勢（過去12個月）                            │
│ (折線圖顯示各等級風險變化)                        │
│                                                  │
│ 高風險項目 (Top 10)                              │
│ (表格列表)                                       │
└─────────────────────────────────────────────────┘
```

---

## 🎯 達成的目標

1. ✅ **完整的報告生成功能**
   - 個別風險報告
   - 整體風險評估報告
   - 支援列印與匯出

2. ✅ **豐富的數據視覺化**
   - 多種圖表類型
   - 趨勢分析
   - 統計摘要

3. ✅ **風險分析功能**
   - 風險降低效果計算
   - 處理行動追蹤
   - 審查歷史記錄

4. ✅ **良好的使用者體驗**
   - 響應式設計
   - 列印友善
   - 直觀的操作介面

---

## 🔄 與其他模組的整合

### 與資產管理模組整合
- 報告中顯示受影響資產清單
- 包含資產的詳細資訊（擁有者、部門、CIA 等級）

### 與風險管理模組整合
- 自動獲取風險數據
- 計算統計指標
- 追蹤處理行動與審查記錄

### 與使用者管理模組整合
- 顯示負責人資訊
- 記錄審查人員
- 追蹤創建與更新人員

---

## 📈 後續可擴展功能

1. **PDF 生成優化**
   - 使用 WeasyPrint 或 ReportLab 生成真正的 PDF
   - 支援更多格式（Word、Excel）

2. **報告排程與自動化**
   - 定期自動生成報告
   - Email 自動發送
   - 報告訂閱功能

3. **自訂報告範本**
   - 使用者自訂報告欄位
   - 多種報告範本選擇
   - 公司品牌客製化

4. **更多圖表類型**
   - 熱力圖（風險矩陣）
   - 雷達圖（多維度分析）
   - 甘特圖（處理行動時程）

5. **報告比較功能**
   - 不同時期報告對比
   - 趨勢變化分析
   - 改善建議

---

## 📚 相關文件

- **規劃文件：** `spec/ISO27001-MVP10規劃.md`
- **實作計劃：** `plan.md`
- **API 文件：** 後端自動生成 (Swagger/OpenAPI)
- **測試腳本：** `test_risk_reports.sh`

---

## 🚀 使用方式

### 啟動服務

```bash
# 後端
cd backend
python manage.py runserver

# 前端
cd frontend
npm start
```

### 訪問報告

1. **個別風險報告：**
   - 訪問風險列表：http://localhost:3000/risks
   - 點擊「查看」圖示進入報告頁面
   - 或直接訪問：http://localhost:3000/risks/{risk_id}

2. **整體風險報告：**
   - 在風險列表頁點擊「整體報告」按鈕
   - 或直接訪問：http://localhost:3000/risks/reports/overall

3. **匯出報告：**
   - 在個別報告頁面點擊「匯出 PDF」按鈕
   - 或點擊「列印」按鈕使用瀏覽器列印功能

---

## ✅ 驗收標準

1. ✅ 可以生成個別風險的詳細報告
2. ✅ 可以生成整體風險評估報告
3. ✅ 包含過去12個月的趨勢分析
4. ✅ 圖表正確顯示風險分布
5. ✅ 支援報告匯出與列印
6. ✅ 計算風險降低率
7. ✅ 顯示處理行動進度
8. ✅ 展示審查歷史記錄
9. ✅ 響應式設計適配各種螢幕
10. ✅ 列印輸出格式良好

---

## 🎉 完成總結

本次開發成功實作了完整的風險報告生成功能，提供了從個別風險到整體評估的全面報告解決方案。透過數據視覺化和友善的使用者介面，讓管理階層能夠快速掌握組織的風險狀況，並追蹤風險處理進度。

**主要成就：**
- 4 個新的後端 API 端點
- 2 個新的前端報告頁面
- 整合 Recharts 圖表庫
- 完整的報告匯出功能
- 測試腳本驗證

**下一步建議：**
根據 `plan.md`，下一個待實作的功能是：
- **2.1.4 風險監控儀表板** - 實時風險監控與警示功能

---

**報告生成時間：** 2025-10-31  
**文件版本：** 1.0