@isofh/chuyen-doi-dia-chi-2-cap 1.0.0 → 1.0.2

package/README.md

@@ -1,11 +1,11 @@
 # @isofh/chuyen-doi-dia-chi-2-cap
 
-Package chuẩn hóa địa chỉ hành chính cũ sang format 2 cấp mới, kèm theo bộ dữ liệu `dataXa.json`.
+Package chuẩn hóa địa chỉ hành chính sang format 2 cấp, kèm theo bộ dữ liệu `dataXa.json`.
 
 ## Mục tiêu
 
-- đóng gói `dataXa.json` để có thể dùng lại giữa nhiều dự án
-- tách logic `convertDiaChiMoi` khỏi component UI
+- cung cấp bộ dữ liệu hành chính dùng cho chuẩn hóa địa chỉ
+- cung cấp các hàm chuẩn hóa, kiểm tra xã hợp lệ và bóc địa chỉ từ QR CCCD
 - đóng gói thành npm package để dùng lại giữa nhiều dự án
 
 ## Cài đặt
@@ -39,19 +39,22 @@ const {
   extractAndConvertCccdAddress,
 } = require("@isofh/chuyen-doi-dia-chi-2-cap");
 
-const output = convertDiaChiMoi("Xuân Thành, Xuân Lộc, Đồng Nai");
-console.log(output);
-
 const verifyResult = verifyXaName("Xuân Thành", "Đồng Nai");
 console.log(verifyResult.isValid);
 
 const splitResult = splitAddressByValidXa("Phú Thạch, Phú Trung, Đồng Nai", "Đồng Nai");
 console.log(splitResult);
 
-const cccdResult = extractAndConvertCccdAddress(
-  "079306006606||Vũ Ngọc Như Lan|27102006|Nữ|19/20 Tổ 71, Khu, Phố 6, Phường 06, Tân Bình, TP.Hồ Chí Minh|26012022"
-);
-console.log(cccdResult);
+(async () => {
+  const output = await convertDiaChiMoi("Xuân Thành, Xuân Lộc, Đồng Nai");
+  console.log(output);
+
+  const cccdResult = await extractAndConvertCccdAddress(
+    "079306006606||Vũ Ngọc Như Lan|27102006|Nữ|19/20 Tổ 71, Khu, Phố 6, Phường 06, Tân Bình, TP.Hồ Chí Minh|26012022"
+  );
+  console.log(cccdResult.soNha);
+  console.log(cccdResult.diaChi);
+})();
 ```
 
 ## Input hỗ trợ
@@ -75,17 +78,20 @@ const fullAddress = "4A Lê Thánh Tông, Cửa Nam, Hà Nội";
 // Caller tự chuẩn hóa/tách phần hành chính trước
 const administrativeAddress = "Cửa Nam, Hà Nội";
 
-const output = convertDiaChiMoi(administrativeAddress);
+(async () => {
+  const output = await convertDiaChiMoi(administrativeAddress);
+  console.log(output);
+})();
 ```
 
 ## Nguyên tắc xử lý
 
-Logic hiện tại bám theo bộ quy tắc chuyển đổi địa chỉ đang dùng trong hệ thống HIS.
+Logic hiện tại bám theo bộ quy tắc chuẩn hóa địa chỉ hành chính 2 cấp.
 
 Thứ tự xử lý chính:
 
 1. Match tỉnh trước bằng tên mới hoặc tên cũ trong `dsTinh`.
-2. Nếu input là 3 vế thì ưu tiên hiểu là `xã cũ, huyện cũ, tỉnh cũ` và chỉ giữ xã + tỉnh để đưa về 2 cấp.
+2. Nếu input là 3 vế thì ưu tiên hiểu là `xã/phường, huyện/quận, tỉnh/thành` và chỉ giữ xã + tỉnh để đưa về 2 cấp.
 3. Tìm xã/phường theo thứ tự từ chặt đến lỏng:
    - match chính xác tên xã hiện tại
    - match trong `satNhapTu`
