# 📡 API Specification (OpenAPI/Swagger) — GOFLOW Enterprise AI OS Portal

**API Specification Document**
เวอร์ชัน 1.0 · Confidential – GOFLOW Enterprise · อัปเดตล่าสุด: 2026-08-07
Base URL: `https://api.goflow.click/api/v1` (ตัวอย่าง) · Format: JSON · Auth: Bearer JWT

---

## 1. หลักการร่วม (Common Conventions)

| เรื่อง | กติกา |
|---|---|
| Authentication | `Authorization: Bearer <access_token>` (JWT) — refresh ผ่าน `/auth/refresh` |
| Content-Type | `application/json` ทั้ง request/response |
| เวลา | ISO 8601 UTC |
| Pagination | `?page=1&limit=20` → response มี `meta: {page, limit, total}` |
| Error format | `{ "error": { "code": "VALIDATION_ERROR", "message": "…", "details": [] } }` |
| Rate limit | Header `X-RateLimit-Remaining`; เกิน → `429 TOO_MANY_REQUESTS` |
| Idempotency | State-changing: ส่ง header `Idempotency-Key` |

### HTTP Status Codes ที่ใช้

| Code | ความหมาย |
|---|---|
| 200/201 | สำเร็จ |
| 400 | Input ผิด (Validation) |
| 401 | ไม่ได้ยืนยันตัวตน / Token หมดอายุ |
| 403 | ไม่มีสิทธิ์ (RBAC) |
| 404 | ไม่พบทรัพยากร |
| 409 | ขัดแย้ง (เช่น อีเมลซ้ำ) |
| 422 | Business rule ผิด |
| 429 | เกิน Rate Limit |
| 500 | ระบบผิดพลาด |

---

## 2. Authentication

### POST `/auth/login`
ยืนยันตัวตน รับ access + refresh token
```json
{ "email": "user@company.com", "password": "***" }
```
→ `200` `{ "accessToken": "…", "refreshToken": "…", "user": { "id", "role" } }`

### POST `/auth/refresh`
```json
{ "refreshToken": "…" }
```
→ `200` `{ "accessToken": "…" }`

### POST `/auth/register-organization`
ลงทะเบียนองค์กร (จาก Landing)
```json
{ "orgName": "…", "contactName": "…", "email": "…", "size": "SME|ENTERPRISE|GOV" }
```
→ `201` `{ "organizationId": "…", "status": "PENDING_REVIEW" }`

---

## 3. AI Integration (NEXUS AI)

### POST `/ai/chat` — ⭐ ใช้งานจริงใน Production แล้ว
สนทนากับ GOFLOW NEXUS AI (RAG + User Memory + Intelligent Memory Fusion)

Request:
```json
{
  "message": "สรุปผลการดำเนินงานไตรมาสนี้",
  "memory": "organization",          // organization | user | none
  "sessionId": "opt-session-uuid"
}
```

Response `200`:
```json
{
  "reply": "…",
  "memory": { "recalled": true, "userMemory": true, "intelligentMemory": true },
  "sources": [ { "docId": "…", "title": "…", "score": 0.92 } ],
  "reasoningMode": "rag-memory-intelligence-fusion-reasoning-v7.3"
}
```

Error ตัวอย่าง: `429` เมื่อเกิน quota, `503` เมื่อ LLM ไม่พร้อม

### POST `/ai/resolve`
ส่งปัญหามาให้ AI วิเคราะห์และเสนอวิธีแก้
```json
{ "problem": "…", "context": { "department": "sales" } }
```
→ `200` `{ "resolution": "…", "steps": ["…"], "confidence": 0.87 }`

### GET `/knowledge/search`
Semantic Search ใน Knowledge Base
```
?q=คำค้น&limit=10
```
→ `200` `{ "results": [ { "id", "title", "snippet", "score" } ] }`

