# แผนการพัฒนาและคู่มือสร้างแผนที่ 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`](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](https://github.com/nullifye/malaysia.geojson)** *(แนะนำสูงสุด ⭐)*
   - **ไฟล์หลัก:** `malaysia.state.geojson` (ระดับรัฐ)
   - **ไฟล์รอง (อำเภอ):** `malaysia.district.geojson` (ระดับอำเภอ/เขต)
   - **จุดเด่น:** สะอาด น้ำหนักไฟล์เบา พิกัดมาตรฐาน WGS84 นำมาใส่ SVG ผ่าน `d3-geo` ได้ทันที
2. **[mptwaktusolat/jakim.geojson](https://github.com/mptwaktusolat/jakim.geojson)**
   - **ไฟล์หลัก:** `malaysia.state.geojson`
   - **จุดเด่น:** มีการแมปโซนมาตรฐาน
3. **[wmgeolab/geoBoundaries (Malaysia)](https://github.com/wmgeolab/geoBoundaries)**
   - **จุดเด่น:** ฐานข้อมูลระดับโลกที่มีการ Verify มาตรฐานขอบเขต (ADM1: รัฐ, ADM2: เขต)

---

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

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