78efac64e2
Phase 0 & Phase 2 completed: - Project structure setup - Environment configuration (.env, .gitignore) - Enterprise-grade dependencies (bcrypt, helmet, mysql2, etc.) - Complete database schema with 8 tables + 2 views - Database initialization scripts - Comprehensive documentation Database Tables: - users (user management with 3-tier permissions) - analyses (analysis records) - analysis_perspectives (multi-angle analysis) - analysis_whys (detailed 5 Why records) - llm_configs (LLM API configurations) - system_settings (system parameters) - audit_logs (security audit trail) - sessions (session management) Tech Stack: - Backend: Node.js + Express - Frontend: React 18 + Vite + Tailwind CSS - Database: MySQL 9.4.0 - AI: Ollama API (qwen2.5:3b) Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
344 lines
10 KiB
Markdown
344 lines
10 KiB
Markdown
# 5 Why 根因分析器 (5 Why Root Cause Analyzer)
|
||
|
||
[](https://github.com/yourusername/5why-analyzer)
|
||
[](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
|