@digiforce-nc/plugin-field-vietnam-region

Plugin cung cấp kiểu field Tỉnh/Huyện/Xã Việt Nam — tích hợp sẵn bộ dữ liệu hành chính 63 tỉnh thành với cascading picker 3 cấp, lưu trữ trong collection vietnamRegions dạng cây phân cấp.

Plugin này làm gì?

Hãy hình dung: bạn cần trường chọn địa chỉ Việt Nam (Tỉnh → Quận/Huyện → Phường/Xã) trong form. Plugin này cung cấp sẵn toàn bộ dữ liệu hành chính (63 tỉnh, 700+ huyện, 10,000+ xã) và UI cascading picker tự động lọc theo cấp cha — không cần tự xây dựng.

Ba nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Dữ liệu hành chính	Bulk load 63 tỉnh, 700+ huyện, 10,000+ xã khi install
2	Cascading picker	UI chọn 3 cấp với lazy loading theo cấp cha
3	Giá trị chuẩn hóa	`toValue` / `toString` chuyển đổi giữa code và tên đầy đủ

Kiến trúc

Tổng quan

Plugin có cả server (collection, data import, ACL) và client (cascading picker, hooks). Server quản lý dữ liệu vùng miền; client cung cấp UI chọn địa chỉ.

Luồng install

Khi install, plugin đọc 3 file JSON (provinces, districts, communes) và bulk insert vào collection vietnamRegions theo 3 cấp (63 tỉnh → 700+ huyện → 10,000+ xã).

Luồng chọn địa chỉ trên UI

Collection: vietnamRegions

Cột	Kiểu	Mô tả
`code`	STRING	Mã vùng (primary key) — ví dụ: `79` (TP.HCM)
`name`	STRING	Tên vùng — ví dụ: `Thành phố Hồ Chí Minh`
`parentCode`	STRING	Mã vùng cha (null cho level 1)
`level`	INTEGER	Cấp: 1 = tỉnh, 2 = huyện, 3 = xã

Interface: vietnamRegion

Hỗ trợ toValue (mã code → giá trị lưu trữ) và toString (mã code → tên đầy đủ "Phường X, Quận Y, TP Z").

ACL

Permission	Mô tả
`vietnamRegions:list`	Cho phép đọc danh sách vùng miền (cần cho cascading picker)

Client Hooks

Hook	Chức năng
`useVietnamRegionDataSource`	Cung cấp data source cho cascading picker
`useVietnamRegionLoadData`	Lazy load dữ liệu theo cấp cha khi user chọn

Ví dụ sử dụng

Cấu hình field vietnam region

typescript

const addressField = {
  name: 'address',
  type: 'vietnamRegion',
  interface: 'vietnamRegion',
  uiSchema: {
    type: 'array',
    title: 'Địa chỉ',
    'x-component': 'VietnamRegionCascader',
  },
};

Giá trị lưu trữ

typescript

// Giá trị lưu trong DB (array mã code)
const value = ['79', '760', '26734'];

// toString → "Phường Bến Nghé, Quận 1, TP. Hồ Chí Minh"

Thành phần client

Thành phần	Mô tả
`VietnamRegionCascader`	Cascading picker 3 cấp
`useVietnamRegionDataSource`	Hook cung cấp data source
`useVietnamRegionLoadData`	Hook lazy load theo cấp cha

Dependencies

Package	Vai trò
`@digiforce-nc/server`	Server framework — collection, ACL
`@digiforce-nc/database`	Database ORM — đăng ký field type
`@digiforce-nc/client`	Client framework — đăng ký component
`vietnam-division`	Dữ liệu hành chính Việt Nam (JSON)