docs: Add comprehensive usage guide with troubleshooting
Added USAGE_GUIDE.md with: - Three ways to run the application - Step-by-step setup instructions - Detailed feature documentation - User roles and permissions guide - Comprehensive troubleshooting section - Security best practices - System monitoring commands - Performance optimization tips Covers: ✅ 5 Why Analysis Tool usage ✅ Analysis History management ✅ Admin Dashboard features ✅ User, Admin, and Super Admin roles ✅ Common issues and solutions ✅ Database troubleshooting ✅ Network and connectivity issues ✅ Production deployment tips 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
donald
422
USAGE_GUIDE.md
Normal file
422
USAGE_GUIDE.md
Normal file
@@ -0,0 +1,422 @@
|
|||||||
|
# 5 Why Root Cause Analyzer - Usage Guide
|
||||||
|
|
||||||
|
## 📖 Table of Contents
|
||||||
|
1. [Quick Start](#quick-start)
|
||||||
|
2. [Three Ways to Run](#three-ways-to-run)
|
||||||
|
3. [Step-by-Step Guide](#step-by-step-guide)
|
||||||
|
4. [Application Features](#application-features)
|
||||||
|
5. [User Roles](#user-roles)
|
||||||
|
6. [Troubleshooting](#troubleshooting)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Quick Start
|
||||||
|
|
||||||
|
### Easiest Way (Recommended):
|
||||||
|
```bash
|
||||||
|
python app.py
|
||||||
|
```
|
||||||
|
|
||||||
|
That's it! The application will:
|
||||||
|
- Check all prerequisites
|
||||||
|
- Start backend and frontend
|
||||||
|
- Display access URLs
|
||||||
|
- Show test account credentials
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Three Ways to Run
|
||||||
|
|
||||||
|
### 1️⃣ **Python Launcher (Recommended)**
|
||||||
|
```bash
|
||||||
|
python app.py
|
||||||
|
```
|
||||||
|
✅ Checks prerequisites
|
||||||
|
✅ Starts both services
|
||||||
|
✅ Single terminal window
|
||||||
|
✅ Colored output
|
||||||
|
✅ Graceful shutdown
|
||||||
|
|
||||||
|
### 2️⃣ **NPM Command**
|
||||||
|
```bash
|
||||||
|
npm start
|
||||||
|
```
|
||||||
|
Same as Python launcher (calls `python app.py`)
|
||||||
|
|
||||||
|
### 3️⃣ **Windows Batch File**
|
||||||
|
```bash
|
||||||
|
start.bat
|
||||||
|
```
|
||||||
|
Double-click `start.bat` in Windows Explorer
|
||||||
|
|
||||||
|
### 4️⃣ **Manual Start (Advanced)**
|
||||||
|
```bash
|
||||||
|
# Terminal 1
|
||||||
|
npm run server
|
||||||
|
|
||||||
|
# Terminal 2 (separate window)
|
||||||
|
npm run client
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 Step-by-Step Guide
|
||||||
|
|
||||||
|
### Step 1: First-Time Setup
|
||||||
|
|
||||||
|
#### 1.1 Install Dependencies
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 1.2 Configure Environment
|
||||||
|
```bash
|
||||||
|
# Copy example file
|
||||||
|
cp .env.example .env
|
||||||
|
|
||||||
|
# Edit .env file with your settings
|
||||||
|
# Windows: notepad .env
|
||||||
|
# Linux: nano .env
|
||||||
|
```
|
||||||
|
|
||||||
|
**Required .env settings:**
|
||||||
|
```env
|
||||||
|
# Database
|
||||||
|
DB_HOST=mysql.theaken.com
|
||||||
|
DB_PORT=33306
|
||||||
|
DB_NAME=db_A102
|
||||||
|
DB_USER=A102
|
||||||
|
DB_PASSWORD=Bb123456
|
||||||
|
|
||||||
|
# Session
|
||||||
|
SESSION_SECRET=your-super-secret-key-change-this-in-production
|
||||||
|
|
||||||
|
# Server
|
||||||
|
PORT=3001
|
||||||
|
NODE_ENV=development
|
||||||
|
|
||||||
|
# CORS
|
||||||
|
CORS_ORIGIN=http://localhost:5173
|
||||||
|
|
||||||
|
# Ollama API
|
||||||
|
OLLAMA_API_URL=https://ollama_pjapi.theaken.com
|
||||||
|
OLLAMA_MODEL=qwen2.5:3b
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 1.3 Initialize Database (if needed)
|
||||||
|
```bash
|
||||||
|
npm run db:init
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 1.4 Test Connection
|
||||||
|
```bash
|
||||||
|
npm run db:test
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: Start Application
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python app.py
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Access Application
|
||||||
|
|
||||||
|
Open your browser and go to:
|
||||||
|
```
|
||||||
|
http://localhost:5173
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: Login
|
||||||
|
|
||||||
|
Use one of the test accounts:
|
||||||
|
|
||||||
|
| Role | Email | Password |
|
||||||
|
|------|-------|----------|
|
||||||
|
| **Admin** | admin@example.com | Admin@123456 |
|
||||||
|
| User | user001@example.com | User@123456 |
|
||||||
|
| User | user002@example.com | User@123456 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎨 Application Features
|
||||||
|
|
||||||
|
### 1. **5 Why Analysis Tool**
|
||||||
|
Create a root cause analysis:
|
||||||
|
|
||||||
|
1. Navigate to **"分析工具"** (Analysis Tool) tab
|
||||||
|
2. Enter your **發現** (Finding/Problem)
|
||||||
|
3. Enter **工作內容** (Job/Context)
|
||||||
|
4. Select **語言** (Language) - 7 options available
|
||||||
|
5. Click **執行分析** (Execute Analysis)
|
||||||
|
|
||||||
|
**AI will analyze from 3 perspectives:**
|
||||||
|
- 🔧 **技術角度** (Technical Perspective)
|
||||||
|
- 📋 **流程角度** (Process Perspective)
|
||||||
|
- 👥 **人員角度** (Human Perspective)
|
||||||
|
|
||||||
|
Each perspective includes:
|
||||||
|
- 5 Why questions and answers
|
||||||
|
- Root cause identification
|
||||||
|
- Recommended solutions
|
||||||
|
|
||||||
|
### 2. **Analysis History**
|
||||||
|
View and manage past analyses:
|
||||||
|
|
||||||
|
1. Navigate to **"分析歷史"** (Analysis History) tab
|
||||||
|
2. See all your past analyses
|
||||||
|
3. Click **查看詳情** (View Details) to see full analysis
|
||||||
|
4. Click **刪除** (Delete) to remove analysis
|
||||||
|
5. Use pagination to browse
|
||||||
|
|
||||||
|
### 3. **Admin Dashboard** (Admin/Super Admin only)
|
||||||
|
Manage the entire system:
|
||||||
|
|
||||||
|
#### Tab 1: **總覽** (Overview)
|
||||||
|
- Total users count
|
||||||
|
- Total analyses count
|
||||||
|
- Monthly analyses
|
||||||
|
- Active users statistics
|
||||||
|
|
||||||
|
#### Tab 2: **使用者管理** (User Management)
|
||||||
|
- View all users
|
||||||
|
- Create new users
|
||||||
|
- Delete users
|
||||||
|
- Manage roles (user, admin, super_admin)
|
||||||
|
|
||||||
|
#### Tab 3: **分析記錄** (Analysis Records)
|
||||||
|
- View all system analyses (all users)
|
||||||
|
- Filter and search analyses
|
||||||
|
- System-wide statistics
|
||||||
|
|
||||||
|
#### Tab 4: **稽核日誌** (Audit Logs)
|
||||||
|
- Security audit trail
|
||||||
|
- User actions logged
|
||||||
|
- IP addresses tracked
|
||||||
|
- Login/logout events
|
||||||
|
- CRUD operations
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 👥 User Roles
|
||||||
|
|
||||||
|
### 🔵 **User** (一般使用者)
|
||||||
|
**Can:**
|
||||||
|
- ✅ Create 5 Why analyses
|
||||||
|
- ✅ View own analysis history
|
||||||
|
- ✅ Delete own analyses
|
||||||
|
- ✅ Change own password
|
||||||
|
|
||||||
|
**Cannot:**
|
||||||
|
- ❌ Access admin dashboard
|
||||||
|
- ❌ View other users' data
|
||||||
|
- ❌ Create/delete users
|
||||||
|
- ❌ View audit logs
|
||||||
|
|
||||||
|
### 🟢 **Admin** (管理員)
|
||||||
|
**All User permissions, plus:**
|
||||||
|
- ✅ Access admin dashboard
|
||||||
|
- ✅ View all users
|
||||||
|
- ✅ Create new users (user, admin roles)
|
||||||
|
- ✅ Delete users
|
||||||
|
- ✅ View all analyses (system-wide)
|
||||||
|
- ✅ View audit logs
|
||||||
|
|
||||||
|
**Cannot:**
|
||||||
|
- ❌ Create super_admin users
|
||||||
|
- ❌ Delete super_admin users
|
||||||
|
|
||||||
|
### 🔴 **Super Admin** (超級管理員)
|
||||||
|
**Full system access:**
|
||||||
|
- ✅ All Admin permissions
|
||||||
|
- ✅ Create super_admin users
|
||||||
|
- ✅ Delete any user (including admins)
|
||||||
|
- ✅ Full system control
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🛠️ Troubleshooting
|
||||||
|
|
||||||
|
### Issue: "Python is not installed"
|
||||||
|
**Solution:**
|
||||||
|
1. Download Python 3.7+ from https://www.python.org/
|
||||||
|
2. During installation, check **"Add Python to PATH"**
|
||||||
|
3. Restart terminal
|
||||||
|
4. Verify: `python --version`
|
||||||
|
|
||||||
|
### Issue: "Node.js is not installed"
|
||||||
|
**Solution:**
|
||||||
|
1. Download Node.js 18+ from https://nodejs.org/
|
||||||
|
2. Install LTS version
|
||||||
|
3. Restart terminal
|
||||||
|
4. Verify: `node --version`
|
||||||
|
|
||||||
|
### Issue: "Dependencies not installed"
|
||||||
|
**Solution:**
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
### Issue: ".env file not found"
|
||||||
|
**Solution:**
|
||||||
|
```bash
|
||||||
|
cp .env.example .env
|
||||||
|
# Then edit .env with your settings
|
||||||
|
```
|
||||||
|
|
||||||
|
### Issue: "Database connection failed"
|
||||||
|
**Solution:**
|
||||||
|
1. Check `.env` database credentials
|
||||||
|
2. Verify MySQL is running
|
||||||
|
3. Test connection: `npm run db:test`
|
||||||
|
4. Check firewall allows port 33306
|
||||||
|
5. Verify network connectivity to mysql.theaken.com
|
||||||
|
|
||||||
|
### Issue: "Port 3001 already in use"
|
||||||
|
**Solution:**
|
||||||
|
```bash
|
||||||
|
# Windows
|
||||||
|
netstat -ano | findstr :3001
|
||||||
|
taskkill /F /PID <pid>
|
||||||
|
|
||||||
|
# Linux
|
||||||
|
lsof -ti:3001 | xargs kill -9
|
||||||
|
|
||||||
|
# Or change PORT in .env
|
||||||
|
```
|
||||||
|
|
||||||
|
### Issue: "Port 5173 already in use"
|
||||||
|
**Solution:**
|
||||||
|
- Vite will automatically use next available port (5174, 5175, etc.)
|
||||||
|
- Or kill the process using the port
|
||||||
|
|
||||||
|
### Issue: "Cannot login"
|
||||||
|
**Solution:**
|
||||||
|
1. Check database is initialized: `npm run db:init`
|
||||||
|
2. Verify backend is running (http://localhost:3001/health)
|
||||||
|
3. Check browser console for errors
|
||||||
|
4. Clear browser cookies/cache
|
||||||
|
5. Try different test account
|
||||||
|
|
||||||
|
### Issue: "Ollama API not responding"
|
||||||
|
**Solution:**
|
||||||
|
1. Check `.env` OLLAMA_API_URL is correct
|
||||||
|
2. Test URL: `curl https://ollama_pjapi.theaken.com`
|
||||||
|
3. Check network connectivity
|
||||||
|
4. Verify firewall allows outbound HTTPS
|
||||||
|
|
||||||
|
### Issue: "Frontend white screen"
|
||||||
|
**Solution:**
|
||||||
|
1. Check browser console for errors
|
||||||
|
2. Verify backend is running
|
||||||
|
3. Clear browser cache
|
||||||
|
4. Try different browser
|
||||||
|
5. Check CORS settings in backend
|
||||||
|
|
||||||
|
### Issue: "Sessions not persisting"
|
||||||
|
**Solution:**
|
||||||
|
1. Check `SESSION_SECRET` in .env
|
||||||
|
2. Clear browser cookies
|
||||||
|
3. Check if cookies are enabled in browser
|
||||||
|
4. Verify backend session middleware is working
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔒 Security Best Practices
|
||||||
|
|
||||||
|
### For Production:
|
||||||
|
1. ✅ Change default admin password immediately
|
||||||
|
2. ✅ Use strong `SESSION_SECRET` (32+ random characters)
|
||||||
|
3. ✅ Enable HTTPS (SSL certificate)
|
||||||
|
4. ✅ Set `NODE_ENV=production` in .env
|
||||||
|
5. ✅ Update `CORS_ORIGIN` to your domain
|
||||||
|
6. ✅ Regular database backups
|
||||||
|
7. ✅ Monitor audit logs regularly
|
||||||
|
8. ✅ Keep dependencies updated: `npm audit`
|
||||||
|
9. ✅ Restrict database access
|
||||||
|
10. ✅ Use firewall rules
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 System Monitoring
|
||||||
|
|
||||||
|
### Check Backend Health:
|
||||||
|
```bash
|
||||||
|
curl http://localhost:3001/health
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected response:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "ok",
|
||||||
|
"timestamp": "2025-12-05T12:00:00.000Z",
|
||||||
|
"uptime": 1234.567
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Check Database Health:
|
||||||
|
```bash
|
||||||
|
curl http://localhost:3001/health/db
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected response:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "ok",
|
||||||
|
"database": "connected",
|
||||||
|
"timestamp": "2025-12-05T12:00:00.000Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Monitor Processes:
|
||||||
|
The `app.py` launcher automatically monitors both processes.
|
||||||
|
If either crashes, you'll see an error message.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Performance Tips
|
||||||
|
|
||||||
|
### For Better Performance:
|
||||||
|
1. Use **Node.js 20 LTS** (faster than Node 18)
|
||||||
|
2. Increase database connection pool (edit config.js)
|
||||||
|
3. Enable gzip compression in production
|
||||||
|
4. Use production build: `npm run build`
|
||||||
|
5. Deploy behind Nginx reverse proxy
|
||||||
|
6. Use PM2 for process management
|
||||||
|
7. Enable database query caching
|
||||||
|
8. Optimize Ollama API calls (reduce timeout if too slow)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📞 Getting Help
|
||||||
|
|
||||||
|
### Documentation:
|
||||||
|
- **Quick Start**: [START_HERE.md](START_HERE.md)
|
||||||
|
- **Full README**: [README_FULL.md](README_FULL.md)
|
||||||
|
- **API Docs**: [docs/API_DOC.md](docs/API_DOC.md)
|
||||||
|
- **System Design**: [docs/SDD.md](docs/SDD.md)
|
||||||
|
- **Deployment**: [docs/DEPLOYMENT_CHECKLIST.md](docs/DEPLOYMENT_CHECKLIST.md)
|
||||||
|
- **Security**: [docs/security_audit.md](docs/security_audit.md)
|
||||||
|
|
||||||
|
### Repository:
|
||||||
|
https://gitea.theaken.com/donald/5why-analyzer
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎉 Success Indicators
|
||||||
|
|
||||||
|
Your application is working correctly when:
|
||||||
|
- ✅ `python app.py` starts without errors
|
||||||
|
- ✅ Backend responds at http://localhost:3001/health
|
||||||
|
- ✅ Frontend loads at http://localhost:5173
|
||||||
|
- ✅ You can login with test accounts
|
||||||
|
- ✅ 5 Why analysis creates results
|
||||||
|
- ✅ Analysis history displays records
|
||||||
|
- ✅ Admin dashboard shows statistics (for admin users)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Version**: 1.0.0
|
||||||
|
**Status**: ✅ Production Ready
|
||||||
|
**Security Rating**: A (92/100)
|
||||||
|
|
||||||
|
**Made with Claude Code** 🤖
|
||||||
Reference in New Issue
Block a user