5why-analyzer/USAGE_GUIDE.md

# 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** 🤖