README.md

---
license: apache-2.0
---

# address - Vietnamese Address Converter

Chuyển đổi địa chỉ Việt Nam từ hệ thống hành chính cũ (63 tỉnh/thành phố, 3 cấp) sang hệ thống mới sau sáp nhập (34 tỉnh/thành phố, 2 cấp), có hiệu lực từ 01/07/2025.

## Technical Report

### 1. Bối cảnh

Nghị quyết của Quốc hội về sáp nhập đơn vị hành chính có hiệu lực ngày 01/07/2025, thay đổi cấu trúc hành chính Việt Nam:

| | Cũ | Mới |
|---|---|---|
| Tỉnh/Thành phố | 63 | 34 |
| Cấp hành chính | Tỉnh > Huyện > Xã | Tỉnh > Xã |
| Tổng số xã/phường | ~10,600 | ~3,300 |

Cấp huyện (quận/huyện/thị xã/thành phố trực thuộc tỉnh) bị loại bỏ hoàn toàn khỏi địa chỉ hành chính. Các xã/phường được sáp nhập, đổi tên, chia tách hoặc giữ nguyên tùy khu vực.

### 2. Kiến trúc hệ thống

```
address/
├── pyproject.toml                 # Package config (uv + hatchling)
├── data/
│   └── mapping.json               # 10,602 bản ghi mapping (4.7 MB)
├── src/
│   ├── __init__.py                # Public API
│   ├── models.py                  # Data models & enums
│   ├── normalizer.py              # Chuẩn hóa tiếng Việt
│   ├── parser.py                  # Phân tích chuỗi địa chỉ
│   ├── converter.py               # Logic chuyển đổi chính
│   └── cli.py                     # CLI (click)
├── scripts/
│   └── build_mapping.py           # Tạo mapping.json từ vietnamadminunits
└── tests/
    └── test_converter.py          # 13 test cases
```

**Nguyên tắc thiết kế**: Package hoạt động standalone — dữ liệu mapping được extract một lần từ `vietnamadminunits` (dev dependency) vào `data/mapping.json`, sau đó runtime chỉ cần `click` là dependency duy nhất.

### 3. Nguồn dữ liệu

Dữ liệu mapping được extract từ package `vietnamadminunits` v1.0.4 (PyPI, MIT license) thông qua script `scripts/build_mapping.py`. Package này cung cấp 3 file JSON chính:

| File | Nội dung | Kích thước |
|---|---|---|
| `converter_2025.json` | Mapping cũ → mới (province + ward) | 596 KB |
| `parser_legacy.json` | Dữ liệu hành chính cũ (63 tỉnh, 3 cấp) | 2.6 MB |
| `parser_from_2025.json` | Dữ liệu hành chính mới (34 tỉnh, 2 cấp) | 957 KB |

**Cấu trúc dữ liệu gốc** (trong `converter_2025.json`):

- `DICT_PROVINCE`: `{new_province_key: [old_province_key_1, old_province_key_2, ...]}` — mapping tỉnh
- `DICT_PROVINCE_WARD_NO_DIVIDED`: `{new_prov: {new_ward: [old_compound_key, ...]}}` — xã không bị chia tách
- `DICT_PROVINCE_WARD_DIVIDED`: `{new_prov: {old_compound_key: [{newWardKey, isDefaultNewWard, ...}]}}` — xã bị chia tách

Compound key format: `{province_key}_{district_key}_{ward_key}` (ví dụ: `thanhphohanoi_quanbadinh_phuongphucxa`).

### 4. Build mapping (`scripts/build_mapping.py`)

Script extract và chuẩn hóa dữ liệu từ 3 file JSON của vietnamadminunits thành một file `data/mapping.json` thống nhất:

```
uv run python scripts/build_mapping.py
```

**Output `mapping.json`** chứa:

| Trường | Mô tả |
|---|---|
| `metadata` | Source, version, effective_date, thống kê |
| `province_mapping` | `{old_key: new_key}` — 63 entries |
| `province_names` | `{key: {name, short, code}}` — 34 tỉnh mới |
| `old_province_names` | `{key: {name, short, code}}` — 63 tỉnh cũ |
| `ward_mapping` | List 10,602 records chi tiết |

