คู่มือโครงสร้าง JSON สำหรับนำเข้าสินค้า (Product JSON Import Specification)

ระบบนำเข้าสินค้าของ HomAroma รองรับการ Import ผ่านไฟล์ .json หรือวาง Payload JSON Array ได้โดยตรงผ่าน:

หน้าจอ Admin: เมนู /products -> กดปุ่ม "Import JSON"
API Endpoint: POST /api/products/bulk หรือ POST /api/products

1. รูปแบบโครงสร้าง JSON (JSON Schema)

Payload หลักจะต้องเป็น JSON Array ของสินค้า โดยรองรับสินค้า 2 รูปแบบหลัก:

แบบที่ 1: สินค้าเดี่ยว (Simple Product - ไม่มีตัวเลือกย่อย)

เหมาะสำหรับสินค้าที่มีขนาดเดียว ราคาเดียว ไม่ต้องแตก Variant:

{
  "name": "ก้านไม้หอมปรับอากาศ กลิ่นมะลิไทย (Reed Diffuser Jasmine)",
  "categoryName": "Reed Diffuser",
  "brandName": "HomAroma",
  "price": 490,
  "stock": 100,
  "sku": "HA-RD-JAS-100",
  "barcode": "8859123456801",
  "description": "ก้านไม้กระจายความหอมกลิ่นดอกมะลิธรรมชาติ หอมละมุน 4-6 สัปดาห์",
  "details": "ปริมาตร: 100ml\nรวมก้านไม้ไฟเบอร์ 6 ก้าน",
  "images": [
    "https://example.com/uploads/diffuser-1.jpg",
    "https://example.com/uploads/diffuser-2.jpg"
  ]
}

ระบบ Auto-Handling: เมื่อใส่ price, stock, sku, barcode ไว้ที่ระดับบนสุด ระบบจะสร้าง Default Base Variant ให้โดยอัตโนมัติ

แบบที่ 2: สินค้าที่มีหลายตัวเลือกย่อย (Variable Product)

เหมาะสำหรับสินค้าที่มี ขนาด, กลิ่น, หรือสี ให้เลือก:

{
  "name": "น้ำมันหอมระเหย ลาเวนเดอร์ 100% Pure Essential Oil",
  "categoryName": "Aroma Oil",
  "brandName": "HomAroma",
  "description": "น้ำมันหอมระเหยบริสุทธิ์แท้ 100% สกัดจากดอกลาเวนเดอร์ประเทศฝรั่งเศส",
  "details": "วิธีใช้: หยด 3-5 หยดลงในเตาอโรมา\nขนาด: 10ml, 30ml",
  "options": [
    {
      "name": "ขนาด",
      "values": ["10ml", "30ml"]
    }
  ],
  "variants": [
    {
      "option1": "10ml",
      "price": 390,
      "stock": 50,
      "sku": "HA-LAV-10ML",
      "barcode": "8859123456701"
    },
    {
      "option1": "30ml",
      "price": 890,
      "stock": 30,
      "sku": "HA-LAV-30ML",
      "barcode": "8859123456702"
    }
  ],
  "images": [
    "https://example.com/uploads/lav-1.jpg"
  ]
}

แบบที่ 3: รองรับหลายภาษา (Multilingual - รองรับ 8 ภาษา: th, en, ja, zh, vi, ko, lo, it)

สามารถใส่ข้อความหลายภาษาใน translations หรือใส่เป็น Object ที่ฟิลด์ name, description, details ได้โดยตรง:

{
  "name": "น้ำมันหอมระเหย ยูคาลิปตัส",
  "categoryName": "Aroma Oil",
  "brandName": "HomAroma",
  "price": 320,
  "stock": 60,
  "sku": "HA-EUC-10ML",
  "translations": {
    "th": {
      "name": "น้ำมันหอมระเหย ยูคาลิปตัส 100%",
      "description": "ช่วยให้หายใจโล่ง สดชื่น ปลอดโปร่ง",
      "details": "ขนาด: 10ml"
    },
    "en": {
      "name": "Eucalyptus Pure Essential Oil 100%",
      "description": "Refreshes breathing and clarifies the mind.",
      "details": "Size: 10ml"
    },
    "ja": {
      "name": "ユーカリ 100% ピュア エッセンシャルオイル",
      "description": "クリアで清涼感あふれる香りが呼吸をスムーズに整えます。",
      "details": "容量: 10ml"
    },
    "zh": {
      "name": "尤加利 100% 纯天然单方精油",
      "description": "清爽提神的天然尤加利香气，畅通呼吸，净化空气。",
      "details": "规格: 10ml"
    }
  }
}

