docs: add LLM_PRODUCT_JSON_GENERATOR_GUIDE.md for generating product JSON catalog

2026-09-25 04:22:07 +07:00
1 parent 101143f26a
commit 0f632f2a93
@@ -0,0 +1,153 @@
+# LLM Guide: Prompt & Schema สำหรับสั่งให้ AI สร้าง JSON สินค้าของ HomAroma
+
+เอกสารฉบับนี้ออกแบบมาเพื่อ **Copy & Paste ส่งต่อให้ LLM (เช่น ChatGPT, Claude, Gemini)** เพื่อสั่งให้ AI สร้างข้อมูลสินค้าให้ออกมาเป็น **Valid JSON Array** ที่ถูกต้อง 100% ตาม Schema ของระบบ HomAroma และสามารถนำไปกด **"Import JSON"** ในหน้า Admin หรือเรียก `POST /api/products/bulk` ได้ทันทีโดยไม่ติด Error ใดๆ
+
+---
+
+## 📋 ส่วนที่ 1: Prompt สำหรับ Copy ส่งให้ LLM (Master Prompt)
+
+> **วิธีใช้งาน:** คัดลอกข้อความในกรอบด้านล่างนี้ทั้งหมด แล้วส่งให้ LLM โดยคุณสามารถแก้ประเภทสินค้า, จำนวนสินค้า หรือแบรนด์ตามต้องการได้ที่ส่วนท้ายของ Prompt:
+
+```text
+คุณคือ Senior E-commerce Catalog Specialist และ Luxury Product Copywriter ประจำแบรนด์ HomAroma
+หน้าที่ของคุณคือ: ออกแบบและสร้างข้อมูลสินค้าสำหรับนำเข้าสู่ระบบ E-commerce ในรูปแบบ Valid JSON Array ตามข้อกำหนดอย่างเคร่งครัด
+
+[กฎและข้อกำหนดโครงสร้าง JSON]:
+1. ผลลัพธ์ต้องเป็น Valid JSON Array ของ Object สินค้าเท่านั้น (เริ่มต้นด้วย [ และจบด้วย ])
+2. ห้ามมีคำเกริ่นนำ ห้ามมีคำลงท้าย ให้ส่งเฉพาะ JSON ล้วนๆ
+3. ฟิลด์ตัวเลข (price, stock, order) ต้องเป็น Number ห้ามใส่เครื่องหมายคำพูด (ห้ามเป็น String)
+4. สินค้าแต่ละชิ้นต้องมีข้อมูลครบถ้วน:
+   - "name": ชื่อสินค้าที่น่าสนใจ ดึงดูด และดูพรีเมียม
+   - "categoryName": หมวดหมู่สินค้า เช่น "Aroma Oil", "Reed Diffuser", "Room Spray", "Car Diffuser", "Essential Oil", "Candle" หรือหมวดอื่นๆ ตามความเหมาะสม
+   - "brandName": ชื่อแบรนด์ เช่น "HomAroma" หรือแบรนด์ตามโจทย์
+   - "description": คำบรรยายสรรพคุณ อารมณ์ กลิ่นสัมผัส ความรู้สึกระดับพรีเมียม (ความยาว 2-4 บรรทัด)
+   - "details": รายละเอียดเชิงลึก เช่น Scent Notes (Top/Middle/Base Notes), ขนาดบรรจุ, วิธีการใช้งาน, ข้อควรระวัง
+   - "images": Array ของ URL รูปภาพสินค้าความละเอียดสูง (ใช้ลิงก์รูปจริงจาก Unsplash เกี่ยวกับ Aroma, Diffuser, Perfume, Spa ที่เปิดดูได้จริง)
+5. ประเภทสินค้า (เลือกทำแบบใดแบบหนึ่งตามความเหมาะสมของสินค้า):
+   - แบบ A: สินค้าเดี่ยว (Simple Product):
+     ใส่ "price", "stock", "sku", "barcode" (บาร์โค้ดสากล 13 หลัก) ไว้ที่ระดับบนสุดของ Object
+   - แบบ B: สินค้ามีตัวเลือกย่อย (Variable Product เช่น มีหลายขนาด หรือหลายกลิ่น):
+     ต้องมี "options" ระบุชื่อตัวเลือกและค่าที่เป็นไปได้ และมี "variants" ที่ระบุ "option1", "price", "stock", "sku", "barcode" ให้สอดคล้องกันทุกตัว
+6. รองรับ 2 ภาษา (Bilingual):
+   - มีฟิลด์ "translations" กำหนดทั้ง "th" (ภาษาไทย) และ "en" (ภาษาอังกฤษ) สำหรับ "name", "description", และ "details"
+
+[โจทย์สินค้าที่ต้องการให้คุณสร้าง]:
+กรุณาสร้างข้อมูลสินค้าจำนวน 5 รายการ ในหมวดเครื่องหอมและสปา (Essential Oil, Reed Diffuser, Room Spray) โดยมีทั้งสินค้าแบบ Simple Product และ Variable Product ที่มีขนาด 10ml, 30ml, 50ml, 100ml ให้สมบูรณ์แบบพร้อมใช้งานทันที
+```
+
+---
+
+## 📐 ส่วนที่ 2: โครงสร้าง Schema อ้างอิงทางเทคนิค (Data Specification)
+
+### 1. แบบสินค้ามีตัวเลือกย่อย (Variable Product - มีขนาด/กลิ่น/สี)
+
+```json
+{
+  "name": "น้ำมันหอมระเหย ลาเวนเดอร์ 100% Pure Essential Oil",
+  "categoryName": "Aroma Oil",
+  "brandName": "HomAroma",
+  "description": "น้ำมันหอมระเหยบริสุทธิ์แท้ 100% สกัดจากดอกลาเวนเดอร์ประเทศฝรั่งเศส กลิ่นหอมนุ่มนวล ช่วยผ่อนคลายความตึงเครียด บำบัดจิตใจ และช่วยให้นอนหลับลึกอย่างมีคุณภาพ",
+  "details": "• Scent Profile: Floral, Herbal, Calming\n• Top Notes: French Lavender, Fresh Bergamot\n• Heart Notes: Clary Sage, Chamomile\n• Base Notes: Soft Cedarwood\n• วิธีใช้: หยด 3-5 หยดลงในเตาอโรมาหรือเครื่องพ่นไอน้ำ\n• ขนาดบรรจุ: 10ml / 30ml\n• มาตรฐาน: 100% Pure Therapeutic Grade",
+  "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://images.unsplash.com/photo-1608571423902-eed4a5ad8108?w=800",
+    "https://images.unsplash.com/photo-1617897903246-719242758050?w=800"
+  ],
+  "translations": {
+    "th": {
+      "name": "น้ำมันหอมระเหย ลาเวนเดอร์ 100% Pure Essential Oil",
+      "description": "น้ำมันหอมระเหยบริสุทธิ์แท้ 100% สกัดจากดอกลาเวนเดอร์ประเทศฝรั่งเศส ช่วยผ่อนคลายความตึงเครียดและช่วยให้นอนหลับลึก",
+      "details": "• กลิ่น: ฟลอรัล สมุนไพร ผ่อนคลาย\n• วิธีใช้: หยด 3-5 หยดลงในเตาอโรมาหรือเครื่องพ่นไอน้ำ\n• ขนาด: 10ml / 30ml"
+    },
+    "en": {
+      "name": "Lavender Pure Essential Oil 100%",
+      "description": "100% pure natural French lavender essential oil. Calms the mind, relieves daily stress, and encourages restorative sleep.",
+      "details": "• Scent Profile: Floral, Herbal, Calming\n• Usage: Diffuse 3-5 drops in an aroma diffuser or burner.\n• Sizes: 10ml / 30ml"
+    }
+  }
+}
+```
+
+---
+
+### 2. แบบสินค้าเดี่ยว (Simple Product - ไม่มีตัวเลือกย่อย)
+
+```json
+{
+  "name": "ก้านไม้หอมปรับอากาศ กลิ่นมะลิไทยแท้ (Siam Jasmine Reed Diffuser)",
+  "categoryName": "Reed Diffuser",
+  "brandName": "HomAroma",
+  "price": 590,
+  "stock": 80,
+  "sku": "HA-RD-JAS-100",
+  "barcode": "8859123456801",
+  "description": "ก้านไม้กระจายความหอมระดับพรีเมียม สกัดความหอมละมุนจากดอกมะลิซ้อนสยาม สร้างบรรยากาศอบอุ่น ผ่อนคลาย และหรูหราให้ทุกมุมบ้าน กระจายกลิ่นต่อเนื่องยาวนาน 4-6 สัปดาห์",
+  "details": "• ปริมาตรสุทธิ: 100 ml\n• อายุการใช้งาน: 4-6 สัปดาห์ (ขึ้นอยู่กับอุณหภูมิและความชื้น)\n• อุปกรณ์ในกล่อง: ขวดแก้วทรงคลาสสิก พร้อมก้านไม้ไฟเบอร์นำเข้าสีดำ 6 ก้าน\n• พื้นที่แนะนำ: ห้องนอน, ห้องรับแขก, ห้องทำงาน ขนาด 15-25 ตารางเมตร",
+  "images": [
+    "https://images.unsplash.com/photo-1617897903246-719242758050?w=800",
+    "https://images.unsplash.com/photo-1608571423902-eed4a5ad8108?w=800"
+  ],
+  "translations": {
+    "th": {
+      "name": "ก้านไม้หอมปรับอากาศ กลิ่นมะลิไทยแท้ (Siam Jasmine Reed Diffuser)",
+      "description": "ก้านไม้กระจายความหอมระดับพรีเมียม กลิ่นมะลิซ้อนสยาม หอมละมุนยาวนาน 4-6 สัปดาห์",
+      "details": "ปริมาตร: 100ml รวมก้านไม้ 6 ก้าน เหมาะสำหรับห้องขนาด 15-25 ตร.ม."
+    },
+    "en": {
+      "name": "Siam Jasmine Reed Diffuser 100ml",
+      "description": "Premium reed diffuser capturing authentic royal Thai jasmine scent. Long-lasting fragrance diffusion for 4-6 weeks.",
+      "details": "Volume: 100ml. Includes 6 fiber reeds. Recommended for rooms 15-25 sqm."
+    }
+  }
+}
+```
+
+---
+
+## 🛠️ ส่วนที่ 3: กฎสำคัญที่ LLM มักจะพลาด (Gotchas & Validation Rules)
+
+1. **Option Values ต้องตรงกับ Variant Option:**
+   - หากประกาศ `"options": [ { "name": "ขนาด", "values": ["10ml", "30ml"] } ]`
+   - ใน `variants` แต่ละตัว ค่าของ `"option1"` **ต้องเป็น "10ml" หรือ "30ml" ตรงกันทุกตัวอักษร** (ห้ามพิมพ์เป็น `"10 ml"` หรือ `"10ML"` ที่ต่างตัวพิมพ์)
+2. **ราคาและสต็อกต้องเป็นตัวเลขจริง (Numeric Type):**
+   - ถูกต้อง: `"price": 490`, `"stock": 100`
+   - ผิด: `"price": "490"`, `"price": "฿490"`
+3. **รูปภาพต้องเป็น Array:**
+   - รองรับทั้ง Array ของ URL: `["https://...", "https://..."]`
+   - หรือ Array ของ Object: `[{"url": "https://...", "order": 0}]`
+4. **Barcode ต้องไม่ซ้ำ (Unique per Variant):**
+   - สินค้าหรือตัวเลือกย่อยแต่ละชิ้นควรมีรหัส Barcode 13 หลัก (เช่น ขึ้นต้นด้วย `885...` ของประเทศไทย) ที่ไม่ซ้ำกัน เพื่อให้ใช้กับเครื่องสแกนบาร์โค้ดที่ระบบ POS ได้ทันที
+5. **Auto-Category & Brand:**
+   - สามารถระบุชื่อหมวดหมู่ (`categoryName`) และชื่อแบรนด์ (`brandName`) เป็นภาษาไทยหรืออังกฤษได้ตามต้องการ หากในระบบยังไม่มี หมวดหมู่และแบรนด์เหล่านั้นจะถูกสร้างให้อัตโนมัติ
+
+---
+
+## 🚀 ขั้นตอนการนำเข้าหลังจากได้ JSON จาก LLM
+
+1. คัดลอก JSON Array ที่ LLM ตอบกลับมา
+2. เข้าสู่ระบบ Admin ที่เมนู **Products** (`https://admin.homaroma.shop/products` หรือ URL ของ Subdomain ที่ต้องการ)
+3. กดปุ่ม **"Import JSON"** สีเขียวข้างปุ่ม Add Product
+4. วางโค้ด JSON ลงในช่อง Textarea (หรือเซฟเป็นไฟล์ `.json` แล้วกดอัปโหลด)
+5. กดปุ่ม **"ยืนยันนำเข้าสินค้า"**
+6. ระบบจะบันทึกสินค้า, สร้าง Variant, ตั้งค่าคลังสต็อก, เชื่อมโยงหมวดหมู่, และสร้าง Section หน้าบ้าน Next.js SSR ให้พร้อมใช้งานทันที!