# คู่มือ API ระบบงานบริการติดต่อ (Services API)

วิทยาลัยการอาชีพปราสาท - SmartPR Kiosk System

## Base URL

```
https://api.prasat.ac.th/api
```

---

## 1. Services API (`services.php`)

### 1.1 ดึงรายการงานบริการทั้งหมด

**Request:**
```http
GET /api/services.php
```

**Parameters (Query String):**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| category | string | No | กรองตามหมวดหมู่ เช่น `งานทะเบียน` |
| search | string | No | ค้นหาจากชื่อหรือคำอธิบาย |
| limit | int | No | จำนวนรายการ (default: 50) |

**Response Success:**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "ขอใบรับรองการเป็นนักศึกษา",
      "description": "บริการออกใบรับรองการเป็นนักศึกษา",
      "icon": "description",
      "color": "#4CAF50",
      "department": "งานทะเบียน",
      "location": "อาคาร 1 ชั้น 1",
      "contact_person": "คุณสมหญิง",
      "contact_phone": "044-551234",
      "requirements": ["บัตรนักศึกษา", "บัตรประชาชน"],
      "steps": ["ยื่นคำร้อง", "ชำระค่าธรรมเนียม", "รับเอกสาร"],
      "service_hours": "08:30-16:30 น.",
      "estimated_time": "1-3 วัน",
      "fee": "20 บาท",
      "online_link": null,
      "qr_code_url": null,
      "category": "งานทะเบียน",
      "view_count": 15,
      "created_at": "2025-01-20 10:00:00"
    }
  ],
  "total": 10
}
```

**Response Error:**
```json
{
  "success": false,
  "error": "ข้อความ error"
}
```

---

### 1.2 ดึงรายละเอียดงานบริการ

**Request:**
```http
GET /api/services.php?id={id}
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | int | Yes | ID ของงานบริการ |

**Response:**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "ขอใบรับรองการเป็นนักศึกษา",
    "description": "บริการออกใบรับรองการเป็นนักศึกษา...",
    "icon": "description",
    "color": "#4CAF50",
    "department": "งานทะเบียน",
    "location": "อาคาร 1 ชั้น 1 ห้องทะเบียน",
    "contact_person": "คุณสมหญิง",
    "contact_phone": "044-551234 ต่อ 101",
    "requirements": [
      "บัตรนักศึกษา",
      "บัตรประชาชน",
      "ค่าธรรมเนียม 20 บาท/ฉบับ"
    ],
    "steps": [
      "ยื่นคำร้องที่ห้องทะเบียน",
      "ชำระค่าธรรมเนียม",
      "รอรับเอกสาร 1-3 วันทำการ"
    ],
    "service_hours": "08:30 - 16:30 น. (วันจันทร์-ศุกร์)",
    "estimated_time": "1-3 วันทำการ",
    "fee": "20 บาท/ฉบับ",
    "online_link": "https://example.com/form",
    "qr_code_url": "https://example.com/qr.png",
    "category": "งานทะเบียน",
    "display_order": 1,
    "view_count": 25,
    "created_at": "2025-01-20 10:00:00",
    "updated_at": "2025-01-25 14:30:00"
  }
}
```

---

### 1.3 ดึงรายการหมวดหมู่

**Request:**
```http
GET /api/services.php?action=categories
```

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "งานทะเบียน",
      "name_en": "Registration",
      "icon": "assignment",
      "color": "#4CAF50",
      "display_order": 1
    },
    {
      "id": 2,
      "name": "งานการเงิน",
      "name_en": "Finance",
      "icon": "payments",
      "color": "#FF9800",
      "display_order": 2
    }
  ]
}
```

---

### 1.4 เพิ่ม View Count

**Request:**
```http
POST /api/services.php
Content-Type: application/json

{
  "action": "increment_view",
  "id": 1
}
```

**Response:**
```json
{
  "success": true,
  "message": "View count updated"
}
```

---

## 2. Service Advisor API (`service_advisor.php`)

ระบบแนะนำงานบริการด้วย AI (DeepSeek)

### 2.1 ถาม AI เพื่อแนะนำงานบริการ

**Request:**
```http
POST /api/service_advisor.php
Content-Type: application/json

{
  "question": "ต้องการขอใบรับรองไปสมัครงาน ต้องทำอย่างไร"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "answer": "สำหรับการขอใบรับรองการเป็นนักศึกษาเพื่อไปสมัครงาน คุณต้องติดต่องานทะเบียน...",
    "suggested_services": [
      {
        "id": 1,
        "name": "ขอใบรับรองการเป็นนักศึกษา",
        "description": "บริการออกใบรับรอง...",
        "department": "งานทะเบียน",
        "location": "อาคาร 1 ชั้น 1",
        "fee": "20 บาท"
      }
    ],
    "inquiry_id": 123
  }
}
```

---

## 3. ตัวอย่างการใช้งานกับ Flutter

### 3.1 ดึงรายการงานบริการ

