homaroma/BUSINESS_ANALYTICS_MAPS_PLAN.md

แผนการพัฒนาและคู่มือสร้างแผนที่ Malaysia & Vietnam Map

Platform capability plan: Geographic coverage, data availability, and analytics configuration are platform capabilities enabled per tenant. HomAroma is the reference tenant. See docs/PLATFORM_OVERVIEW.md. สำหรับเมนู Business Analytics บนระบบ DBK Platform Admin (Multi-tenant & Multi-region)

เอกสารนี้รวบรวมรายละเอียด แหล่งข้อมูล Open-source Repositories สำหรับดาวน์โหลดไฟล์ GeoJSON สถาปัตยกรรมทางเทคนิค และแผนขั้นตอนการนำไปพัฒนาต่อยอดให้เหมือนกับ Omnichannel Sales Map (แผนที่ประเทศไทย) เดิม

---

1. สถาปัตยกรรมเดิมของ Thailand Sales Map (Reference Architecture)

ในระบบปัจจุบัน แผนที่ประเทศไทย (apps/admin/src/components/tiktok-map/ThailandMapSvg.tsx) และหน้าหลัก (OmnichannelSalesMapPage.tsx) มีกลไกการทำงานดังนี้:

• Rendering Engine: ใช้ SVG Vector + d3-geo
• Projection: ใช้ d3Geo.geoMercator().fitExtent([[padding, padding], [width - padding, height - padding]], geoData)
  • ข้อดี: ฟังก์ชัน fitExtent จะคำนวณและปรับขนาดอัตราส่วน (Scale & Center) ของแผนที่ให้พอดีกับ Viewport SVG โดยอัตโนมัติ ไม่ว่าแผนที่จะมีรูปร่างยาว (เช่น เวียดนาม) หรือกว้าง (เช่น มาเลเซีย)
• Interactive Features:
  • Pan & Zoom: ควบคุมผ่าน SVG transform matrix (scale(...) translate(...)) มีปุ่ม Zoom In, Zoom Out และ Reset
  • Hover Tooltip: ตรวจจับตำแหน่งเมาส์และแสดงชื่อพื้นที่ (EN / Localized)
  • Choropleth Color: คำนวณความเข้มของสีตามค่าข้อมูลสถิติ (Min-Max)
  • Selection: คลิกเพื่อเลือกพื้นที่สำหรับดูสถิติเจาะลึก
• ที่เก็บไฟล์แผนที่: เก็บใน apps/admin/public/maps/ โหลดผ่าน fetch('/maps/...')

---

2. แหล่งข้อมูล GeoJSON Open-Source (Git Repositories)

สำหรับการทำ Malaysia Map และ Vietnam Map สามารถดาวน์โหลดไฟล์ Boundary ได้จาก Repository ที่คัดสรรแล้ว ดังต่อไปนี้:

🇲🇾 Malaysia (มาเลเซีย)

โครงสร้างการปกครอง: 13 รัฐ (States) + 3 ดินแดนสหพันธ์ (Federal Territories)

1. nullifye/malaysia.geojson (แนะนำสูงสุด ⭐)
   • ไฟล์หลัก: malaysia.state.geojson (ระดับรัฐ)
   • ไฟล์รอง (อำเภอ): malaysia.district.geojson (ระดับอำเภอ/เขต)
   • จุดเด่น: สะอาด น้ำหนักไฟล์เบา พิกัดมาตรฐาน WGS84 นำมาใส่ SVG ผ่าน d3-geo ได้ทันที
2. mptwaktusolat/jakim.geojson
   • ไฟล์หลัก: malaysia.state.geojson
   • จุดเด่น: มีการแมปโซนมาตรฐาน
3. wmgeolab/geoBoundaries (Malaysia)
   • จุดเด่น: ฐานข้อมูลระดับโลกที่มีการ Verify มาตรฐานขอบเขต (ADM1: รัฐ, ADM2: เขต)

---

🇻🇳 Vietnam (เวียดนาม)

โครงสร้างการปกครอง: 63 จังหวัดและเทศบาลนครส่วนกลาง (Provinces & Centrally-governed Municipalities)

1. thanglequoc/vietnamese-provinces-database (แนะนำสูงสุด ⭐)
   • โฟลเดอร์ไฟล์: json/geojson/
   • ไฟล์หลัก: provinces.geojson หรือ vietnam_provinces.geojson
   • ไฟล์รอง (อำเภอ): districts.geojson
   • จุดเด่น: เป็น Repo ฐานข้อมูลการปกครองเวียดนามที่สมบูรณ์และอัปเดตที่สุด มีรหัส Code และชื่อ 2 ภาษา (VI / EN)
