fix update Section Block

2026-06-17 21:08:24 -04:00
1 parent 996dfdabd0
commit 6f67ee6077
@@ -0,0 +1,254 @@
+# HomAroma MCP Update: `mega-showcase`
+
+เอกสารนี้สรุปผลการใช้งาน `homaroma_mcp` กับหน้า CMS `mega-showcase` เพื่อส่งต่อให้ทีม Dev ของ MCP Tool และ Backend ใช้พัฒนาต่อ
+
+## เป้าหมายงาน
+
+- ต้องการให้หน้า CMS `mega-showcase` แปลภาษาให้ครบทุก section
+- ต้องทำผ่าน MCP Tool เท่านั้น
+- ห้ามใช้ workaround ด้วยการแก้โค้ด, แก้ DB, หรือ patch ข้อมูลนอก MCP
+- ถ้า MCP ไม่รองรับบางส่วน ต้องระบุข้อจำกัดให้ชัดเจน
+
+## สิ่งที่ตรวจสอบแล้วก่อนลงมือ
+
+- ตรวจสอบหน้า dynamic page ด้วย `get_dynamic_page_detail(slug: "mega-showcase")`
+- ตรวจสอบ schema section ที่เกี่ยวข้องใน:
+  - `packages/types/index.ts`
+  - `apps/backend/src/routes/pages.ts`
+  - `apps/mcp-server/index.ts`
+- ยืนยันแล้วว่า `LocalizedStringSchema` รองรับทั้ง string และ object map ของภาษา
+- ยืนยันแล้วว่า section types บางตัวรองรับ localized payload โดยตรง
+
+## สรุปผลที่ทำสำเร็จผ่าน MCP
+
+### 1) Page translation
+
+อัปเดต translation ของหน้า `mega-showcase` สำเร็จครบ 6 ภาษา
+
+- `th`: `หน้าเมก้าโชว์เคส`
+- `en`: `Mega Showcase Page`
+- `ja`: `メガショーケースページ`
+- `zh`: `超级展示页面`
+- `vi`: `Trang Mega Showcase`
+- `ko`: `메가 쇼케이스 페이지`
+
+### 2) Product translation
+
+สินค้า `id: 16` ซึ่งอยู่ใน `PRODUCTS` section ถูกแปลครบ 6 ภาษาแล้ว
+
+- `name`
+- `description`
+- `details`
+
+Translation records ถูกบันทึกจริงในระบบและยืนยันได้จาก `get_product_detail(id: 16, lang: "all")`
+
+### 3) Sections ที่อัปเดตสำเร็จ
+
+#### Section 87 - `HERO`
+
+อัปเดตได้สำเร็จ:
+
+- `title`
+- `tagline`
+- `description`
+- `buttonText`
+
+คงค่าเดิมไว้:
+
+- `imageUrl`
+- `buttonLink`
+
+#### Section 88 - `CATEGORIES`
+
+อัปเดตได้สำเร็จ:
+
+- `title`
+- `subtitle`
+
+คงค่าเดิมไว้:
+
+- `categoryIds`
+
+#### Section 89 - `PRODUCTS`
+
+อัปเดตได้สำเร็จ:
+
+- `title`
+
+คงค่าเดิมไว้:
+
+- `type`
+- `limit`
+- `products`
+
+รายการสินค้าใน block นี้ประกอบด้วย `1, 6, 11, 16` และสินค้า `16` ถูกแปลครบแล้วในระดับ product translation
+
+#### Section 90 - `BANNER`
+
+อัปเดตได้สำเร็จ:
+
+- `title`
+
+คงค่าเดิมไว้:
+
+- `imageUrl`
+
+#### Section 91 - `TEXT`
+
+อัปเดตได้สำเร็จ:
+
+- `content`
+
+คงค่าเดิมไว้:
+
+- `textAlign`
+
+#### Section 92 - `ANNOUNCEMENT_BAR`
+
+อัปเดตได้สำเร็จ:
+
+- `slides[0]`
+- `slides[1]`
+
+#### Section 93 - `NEWSLETTER`
+
+อัปเดตได้สำเร็จ:
+
+- `title`
+- `description`
+- `buttonText`
+
+คงค่าเดิมไว้:
+
+- `showPrivacyCheckbox`
+
+#### Section 94 - `EDITORIAL_TILE`
+
+อัปเดตได้สำเร็จ:
+
+- `title`
+- `description`
+
+คงค่าเดิมไว้:
+
+- `imageUrl`
+- `imagePosition`
+
+#### Section 95 - `EDITORIAL_CAROUSEL`
+
+อัปเดตได้สำเร็จ:
+
+- `title`
+- `slides[0].category`
+- `slides[0].title`
+- `slides[0].description`
+
+คงค่าเดิมไว้:
+
+- `imageUrl`
+
+## สถานะหลังอัปเดต
+
+### ยืนยันจาก MCP ว่าบันทึกสำเร็จ
+
+- `get_product_detail(id: 16, lang: "all")` แสดง translation records ครบจริง
+- `get_dynamic_page_detail(slug: "mega-showcase")` แสดง payload ของ section ที่อัปเดตแล้วเป็น multilingual object จริง
+
+### ตัวอย่างข้อมูลที่ยืนยันได้
+
+- Hero payload เก็บเป็น object แยกภาษาแล้ว
+- Categories payload เก็บเป็น object แยกภาษาแล้ว
+- Announcement bar slides เก็บเป็น object แยกภาษาแล้ว
+- Newsletter / Editorial / Banner / Text เก็บเป็น object แยกภาษาแล้ว
+
+## Sections ที่ปิด gap แล้ว
+
+หลังจากขยาย backend validation และเพิ่ม UI/renderer ให้รองรับ payload แบบ localized แล้ว section ต่อไปนี้ใช้งาน multilingual ได้ครบในทางปฏิบัติ:
+
+- `96 - HERO_ARTICLE`
+- `97 - RICH_TEXT`
+- `98 - SCENT_NOTES_BREAKDOWN`
+- `99 - QUOTE_CALLOUT`
+- `100 - PRODUCT_CAROUSEL`
+- `101 - ACCORDION`
+- `102 - CONTACT_INFO`
+- `103 - CONTACT_FORM`
+
+### สิ่งที่ปิด gap ให้ครบ
+
+- `apps/backend/src/routes/pages.ts` รับ payload ของ section เหล่านี้ได้แล้วผ่าน validation แบบ localized-friendly
+- `apps/admin` มี form สำหรับสร้าง/แก้ block เหล่านี้แล้ว
+- `apps/spa` แสดงผล block เหล่านี้ตามภาษา active ได้แล้ว
+
+## จุดที่ยังควรยกระดับสำหรับ LLM
+
+แม้ section gap จะปิดแล้ว แต่ถ้าเป้าหมายคือทำให้ LLM ใช้งาน MCP ได้ดีที่สุด ยังมีงานที่ควรทำต่อ:
+
+### 1) เพิ่ม tool แบบเฉพาะ block
+
+ตอนนี้มี tool เฉพาะ block เพิ่มแล้ว โดยยังคง `add_page_section` และ `update_page_section` เป็น fallback:
+
+- `update_hero_article`
+- `update_rich_text`
+- `update_scent_notes_breakdown`
+- `update_quote_callout`
+- `update_product_carousel`
+- `update_accordion`
+- `update_contact_info`
+- `update_contact_form`
+
+ถ้าจะเพิ่มฝั่ง create แบบเฉพาะ block ต่อไป ค่อยขยายเป็นคู่ `add_*` เพิ่มจากชุดนี้ได้อีกชั้น
+
+### 2) ทำ structured read-back
+
+ตอนนี้ update tools คืนข้อมูลแบบ normalize แล้วใน JSON response
+
+ถ้าจะยกระดับต่อ ควรแยกให้ชัดขึ้นอีก:
+
+- field ไหนถูก merge
+- field ไหนถูก overwrite
+- payload สุดท้ายหน้าตาเป็นอะไร
+
+### 3) ทำ error ให้ LLM-friendly
+
+validation error ควรบอก:
+
+- `field`
+- `expected`
+- `got`
+- `suggestion`
+
+> ตอนนี้ backend/MCP ยังคืน error เป็นข้อความรวมอยู่เป็นหลัก จึงยังมีช่องให้ขยายต่อในรอบถัดไป
+
+### 4) ชัดเจนเรื่อง supported shape
+
+tool description ควรบอกตัวอย่าง payload ที่คาดหวังสำหรับแต่ละ block ให้ชัดขึ้น เพื่อให้ LLM ไม่ต้องเดาจาก schema ล้วน ๆ
+
+## ผลกระทบกับ user-facing CMS
+
+ตอนนี้หน้า `mega-showcase` สามารถแปล section หลักได้ครบมากขึ้นแล้ว และ block ที่เคยค้างอยู่ฝั่ง data shape ก็ปิด gap ไปแล้ว
+
+สิ่งที่เหลือเป็นเรื่องของ UX สำหรับผู้ใช้เครื่องมือและความชัดเจนของ MCP tool layer มากกว่าความสามารถในการ render จริง
+
+## จุดที่ควรทดสอบเพิ่ม
+
+- เปิดหน้า `mega-showcase` ใน SPA แล้วสลับภาษาเพื่อตรวจ render จริง
+- ตรวจว่าภาษา active ถูก resolve จาก object map ใน section ที่อัปเดตแล้ว
+- ตรวจว่า product `16` แสดงชื่อ/description/details ตามภาษาที่เลือกจริง
+- ตรวจว่า block ใหม่ทั้ง 8 แบบ บันทึกและแก้ไขได้ต่อเนื่องผ่าน admin แล้วไม่ทำให้หน้า error เมื่อสลับภาษา
+
+## รายการ Tools ที่เกี่ยวข้อง
+
+- `get_dynamic_page_detail`
+- `update_page_translation`
+- `update_page_section`
+- `get_product_detail`
+- `update_product_translation`
+
+## บทสรุปสำหรับทีม Dev
+
+MCP Tool ของ HomAroma ตอนนี้ใช้งานได้จริงมากขึ้นสำหรับการแปลหน้า CMS `mega-showcase`
+
+gap ของ section ที่เคยค้างอยู่ถูกปิดด้วยการขยาย backend validation, admin forms, และ spa renderer แล้ว
+
+ถ้าเป้าหมายถัดไปคือให้ LLM ใช้งาน MCP ได้ “ดีมาก” ไม่ใช่แค่ “ทำงานได้” ควรเพิ่ม dedicated tools, structured read-back, และ error messages ที่สื่อกับโมเดลได้ตรงขึ้น