Định nghĩa các trường CCCD

Mọi trường được trích xuất từ Căn cước công dân Việt Nam (CCCD — Căn cước công dân gắn chip) thông qua OCR, phân tích QR và phân tích MRZ, cùng định dạng chuẩn, nguồn dữ liệu, quy tắc kiểm tra hợp lệ và yêu cầu chuẩn hóa.

Mô hình dữ liệu

Pipeline trích xuất tổng hợp ba nguồn độc lập thành một tập dữ liệu thống nhất:

Thông tin	Mô tả
OCR	Nhận dạng ký tự quang học trên bề mặt in của thẻ.
QR	Payload QR chính thức phân tách bằng dấu gạch đứng, được mã hóa trên thẻ.
MRZ	Vùng đọc bằng máy (machine-readable zone) tuân theo chuẩn ICAO 9303.
Metadata ảnh	Bounding box của thẻ và các tham chiếu tiền xử lý được tạo ra trong quá trình trích xuất.

{
  "code": 0,
  "success": true,
  "data": {
    "image1": {},
    "image2": {},
    "status": "success",
    "request_id": "uuid",
    "card_information": []
  }
}

Trường định danh

Trường	Kiểu	Mô tả
id	string	Số định danh cá nhân 12 chữ số (Mã số định danh cá nhân). Định dạng ^[0-9]{12}$. Nguồn: OCR, QR, MRZ. Duy nhất cho mỗi công dân; mã hóa tỉnh, ký hiệu giới tính-thế kỷ và một chuỗi ngẫu nhiên. Checksum của MRZ là tùy chọn.
id_1	string	Số CMND cũ gồm 9 chữ số. Định dạng ^[0-9]{9}$. Nguồn: chỉ từ QR. Tùy chọn — chỉ có nếu công dân từng có thẻ CMND cũ.
id_last_9	string	9 chữ số cuối của số CCCD đầy đủ. Định dạng ^[0-9]{9}$. Nguồn: MRZ, vốn yêu cầu dạng rút gọn.
gender	string	Nam hoặc Nữ. Nguồn: OCR, QR, MRZ. Ánh xạ MRZ M → Nam và F → Nữ.
dob	string	Ngày sinh. DD/MM/YYYY từ OCR/MRZ, DDMMYYYY từ QR. Phải cho ra một ngày ISO hợp lệ; chuyển đổi sang dạng chuẩn YYYY-MM-DD.
nationality	string	Giá trị cố định Việt Nam. Nguồn: OCR (mặt trước).

Trường họ tên

Trường	Kiểu	Mô tả
name	string	Họ tên đầy đủ theo pháp lý. Unicode. Nguồn: OCR, QR, MRZ. Viết hoa toàn bộ từ OCR, Title Case từ QR/MRZ — chuẩn hóa về Title Case.
last_name	string	Họ, ví dụ NGUYỄN. Unicode. Nguồn: OCR/MRZ. Thành phần đầu tiên.
middle_name	string	Tên đệm, ví dụ VĂN. Unicode. Nguồn: OCR/MRZ. Không hoặc nhiều thành phần.
first_name	string	Tên, ví dụ A. Unicode. Nguồn: OCR/MRZ. Thành phần cuối cùng.

Bắt buộc phải chuẩn hóa tên: loại bỏ khoảng trắng thừa, chuyển sang Unicode NFC, và chuẩn hóa cách viết hoa theo quy tắc sản phẩm của bạn.

Trường địa chỉ

Địa chỉ Việt Nam có cấu trúc phân cấp, từ tỉnh xuống đến tổ/khu dân cư:

Cấp 1 → Cấp 2 → Cấp 3 → Cấp 4
Tỉnh → Huyện → Xã → Thôn/Tổ

Trường	Kiểu	Mô tả
address	string	Địa chỉ thường trú đầy đủ được in trên thẻ. Văn bản tự do. Nguồn: OCR. Dùng làm dự phòng khi không thể tái tạo các thành phần phân cấp.
address_level_1_(city)	string	Tỉnh hoặc thành phố trực thuộc trung ương, ví dụ TP. Hồ Chí Minh.
address_level_1_(city)_code	string	Mã hành chính cấp tỉnh, ví dụ 79.
address_level_2_(district)	string	Đơn vị hành chính cấp huyện, ví dụ Quận 1.
address_level_2_(district)_code	string	Mã hành chính cấp huyện, ví dụ 760.
address_level_3_(ward)	string	Xã, phường hoặc thị trấn, ví dụ Phường Bến Nghé.
address_level_3_(ward)_code	string	Mã hành chính cấp xã, ví dụ 26740.
address_level_4	string	Đơn vị hành chính nhỏ nhất — thôn hoặc tổ dân cư, ví dụ Tổ 1.
native_place	string	Quê quán — nơi sinh đăng ký của công dân, không nhất thiết là nơi cư trú hiện tại. Thường có dạng <Ward/Commune>, <District>, <Province>. Nguồn: OCR hoặc QR.

