feat: Implement role-based access control (RBAC) with 3-tier authorization
- Add 3 user roles: user, admin, super_admin - Restrict LLM config management to super_admin only - Restrict audit logs and statistics to super_admin only - Update AdminPage with role-based tab visibility - Add complete 5 Why prompt from 5why-analyzer.jsx - Add system documentation and authorization guide - Add ErrorModal component and seed test users script 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
donald
344
系統使用說明書.md
Normal file
344
系統使用說明書.md
Normal file
@@ -0,0 +1,344 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user