Giao diện
@digiforce-nc/plugin-map
Plugin hiển thị dữ liệu địa lý trên bản đồ (Map View) và cung cấp các field type địa lý (point, polygon, lineString, circle) - tích hợp Google Maps với cấu hình API key lưu trong database.
Plugin này làm gì?
Map plugin mở rộng hệ thống theo hai hướng: (1) thêm field types cho dữ liệu địa lý - cho phép lưu tọa độ, vùng, đường, hình tròn vào bất kỳ collection nào; (2) cung cấp Map block hiển thị records trên bản đồ Google Maps. Cấu hình API key được lưu trong database, quản lý qua resource riêng.
Ba nhiệm vụ chính
| # | Nhiệm vụ | Chi tiết |
|---|---|---|
| 1 | Geo field types | Thêm point, polygon, lineString, circle vào hệ thống field |
| 2 | Map block | Hiển thị records trên bản đồ Google Maps |
| 3 | Cấu hình provider | Lưu API key Google Maps trong database, quản lý qua API |
Kiến trúc
Tổng quan
Plugin có server (field types, value parsers, map configuration resource) và client (map block, field widgets, Google Maps integration):
| Tầng | Vai trò | Thành phần |
|---|---|---|
| Client UI | Render bản đồ, field widgets | MapBlockWidget, field widgets |
| Server API | Cấu hình map, field types | map-configuration, value parsers |
| Database | Lưu API key, geo data | mapConfiguration, geo fields |
| Google Maps | Map rendering engine | @googlemaps/js-api-loader |
API endpoints
| Endpoint | Method | Mô tả |
|---|---|---|
map-configuration:get | GET | Lấy cấu hình map provider (API key, type) |
map-configuration:set | POST | Cập nhật cấu hình map provider |
Admin cấu hình API key qua trang Settings > Map Configuration. Client gọi map-configuration:get để lấy key trước khi load Google Maps API.
Database
Bảng mapConfiguration
| Cột | Kiểu | Mô tả |
|---|---|---|
type | string | Loại map provider (google) |
accessKey | string | API key của map provider |
securityJsCode | string | Mã bảo mật JavaScript (nếu cần) |
Field types địa lý
Plugin đăng ký 4 field type mới vào hệ thống:
| Field Type | Giá trị lưu trữ | Ví dụ |
|---|---|---|
| point | [lng, lat] | [106.6297, 10.8231] (TP.HCM) |
| polygon | [[lng, lat], ...] | Mảng tọa độ tạo thành vùng khép kín |
| lineString | [[lng, lat], ...] | Mảng tọa độ tạo thành đường |
| circle | { center: [lng, lat], radius: number } | Tâm + bán kính (mét) |
Mỗi field type có value parser tương ứng trên server để chuyển đổi dữ liệu geo giữa client format và storage format.
Luồng hiển thị Map block
Tính năng
| Tính năng | Mô tả |
|---|---|
| Point field | Chọn vị trí trên bản đồ, lưu tọa độ |
| Polygon field | Vẽ vùng đa giác trên bản đồ |
| LineString field | Vẽ đường trên bản đồ |
| Circle field | Vẽ hình tròn (tâm + bán kính) |
| Map block | Hiển thị records trên bản đồ |
| Marker clustering | Gom nhóm markers khi zoom xa |
| Popup detail | Click marker hiển thị thông tin record |
| Provider config | Quản lý API key trong Settings |
| Field widgets | Input widget với map picker cho từng geo type |
Thành phần client
| Thành phần | Mô tả |
|---|---|
MapBlockWidget | Widget chính đăng ký Map block |
GoogleMaps | Component bọc Google Maps API |
MapBlockInitializer | Đăng ký vào menu "Add block" |
MapDesigner | Designer: cấu hình geo field, zoom, center |
GeoFieldWidgets | Input/display widgets cho point, polygon, lineString, circle |
MapConfigurationPage | Trang Settings > Map Configuration |
Dependencies
| Package | Vai trò |
|---|---|
@digiforce-nc/client | Client framework (peer) |
@digiforce-nc/server | Server framework (peer) |
@digiforce-nc/database | Database ORM (peer) |
@googlemaps/js-api-loader | Tải Google Maps JavaScript API |