```dart
Future<List<ServiceModel>> getServices({String? category}) async {
  final response = await dio.get(
    '$baseUrl/api/services.php',
    queryParameters: {
      if (category != null) 'category': category,
    },
  );

  if (response.data['success'] == true) {
    final List<dynamic> data = response.data['data'];
    return data.map((json) => ServiceModel.fromJson(json)).toList();
  }
  throw Exception(response.data['error']);
}
```

### 3.2 ดึงรายละเอียดงานบริการ

```dart
Future<ServiceModel> getServiceDetail(int id) async {
  final response = await dio.get(
    '$baseUrl/api/services.php',
    queryParameters: {'id': id},
  );

  if (response.data['success'] == true) {
    return ServiceModel.fromJson(response.data['data']);
  }
  throw Exception(response.data['error']);
}
```

### 3.3 ถาม AI Advisor

```dart
Future<Map<String, dynamic>> askServiceAdvisor(String question) async {
  final response = await dio.post(
    '$baseUrl/api/service_advisor.php',
    data: {'question': question},
  );

  if (response.data['success'] == true) {
    return response.data['data'];
  }
  throw Exception(response.data['error']);
}
```

---

## 4. โครงสร้างฐานข้อมูล

### 4.1 ตาราง `services`

| Column | Type | Description |
|--------|------|-------------|
| id | INT | Primary Key |
| name | VARCHAR(255) | ชื่องานบริการ |
| description | TEXT | รายละเอียด |
| icon | VARCHAR(100) | ชื่อ Material Icon |
| color | VARCHAR(20) | สี Hex เช่น #4CAF50 |
| department | VARCHAR(255) | หน่วยงาน |
| location | VARCHAR(255) | สถานที่ |
| contact_person | VARCHAR(255) | ผู้ติดต่อ |
| contact_phone | VARCHAR(50) | เบอร์โทร |
| requirements | TEXT (JSON) | เอกสารที่ต้องใช้ |
| steps | TEXT (JSON) | ขั้นตอน |
| service_hours | VARCHAR(255) | เวลาให้บริการ |
| estimated_time | VARCHAR(100) | ระยะเวลา |
| fee | VARCHAR(100) | ค่าธรรมเนียม |
| online_link | VARCHAR(500) | ลิงก์ออนไลน์ |
| qr_code_url | VARCHAR(500) | URL QR Code |
| category | VARCHAR(100) | หมวดหมู่ |
| display_order | INT | ลำดับการแสดง |
| is_active | TINYINT(1) | สถานะ 1=เปิด |
| view_count | INT | จำนวนเข้าชม |
| created_at | TIMESTAMP | วันที่สร้าง |
| updated_at | TIMESTAMP | วันที่แก้ไข |

### 4.2 ตาราง `service_categories`

| Column | Type | Description |
|--------|------|-------------|
| id | INT | Primary Key |
| name | VARCHAR(100) | ชื่อหมวดหมู่ |
| name_en | VARCHAR(100) | ชื่อภาษาอังกฤษ |
| icon | VARCHAR(100) | ชื่อ Icon |
| color | VARCHAR(20) | สี Hex |
| display_order | INT | ลำดับ |
| is_active | TINYINT(1) | สถานะ |

### 4.3 ตาราง `service_inquiries`

| Column | Type | Description |
|--------|------|-------------|
| id | INT | Primary Key |
| user_question | TEXT | คำถามผู้ใช้ |
| ai_response | TEXT | คำตอบจาก AI |
| suggested_service_ids | TEXT | ID ที่แนะนำ |
| device_info | VARCHAR(255) | ข้อมูลอุปกรณ์ |
| ip_address | VARCHAR(45) | IP Address |
| created_at | TIMESTAMP | วันที่ |

---

## 5. การติดตั้ง

### 5.1 สร้างตารางอัตโนมัติ

เปิด URL:
```
https://api.prasat.ac.th/api/install_services.php
```

### 5.2 สร้างตารางด้วย SQL

Import ไฟล์ `sql/services_tables.sql` ผ่าน phpMyAdmin

---

## 6. Error Codes

| Code | Message | Description |
|------|---------|-------------|
| 400 | Missing required field | ไม่ได้ส่งข้อมูลที่จำเป็น |
| 404 | Service not found | ไม่พบงานบริการ |
| 500 | Database error | เกิดข้อผิดพลาดฐานข้อมูล |
| 500 | AI service unavailable | ไม่สามารถเชื่อมต่อ AI ได้ |

---

## 7. ตัวอย่าง cURL

### ดึงรายการทั้งหมด
```bash
curl -X GET "https://api.prasat.ac.th/api/services.php"
```

### ดึงตามหมวดหมู่
```bash
curl -X GET "https://api.prasat.ac.th/api/services.php?category=งานทะเบียน"
```

### ดึงรายละเอียด
```bash
curl -X GET "https://api.prasat.ac.th/api/services.php?id=1"
```

### ถาม AI
```bash
curl -X POST "https://api.prasat.ac.th/api/service_advisor.php" \
  -H "Content-Type: application/json" \
  -d '{"question": "ขอใบรับรองต้องใช้เอกสารอะไรบ้าง"}'
```

---

**Version:** 1.0
**Last Updated:** 2025-01-25
**Author:** SmartPR Development Team