# 5 Why 根因分析系統 - 使用說明書

**版本**: 1.3.0
**更新日期**: 2025-12-08

---

## 目錄

1. [系統概述](#1-系統概述)
2. [系統架構](#2-系統架構)
3. [使用流程](#3-使用流程)
4. [功能說明](#4-功能說明)
5. [優化設計](#5-優化設計)
6. [常見問題](#6-常見問題)

---

## 1. 系統概述

### 1.1 什麼是 5 Why 分析法？

5 Why 分析法是一種根因分析技術，透過連續追問「為什麼」來深入探究問題的根本原因，而非停留在表面症狀。

### 1.2 系統目標

本系統整合 AI 大型語言模型（LLM），協助使用者：

- **快速進行根因分析**：AI 從多個角度自動生成 5 Why 分析
- **確保分析品質**：遵循五大執行要項，避免常見錯誤
- **提供永久對策**：聚焦系統性解決方案，而非暫時性補救

### 1.3 系統特色

| 特色 | 說明 |
|------|------|
| 多角度分析 | 自動從 3 個不同角度（流程面、系統面、管理面等）進行分析 |
| 邏輯檢核 | 每個分析自動進行順向/逆向邏輯驗證 |
| 多語言支援 | 支援繁中、簡中、英、日、韓、越、泰 7 種語言 |
| 歷史記錄 | 自動保存所有分析記錄，可隨時查詢 |

---

## 2. 系統架構

### 2.1 技術架構

```
┌─────────────────────────────────────────────────────────┐
│                      使用者介面                          │
│                   (React + Tailwind CSS)                 │
├─────────────────────────────────────────────────────────┤
│                      後端服務                            │
│                   (Node.js + Express)                    │
├──────────────────┬──────────────────┬───────────────────┤
│   MySQL 資料庫    │   Session 管理   │    LLM API        │
│  (分析記錄儲存)   │   (使用者認證)   │  (DeepSeek/Ollama)│
└──────────────────┴──────────────────┴───────────────────┘
```

### 2.2 模組說明

| 模組 | 功能 |
|------|------|
| 認證模組 | 使用者登入、登出、密碼管理 |
| 分析模組 | 5 Why 分析、翻譯、歷史查詢 |
| 管理模組 | 使用者管理、LLM 配置、稽核日誌 |

---

## 3. 使用流程

### 3.1 整體流程圖

```
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│   登入   │ -> │ 輸入問題 │ -> │ AI 分析  │ -> │ 查看結果 │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
                     │                              │
                     v                              v
              ┌──────────────┐              ┌──────────────┐
              │ 選擇輸出語言  │              │ 翻譯/匯出   │
              └──────────────┘              └──────────────┘
```

### 3.2 詳細操作步驟

#### 步驟 1：登入系統

1. 開啟系統網址 `http://localhost:5176`
2. 輸入帳號（Email 或工號）與密碼
3. 點擊「登入」按鈕

**測試帳號**：

| 角色 | Email | 密碼 |
|------|-------|------|
| 超級管理員 | admin@example.com | Admin@123456 |
| 管理員 | manager@example.com | Manager@123456 |
| 一般使用者 | user@example.com | User@123456 |

#### 步驟 2：輸入分析內容

在「5 Why 根因分析」頁面：

1. **發現的現象**（必填）
   - 描述您觀察到的問題或異常
   - 範例：「伺服器每週二凌晨 3 點當機」

2. **工作內容/背景**（必填）
   - 提供相關的背景資訊
   - 包含：系統環境、作業流程、相關人員等

3. **輸出語言**
   - 選擇分析結果的語言

#### 步驟 3：執行分析

1. 點擊「開始分析」按鈕
2. 等待 AI 處理（約 30-60 秒）
3. 系統會顯示分析進度

#### 步驟 4：查看結果

分析完成後，會顯示：

```
┌─────────────────────────────────────────────────────┐
│ 問題重述 (5W1H)                                      │
│ ─────────────────────────────────────────────────── │
│ [AI 用 5W1H 格式重新描述問題]                        │
├─────────────────────────────────────────────────────┤
│ 🔄 流程面分析                                        │
│ ─────────────────────────────────────────────────── │
│ Why 1: [問題] → [答案] ✓已確認                       │
│ Why 2: [問題] → [答案] ⚠待驗證                       │
│ Why 3: [問題] → [答案] ✓已確認                       │
│                                                     │
│ 🎯 根本原因：[分析結果]                              │
│                                                     │
│ 🔄 邏輯檢核：                                        │
│    ➡️ 順向：如果[原因]發生，則[結果]必然發生         │
│    ⬅️ 逆向：如果消除[原因]，則[結果]不會發生         │
│                                                     │
│ 💡 永久對策：[系統性解決方案]                        │
│    行動項目：                                        │
│    • [具體行動 1]                                    │
│    • [具體行動 2]                                    │
└─────────────────────────────────────────────────────┘
```

---

## 4. 功能說明

### 4.1 分析功能

#### 4.1.1 多角度分析

系統自動從 3 個不同角度進行分析：

- **流程面**：作業流程、標準程序
- **系統面**：技術系統、設備機制
- **管理面**：管理制度、監督機制

#### 4.1.2 5 Why 深度追問

每個角度會進行 3-5 次「為什麼」追問：

```
Why 1: 為什麼發生 A？ → 因為 B
Why 2: 為什麼發生 B？ → 因為 C
Why 3: 為什麼發生 C？ → 因為 D（根本原因）
```

#### 4.1.3 邏輯雙向檢核

每個分析包含邏輯驗證：

- **順向檢核**：如果原因發生，結果是否必然發生？
- **逆向檢核**：如果消除原因，結果是否就不會發生？

### 4.2 管理功能（僅管理員）

#### 4.2.1 儀表板

- 分析統計（總數、成功率、平均處理時間）
- 使用者活動統計
- 系統健康狀態

#### 4.2.2 使用者管理

- 新增/編輯/停用使用者
- 角色權限設定
- 密碼重設

#### 4.2.3 LLM 配置

- 新增/編輯 LLM 端點
- 模型選擇與參數調整
- 連線測試

#### 4.2.4 LLM 測試台

- 動態載入可用模型
- 快速連線測試
- 互動式對話測試

---

## 5. 優化設計

### 5.1 分析品質優化

#### 5.1.1 五大執行要項

系統 Prompt 內建五大執行要項，確保分析品質：

| 要項 | 說明 |
|------|------|
| 精準定義問題 | 使用 5W1H 描述現象，而非結論 |
| 聚焦流程與系統 | 追問「系統為何允許疏失發生」 |
| 基於事實 | 每個 Why 標註「已確認」或「待驗證」 |
| 邏輯檢核 | 順向+逆向雙向驗證 |
| 可執行對策 | 永久性系統解決方案 |

#### 5.1.2 Prompt 精簡化

```
優化前：80+ 行複雜 Prompt
優化後：15 行精簡 Prompt

效果：
- 減少 LLM 混淆
- 提高 JSON 格式正確率
- 降低回應被截斷風險
```

### 5.2 技術優化

#### 5.2.1 JSON 解析強化

多層修復策略處理 LLM 輸出格式問題：

```javascript
1. 清理特殊標記（```json、<think>等）
2. 提取 { 到 } 之間的純 JSON
3. 修復常見格式問題（尾部逗號、缺少逗號）
4. 補齊未閉合的括號
```

#### 5.2.2 API 參數優化

```javascript
// 問題：DeepSeek 限制 max_tokens 最大 8192
// 解決：動態限制在 4000-8000 之間
const effectiveMaxTokens = Math.min(
  Math.max(parseInt(llmConfig.max_tokens) || 4000, 4000),
  8000
);

// 問題：temperature 為字串導致 API 錯誤
// 解決：確保轉換為數字
const effectiveTemperature = parseFloat(llmConfig.temperature) || 0.7;
```

### 5.3 使用者體驗優化

#### 5.3.1 結果視覺化

- 分析角度以卡片式呈現
- Why 層級以縮排+左邊界線區分
- 已確認/待驗證以顏色標記
- 根本原因、邏輯檢核、永久對策區塊化

#### 5.3.2 載入狀態

- 分析中顯示動畫與預估時間
- 錯誤發生時顯示詳細訊息

---

## 6. 常見問題

### Q1: 分析時間很長怎麼辦？

**原因**：LLM API 回應時間取決於模型負載與輸入長度

**建議**：
- 簡化輸入內容，聚焦關鍵資訊
- 避免在尖峰時段使用

### Q2: 出現「JSON 解析失敗」錯誤？

**原因**：LLM 輸出格式不正確

**解決**：
- 點擊「重試」重新分析
- 簡化輸入內容
- 聯繫管理員檢查 LLM 配置

### Q3: 分析結果不符合預期？

**建議**：
- 提供更詳細的背景資訊
- 明確描述問題現象（5W1H）
- 避免主觀結論，描述客觀事實

### Q4: 如何切換 LLM 模型？

**步驟**（需管理員權限）：
1. 進入「管理員」頁面
2. 選擇「LLM 配置」Tab
3. 新增或編輯配置
4. 點擊「啟用」設為預設

---

## 附錄

### A. 系統需求

| 項目 | 最低需求 |
|------|----------|
| 瀏覽器 | Chrome 90+、Firefox 88+、Edge 90+ |
| 網路 | 穩定的網際網路連線 |

### B. 快速鍵

| 快速鍵 | 功能 |
|--------|------|
| `Enter` | 在登入頁面提交表單 |
| `Ctrl+Enter` | 在分析頁面開始分析 |

### C. 聯絡支援

如有問題，請聯繫系統管理員或參考：
- GitHub Issues: https://github.com/anthropics/claude-code/issues

---

**文件版本**: 1.0.0
**編寫日期**: 2025-12-08
**編寫者**: Development Team