109 lines
9.9 KiB
Markdown
109 lines
9.9 KiB
Markdown
# แผนการพัฒนาและคู่มือสร้างแผนที่ 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 ทั้งระดับรัฐ/จังหวัด และระดับอำเภอ/เขต
|