Geo Module

Mục đích

Geo là module hạ tầng dùng chung để tra cứu dữ liệu địa lý: quốc gia, địa điểm, subdivision và trạng thái vị trí người dùng. Nó đóng vai trò data provider hơn là một màn hình nghiệp vụ độc lập.

Quy mô

• 0 FE pages
• 6 FE widgets dùng chung (AddressInput, AddressDisplay, ProvinceSelect, DistrictSelect, WardSelect, GMapAutocomplete)
• 1 composition (useGeo)
• 1 store (useGeoStore)
• 1 GraphQL file
• 3 function/backend entry points (search_place, search_subdivision, search_user_position_status)

Actors & Permissions

Nhóm chức năng	Scope
Shared geo lookup	Dùng gián tiếp bởi các module cần country/place/subdivision

Feature Groups

Group	Mô tả
Geo Lookup & Cache	useGeo.ts query country, cache vào useGeoStore, hỗ trợ filter local theo keywords
Address Compose	AddressInput ghép province + ward + street, AddressDisplay render địa chỉ đã lưu
Subdivision Search	ProvinceSelect / DistrictSelect / WardSelect query GraphQL và hỗ trợ mapping dữ liệu cũ
Map Autocomplete	GMapAutocomplete bọc Google Places Autocomplete để nhập place từ bản đồ

Liên kết Modules

• user — địa chỉ/account/contact book
• crm — customer address, reference address
• settings — region/subdivision config
• ecommerce — shipping/billing/place-related data

Backend Services

Service	Vai trò
geo-api	Actions/place search, subdivision lookup
controller (Hasura)	Geo functions, seeded data

Databases

DB	Key functions / seeds
geo	search_place, search_subdivision, search_user_position_status, country seeds

Đặc điểm kiến trúc

• Không có page độc lập trong FE hiện tại; module này tồn tại để cung cấp composition/store dùng chung.
• useGeo.ts ưu tiên cache local trong store và chỉ refresh từ network khi cần.
• Dữ liệu nền được seed sẵn từ countries.sql và vietnam_geo.sql.