Trường cấp phát thẻ

Trường	Kiểu	Mô tả
issue_date	string	Ngày cấp thẻ. DD/MM/YYYY từ OCR, DDMMYYYY từ QR. Chuẩn hóa về ISO YYYY-MM-DD.
expiry_date	string	Ngày thẻ hết hạn — 20 năm kể từ ngày cấp đối với độ tuổi 14–59, không hết hạn trên 60 tuổi. Định dạng DD/MM/YYYY. Phải muộn hơn ngày cấp.
issue_place	string	Cơ quan cấp thẻ, ví dụ CỤC TRƯỞNG CỤC CẢNH SÁT QUẢN LÝ HÀNH CHÍNH VỀ TRẬT TỰ XÃ HỘI.
issue_place_code	string	ID cơ quan cấp thẻ đã mã hóa. Định dạng ^[0-9]{4}$, ví dụ 7740 cho cơ quan quản lý hành chính công an quốc gia.
signature	string	Chữ ký của cán bộ cấp thẻ, ở mặt sau thẻ.

Trường metadata thẻ

Trường	Kiểu	Mô tả
card_type	string	Phiên bản/loại thẻ dùng cho xử lý OCR, ví dụ vn.cccd_new.
card_label	string	Loại thẻ mặt trước hoặc mặt sau dùng cho engine OCR, ví dụ vn.cccd_new.front, vn.cccd_new.back.

Trường mã QR

Payload QR chính thức là một chuỗi phân tách bằng dấu gạch đứng:

<CCCD>|<Legacy_ID>|<Name>|<DOB>|<Gender>|<Native_Place>|<Issue_Date>

Ví dụ:

001xxxxxxxxx|xxxxxxxxx|Nguyễn Văn A|12121990|Nam|Tổ 1, Phường Bến Nghé, Quận 1, TP. Hồ Chí Minh|01012021

Trường	Kiểu	Mô tả
id	string	Vị trí 1 — số CCCD, 12 chữ số.
id_1	string	Vị trí 2 — số CMND cũ, 9 chữ số. Tùy chọn.
name	string	Vị trí 3 — họ tên đầy đủ. Unicode.
dob	string	Vị trí 4 — ngày sinh, DDMMYYYY.
gender	string	Vị trí 5 — Nam hoặc Nữ.
native_place	string	Vị trí 6 — quê quán. Văn bản tự do.
issue_date	string	Vị trí 7 — ngày cấp, DDMMYYYY.

Trường MRZ

MRZ tuân theo chuẩn ICAO 9303 dành cho thẻ định danh:

IDVNMxxxxxxxxxx001xxxxxxxxx<<x9012123M3012121VNM<<<<<<<<<<<xNGUYEN<<VAN<A<<<<<<<<<<<<<<<<<

Trường	Kiểu	Mô tả
document_type	string	Loại document — ID.
country_code	string	Quốc gia cấp — VNM.
id	string	Số CCCD.
id_last_9	string	9 chữ số cuối của số CCCD.
dob	string	Ngày sinh, YYMMDD.
gender	string	M hoặc F.
expiry_date	string	Ngày hết hạn, YYMMDD.
name	string	Họ tên theo dạng LAST<<MIDDLE<FIRST.

Metadata ảnh

Trường	Kiểu	Mô tả
card_box	object	Bounding box của thẻ trong ảnh đầu vào, dùng để hiệu chỉnh phối cảnh, cắt và căn chỉnh.
transformed_image_id	string	ID tham chiếu nội bộ cho ảnh đã được xử lý và chuẩn hóa.

{
  "top_left": { "x": 44, "y": 309 },
  "top_right": { "x": 734, "y": 309 },
  "bottom_left": { "x": 44, "y": 758 },
  "bottom_right": { "x": 734, "y": 758 }
}

Chỉ số độ tin cậy

Trường	Kiểu	Mô tả
confidence_score	float	Xác suất từ 0 đến 1 cho thấy OCR đã đọc đúng trường này.
confidence_verdict	string	Nhãn tùy chọn — SURE cho độ chắc chắn cao, rỗng cho một lần đọc bình thường.
digit_confidence_scores	float[]	Xác suất theo từng chữ số, dùng cho các trường dạng số như mã ID.

