5why-analyzer/README_FULL.md

5 Why 根因分析器 (5 Why Root Cause Analyzer)

這是一個基於 5 Why 方法論的企業級根因分析工具，使用 Ollama API (qwen2.5:3b 模型) 進行智能分析。系統遵循完整的開發流程 SOP，包含使用者管理、權限控制、資料庫整合等企業級功能。

📋 目錄

• 功能特點
• 系統架構
• 快速開始
• 環境設定
• 使用說明
• API 文件
• 專案結構
• 開發流程
• 資安說明
• 常見問題

✨ 功能特點

核心分析功能

• ✅ 5 Why 深度分析: 從三個不同角度進行根本原因分析
• ✅ 多語言支援: 繁中、簡中、英文、日文、韓文、越南文、泰文
• ✅ 邏輯雙向檢核: 驗證因果關係的嚴謹性
• ✅ 永久性對策: 產出系統性解決方案，避免暫時性措施
• ✅ 執行要項指南: 內建 5 Why 方法論最佳實踐指南

管理者功能（開發中）

• 👥 使用者管理: 工號、姓名、Email、權限等級
• 🔐 三級權限控制: 一般使用者 / 管理者 / 最高權限管理者
• 🤖 LLM API 設定: 支援 Gemini / DeepSeek / OpenAI / Ollama
• 📊 系統參數設定: 彈性的系統配置介面

通用功能（開發中）

• 📥 CSV 匯入/匯出: 所有資料表支援批次處理
• 🔍 欄位排序: 清單頁面支援多欄位排序
• ⚠️ 錯誤處理: 統一的錯誤處理與通知機制
• 🔄 Loading 指示器: 改善使用者體驗

資安功能（規劃中）

• 🛡️ SQL Injection 防護: 參數化查詢
• 🔒 XSS 防護: 輸入驗證與輸出編碼
• 🔑 密碼加密: bcrypt 加密儲存
• 🚦 API Rate Limiting: 防止濫用
• 🎫 Session 安全: Secure cookie 設定

🏗️ 系統架構

後端技術棧

• 框架: Node.js + Express
• 資料庫: MySQL 8.0+ (規劃中)
• AI 引擎: Ollama API (qwen2.5:3b)
• 安全: Helmet, bcryptjs, express-session
• API: RESTful API

前端技術棧

• 框架: React 18
• 建置工具: Vite
• 樣式: Tailwind CSS
• 狀態管理: React Hooks
• 響應式設計: Mobile-first approach

資料庫架構（規劃中）

• users - 使用者資料表
• analyses - 分析記錄表
• llm_configs - LLM API 配置表
• system_settings - 系統設定表
• audit_logs - 稽核日誌表

詳細資料庫結構請參考 docs/db_schema.md（待建立）

🚀 快速開始

1. 環境需求

• Node.js 16.x 或更高版本
• MySQL 8.0 或更高版本（若需要資料庫功能）
• npm 或 yarn
• 現代瀏覽器（Chrome、Firefox、Edge）

2. 安裝步驟

# 1. 進入專案目錄
cd 5why

# 2. 安裝依賴
npm install

# 3. 設定環境變數（選擇性）
cp .env.example .env
# 編輯 .env 填入您的設定（當前版本可以不設定）

# 4. 啟動應用
npm run dev

3. 訪問應用

• 前端: http://localhost:5173
• 後端 API: http://localhost:3001

⚙️ 環境設定

.env 配置說明（選擇性）

# Ollama API 設定
OLLAMA_API_URL=https://ollama_pjapi.theaken.com
OLLAMA_MODEL=qwen2.5:3b

# 伺服器設定
SERVER_PORT=3001
CLIENT_PORT=5173

完整配置說明請參考 .env.example

📖 使用說明

基本使用流程

1. 填寫 Finding: 具體描述問題現象（使用 5W1H）

   • 誰（Who）：涉及哪些人或部門
   • 什麼（What）：發生了什麼問題
   • 何時（When）：何時發生
   • 何地（Where）：在哪裡發生
   • 為何（Why）：初步判斷
   • 如何（How）：問題如何呈現

2. 說明工作內容: 填寫您的職責範圍，幫助 AI 聚焦在可控因素

3. 選擇輸出語言: 支援 7 種語言

   • 🇹🇼 繁體中文
   • 🇨🇳 简体中文
   • 🇺🇸 English
   • 🇯🇵 日本語
   • 🇰🇷 한국어
   • 🇻🇳 Tiếng Việt
   • 🇹🇭 ภาษาไทย

4. 執行分析: 點擊「Find My 5 Why」按鈕

5. 查看結果: 系統會從三個不同角度進行分析：

   • 流程面分析
   • 系統面分析
   • 管理面分析（或其他相關角度）

6. 切換語言: 使用翻譯功能即時切換分析結果的語言

5 Why 執行要項指南

系統內建完整的 5 Why 方法論指南，包含：

1. 精準定義問題: 描述現象，而非結論
2. 聚焦流程與系統: 而非責備個人
3. 基於事實與現場: 拒絕猜測
4. 邏輯雙向檢核: 因果關係必須嚴謹
5. 止於可執行對策: 永久性對策，非暫時性

🔌 API 文件

當前可用端點

