# 5 Why Analyzer - API Documentation

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

---

## Table of Contents

1. [Authentication](#authentication)
2. [Analysis](#analysis)
3. [Admin](#admin)
4. [Health Check](#health-check)
5. [Error Handling](#error-handling)
6. [Rate Limiting](#rate-limiting)

---

## Authentication

### POST /api/auth/login

User login with email or employee ID.

**Request Body**:
```json
{
  "identifier": "admin@example.com",  // or "ADMIN001"
  "password": "Admin@123456"
}
```

**Success Response** (200):
```json
{
  "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):
```json
{
  "success": false,
  "error": "帳號或密碼錯誤"
}
```

---

### POST /api/auth/logout

Logout current user and destroy session.

**Authentication**: Required (Session)

**Success Response** (200):
```json
{
  "success": true,
  "message": "已登出"
}
```

---

### GET /api/auth/me

Get current authenticated user information.

**Authentication**: Required (Session)

**Success Response** (200):
```json
{
  "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):
```json
{
  "success": false,
  "error": "未登入"
}
```

---

### POST /api/auth/change-password

Change user password.

**Authentication**: Required (Session)

**Request Body**:
```json
{
  "oldPassword": "Admin@123456",
  "newPassword": "NewPassword@123"
}
```

**Success Response** (200):
```json
{
  "success": true,
  "message": "密碼已更新"
}
```

**Error Response** (400):
```json
{
  "success": false,
  "error": "舊密碼錯誤"
}
```

---

## Analysis

### POST /api/analyze

Create a new 5 Why analysis with AI.

**Authentication**: Required (Session)

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

**Success Response** (200):
```json
{
  "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):
```json
{
  "success": false,
  "error": "請填寫所有必填欄位"
}
```

---

### POST /api/analyze/translate

Translate existing analysis to another language.

**Authentication**: Required (Session)

**Request Body**:
```json
{
  "analysisId": 1,
  "targetLanguage": "en"
}
```

**Success Response** (200):
```json
{
  "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):
```json
{
  "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):
```json
{
  "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):
```json
{
  "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):
```json
{
  "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):
```json
{
  "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**:
```json
{
  "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):
```json
{
  "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**:
```json
{
  "username": "Updated Name",
  "email": "newemail@example.com",
  "role": "admin",
  "department": "IT",
  "position": "Senior Engineer",
  "is_active": 1
}
```

**Success Response** (200):
```json
{
  "success": true,
  "message": "使用者已更新"
}
```

---

### DELETE /api/admin/users/:id

Delete a user (soft delete).

**Authentication**: Required (Admin)

**Success Response** (200):
```json
{
  "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):
```json
{
  "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):
```json
{
  "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):
```json
{
  "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):
```json
{
  "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):
```json
{
  "status": "ok",
  "database": "connected"
}
```

**Error Response** (500):
```json
{
  "status": "error",
  "database": "error",
  "message": "Connection failed"
}
```

---

## Error Handling

All API endpoints follow a consistent error response format:

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

### Development Mode
In development, errors include stack traces:
```json
{
  "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):
```json
{
  "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:

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