@isofh/chuyen-doi-dia-chi-2-cap 0.1.0

package/README.md

@@ -0,0 +1,251 @@
+# @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`.
+
+## 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
+- đóng gói thành npm package để dùng lại giữa nhiều dự án
+
+## Cài đặt
+
+```bash
+npm install @isofh/chuyen-doi-dia-chi-2-cap
+```
+
+## API
+
+Package export các thành phần sau:
+
+- `convertDiaChiMoi(input, options?)`
+- `verifyXaName(tenXa, tinh?, options?)`
+- `splitAddressByValidXa(input, tinh?, options?)`
+- `parseCccdQrString(input)`
+- `extractCccdAddressText(input)`
+- `extractAndConvertCccdAddress(input, ngayCap?, options?)`
+- `dataXa`
+- `createUniqueText(text)`
+- `stripAdministrativePrefix(text)`
+- `normalizeAdministrativeCode(text)`
+
+## Cách dùng cơ bản
+
+```js
+const {
+  convertDiaChiMoi,
+  verifyXaName,
+  splitAddressByValidXa,
+  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);
+```
+
+## Input hỗ trợ
+
+`convertDiaChiMoi` nhận:
+
+- chuỗi địa chỉ hành chính, ví dụ `"Xuân Thành, Xuân Lộc, Đồng Nai"`
+- hoặc mảng các phần tử địa chỉ, ví dụ `['Xuân Thành', 'Xuân Lộc', 'Đồng Nai']`
+
+## Lưu ý quan trọng
+
+Hàm này chỉ xử lý phần địa chỉ hành chính.
+
+Nếu input gốc có cả số nhà, tên đường, khu phố..., caller nên tách phần hành chính trước khi gọi hàm này.
+
+Ví dụ:
+
+```js
+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);
+```
+
+## 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.
+
+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.
+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`
+   - match gần đúng trong `satNhapTu`
+   - fallback về match chính xác tên xã hiện tại nhưng bỏ điều kiện huyện
+
+## Ví dụ
+
+```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"]));
+```
+
+## Verify tên xã
+
+Hàm `verifyXaName` dùng để kiểm tra một tên xã/phường có tồn tại hợp lệ hay không bằng cách so sánh:
+
+- tên xã hiện tại trong `dsXa`
+- tên xã cũ trong `satNhapTu`
+
+Tham số thứ 2 là `tỉnh` để thu hẹp phạm vi tìm kiếm. Đây là tham số nên truyền vào trong các case tách `soNha`, vì cùng một tên xã có thể tồn tại ở nhiều tỉnh khác nhau.
+
+Ví dụ:
+
+```js
+const { verifyXaName } = require("@isofh/chuyen-doi-dia-chi-2-cap");
+
+console.log(verifyXaName("Cửa Nam", "Hà Nội"));
+console.log(verifyXaName("Xuân Thành", "Đồng Nai"));
+```
+
+Kết quả trả về có dạng:
+
+```js
+{
+  input: "Xuân Thành",
+  normalizedInput: "xuanthanh",
+  isValid: true,
+  matches: [
+    {
+      matchType: "current",
+      tenXa: "Xuân Thành",
+      tenTinh: "Đồng Nai"
+    },
+    {
+      matchType: "satNhapTu",
+      tenXa: "Long Khánh",
+      tenTinh: "Đồng Nai",
+      tenXaCu: "Xuân Thành"
+    }
+  ]
+}
+```
+
+`options` hỗ trợ:
+
+- `dataXa`: truyền bộ dữ liệu khác nếu caller muốn override
+
+Ngoài export thường, package cũng tự mount sẵn các hàm này lên `globalThis` khi được require:
+
+```js
+globalThis.verifyXaName;
+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.
+
+## 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ụ:
+
+```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
+```
+
+Hàm sẽ tách ra các field chuẩn như số giấy tờ, họ tên, ngày sinh, giới tính, địa chỉ, ngày cấp.
+
+`extractCccdAddressText` dùng để lấy đúng field địa chỉ từ chuỗi QR CCCD dạng pipe.
+
+Ví dụ:
+
+```js
+const { extractCccdAddressText } = require("@isofh/chuyen-doi-dia-chi-2-cap");
+
+console.log(extractCccdAddressText("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"));
+```
+
+`extractAndConvertCccdAddress` là hàm mức cao để:
+
+- lấy field địa chỉ từ QR căn cước
+- 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`
+
+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"
+  )
+);
+```
+
+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.
+
+## Tách số nhà dựa trên xã hợp lệ
+
+Ý tưởng của hàm `splitAddressByValidXa` là:
+
+- nếu một phần tử không phải xã hợp lệ
+- nhưng phần tử đứng sau nó lại là xã hợp lệ trong tỉnh tương ứng
+- thì phần tử không hợp lệ phía trước sẽ được coi là `soNha`
+
+Ví dụ:
+
+```js
+const { splitAddressByValidXa } = require("@isofh/chuyen-doi-dia-chi-2-cap");
+
+console.log(splitAddressByValidXa("Phú Thạch, Phú Trung, Đồng Nai", "Đồng Nai"));
+console.log(splitAddressByValidXa("4A Lê Thánh Tông, Cửa Nam, Hà Nội", "Hà Nội"));
+console.log(splitAddressByValidXa("Tổ 6, Quang Trung, Phủ Lý, Hà Nam", "Hà Nam"));
+```
+
+Kết quả kỳ vọng:
+
+```js
+{
+  soNha: "Phú Thạch",
+  diaChi: "Phú Trung, Đồng Nai"
+}
+```
+
+Hàm sẽ dò từ trái sang phải và chọn xã hợp lệ đầu tiên trong tỉnh đích. Toàn bộ phần đứng trước xã đó sẽ được coi là `soNha`.
+
+## Dependency string utils
+
+Package này đang `require("mainam-react-native-string-utils")` để dùng lại các helper string đã có sẵn như `createUniqueText`, tránh viết lại logic normalize ở nhiều nơi.
+
+Vì vậy package cần khai báo đúng dependency này trong `package.json`.
+
+## Export dữ liệu
+
+```js
+const { dataXa } = require("@isofh/chuyen-doi-dia-chi-2-cap");
+
+console.log(dataXa.length);
+```
+
+## Nguồn dữ liệu
+
+- `dataXa.json` là bộ dữ liệu hành chính dùng cho logic chuyển đổi địa chỉ
+
+## Ghi chú
+
+- package ưu tiên giữ behavior ổn định theo các case nghiệp vụ thực tế
+- có thể tiếp tục mở rộng thêm test case khi phát sinh dữ liệu mới