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

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/yourusername/5why-analyzer)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

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

## 📋 目錄

- [功能特點](#功能特點)
- [系統架構](#系統架構)
- [快速開始](#快速開始)
- [環境設定](#環境設定)
- [使用說明](#使用說明)
- [API 文件](#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](docs/db_schema.md)（待建立）

## 🚀 快速開始

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

### 2. 安裝步驟

```bash
# 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 配置說明（選擇性）

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

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

完整配置說明請參考 [.env.example](.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 請求範例

#### 執行分析

```javascript
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 回應內容
```

#### 翻譯結果

```javascript
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](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](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](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