2. nguyenduy1133/Free-GIS-Data
   • จุดเด่น: มีไฟล์ GeoJSON ระดับจังหวัดที่ถูก Simplify เส้นขอบให้เบาและเหมาะกับการเรนเดอร์ใน Web Browser
3. wmgeolab/geoBoundaries (Vietnam)
   • จุดเด่น: ข้อมูล Boundary มาตรฐานสากลระดับ ADM1

---

3. แผนขั้นตอนการลงมือพัฒนา (Implementation Roadmap)

Phase 1: เตรียมข้อมูลแผนที่ (Static Assets)

1. นำไฟล์ GeoJSON ไปวางไว้ที่:
   • apps/admin/public/maps/malaysia-states.json
   • apps/admin/public/maps/vietnam-provinces.json
2. ตรวจสอบ Property ภายใน GeoJSON เช่น ชื่อฟิลด์ name, code หรือชื่อภาษาอังกฤษ/ท้องถิ่น เพื่อนำมาแสดงบน Tooltip

Phase 2: สร้าง Map Component & Utility Functions

1. สร้าง Utility สำหรับแปลงชื่อหรือจัดกลุ่มโซน (ถ้าต้องการ):
   • apps/admin/src/utils/malaysiaGeoUtils.ts
   • apps/admin/src/utils/vietnamGeoUtils.ts
2. สร้าง Vector Map Component:
   • apps/admin/src/components/analytics/MalaysiaMapSvg.tsx
   • apps/admin/src/components/analytics/VietnamMapSvg.tsx (หรือสร้าง Reusable Component เช่น GenericCountryMapSvg.tsx ที่รับ mapUrl และ property identifier)

Phase 3: สร้างหน้า Page และเชื่อมต่อเมนูใน Sidebar

1. สร้างหน้า Page (เบื้องต้นเป็นแผนที่เปล่าและตารางรายชื่อรัฐ/จังหวัด):
   • apps/admin/src/pages/analytics/MalaysiaSalesMapPage.tsx
   • apps/admin/src/pages/analytics/VietnamSalesMapPage.tsx
2. อัปเดต Router ใน apps/admin/src/App.tsx:
   • Path: /business-analytics/malaysia-map
   • Path: /business-analytics/vietnam-map
3. เพิ่มเมนูใน apps/admin/src/components/Sidebar.tsx:

   const BUSINESS_ANALYTICS_MENU = [
     { icon: Globe2, label: t('nav.omnichannelSalesMap', 'Omnichannel Sales Map'), to: '/business-analytics/sales-map' },
     { icon: Package, label: t('nav.productSalesMap', 'Product Sales Map'), to: '/business-analytics/sales-map-products' },
     { icon: MapPin, label: t('nav.malaysiaSalesMap', 'Malaysia Sales Map'), to: '/business-analytics/malaysia-map' },
     { icon: MapPin, label: t('nav.vietnamSalesMap', 'Vietnam Sales Map'), to: '/business-analytics/vietnam-map' },
   ]
   

4. เพิ่มคำแปลใน locales/th/translation.json และ locales/en/translation.json

Phase 4: ระบบเจาะลึกระดับอำเภอ/เขต (District Drill-down Modal) - [COMPLETED]

• ดาวน์โหลดและจัดเตรียมข้อมูล GeoJSON ระดับอำเภอ:
  • apps/admin/public/maps/malaysia-districts.json (160 Daerah)
  • apps/admin/public/maps/vietnam-districts.json (708 Quận/Huyện/Thị xã)
• สร้าง Component Modal:
  • apps/admin/src/components/analytics/MalaysiaDistrictModal.tsx
  • apps/admin/src/components/analytics/VietnamDistrictModal.tsx
• ติดตั้งปุ่ม "เจาะลึกรายอำเภอ (View Districts)" ทั้งในกล่องรายละเอียดของรัฐ/จังหวัด และในตารางรายชื่อ สามารถคลิกเพื่อเปิด Modal ซูมดูแผนที่อำเภอแบบเดียวกับ TikTok Thai Sales Map ได้ทันที

Phase 5: เชื่อมโยงข้อมูลยอดขายในอนาคต (Future Backend Integration)

• เมื่อมีข้อมูลการขายของมาเลเซียและเวียดนาม (เช่น Shopee MY, TikTok MY/VN, Lazada VN) สามารถเพิ่ม Endpoint ใน Backend:
  • GET /business-analytics/sales-map?country=MY
  • GET /business-analytics/sales-map?country=VN
• แมปรหัสรัฐ/จังหวัดเข้ากับรหัสบน GeoJSON เพื่อแสดงความเข้มของสีและยอดขายแบบ Real-time ทั้งระดับรัฐ/จังหวัด และระดับอำเภอ/เขต