GET  /health              - 健康檢查
GET  /api/models          - 列出可用的 Ollama 模型
POST /api/analyze         - 執行 5 Why 分析
POST /api/translate       - 翻譯分析結果

API 請求範例

執行分析

const response = await fetch('http://localhost:3001/api/analyze', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: '您的完整分析提示...'
  })
});

const data = await response.json();
console.log(data.content); // AI 回應內容

翻譯結果

const response = await fetch('http://localhost:3001/api/translate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: '翻譯提示...'
  })
});

const data = await response.json();
console.log(data.content); // 翻譯後的內容

完整 API 文件請參考 docs/API_DOC.md（待建立）

📁 專案結構

5why-analyzer/
├── server.js              # Express 主程式
├── package.json           # 專案配置
├── .env.example           # 環境變數範本
├── .gitignore             # Git 忽略清單
│
├── models/                # 資料庫模型（待建立）
├── routes/                # API 路由（待建立）
├── middleware/            # 中介層（待建立）
├── templates/             # 前端模板（待建立）
├── static/                # 靜態資源
│   ├── css/
│   ├── js/
│   └── images/
│
├── src/                   # React 前端
│   ├── main.jsx           # React 入口
│   ├── App.jsx            # 主應用組件
│   ├── FiveWhyAnalyzer.jsx # 5 Why 分析器組件
│   └── index.css          # 全局樣式
│
├── docs/                  # 文件目錄
│   ├── user_command_log.md # 指令紀錄
│   ├── SDD.md            # 系統設計文件（待建立）
│   ├── db_schema.md      # 資料庫架構（待建立）
│   ├── API_DOC.md        # API 文件（待建立）
│   ├── CHANGELOG.md      # 變更紀錄（待建立）
│   └── security_audit.md # 資安稽核（待建立）
│
├── index.html             # HTML 入口
├── vite.config.js         # Vite 配置
├── tailwind.config.js     # Tailwind CSS 配置
├── postcss.config.js      # PostCSS 配置
└── README.md              # 本文件

🔄 開發流程

本專案遵循完整的開發流程 SOP：

• ✅ Phase 0: 專案初始化 (完成)

  • ✅ 建立專案資料夾結構
  • ✅ 建立 .env.example
  • ✅ 建立 .gitignore
  • ✅ 更新 package.json
  • ✅ 建立 README.md

• 🔄 Phase 1: 版本控制設定（待用戶提供 Gitea 資訊）

• 🔄 Phase 2: 資料庫架構設計（待用戶提供 MySQL 資訊）

• ⏳ Phase 3: UI/UX 預覽確認

• ⏳ Phase 4: 核心程式開發

• ⏳ Phase 5: 管理者功能開發

• ⏳ Phase 6: 通用功能實作

• ⏳ Phase 7: 資安檢視

• ⏳ Phase 8: 文件維護

• ⏳ Phase 9: 部署前檢查

進度追蹤請參考 docs/user_command_log.md

🛡️ 資安說明

本系統將實施多層次資安防護（Phase 7 實作）：

1. 輸入驗證: 所有用戶輸入進行驗證與淨化
2. SQL Injection 防護: 使用參數化查詢
3. XSS 防護: 輸出編碼與 Content Security Policy
4. CSRF 防護: CSRF Token 機制
5. 密碼安全: bcrypt 加密 + 密碼強度檢查
6. Session 安全: HttpOnly + Secure + SameSite cookies
7. Rate Limiting: API 請求頻率限制
8. Audit Logging: 所有操作記錄

資安稽核報告將在 Phase 7 產出：docs/security_audit.md

❓ 常見問題

Q: 分析時間過長怎麼辦？

A: Ollama API 回應時間約 30-60 秒，這是正常現象。請耐心等待，系統會顯示 Loading 動畫。

Q: 為什麼分析結果是英文？

A: 請確認您在「輸出語言」選項中選擇了正確的語言。預設是繁體中文。

Q: 可以離線使用嗎？

A: 目前不支援，因為需要連線至 Ollama API。未來可能會支援本地部署。

Q: 分析結果準確嗎？

A: 分析結果由 AI 生成，僅供參考。建議結合實際情況進行驗證和調整。

Q: 支援哪些瀏覽器？

A: 建議使用 Chrome、Firefox 或 Edge 的最新版本。不建議使用 IE。

Q: 如何更換 AI 模型？

A: 目前固定使用 qwen2.5:3b。管理者功能完成後，可在管理後台切換其他模型。

🚧 待開發功能

以下功能將在後續 Phase 開發：

• 使用者登入/註冊系統
• 使用者權限管理
• 分析歷史記錄
• CSV 匯入/匯出
• 多 LLM 支援（Gemini、DeepSeek、OpenAI）
• 資料庫整合
• 稽核日誌
• PDF 報告匯出
• 批次分析功能

📝 授權

MIT License

🤝 貢獻

歡迎提交 Issue 和 Pull Request！

開發指南：

1. Fork 本專案
2. 建立您的功能分支 (git checkout -b feature/AmazingFeature)
3. 提交您的修改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 開啟 Pull Request

📞 聯絡方式

如有問題或建議，請：

• 提交 Issue
• 聯繫專案維護者

---

版本: v1.0.0 最後更新: 2025-12-05 開發狀態: Phase 0 完成，Phase 1-9 進行中 授權: MIT License