Ngưỡng chấp nhận tối thiểu được khuyến nghị:

Trường	Kiểu	Mô tả
Trường quan trọng	id, name, dob	>= 0.90
Trường thứ cấp	address, signature	>= 0.80

Thứ tự ưu tiên và quy tắc gộp trường

Khi cùng một trường đến từ nhiều nguồn, hãy ưu tiên theo thứ tự sau — đáng tin cậy nhất đến ít tin cậy nhất:

1. QR — được mã hóa ngay từ lúc cấp thẻ, không chịu lỗi nhận dạng.
2. MRZ — đọc bằng máy và được bảo vệ bằng checksum.
3. OCR — nhận dạng bề mặt in, dễ sai sót nhất.

if QR.dob is valid: use QR
else if MRZ.dob is valid: use MRZ
else use OCR

Việc tái tạo địa chỉ theo cùng logic dự phòng:

address = join(level_4, level_3, level_2, level_1)
if OCR.address exists and structured parts fail: fallback to OCR.address

Yêu cầu xử lý lỗi

Trường	Kiểu	Mô tả
CARD_NOT_DETECTED	string	Không tìm thấy thẻ trong ảnh. Hành vi: yêu cầu quét lại.
QR_PARSE_ERROR	string	Không thể phân tích mã QR. Hành vi: tiếp tục với OCR/MRZ.
INCOMPLETE_DATA	string	Thiếu một trường quan trọng (id, name, dob). Hành vi: cho trích xuất thất bại.
LOW_CONFIDENCE	string	Một trường có điểm số dưới ngưỡng. Hành vi: trả về một nhãn cảnh báo.

Quy tắc chuẩn hóa đầu ra

• Mọi ngày tháng → YYYY-MM-DD
• Họ tên → Title Case
• Các thành phần địa chỉ → Title Case
• Chuẩn hóa Unicode → NFC
• Loại bỏ khoảng trắng lặp và các bất nhất về dấu câu

Schema database được đề xuất

Trường	Kiểu	Mô tả
id	VARCHAR(12)	Khóa chính — số CCCD.
id_legacy	VARCHAR(9)	Số CMND cũ. Cho phép null.
full_name	TEXT	Họ tên đầy đủ theo pháp lý.
last_name	TEXT	Họ.
middle_name	TEXT	Tên đệm.
first_name	TEXT	Tên.
gender	ENUM('Male','Female')	Giới tính đã chuẩn hóa.
dob	DATE	Ngày sinh.
nationality	TEXT	Quốc tịch.
native_place	TEXT	Nơi sinh đăng ký.
address	TEXT	Chuỗi địa chỉ dự phòng.
ward	TEXT	Tên xã cấp 3.
ward_code	VARCHAR(10)	Mã hành chính cấp 3.
district	TEXT	Tên huyện cấp 2.
district_code	VARCHAR(10)	Mã hành chính cấp 2.
province	TEXT	Tên tỉnh cấp 1.
province_code	VARCHAR(10)	Mã hành chính cấp 1.
issue_date	DATE	Ngày cấp thẻ.
expiry_date	DATE	Ngày hết hạn thẻ.
issue_place	TEXT	Cơ quan cấp thẻ.
issue_place_code	VARCHAR(10)	Mã cơ quan cấp thẻ.
signature	TEXT	Chữ ký của cán bộ cấp thẻ.
confidence_overall	FLOAT	Độ tin cậy tổng hợp của quá trình trích xuất.

WARNING

Mọi cột ở trên đều là dữ liệu cá nhân theo quy định bảo vệ dữ liệu của Việt Nam, và face_image từ chip là dữ liệu sinh trắc học. Hãy mã hóa khi lưu trữ, giới hạn quyền đọc cho các bên gọi có lý do nghiệp vụ, và áp dụng chính sách lưu giữ dữ liệu — không giữ hồ sơ định danh lâu hơn thời gian mối quan hệ yêu cầu.

Đề xuất kiểm tra hợp lệ bổ sung

• Tra cứu mã tỉnh, huyện và xã với cơ sở dữ liệu hành chính Việt Nam.
• Kiểm tra tính nhất quán của ngày tháng — ngày sinh phải trước hoặc bằng ngày cấp thẻ.
• Đối chiếu chéo giới tính giữa MRZ và QR.

Bước tiếp theo

• Đọc NFC — API trả về các trường này từ chip
• Tổng quan — toàn bộ vòng đời giao dịch