@@ -97,9 +103,11 @@ Thứ tự xử lý chính:
 ```js
 const { convertDiaChiMoi } = require("@isofh/chuyen-doi-dia-chi-2-cap");
 
-console.log(convertDiaChiMoi("Xuân Thành, Xuân Lộc, Đồng Nai"));
-console.log(convertDiaChiMoi("Cửa Nam, Hà Nội"));
-console.log(convertDiaChiMoi(["Phú Thạch", "Phú Trung", "Đồng Nai"]));
+(async () => {
+  console.log(await convertDiaChiMoi("Xuân Thành, Xuân Lộc, Đồng Nai"));
+  console.log(await convertDiaChiMoi("Cửa Nam, Hà Nội"));
+  console.log(await convertDiaChiMoi(["Phú Thạch", "Phú Trung", "Đồng Nai"]));
+})();
 ```
 
 ## Verify tên xã
@@ -155,11 +163,11 @@ globalThis.splitAddressByValidXa;
 globalThis.extractAndConvertCccdAddress;
 ```
 
-Mục đích là để một package khác như `mainam-react-native-string-utils` có thể tận dụng runtime function này mà không phải tạo dependency ngược.
+Mục đích là để caller có thể tận dụng các helper này ở runtime mà không cần tự truyền tay qua nhiều lớp.
 
 ## Trích xuất địa chỉ căn cước
 
-`parseCccdQrString` dùng để parse chuỗi QR CCCD dạng đang được app HIS quét vào, ví dụ:
+`parseCccdQrString` dùng để parse chuỗi QR CCCD dạng pipe, ví dụ:
 
 ```txt
 079306006606||Vũ Ngọc Như Lan|27102006|Nữ|19/20 Tổ 71, Khu, Phố 6, Phường 06, Tân Bình, TP.Hồ Chí Minh|26012022
@@ -183,21 +191,39 @@ console.log(extractCccdAddressText("079306006606||Vũ Ngọc Như Lan|27102006|N
 - parse theo logic `toAddress`
 - convert phần địa chỉ hành chính về format mới bằng `convertDiaChiMoi`
 - trả về object đúng shape của `String.prototype.toAddress`
+- giữ lại `soNha` ở top-level output
+- bổ sung `data.soNha` và `data.diaChiGoc` để caller có thể dùng lại dữ liệu trước và sau bước convert
 
 Ví dụ:
 
 ```js
 const { extractAndConvertCccdAddress } = require("@isofh/chuyen-doi-dia-chi-2-cap");
 
-console.log(
-  extractAndConvertCccdAddress(
-    "079306006606||Vũ Ngọc Như Lan|27102006|Nữ|19/20 Tổ 71, Khu, Phố 6, Phường 06, Tân Bình, TP.Hồ Chí Minh|26012022"
-  )
-);
+(async () => {
+  console.log(
+    await extractAndConvertCccdAddress(
+      "079306006606||Vũ Ngọc Như Lan|27102006|Nữ|19/20 Tổ 71, Khu, Phố 6, Phường 06, Tân Bình, TP.Hồ Chí Minh|26012022"
+    )
+  );
+})();
 ```
 
 Nếu không truyền `ngayCap`, hàm sẽ tự lấy ngày cấp từ field QR CCCD nếu chuỗi input đúng format pipe.
 
+Ví dụ output rút gọn:
+
+```js
+{
+  soNha: "19/20 Tổ 71, Khu, Phố 6",
+  diaChi: "Tân Hòa, Hồ Chí Minh",
+  data: {
+    soNha: "19/20 Tổ 71, Khu, Phố 6",
+    diaChiGoc: "06, Tân Bình, TP.Hồ Chí Minh",
+    convertedDiaChi: "Tân Hòa, Hồ Chí Minh"
+  }
+}
+```
+
 ## Tách số nhà dựa trên xã hợp lệ
 
 Ý tưởng của hàm `splitAddressByValidXa` là:

package/dataXa.json

@@ -23849,7 +23849,7 @@
         "huyen": "xuanloc",
         "satNhapTu": [
           { "ten": "Suối Cao", "timKiem": "suoicao" },
-          { "ten": "Xuân Thành", "timKiem": "xuanthanh", "huyen":"xuanloc" }
+          { "ten": "Xuân Thành", "timKiem": "xuanthanh", "huyen": "xuanloc" }
         ]
       },
       {
@@ -24313,6 +24313,7 @@
     "timKiem": "hochiminh",
     "dsTinh": [
       { "ten": "Bà Rịa - Vũng Tàu", "timKiem": "baria-vungtau" },
+      { "ten": "BR-VT", "timKiem": "br-vt" },
       { "ten": "Bình Dương", "timKiem": "binhduong" }
     ],
     "dsXa": [
@@ -26887,8 +26888,8 @@
         "ten": "Mỹ Tho",
         "timKiem": "mytho",
         "satNhapTu": [
-          { "ten": "1", "timKiem": "1" },
-          { "ten": "2", "timKiem": "2" },
+          { "ten": "1", "timKiem": "1", "huyen": "mytho" },
+          { "ten": "2", "timKiem": "2", "huyen": "mytho" },
           { "ten": "Tân Long", "timKiem": "tanlong" }
         ]
       },
@@ -26914,7 +26915,7 @@
         "ten": "Thới Sơn",
         "timKiem": "thoison",
         "satNhapTu": [
-          { "ten": "6", "timKiem": "6" },
+          { "ten": "6", "timKiem": "6", "huyen": "mytho" },
           { "ten": "Thới Sơn", "timKiem": "thoison" }
         ]
       },
@@ -26922,7 +26923,7 @@
         "ten": "Trung An",
         "timKiem": "trungan",
         "satNhapTu": [
-          { "ten": "10", "timKiem": "10" },
+          { "ten": "10", "timKiem": "10", "huyen": "mytho" },
           { "ten": "Trung An", "timKiem": "trungan" },
           { "ten": "Phước Thạnh", "timKiem": "phuocthanh" }
         ]
@@ -26931,8 +26932,8 @@
         "ten": "Gò Công",
         "timKiem": "gocong",
         "satNhapTu": [
-          { "ten": "1", "timKiem": "1" },
-          { "ten": "5", "timKiem": "5" },
+          { "ten": "1", "timKiem": "1", "huyen": "gocong" },
+          { "ten": "5", "timKiem": "5", "huyen": "gocong" },
           { "ten": "Long Hòa", "timKiem": "longhoa" }
         ]
       },
