Address Reference

Yêu cầu hệ thống

Vai trò

• Address Reference là yêu cầu hệ thống, không phải feature sản phẩm riêng.
• Cung cấp master data hành chính Việt Nam theo mô hình 2 cấp 2025 (tỉnh/thành → phường/xã, không có cấp huyện).
• Là nguồn canonical cho địa chỉ trong V-Nexus: 34 tỉnh/thành, 3.321 phường/xã.

Nguyên tắc bất biến

• Read-only tại runtime — không API tạo/sửa/xóa qua ứng dụng; thay đổi chỉ qua phát hành dữ liệu (migration) có kiểm soát.
• UUID (id) là khóa trao đổi khi gán địa chỉ cho listing, property, user — không dùng code hoặc name thô làm khóa nghiệp vụ.
• Seed ban đầu cố định — cập nhật sau bằng migration bổ sung; không sửa lại bộ seed gốc đã chạy.
• Sáp nhập / bãi bỏ — không hard-delete row; ưu tiên giữ bản ghi + deprecated_at (hoặc tương đương) cho tham chiếu lịch sử.
• FK sang property/user/listing — giai đoạn hiện có thể vẫn lưu text; wiring FK là hạng mục sau.

Phạm vi tra cứu

Nhu cầu	Hành vi
Danh sách tỉnh	Toàn bộ, sắp code tăng dần
Chi tiết tỉnh	Theo UUID; không tồn tại → 404
Phường theo tỉnh	Toàn bộ thuộc tỉnh, sắp code; không paginate (~100–200/tỉnh, phù hợp dropdown)
Toàn bộ phường	Phân trang (mặc định size=50, sort=code,asc)
Chi tiết phường	Theo UUID; không tồn tại → 404

Tra cứu công khai (không yêu cầu đăng nhập), chỉ phương thức GET.

Rate limit

Bucket riêng address, tách khỏi public-read. Chi tiết bucket và routing: Rate Limit (tab Bucket Matrix / Routing Rules).

Môi trường	Giới hạn
Production	300 request/phút/caller
Dev	600 request/phút/caller

Caller ẩn danh → key theo IP; đã đăng nhập → key theo user ID.

Feature liên quan (tiêu thụ master data)

• properties-create
• listing-create
• user-profile-update-web
• admin-user-list-search
• broker-daily-listing-distribution
• listing-crawl-external-sources

Dữ liệu & Seed

Quy mô sau seed ban đầu

Tập	Số lượng	Ghi chú
Tỉnh/thành	34	Baseline seed
Phường/xã	3.321	Mỗi phường gắn một tỉnh

Thuộc tính nghiệp vụ

Tỉnh (Province):

• id — UUID (định danh API)
• code — mã hành chính 2 ký tự (vd 01 = Hà Nội)
• name — tên đầy đủ (vd Thành phố Hà Nội)

Phường (Ward):

• id — UUID
• code — mã hành chính 8 ký tự (vd 10105001)
• name — tên đầy đủ
• provinceId — UUID tỉnh chứa

Vận hành cập nhật danh mục

Tình huống	Quy tắc
Thêm tỉnh/phường	Migration bổ sung (vd V20.1__...), không sửa seed V20
Đổi tên	Migration UPDATE name
Sáp nhập / xóa	Không DELETE; có thể set deprecated_at

Triển khai

Schema bảng provinces / wards và file Flyway (V19, V20, …) nằm ở repo source BE — không mô tả chi tiết tại đây.

Hợp đồng API

Tổng quan

• Base: /api
• Auth: không bắt buộc
• Method: chỉ GET

Tỉnh/thành

GET /provinces

Danh sách toàn bộ tỉnh, sắp code tăng dần.

GET /provinces/{id}

Chi tiết một tỉnh theo UUID. 404 nếu không tồn tại.

GET /provinces/{id}/wards

Toàn bộ phường thuộc tỉnh, sắp code. 404 nếu tỉnh không tồn tại; [] nếu tỉnh hợp lệ nhưng không có phường.

Phường/xã

GET /wards

Toàn bộ phường, phân trang.

Query	Mặc định	Mô tả
page	0	Trang (zero-based)
size	50	Kích thước trang
sort	code,asc	Sắp xếp

GET /wards/{id}

Chi tiết một phường theo UUID. 404 nếu không tồn tại.

Response envelope

Mọi response dùng envelope chuẩn V-Nexus (success, code, data). Ví dụ payload — xem OpenAPI / repo BE.