2. พจนานุกรมฟิลด์ (Data Dictionary)

ฟิลด์	ชนิดข้อมูล	จำเป็น?	คำอธิบายและข้อกำหนด
`name`	`string` \| `object`	ใช่	ชื่อสินค้า (เช่น `"Aroma Oil"` หรือ `{"th": "...", "en": "..."}`)
`categoryName`	`string`	ทางเลือก	ชื่อหมวดหมู่ (หากยังไม่มีในระบบ ระบบจะ Auto-Create ให้ทันที)
`categoryId`	`number`	ทางเลือก	รหัสหมวดหมู่เดิมในระบบ (ใช้แทน `categoryName` ได้)
`brandName`	`string`	ทางเลือก	ชื่อแบรนด์ (หากยังไม่มีในระบบ ระบบจะ Auto-Create ให้ทันที)
`brandId`	`number`	ทางเลือก	รหัสแบรนด์เดิมในระบบ (ใช้แทน `brandName` ได้)
`description`	`string` \| `object`	ไม่	คำอธิบายสินค้าโดยย่อ
`details`	`string` \| `object`	ไม่	รายละเอียดสินค้า วิธีการใช้งาน คุณสมบัติ
`price`	`number`	ไม่*	ราคาจำหน่าย (กรณีสินค้าเดี่ยวไม่มี Variants)
`stock`	`number`	ไม่*	จำนวนสต็อกคงเหลือ (กรณีสินค้าเดี่ยวไม่มี Variants)
`sku`	`string`	ไม่	รหัสสินค้า SKU
`barcode`	`string`	ไม่	รหัสบาร์โค้ดสินค้า (สำหรับยิงขายที่ POS)
`images`	`array`	ไม่	รายการรูปภาพ (รองรับทั้ง Array URL `["https://..."]` หรือ `[{"url": "...", "order": 0}]`)
`options`	`array`	ไม่*	รายการตัวเลือก สูงสุด 3 ตัวเลือก เช่น `[{"name": "ขนาด", "values": ["10ml", "30ml"]}]`
`variants`	`array`	ไม่*	รายการสินค้าย่อย โดย `option1`, `option2`, `option3` จะแมปตามลำดับของ `options`
`translations`	`object`	ไม่	แผนที่ภาษา รองรับ 8 ภาษา: `th`, `en`, `ja`, `zh`, `vi`, `ko`, `lo`, `it` เช่น `{"th": {...}, "en": {...}, "ja": {...}, ...}`

3. กลไกอัตโนมัติของ Backend (Auto-Provisioning Engine)

เมื่อส่ง JSON เข้าสู่ POST /api/products/bulk:

Auto-Category & Auto-Brand: หากส่ง categoryName หรือ brandName ที่ยังไม่มีในระบบ ระบบจะสร้าง Category/Brand ใหม่ให้โดยอัตโนมัติ ไม่เกิด Error
Auto-Default Base Variant: หากไม่ส่ง variants มา แต่ระบุ price หรือ stock หรือ sku ที่ระดับบนสุด ระบบจะแปลงเป็น Single Base Variant ให้อัตโนมัติ ทำให้สินค้าพร้อมขายและตัดสต็อกใน POS ได้ทันที
Auto-Normalize Images: แปลงทั้ง String URLs และ Image Objects ให้อยู่ในฟอร์แมตฐานข้อมูลพร้อมกำหนด Order ให้อัตโนมัติ
Auto-Seed CMS Detail Sections: ระบบจะสร้าง Section มาตรฐานสำหรับหน้าเว็บ Next.js SSR (Product Main Card, Description, Specifications, Reviews, Related Products) ให้ทันที ทำให้หน้าบ้านแสดงผลได้สมบูรณ์แบบโดยไม่ต้องเข้าไปตั้งค่าทีละชิ้น

8.9 KiB Raw Blame History