@@ -26940,7 +26941,7 @@
         "ten": "Long Thuận",
         "timKiem": "longthuan",
         "satNhapTu": [
-          { "ten": "2", "timKiem": "2" },
+          { "ten": "2", "timKiem": "2", "huyen": "gocong" },
           { "ten": "Long Thuận", "timKiem": "longthuan" }
         ]
       },
@@ -26965,8 +26966,8 @@
         "ten": "Mỹ Phước Tây",
         "timKiem": "myphuoctay",
         "satNhapTu": [
-          { "ten": "1", "timKiem": "1" },
-          { "ten": "3", "timKiem": "3" },
+          { "ten": "1", "timKiem": "1", "huyen": "cailay" },
+          { "ten": "3", "timKiem": "3", "huyen": "cailay" },
           { "ten": "Mỹ Hạnh Trung", "timKiem": "myhanhtrung" },
           { "ten": "Mỹ Phước Tây", "timKiem": "myphuoctay" }
         ]
@@ -26975,7 +26976,7 @@
         "ten": "Thanh Hòa",
         "timKiem": "thanhhoa",
         "satNhapTu": [
-          { "ten": "2", "timKiem": "2" },
+          { "ten": "2", "timKiem": "2", "huyen": "cailay" },
           { "ten": "Tân Bình", "timKiem": "tanbinh" },
           { "ten": "Thanh Hòa", "timKiem": "thanhhoa" }
         ]

package/index.js

@@ -1,6 +1,39 @@
 require("mainam-react-native-string-utils");
 
-const dataXa = require("./dataXa.json");
+let dataXa = null;
+let dataXaPromise = null;
+
+// Resolve global runtime để hỗ trợ các hook override giống contract gốc ở repo cũ.
+const getGlobalTarget = () =>
+  typeof globalThis !== "undefined"
+    ? globalThis
+    : typeof window !== "undefined"
+      ? window
+      : typeof global !== "undefined"
+        ? global
+        : null;
+
+// Nạp dataset hành chính ở thời điểm cần dùng thay vì load ngay khi require package.
+const getDataXaSync = () => {
+  if (!dataXa) {
+    dataXa = require("./dataXa.json");
+  }
+
+  return dataXa;
+};
+
+// Giữ contract async của hàm gốc để caller có thể await trước khi convert.
+const loadDataXa = async (customDataXa) => {
+  if (customDataXa) {
+    return customDataXa;
+  }
+
+  if (!dataXaPromise) {
+    dataXaPromise = Promise.resolve().then(() => getDataXaSync());
+  }
+
+  return dataXaPromise;
+};
 
 // Dùng helper của string-utils để tạo key tìm kiếm không dấu, không khoảng trắng.
 const createUniqueText = (text = "") => `${text ?? ""}`.createUniqueText();
