5why-analyzer/docs/API_DOC.md

5 Why Analyzer - API Documentation

Version: 1.0.0 Base URL: http://localhost:3001 Last Updated: 2025-12-05

---

Table of Contents

1. Authentication
2. Analysis
3. Admin
4. Health Check
5. Error Handling
6. Rate Limiting

---

Authentication

POST /api/auth/login

User login with email or employee ID.

Request Body:

{
  "identifier": "admin@example.com",  // or "ADMIN001"
  "password": "Admin@123456"
}

Success Response (200):

{
  "success": true,
  "message": "登入成功",
  "user": {
    "id": 1,
    "employee_id": "ADMIN001",
    "username": "admin",
    "email": "admin@example.com",
    "role": "super_admin",
    "department": "IT",
    "position": "System Administrator",
    "is_active": 1,
    "created_at": "2025-12-05T10:26:57.000Z",
    "last_login_at": "2025-12-05T14:47:57.000Z"
  }
}

Error Response (401):

{
  "success": false,
  "error": "帳號或密碼錯誤"
}

---

POST /api/auth/logout

Logout current user and destroy session.

Authentication: Required (Session)

Success Response (200):

{
  "success": true,
  "message": "已登出"
}

---

GET /api/auth/me

Get current authenticated user information.

Authentication: Required (Session)

Success Response (200):

{
  "success": true,
  "user": {
    "id": 1,
    "employee_id": "ADMIN001",
    "username": "admin",
    "email": "admin@example.com",
    "role": "super_admin",
    "department": "IT",
    "position": "System Administrator",
    "is_active": 1,
    "created_at": "2025-12-05T10:26:57.000Z",
    "last_login_at": "2025-12-05T14:47:57.000Z"
  }
}

Error Response (401):

{
  "success": false,
  "error": "未登入"
}

---

POST /api/auth/change-password

Change user password.

Authentication: Required (Session)

Request Body:

{
  "oldPassword": "Admin@123456",
  "newPassword": "NewPassword@123"
}

Success Response (200):

{
  "success": true,
  "message": "密碼已更新"
}

Error Response (400):

{
  "success": false,
  "error": "舊密碼錯誤"
}

---

Analysis

POST /api/analyze

Create a new 5 Why analysis with AI.

Authentication: Required (Session)

Request Body:

{
  "finding": "伺服器經常當機",
  "jobContent": "我們的 Web 伺服器運行在 Ubuntu 20.04 上，使用 Node.js 16...",
  "outputLanguage": "zh-TW"  // or "zh-CN", "en", "ja", "ko", "vi", "th"
}

Success Response (200):

{
  "success": true,
  "message": "分析完成",
  "analysis": {
    "id": 1,
    "user_id": 1,
    "finding": "伺服器經常當機",
    "status": "completed",
    "created_at": "2025-12-05T15:00:00.000Z",
    "perspectives": [
      {
        "id": 1,
        "perspective_type": "technical",
        "root_cause": "記憶體洩漏導致系統資源耗盡",
        "solution": "實施記憶體監控，修復洩漏問題",
        "whys": [
          {
            "why_level": 1,
            "question": "為什麼伺服器會當機？",
            "answer": "因為記憶體使用率達到 100%"
          },
          // ... 4 more whys
        ]
      },
      // ... process and human perspectives
    ]
  },
  "processingTime": 45.2
}

Error Response (400):

{
  "success": false,
  "error": "請填寫所有必填欄位"
}

---

POST /api/analyze/translate

Translate existing analysis to another language.

Authentication: Required (Session)

Request Body:

{
  "analysisId": 1,
  "targetLanguage": "en"
}

Success Response (200):

{
  "success": true,
  "message": "翻譯完成",
  "translatedAnalysis": {
    "id": 2,
    "original_analysis_id": 1,
    "output_language": "en",
    // ... translated content
  }
}

---

GET /api/analyze/history

Get user's analysis history with pagination.

Authentication: Required (Session)

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 10)
• status (optional): Filter by status (pending/processing/completed/failed)
• date_from (optional): Filter from date (YYYY-MM-DD)
• date_to (optional): Filter to date (YYYY-MM-DD)
• search (optional): Search in finding field