### GET `/executive/report`
สร้างรายงานผู้บริหาร (KPI snapshot)
```
?period=Q3-2026&scope=all
```
→ `200` `{ "report": { "summary", "kpis": [ {"name","value","trend"} ], "generatedAt" } }`

### GET `/executive/tasks`
ภารกิจที่ AI Executive (CEO/CTO/CFO/COO) ดูแลอยู่
```
?status=open
```
→ `200` `{ "tasks": [ { "id", "agent": "ceo", "title", "status", "dueAt" } ] }`

---

## 4. Booking (จอง Demo)

### POST `/bookings`
```json
{
  "type": "ENTERPRISE_DEMO",        // ENTERPRISE_DEMO | AI_CONSULT | PARTNER_MEETING
  "name": "…", "organization": "…", "email": "…",
  "phone": "…", "topic": "enterprise",
  "preferredDate": "2026-08-20", "message": "…"
}
```
→ `201` `{ "bookingId": "…", "status": "PENDING_CONFIRMATION" }`

### GET `/bookings/availability`
```
?from=2026-08-01&to=2026-08-31&type=ENTERPRISE_DEMO
```
→ `200` `{ "slots": [ "2026-08-20T10:00:00+07:00", … ] }`

---

## 5. Recruitment

### GET `/positions`
รายการตำแหน่งที่เปิดรับ → `200` `{ "positions": [ { "id", "title", "team", "headcount", "status", "tags" } ] }`

### POST `/applications`
```json
{
  "positionId": "…",
  "name": "…", "email": "…", "phone": "…",
  "portfolioUrl": "…", "resumeFileId": "…", "message": "…"
}
```
→ `201` `{ "applicationId": "…", "status": "RECEIVED" }`

### POST `/applications/{id}/resume`
Upload resume → MinIO (multipart/form-data) → `200` `{ "fileId": "…" }`

### GET `/applications/{id}`
ติดตามสถานะ → `200` `{ "status": "RECEIVED|REVIEWING|INTERVIEW|OFFER|REJECTED" }`

---

## 6. Marketplace (v1.1)

| เมธอด | Path | หน้าที่ |
|---|---|---|
| GET | `/products` | รายการสินค้า (filter หมวด, ราคา) |
| GET | `/products/{id}` | รายละเอียดสินค้า |
| POST | `/orders` | สร้างออเดอร์ |
| GET | `/orders/{id}` | ดูออเดอร์ + สถานะส่ง |
| POST | `/payments` | สร้างคำสั่งชำระเงิน (GOFLOW Wallet) |
| GET | `/subscriptions/plans` | แผนสมาชิก |

---

## 7. Contact / Partner

### POST `/contact`
```json
{ "name": "…", "email": "…", "topic": "…", "message": "…" }
```
→ `201` `{ "ticketId": "…" }`

### POST `/partners/apply`
```json
{ "company": "…", "type": "TECHNOLOGY|INTEGRATION|CHANNEL", "contactName": "…", "email": "…" }
```
→ `201` `{ "partnerId": "…", "status": "PENDING" }`

---

## 8. Webhook (เหตุการณ์)

| Event | ใช้กับ |
|---|---|
| `booking.confirmed` | ยืนยันการจอง Demo |
| `application.status_changed` | แจ้งผู้สมัครงาน |
| `payment.succeeded` | Marketplace / Wallet |

---

## 9. แผนการเปิดให้บริการ (Rollout)

| Endpoint | สถานะ |
|---|---|
| `/ai/chat` | ✅ Production (NEXUS AI v7.3) |
| `/auth/*`, `/contact`, `/bookings`, `/applications` | Sprint 2–3 |
| `/ai/resolve`, `/knowledge/search`, `/executive/*` | Sprint 3–4 |
| `/products`, `/orders`, `/payments`, `/subscriptions` | v1.1 |

---

*เอกสารนี้เป็นส่วนหนึ่งของ GOFLOW Developer Kit — สร้าง OpenAPI/Swagger ไฟล์จากตารางนี้ได้โดยตรง (openapi: 3.1.0)*