@@ -164,7 +197,7 @@ const dedupeMatches = (matches = []) => {
 // Kiểm tra một tên xã có hợp lệ trong phạm vi tỉnh đích hay không.
 const verifyXaName = (tenXa, tinhOrOptions, maybeOptions) => {
   const { tinh, options } = getVerifyOptions(tinhOrOptions, maybeOptions);
-  const sourceDataXa = options.dataXa || dataXa;
+  const sourceDataXa = options.dataXa || getDataXaSync();
   const normalizedXa = normalizeAdministrativeCode(tenXa);
   const normalizedTinh = normalizeAdministrativeCode(tinh);
   const matchedProvinces = getProvinceCandidates(tinh, sourceDataXa);
@@ -220,7 +253,7 @@ const verifyXaName = (tenXa, tinhOrOptions, maybeOptions) => {
 // Tìm xã hợp lệ đầu tiên trong chuỗi địa chỉ để tách các vế đứng trước thành `soNha`.
 const splitAddressByValidXa = (input, tinhOrOptions, maybeOptions) => {
   const { tinh, options } = getVerifyOptions(tinhOrOptions, maybeOptions);
-  const sourceDataXa = options.dataXa || dataXa;
+  const sourceDataXa = options.dataXa || getDataXaSync();
   const parts = splitAddressParts(input);
 
   if (!parts.length) {
@@ -283,18 +316,21 @@ const splitAddressByValidXa = (input, tinhOrOptions, maybeOptions) => {
 };
 
 // Bóc địa chỉ từ text căn cước rồi trả về output theo đúng contract của `String.prototype.toAddress`.
-const extractAndConvertCccdAddress = (input, ngayCap, options = {}) => {
+const extractAndConvertCccdAddress = async (input, ngayCap, options = {}) => {
   const sourceText = `${input ?? ""}`;
   const parsedQr = parseCccdQrString(sourceText);
   const extractedText = extractCccdAddressText(sourceText);
   const issueDate = normalizeCccdIssueDate(ngayCap || parsedQr?.ngayCap);
   const parsedAddress = extractedText.toAddress({ ngayCap: issueDate, verifyXaName });
+  const soNha = parsedAddress?.soNha || "";
+  const diaChiGoc = parsedAddress?.diaChi || "";
   const convertedDiaChi = parsedAddress?.diaChi
-    ? convertDiaChiMoi(parsedAddress.diaChi, options)
+    ? await convertDiaChiMoi(parsedAddress.diaChi, options)
     : "";
 
   return {
     ...(parsedAddress || {}),
+    soNha,
     diaChi: convertedDiaChi,
     data: {
       ...(parsedAddress?.data || {}),
@@ -302,6 +338,8 @@ const extractAndConvertCccdAddress = (input, ngayCap, options = {}) => {
       cccdFields: parsedQr?.fields || [],
       extractedText,
       issueDate,
+      soNha,
+      diaChiGoc,
       convertedDiaChi,
     },
   };
@@ -310,16 +348,54 @@ const extractAndConvertCccdAddress = (input, ngayCap, options = {}) => {
 /**
  * Nghiệp vụ chuẩn hóa địa chỉ hành chính cũ về format 2 cấp mới.
  *
- * Logic phần này được bê ra từ repo cũ, chỉ thay phần lấy dữ liệu sang `dataXa` local
- * và giữ khả năng override bằng `options.dataXa` để tiện test/publish package.
+ * Đầu vào chấp nhận cả chuỗi lẫn mảng, thường gặp các dạng:
+ * - `Xã/Phường, Tỉnh/Thành`
+ * - `Xã/Phường cũ, Quận/Huyện cũ, Tỉnh/Thành cũ`
+ * - Một số case chỉ có 1 vế nhưng thực chất là tên xã/phường.
+ *
+ * Quy tắc chung:
+ * - Nếu đầu vào là 3 cấp thì chỉ giữ xã và tỉnh để đưa hệ thống về format 2 cấp.
+ * - Tỉnh được match trước, hỗ trợ cả tên tỉnh mới lẫn tỉnh cũ trong `dsTinh`.
+ * - Nếu không match được tỉnh thì trả nguyên dữ liệu cũ để tránh đổi sai địa chỉ.
+ * - Sau khi xác định được tỉnh, xã/phường sẽ được tìm theo thứ tự ưu tiên từ chặt đến lỏng.
+ *
+ * Thứ tự resolve xã/phường:
+ * 1. Case đặc biệt chỉ có 1 vế nhưng thực chất là tên xã trong tỉnh vừa match.
+ * 2. Match chính xác tên xã/phường hiện tại, ưu tiên cùng huyện cũ nếu đầu vào có huyện.
+ * 3. Match chính xác trong danh sách `satNhapTu`, vẫn ưu tiên cùng huyện cũ nếu có.
+ * 4. Nếu chưa ra kết quả thì match gần đúng trong `satNhapTu` và bỏ điều kiện huyện.
+ * 5. Cuối cùng mới nới lỏng sang match chính xác tên xã/phường hiện tại nhưng bỏ điều kiện huyện.
+ *
+ * Kết quả trả về luôn là `Xã/Phường mới, Tỉnh/Thành mới`.
+ * Huyện chỉ dùng để phân biệt khi tìm kiếm, không còn nằm trong output cuối.
+ *
+ * Lưu ý về contract hiện tại của package:
+ * - Hàm giữ dạng `async` để caller có thể `await` giống luồng gốc.
+ * - Dữ liệu hành chính được nạp lazy qua `loadDataXa()` ở thời điểm cần dùng.
+ * - Nếu có `window.modifyDataXa`, dữ liệu sẽ được đi qua hook này trước khi chạy thuật toán mặc định.
+ * - Nếu có `window.convertDiaChiMoi`, hàm sẽ ưu tiên giao toàn bộ việc convert cho hook runtime này.
  */
-const convertDiaChiMoi = (diaChi2CapCu, options = {}) => {
-  const sourceDataXa = options.dataXa || dataXa;
+const convertDiaChiMoi = async (diaChi2CapCu, options = {}) => {
+  const globalTarget = getGlobalTarget();
 
-  if (typeof diaChi2CapCu === "string" && diaChi2CapCu.length <= 6) {
+  if (
+    !globalTarget?.convertDiaChiMoi &&
+    typeof diaChi2CapCu === "string" &&
+    diaChi2CapCu.length <= 6
+  ) {
     return diaChi2CapCu;
   }
 
+  let sourceDataXa = await loadDataXa(options.dataXa);
+
+  if (globalTarget?.modifyDataXa) {
+    sourceDataXa = globalTarget.modifyDataXa(sourceDataXa);
+  }
+
+  if (globalTarget?.convertDiaChiMoi) {
+    return await Promise.resolve(globalTarget.convertDiaChiMoi(diaChi2CapCu, sourceDataXa));
+  }
+
   let diaChi = [];
   const arr = splitAddressParts(diaChi2CapCu);
 
@@ -430,14 +506,7 @@ const convertDiaChiMoi = (diaChi2CapCu, options = {}) => {
 };
 
 // Mount helper lên global để các package khác có thể dùng runtime mà không cần dependency ngược.
-const globalTarget =
-  typeof globalThis !== "undefined"
-    ? globalThis
-    : typeof window !== "undefined"
-      ? window
-      : typeof global !== "undefined"
-        ? global
-        : null;
+const globalTarget = getGlobalTarget();
 
 if (globalTarget) {
   globalTarget.verifyXaName = verifyXaName;
@@ -445,11 +514,11 @@ if (globalTarget) {
   globalTarget.extractAndConvertCccdAddress = extractAndConvertCccdAddress;
 }
 
-module.exports = {
-  dataXa,
+const exported = {
   createUniqueText,
   stripAdministrativePrefix,
   normalizeAdministrativeCode,
+  loadDataXa,
   convertDiaChiMoi,
   verifyXaName,
   splitAddressByValidXa,
@@ -458,3 +527,12 @@ module.exports = {
   extractCccdAddressText,
   extractAndConvertCccdAddress,
 };
+
+Object.defineProperty(exported, "dataXa", {
+  enumerable: true,
+  get() {
+    return getDataXaSync();
+  },
+});
+
+module.exports = exported;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isofh/chuyen-doi-dia-chi-2-cap",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Chuan hoa dia chi hanh chinh cu sang format 2 cap moi",
   "main": "index.js",
   "files": [