Example: /api/analyze/history?page=1&limit=10&status=completed

Success Response (200):

{
  "success": true,
  "data": [
    {
      "id": 1,
      "finding": "伺服器經常當機",
      "status": "completed",
      "output_language": "zh-TW",
      "created_at": "2025-12-05T15:00:00.000Z",
      "updated_at": "2025-12-05T15:01:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3
  }
}

---

GET /api/analyze/:id

Get detailed analysis including all perspectives and whys.

Authentication: Required (Session + Ownership)

Success Response (200):

{
  "success": true,
  "analysis": {
    "id": 1,
    "finding": "伺服器經常當機",
    "job_content": "...",
    "output_language": "zh-TW",
    "status": "completed",
    "created_at": "2025-12-05T15:00:00.000Z",
    "perspectives": [
      {
        "id": 1,
        "perspective_type": "technical",
        "root_cause": "...",
        "solution": "...",
        "whys": [
          {
            "id": 1,
            "why_level": 1,
            "question": "...",
            "answer": "..."
          }
        ]
      }
    ]
  }
}

---

DELETE /api/analyze/:id

Delete an analysis record.

Authentication: Required (Session + Ownership)

Success Response (200):

{
  "success": true,
  "message": "分析已刪除"
}

---

Admin

All admin endpoints require admin or super_admin role.

GET /api/admin/dashboard

Get dashboard statistics.

Authentication: Required (Admin)

Success Response (200):

{
  "success": true,
  "stats": {
    "totalUsers": 10,
    "totalAnalyses": 150,
    "monthlyAnalyses": 45,
    "activeUsers": 8,
    "recentAnalyses": [
      {
        "id": 150,
        "username": "user001",
        "finding": "...",
        "created_at": "2025-12-05T14:00:00.000Z"
      }
    ]
  }
}

---

GET /api/admin/users

Get all users with pagination.

Authentication: Required (Admin)

Query Parameters:

• page (optional): Page number
• limit (optional): Items per page
• role (optional): Filter by role
• is_active (optional): Filter by active status (0/1)
• search (optional): Search in username/email/employee_id

Success Response (200):

{
  "success": true,
  "data": [
    {
      "id": 1,
      "employee_id": "ADMIN001",
      "username": "admin",
      "email": "admin@example.com",
      "role": "super_admin",
      "department": "IT",
      "position": "System Administrator",
      "is_active": 1,
      "created_at": "2025-12-05T10:26:57.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 10,
    "totalPages": 1
  }
}

---

POST /api/admin/users

Create a new user.

Authentication: Required (Admin)

Request Body:

{
  "employee_id": "USER003",
  "username": "新使用者",
  "email": "user003@example.com",
  "password": "Password@123",
  "role": "user",           // "user", "admin", or "super_admin"
  "department": "Engineering",
  "position": "Engineer"
}

Success Response (201):

{
  "success": true,
  "message": "使用者已建立",
  "user": {
    "id": 11,
    "employee_id": "USER003",
    "username": "新使用者",
    "email": "user003@example.com",
    "role": "user"
  }
}

---

PUT /api/admin/users/:id

Update user information.

Authentication: Required (Admin)

Request Body:

{
  "username": "Updated Name",
  "email": "newemail@example.com",
  "role": "admin",
  "department": "IT",
  "position": "Senior Engineer",
  "is_active": 1
}

Success Response (200):

{
  "success": true,
  "message": "使用者已更新"
}

---

DELETE /api/admin/users/:id

Delete a user (soft delete).

Authentication: Required (Admin)

Success Response (200):

{
  "success": true,
  "message": "使用者已刪除"
}

---

GET /api/admin/analyses

Get all analyses across all users.

Authentication: Required (Admin)

Query Parameters:

• page, limit, status, user_id, search

Success Response (200):

{
  "success": true,
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "username": "admin",
      "employee_id": "ADMIN001",
      "finding": "...",
      "status": "completed",
      "created_at": "2025-12-05T15:00:00.000Z"
    }
  ],
  "pagination": { /* ... */ }
}

---

GET /api/admin/audit-logs

Get audit logs with pagination.

Authentication: Required (Admin)

Query Parameters:

• page, limit, user_id, action, status, date_from, date_to

Success Response (200):

{
  "success": true,
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "username": "admin",
      "action": "login",
      "entity_type": null,
      "entity_id": null,
      "old_value": null,
      "new_value": null,
      "ip_address": "::1",
      "user_agent": "Mozilla/5.0...",
      "status": "success",
      "created_at": "2025-12-05T14:47:57.000Z"
    }
  ],
  "pagination": { /* ... */ }
}

---

GET /api/admin/statistics

Get comprehensive system statistics.

Authentication: Required (Admin)

Success Response (200):

{
  "success": true,
  "statistics": {
    "users": {
      "total": 10,
      "active": 8,
      "byRole": {
        "user": 7,
        "admin": 2,
        "super_admin": 1
      }
    },
    "analyses": {
      "total": 150,
      "byStatus": {
        "completed": 140,
        "failed": 8,
        "processing": 2
      },
      "thisMonth": 45,
      "thisWeek": 12
    },
    "topUsers": [
      {
        "username": "user001",
        "analysis_count": 25
      }
    ]
  }
}

---

Health Check

GET /health

Basic server health check.

Authentication: None

Success Response (200):

{
  "status": "ok",
  "message": "Server is running",
  "timestamp": "2025-12-05T15:00:00.000Z",
  "environment": "development"
}

---

GET /health/db

Database connectivity check.

Authentication: None

Success Response (200):

{
  "status": "ok",
  "database": "connected"
}

Error Response (500):

{
  "status": "error",
  "database": "error",
  "message": "Connection failed"
}

---

Error Handling

All API endpoints follow a consistent error response format:

{
  "success": false,
  "error": "Error Type",
  "message": "Human-readable error message"
}

Development Mode

In development, errors include stack traces:

{
  "success": false,
  "error": "ValidationError",
  "message": "Invalid input",
  "stack": "Error: Invalid input\n    at ...",
  "details": { /* additional error details */ }
}

HTTP Status Codes

Code	Meaning	Usage
200	OK	Successful request
201	Created	Resource created successfully
400	Bad Request	Invalid input or validation error
401	Unauthorized	Authentication required or failed
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

---

Rate Limiting

All /api/* endpoints are rate limited:

• Window: 15 minutes
• Max Requests: 100 per IP address
• Headers:
  • RateLimit-Limit: Maximum requests per window
  • RateLimit-Remaining: Remaining requests
  • RateLimit-Reset: Time when limit resets

Rate Limit Exceeded Response (429):

{
  "success": false,
  "error": "請求過於頻繁，請稍後再試"
}

---

Authentication

All protected endpoints require a valid session cookie. The session cookie is set automatically upon successful login.

Session Cookie Name: 5why.sid Session Duration: 24 hours Cookie Attributes:

• httpOnly: true (prevents XSS access)
• maxAge: 86400000 ms (24 hours)

Frontend Integration

When making requests from the frontend, include credentials:

fetch('http://localhost:3001/api/auth/login', {
  method: 'POST',
  credentials: 'include',  // Important: sends cookies
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ identifier, password })
});

---

Complete Endpoint List

Authentication (4 endpoints)

• POST /api/auth/login - User login
• POST /api/auth/logout - User logout
• GET /api/auth/me - Get current user
• POST /api/auth/change-password - Change password

Analysis (5 endpoints)

• POST /api/analyze - Create analysis
• POST /api/analyze/translate - Translate analysis
• GET /api/analyze/history - Get history
• GET /api/analyze/:id - Get analysis detail
• DELETE /api/analyze/:id - Delete analysis

Admin (8 endpoints)

• GET /api/admin/dashboard - Dashboard stats
• GET /api/admin/users - List users
• POST /api/admin/users - Create user
• PUT /api/admin/users/:id - Update user
• DELETE /api/admin/users/:id - Delete user
• GET /api/admin/analyses - List all analyses
• GET /api/admin/audit-logs - View audit logs
• GET /api/admin/statistics - Get statistics

Health (2 endpoints)

• GET /health - Server health
• GET /health/db - Database health

Total: 19 endpoints

---

Document Version: 1.0.0 Last Updated: 2025-12-05 Maintained By: Development Team