Tham chiếu kỹ thuật

Collection vietnamRegions

Dữ liệu lưu trữ trong collection vietnamRegions dạng cây phân cấp:

Cột	Kiểu	Mô tả
code	STRING	Mã vùng (primary key) — ví dụ: '79'
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 hành chính: 1 = tỉnh, 2 = huyện, 3 = xã

Cấu trúc phân cấp

Level 1 (Tỉnh):     code='79', parentCode=null, name='TP. Hồ Chí Minh'
  Level 2 (Huyện):   code='760', parentCode='79', name='Quận 1'
    Level 3 (Xã):    code='26734', parentCode='760', name='Phường Bến Nghé'
    Level 3 (Xã):    code='26737', parentCode='760', name='Phường Bến Thành'
  Level 2 (Huyện):   code='761', parentCode='79', name='Quận 3'
    Level 3 (Xã):    ...

Install — Bulk Load từ JSON Data

Khi plugin install lần đầu:

plugin.install()
  → Tạo collection vietnamRegions (nếu chưa có)
  → Đọc file JSON: provinces.json, districts.json, communes.json
  → Transform dữ liệu thành format { code, name, parentCode, level }
  → Bulk INSERT vào collection vietnamRegions
  → Tổng: ~11,000+ records

Nguồn dữ liệu: package vietnam-division chứa dữ liệu hành chính chuẩn.

Thời gian install

• Bulk insert 11,000+ records mất khoảng 5-15 giây tùy database.
• Chỉ chạy một lần khi install — các lần khởi động sau không import lại.

VietnamRegionInterface — toValue / toString

Interface cung cấp hai hàm chuyển đổi:

toValue

Input: Cascading picker selection ["TP. Hồ Chí Minh", "Quận 1", "Phường Bến Nghé"]
Output: ['79', '760', '26734'] (mảng mã code để lưu DB)

toString

Input: ['79', '760', '26734'] (mảng mã code từ DB)
Output: "Phường Bến Nghé, Quận 1, TP. Hồ Chí Minh" (chuỗi hiển thị)

Client Hooks

useVietnamRegionDataSource

Cung cấp data source cho cascading picker:

Hook khởi tạo:
  → Fetch level 1 (63 tỉnh) → cache
  → Trả về tree structure cho picker

useVietnamRegionLoadData

Lazy load dữ liệu theo cấp cha:

User chọn tỉnh (code='79')
  → Hook gọi API: vietnamRegions:list?filter[parentCode]=79
  → Nhận danh sách quận/huyện thuộc TP.HCM
  → Append vào tree → picker hiển thị cấp 2

API Query

Endpoint	Filter	Kết quả
vietnamRegions:list?filter[level]=1	Level 1	63 tỉnh
vietnamRegions:list?filter[parentCode]=79	Con của tỉnh 79	Các quận/huyện TP.HCM
vietnamRegions:list?filter[parentCode]=760	Con của huyện 760	Các phường/xã Quận 1

ACL

Permission	Mô tả
vietnamRegions:list	Cho phép đọc danh sách vùng miền

Permission này cần được cấp cho tất cả role có form chứa field Vietnam Region. Nếu thiếu, cascading picker sẽ trống.