**Mỗi ward mapping record** gồm:

```json
{
  "old_province": "Thành phố Hà Nội",
  "old_province_key": "thanhphohanoi",
  "old_district": "Quận Ba Đình",
  "old_district_key": "quanbadinh",
  "old_ward": "Phường Phúc Xá",
  "old_ward_key": "phuongphucxa",
  "new_province": "Thành phố Hà Nội",
  "new_province_key": "thanhphohanoi",
  "new_ward": "Phường Hồng Hà",
  "new_ward_key": "phuonghongha",
  "mapping_type": "merged"
}
```

**Phân loại mapping type:**

| Type | Số lượng | Mô tả |
|---|---|---|
| `unchanged` | 149 | Xã giữ nguyên tên |
| `renamed` | 92 | Xã đổi tên (1:1) |
| `merged` | 9,328 | Nhiều xã cũ gộp thành 1 xã mới |
| `divided` | 1,033 | 1 xã cũ chia thành nhiều xã mới |
| **Tổng** | **10,602** | |

**Logic phân loại:**
- `unchanged`: Chỉ có 1 compound key cũ trỏ vào ward mới VÀ tên trùng nhau
- `renamed`: Chỉ có 1 compound key cũ trỏ vào ward mới VÀ tên khác nhau
- `merged`: Nhiều compound key cũ cùng trỏ vào 1 ward mới
- `divided`: Từ `DICT_PROVINCE_WARD_DIVIDED`, có `is_default` flag cho mỗi option

### 5. Modules

#### 5.1 `src/models.py` — Data Models

- `MappingType(str, Enum)`: `UNCHANGED`, `RENAMED`, `MERGED`, `DIVIDED`
- `ConversionStatus(str, Enum)`: `SUCCESS`, `PARTIAL`, `NOT_FOUND`
- `AdminUnit(@dataclass)`: `province`, `district`, `ward`, `street` + `to_address()`
- `ConversionResult(@dataclass)`: `original`, `converted`, `status`, `mapping_type`, `old`, `new`, `note`

#### 5.2 `src/normalizer.py` — Chuẩn hóa tiếng Việt

**Ba hàm chính:**

| Hàm | Input | Output | Mô tả |
|---|---|---|---|
| `remove_diacritics()` | `"Phường Phúc Xá"` | `"Phuong Phuc Xa"` | Unicode NFKD decomposition + xử lý đ/Đ |
| `normalize_key()` | `"Quận Ba Đình"` | `"quanbadinh"` | Lowercase + bỏ dấu + bỏ space/punctuation |
| `expand_abbreviations()` | `"P.Phúc Xá, Q.Ba Đình"` | `"phường phúc xá, quận ba đình"` | Mở rộng viết tắt |

**Bảng viết tắt hỗ trợ:**

| Viết tắt | Đầy đủ |
|---|---|
| `TP.`, `T.P.` | Thành phố |
| `P.` | Phường |
| `Q.` | Quận |
| `H.` | Huyện |
| `TX.`, `T.X.` | Thị xã |
| `TT.`, `T.T.` | Thị trấn |
| `X.` | Xã |

#### 5.3 `src/parser.py` — Phân tích địa chỉ

Parse chuỗi địa chỉ theo format `"street, ward, district, province"` bằng phương pháp **right-to-left positional assignment**:

```
"123 Hàng Bông, Phường Phúc Xá, Quận Ba Đình, TP Hà Nội"
       ↑              ↑              ↑              ↑
    street          ward          district       province
   (parts[:-3])  (parts[-3])    (parts[-2])    (parts[-1])
```

Xử lý đặc biệt cho địa chỉ 2 phần (`"ward, province"`): kiểm tra prefix phường/xã/thị trấn để phân biệt với district.

#### 5.4 `src/converter.py` — Logic chuyển đổi

**Khởi tạo (lazy load):**
- Load `data/mapping.json` lần đầu khi gọi `convert_address()`
- Build index một lần, cache trong module-level globals

