DVC-SmartScan là ứng dụng web hỗ trợ cán bộ tại Bộ phận Một cửa trích xuất thông tin từ Căn cước công dân (CCCD) bằng AI. Người dùng có thể tải lên ảnh hoặc PDF, kiểm tra và hiệu chỉnh dữ liệu nhận dạng, sau đó xuất kết quả thành tệp Word để phục vụ đối soát, lưu trữ hoặc nhập liệu.
Ứng dụng được thiết kế theo nguyên tắc AI hỗ trợ, con người xác nhận: kết quả chỉ có thể xuất sau khi các trường bắt buộc hợp lệ và người dùng xác nhận đã đối chiếu với tài liệu gốc.
- Tải lên một hoặc nhiều ảnh/PDF trong cùng một lần xử lý.
- Hỗ trợ ảnh mặt trước và mặt sau của cùng một CCCD.
- Nhận dạng nhiều CCCD trong một bộ tài liệu và tách kết quả theo từng người.
- Trích xuất các trường:
- Số CCCD/định danh.
- Họ và tên.
- Ngày sinh.
- Giới tính.
- Quốc tịch.
- Quê quán hoặc nơi đăng ký khai sinh.
- Nơi thường trú.
- Ngày cấp.
- Cơ quan cấp.
- Hiển thị trang/ảnh nguồn và cảnh báo đối với dữ liệu mờ, thiếu hoặc không chắc chắn.
- Cho phép chỉnh sửa trực tiếp kết quả trước khi xuất.
- Kiểm tra số CCCD gồm đúng 12 chữ số, họ tên không để trống và ngày sinh theo định dạng
DD/MM/YYYY. - Xuất toàn bộ kết quả thành tệp Microsoft Word (
.docx).
- Chọn ảnh hoặc PDF chứa CCCD.
- Kiểm tra bản xem trước và thứ tự tài liệu.
- Nhấn Bắt đầu trích xuất để gửi tài liệu đến máy chủ xử lý.
- Chuyển giữa các tab nếu hệ thống tìm thấy nhiều CCCD.
- Đối chiếu từng trường với tài liệu gốc và sửa lại nếu cần.
- Đánh dấu xác nhận đã đối chiếu.
- Nhấn Tải file Word (.docx).
| Nội dung | Giới hạn |
|---|---|
| Định dạng ảnh | JPEG, PNG, WEBP, HEIC, HEIF |
| Tài liệu | |
| Số tệp mỗi lần | Tối đa 10 tệp |
| Tổng dung lượng | Tối đa 20 MB |
| Tệp đầu ra | Microsoft Word (.docx) |
Khả năng xem trước HEIC/HEIF phụ thuộc vào trình duyệt. Tệp vẫn có thể được gửi xử lý nếu trình duyệt không hiển thị được ảnh xem trước.
- Giao diện: React 19, Vite 8.
- API: Node.js, Express 5.
- AI: Google Gemini thông qua SDK
@google/genai. - Tải tệp: Multer, lưu tạm trong bộ nhớ máy chủ.
- Xuất tài liệu:
docxvàfile-saver.
Trình duyệt (React)
│ POST /api/extract
│ multipart/form-data
▼
Máy chủ Express
│ kiểm tra loại tệp và dung lượng
▼
Google Gemini
│ kết quả JSON theo cấu trúc định sẵn
▼
Màn hình đối soát → chỉnh sửa → xuất Word
Khóa Gemini chỉ được đọc ở phía máy chủ và không được đóng gói vào mã JavaScript chạy trên trình duyệt.
- Node.js phiên bản 20.19 trở lên (hoặc 22.12 trở lên).
- npm đi kèm Node.js.
- Khóa API Google Gemini có quyền sử dụng model đã cấu hình.
Sao chép mã nguồn và cài các gói phụ thuộc:
git clone <repository-url>
cd DVC-SmartScan
npm installTrong đó:
| Biến | Bắt buộc | Giá trị mặc định | Mô tả |
|---|---|---|---|
GEMINI_API_KEY |
Có | Không có | Khóa dùng để gọi Google Gemini API |
GEMINI_MODEL |
Không | gemini-3.5-flash-lite |
Model dùng để đọc tài liệu |
PORT |
Không | 3001 |
Cổng của API Express |
Không đặt khóa bí mật trong biến có tiền tố VITE_, vì biến môi trường kiểu này có thể được đưa vào mã phía trình duyệt. Tệp .env đã được khai báo trong .gitignore và không nên được commit lên kho mã nguồn.
Khởi động đồng thời giao diện và API:
npm run devPhản hồi thành công có dạng:
{
"documents": [
{
"so_cccd": "001234567890",
"ho_va_ten": "NGUYỄN VĂN A",
"ngay_sinh": "01/01/1990",
"gioi_tinh": "Nam",
"quoc_tich": "Việt Nam",
"que_quan": "...",
"noi_thuong_tru": "...",
"ngay_cap": "...",
"co_quan_cap": "...",
"source_pages": [1, 2],
"warnings": []
}
]
}DVC-SmartScan/
├── public/ # Favicon và tài nguyên tĩnh
├── server/
│ └── index.js # Express API, upload và gọi Gemini
├── src/
│ ├── assets/ # Hình ảnh giao diện
│ ├── utils/
│ │ ├── gemini.js # Gửi tài liệu từ trình duyệt đến API
│ │ └── wordExport.js # Tạo và tải tệp DOCX
│ ├── App.jsx # Luồng tải lên, đối soát và xuất kết quả
│ ├── index.css # Kiểu giao diện
│ └── main.jsx # Điểm khởi tạo React
├── .env # Cấu hình cục bộ, không commit
├── package.json
└── vite.config.js # Cấu hình Vite và proxy API
CCCD chứa dữ liệu cá nhân nhạy cảm. Khi đưa ứng dụng vào sử dụng thực tế, cần:
- Chỉ xử lý tài liệu khi có căn cứ và quyền truy cập phù hợp.
- Dùng HTTPS cho cả giao diện và API.
- Giới hạn người dùng được truy cập ứng dụng.
- Bảo vệ khóa API bằng kho bí mật của môi trường triển khai.
- Xác định chính sách lưu giữ, nhật ký và xóa dữ liệu theo quy định của đơn vị.
- Kiểm tra chính sách xử lý dữ liệu của nhà cung cấp AI trước khi gửi tài liệu thật.
- Không xem kết quả AI là dữ liệu đã được xác minh nếu chưa đối chiếu tài liệu gốc.
Trong phiên bản hiện tại, tệp tải lên được giữ trong bộ nhớ của tiến trình Node.js để gửi đến Gemini; ứng dụng không chủ động ghi tệp lên ổ đĩa hay cơ sở dữ liệu. Tuy nhiên, dữ liệu vẫn được truyền đến dịch vụ AI bên ngoài để xử lý.
Kiểm tra tệp .env nằm ở thư mục gốc, biến được viết đúng tên và khởi động lại npm run dev sau khi thay đổi.
- Kiểm tra tệp thuộc định dạng được hỗ trợ và tổng dung lượng không vượt 20 MB.
- Ưu tiên ảnh rõ nét, không lóa, không mất góc và chữ không quá nhỏ.
- Kiểm tra model trong
GEMINI_MODELcó tồn tại và khóa API có quyền truy cập. - Thử lại nếu dịch vụ Gemini tạm thời không phản hồi.
Đảm bảo API đang chạy trên cổng 3001. Nếu thay đổi PORT, cần cập nhật cấu hình proxy trong vite.config.js hoặc cấu hình reverse proxy tương ứng.
Sửa hết các lỗi hiển thị trên biểu mẫu, sau đó đánh dấu ô xác nhận đã đối chiếu với tài liệu gốc.
Kết quả phụ thuộc vào chất lượng ảnh, bố cục tài liệu và khả năng của model AI. Hệ thống được yêu cầu để trống trường không đọc được thay vì tự suy đoán, nhưng vẫn có thể nhận dạng sai. Người dùng chịu trách nhiệm kiểm tra lại toàn bộ thông tin trước khi sử dụng hoặc xuất tệp.
Dự án hiện chưa khai báo giấy phép nguồn mở. Mọi quyền sử dụng, sao chép hoặc phân phối cần tuân theo quy định của chủ sở hữu dự án.