**Index structure:**

| Index | Key | Value | Mục đích |
|---|---|---|---|
| `province` | `old_prov_key` | `new_prov_key` | Tra cứu tỉnh |
| `province_keywords` | `normalized_name` | `old_prov_key` | Fuzzy match tên tỉnh |
| `exact` | `(prov, dist, ward)` | `[records]` | Tra cứu chính xác |
| `ward_only` | `(prov, ward)` | `[records]` | Tra cứu bỏ qua quận/huyện |

**Luồng chuyển đổi (`convert_address`):**

```
Input: "Phường Phúc Xá, Quận Ba Đình, Thành phố Hà Nội"
  │
  ├─ 1. parse_address() → AdminUnit(ward, district, province)
  │
  ├─ 2. Resolve province
  │     normalize("Thành phố Hà Nội") → "thanhphohanoi"
  │     province_mapping["thanhphohanoi"] → "thanhphohanoi"
  │     ❌ Không tìm thấy → NOT_FOUND
  │
  ├─ 3. Tra cứu ward (2-tier matching)
  │     ├─ Tier 1: exact("thanhphohanoi", "quanbadinh", "phuongphucxa") ✅
  │     └─ Tier 2: ward_only("thanhphohanoi", "phuongphucxa") (fallback)
  │
  ├─ 4. Chọn bản ghi tốt nhất
  │     └─ Nếu divided: ưu tiên is_default=true
  │
  └─ 5. Build result
        ConversionResult(converted="Phường Hồng Hà, Thành phố Hà Nội",
                         status=SUCCESS, mapping_type=MERGED)
```

**Conversion status:**

| Status | Điều kiện |
|---|---|
| `SUCCESS` | Tìm thấy cả province + ward mapping |
| `PARTIAL` | Chỉ tìm thấy province (ward không match) |
| `NOT_FOUND` | Không nhận dạng được province |

#### 5.5 `src/cli.py` — Command Line Interface

Hai commands, sử dụng `click`:

```bash
# Chuyển đổi 1 địa chỉ
address-convert convert "Phường Phúc Xá, Quận Ba Đình, TP Hà Nội"

# Chuyển đổi hàng loạt từ CSV
address-convert batch input.csv output.csv --column address
```

Batch mode đọc CSV, thêm 3 cột vào output: `converted_address`, `conversion_status`, `mapping_type`.

### 6. Test Results

13 test cases, tất cả pass:

```
tests/test_converter.py::TestMergedWard::test_phuc_xa_merged_to_hong_ha        PASSED
tests/test_converter.py::TestMergedWard::test_an_binh_can_tho                  PASSED
tests/test_converter.py::TestUnchangedWard::test_tan_loc_can_tho               PASSED
tests/test_converter.py::TestRenamedWard::test_long_hoa_renamed                PASSED
tests/test_converter.py::TestDividedWard::test_divided_selects_default         PASSED
tests/test_converter.py::TestAbbreviations::test_p_q_tp                        PASSED
tests/test_converter.py::TestAbbreviations::test_tp_shorthand                  PASSED
tests/test_converter.py::TestPartialAddress::test_province_only                PASSED
tests/test_converter.py::TestPartialAddress::test_unknown_province             PASSED
tests/test_converter.py::TestWithStreet::test_street_preserved                 PASSED
tests/test_converter.py::TestBatchConvert::test_batch                          PASSED
tests/test_converter.py::TestProvinceMapping::test_ha_noi_stays                PASSED
tests/test_converter.py::TestProvinceMapping::test_merged_province             PASSED
```

**Coverage theo loại test:**

| Nhóm test | Kiểm tra |
|---|---|
| Merged ward | Nhiều xã cũ → 1 xã mới (Phúc Xá → Hồng Hà) |
| Unchanged ward | Xã giữ nguyên (Tân Lộc) |
| Renamed ward | Xã đổi tên (Long Hòa → Long Tuyền) |
| Divided ward | Xã chia tách, chọn default |
| Abbreviations | `P.`, `Q.`, `TP.` mở rộng đúng |
| Partial address | Chỉ tỉnh, tỉnh không tồn tại |
| Street preserved | Giữ nguyên phần đường khi chuyển đổi |
| Batch convert | Chuyển đổi hàng loạt, mixed results |
| Province mapping | Tỉnh giữ nguyên, tỉnh sáp nhập |

### 7. Danh sách 34 tỉnh/thành phố mới

| Mã | Tên |
|---|---|
| 01 | Thành phố Hà Nội |
| 04 | Tỉnh Cao Bằng |
| 08 | Tỉnh Tuyên Quang |
| 11 | Tỉnh Điện Biên |
| 12 | Tỉnh Lai Châu |
| 14 | Tỉnh Sơn La |
| 15 | Tỉnh Lào Cai |
| 19 | Tỉnh Thái Nguyên |
| 20 | Tỉnh Lạng Sơn |
| 22 | Tỉnh Quảng Ninh |
| 24 | Tỉnh Bắc Ninh |
| 25 | Tỉnh Phú Thọ |
| 31 | Thành phố Hải Phòng |
| 33 | Tỉnh Hưng Yên |
| 37 | Tỉnh Ninh Bình |
| 38 | Tỉnh Thanh Hóa |
| 40 | Tỉnh Nghệ An |
| 42 | Tỉnh Hà Tĩnh |
| 44 | Tỉnh Quảng Trị |
| 46 | Thành phố Huế |
| 48 | Thành phố Đà Nẵng |
| 51 | Tỉnh Quảng Ngãi |
| 52 | Tỉnh Gia Lai |
| 56 | Tỉnh Khánh Hòa |
| 66 | Tỉnh Đắk Lắk |
| 68 | Tỉnh Lâm Đồng |
| 75 | Tỉnh Đồng Nai |
| 79 | Thành phố Hồ Chí Minh |
| 80 | Tỉnh Tây Ninh |
| 82 | Tỉnh Đồng Tháp |
| 86 | Tỉnh Vĩnh Long |
| 91 | Tỉnh An Giang |
| 92 | Thành phố Cần Thơ |
| 96 | Tỉnh Cà Mau |

### 8. Cách sử dụng

#### Python API

```python
from src import convert_address, batch_convert

# Chuyển đổi 1 địa chỉ
result = convert_address("Phường Phúc Xá, Quận Ba Đình, Thành phố Hà Nội")
print(result.converted)      # "Phường Hồng Hà, Thành phố Hà Nội"
print(result.status)         # ConversionStatus.SUCCESS
print(result.mapping_type)   # MappingType.MERGED

# Hỗ trợ viết tắt
result = convert_address("P. Phúc Xá, Q. Ba Đình, TP. Hà Nội")
print(result.converted)      # "Phường Hồng Hà, Thành phố Hà Nội"

# Batch
results = batch_convert(["addr1", "addr2", "addr3"])
```

#### CLI

```bash
# Cài đặt
uv sync

# Chuyển đổi 1 địa chỉ
uv run address-convert convert "P. Phúc Xá, Q. Ba Đình, TP Hà Nội"

# Chuyển đổi CSV
uv run address-convert batch input.csv output.csv --column address
```

#### Cập nhật mapping data

```bash
uv run python scripts/build_mapping.py
```

### 9. Hạn chế và hướng phát triển

**Hạn chế hiện tại:**
- Xã bị chia tách (`divided`): chỉ chọn ward mặc định (`is_default`), không hỗ trợ geocoding để chọn chính xác
- Parser dựa vào vị trí (right-to-left), có thể sai với địa chỉ không chuẩn format
- Chưa hỗ trợ input không dấu hoàn toàn (ví dụ: "Phuong Phuc Xa")

**Hướng phát triển:**
- Thêm geocoding cho divided wards (dựa trên tọa độ đường phố)
- Hỗ trợ input không dấu bằng fuzzy matching trên normalized keys
- Thêm REST API endpoint
- Tích hợp với pandas DataFrame cho batch processing lớn