iNET Portal Docs

Appearance

eKYC & MediaPipe Face Liveness - Documentation ​

Giới thiệu ​

Bộ tài liệu chi tiết về implementation eKYC với face liveness detection sử dụng MediaPipe FaceMesh trong Vue 3 + TypeScript + Vite.

Tổng quan ​

Hệ thống eKYC cho phép xác thực danh tính trực tuyến qua:

  • ✅ OCR từ ảnh CCCD (front/back)
  • ✅ Face liveness detection với MediaPipe
  • ✅ Face verification với backend
  • ✅ Address verification và ward lookup

Cấu trúc bài học (16 bài) ​

🎯 00. Case Study - Executive Summary ​

TL;DR cho Leaders và Stakeholders

  • Vấn đề kỹ thuật & giải pháp
  • Metrics & ROI
  • Lessons learned
  • Production deployment

Thời gian: 15-20 phút
Level: All levels
Format: Template-based case study

Phần 1: Foundations (Nền tảng) ​

01. Tổng quan hệ thống eKYC ​

  • Kiến trúc tổng thể
  • Stack công nghệ
  • Flow hoạt động cơ bản
  • Thách thức kỹ thuật

Thời gian: 15-20 phút
Level: Beginner
Mục tiêu: Hiểu big picture

02. Chi tiết từng bước trong flow ​

  • 5 steps: Preparation → Front → Back → Face → Review
  • State management
  • Step navigation
  • Auto-progression và validation

Thời gian: 30-40 phút
Level: Beginner → Intermediate
Mục tiêu: Hiểu flow chi tiết với code examples

Phần 2: MediaPipe & Camera (Core Implementation) ​

03. Giới thiệu MediaPipe FaceMesh ​

  • MediaPipe là gì?
  • Tại sao chọn MediaPipe?
  • Cách hoạt động (468 landmarks)
  • Configuration options
  • So sánh với alternatives

Thời gian: 25-30 phút
Level: Beginner
Mục tiêu: Hiểu MediaPipe fundamentals

04. Xây dựng MediaPipe Wrapper cho Vue ​

  • Vấn đề: Vue Proxy vs WASM
  • Architecture của wrapper class
  • Implementation chi tiết
  • Best practices
  • Full Vue component example

Thời gian: 45-60 phút
Level: Intermediate → Advanced
Mục tiêu: Master wrapper pattern

05. Camera Pipeline và Detection Loop ​

  • Camera access và permissions
  • Detection loop optimization (setInterval vs RAF)
  • Adaptive frame rate
  • Video processing và capture
  • UI feedback loop
  • Performance monitoring

Thời gian: 40-50 phút
Level: Intermediate
Mục tiêu: Master camera và detection pipeline

06a. Face Detection & Angle Calculation - Fundamentals ​

  • Face detection basics (ML, CNN, MediaPipe)
  • 468 landmarks explained
  • Toán học: Vector operations, Cross product, Normalization
  • Rotation matrix construction
  • Euler angles (Yaw, Pitch, Roll)
  • Step-by-step calculation với số cụ thể
  • Trích dẫn papers & books (MediaPipe, Three.js, Computer Vision)

Thời gian: 60-90 phút
Level: Beginner → Advanced
Mục tiêu: Hiểu toán học và ML đằng sau face detection

06b. Liveness Calculation và Anti-Spoofing ​

  • ✅ [THỰC TẾ] vs 💡 [ĐỀ XUẤT] code
  • Active liveness (face actions)
  • Frame stability check
  • Face distance check
  • Backend anti-spoofing
  • Validation thresholds
  • Complete UI flow

Thời gian: 35-45 phút
Level: Intermediate
Mục tiêu: Hiểu liveness workflow thực tế trong portal

07. Backend Integration: OCR & Face Verify APIs ​

  • API overview và architecture
  • OCR Front/Back APIs
  • Face Verify API
  • Check2FA và Ward Search
  • Error handling patterns
  • Timeout & retry strategies

Thời gian: 40-50 phút
Level: Intermediate
Mục tiêu: Master API integration

08a. Xử Lý Ward/District/Province ​

  • Data structure (wards.json)
  • Text normalization (remove diacritics)
  • Prefix extraction (Phường/Xã/Thị trấn)
  • Word boundary regex matching
  • Position-based priority
  • Duplicate removal
  • Complete algorithm với examples

Thời gian: 45-60 phút
Level: Advanced
Mục tiêu: Hiểu chi tiết xử lý địa chỉ Việt Nam

08b. Review Step: Check2FA và Ward Logic ​

  • Review step overview
  • Check2FA logic
  • Ward search flow
  • Address update warnings
  • UI implementation
  • Edge cases handling

Thời gian: 35-45 phút
Level: Intermediate
Mục tiêu: Implement review step correctly

09. I18n và UX Patterns ​

  • Internationalization setup
  • Locale management
  • UX patterns (loading, errors, empty states)
  • Mobile optimization
  • Accessibility (keyboard, ARIA, focus)
  • Performance UX

Thời gian: 30-40 phút
Level: Beginner → Intermediate
Mục tiêu: Polish UX và i18n

Phần 3: Vue Specific ​

10. MediaPipe với Vue: Ưu và Nhược điểm ​

  • ✅ Pros: Reactivity, Composition API, Template syntax
  • ❌ Cons: Proxy issues, Build complexity, Bundle size
  • So sánh với React
  • Recommendations
  • Best practices

Thời gian: 20-30 phút
Level: Intermediate
Mục tiêu: Hiểu trade-offs khi dùng Vue

Phần 4: Production Issues & Solutions ⚠️ ​

Quan trọng: Đây là phần khó nhất và quan trọng nhất!

11. Vấn đề Build Production ​

  • ❌ Triệu chứng: "FaceMesh is not a constructor"
  • 🔍 Root cause analysis
  • 📊 Debug process
  • 🧪 So sánh dev vs production
  • ⚠️ Tại sao chỉ xảy ra với MediaPipe?

Thời gian: 30-40 phút
Level: Advanced
Mục tiêu: Hiểu root cause của production bug

12. Giải pháp Workaround: Vite Plugin ​

  • ✅ Strategy: 3-Layer Defense
    • Layer 1: Flexible Import
    • Layer 2: Vite Plugin
    • Layer 3: Build Config
  • 🛠️ Implementation từng layer
  • ✅ Verification steps
  • 🐛 Troubleshooting
  • 💡 Alternative solutions

Thời gian: 60-90 phút
Level: Advanced
Mục tiêu: Implement và understand workaround

13. Tích hợp Thư viện - Flow Dữ liệu Chi tiết ​

  • Danh sách thư viện được sử dụng (MediaPipe, Three.js, Axios, Vue)
  • Flow dữ liệu chi tiết từ thư viện này sang thư viện khác
  • Code examples thực tế từ dự án Portal
  • Sơ đồ minh họa luồng xử lý
  • Data types & interfaces
  • Performance & optimization
  • Error handling patterns

Thời gian: 45-60 phút
Level: Intermediate → Advanced
Mục tiêu: Hiểu rõ cách các thư viện tương tác và dữ liệu được xử lý

Quick Start ​

Nếu bạn là Leader/Stakeholder ​

  1. 🎯 Case Study - TL;DR (vấn đề, giải pháp, metrics, ROI)

Nếu bạn mới bắt đầu ​

  1. Tổng quan hệ thống - Hiểu bức tranh tổng thể
  2. Chi tiết flow - Hiểu từng bước
  3. Giới thiệu MediaPipe - Hiểu MediaPipe
  4. Face Detection Fundamentals - Hiểu toán học và ML

Nếu bạn đang triển khai ​

  1. Wrapper class - Xây dựng wrapper
  2. Camera pipeline - Thiết lập camera
  3. Backend integration - Tích hợp API
  4. Review step - Triển khai bước xem lại
  5. I18n & UX - Hoàn thiện UX
  6. Library Integration - Hiểu flow dữ liệu giữa các thư viện

Nếu gặp lỗi production ​

  1. Production issue - Hiểu vấn đề
  2. Vite plugin fix - Áp dụng giải pháp

Nếu cần tối ưu hóa ​

  1. Camera pipeline - Tối ưu vòng lặp phát hiện
  2. Liveness calculation - Cải thiện độ chính xác
  3. I18n & UX - Hiệu suất UX
  4. Library Integration - Tối ưu flow dữ liệu

Prerequisites ​

Kiến thức cần có ​

  • ✅ Vue 3: Composition API, <script setup>, reactivity
  • ✅ TypeScript: Interfaces, types, generics
  • ✅ Vite: Cơ bản về công cụ build
  • ⚠️ WASM: Hiểu biết cơ bản (hữu ích)
  • ⚠️ Rollup: Quy trình bundle (hữu ích)

Môi trường ​

bash
Node.js: >= 18.x
npm: >= 9.x
Vue: 3.x
Vite: 5.x
TypeScript: >= 5.x

Key Takeaways ​

✅ Điểm mạnh ​

  1. MediaPipe: Độ chính xác cao, ưu tiên quyền riêng tư, miễn phí
  2. Vue 3: Reactivity tốt, template rõ ràng
  3. Wrapper pattern: Tách biệt WASM khỏi Vue Proxy
  4. 3-layer defense: Giải pháp mạnh mẽ cho production

⚠️ Điểm cần lưu ý ​

  1. Vấn đề Proxy: Không dùng ref/reactive với WASM
  2. Độ phức tạp build: Cần plugin Vite tùy chỉnh
  3. Kích thước bundle: ~7MB cho MediaPipe
  4. Kiểm thử production: Luôn kiểm thử build production!

🎯 Best Practices ​

typescript
// ✅ DO
let wrapper: MediaPipeFaceMeshWrapper | null = null;
wrapper = new MediaPipeFaceMeshWrapper();

// ❌ DON'T
const wrapper = ref(new MediaPipeFaceMeshWrapper());
typescript
// ✅ DO
if (videoRef.value) {
  wrapper.setVideoElement(videoRef.value);
}

// ❌ DON'T
wrapper.setVideoElement(toRaw(videoRef));
bash
# ✅ DO
npm run build-production
npm run preview:proxy
# Test thoroughly before deploy

# ❌ DON'T
npm run dev  # Only test dev
git push     # Deploy without testing prod

Tham khảo nhanh xử lý sự cố ​

Vấn đềGiải phápLiên kết
Cần tóm tắt điều hànhĐọc case study trước#00
FaceMesh không phải constructorÁp dụng 3-layer defense#12
Module không tìm thấyKiểm tra đường dẫn locateFile#03
Lỗi Vue ProxyDùng wrapper class#04
Kích thước build quá lớnKiểm tra manualChunks#12
Camera không hoạt độngKiểm tra quyền#04
Không tìm thấy phường/xãKiểm tra chuẩn hóa + regex#08a
Nhiều phường/xã được trả vềKiểm tra ranh giới từ#08a
Phát hiện khuôn mặt không ổn địnhĐiều chỉnh ngưỡng#06b
Không hiểu toán họcĐọc fundamentals trước#06a
Không hiểu flow dữ liệuĐọc library integration#13

Kho lưu trữ ví dụ code ​

Tất cả ví dụ trong docs đều dựa trên code thực tế từ:

Frontend:

  • portal-client/src/pages/information/directive/EkycSettingEnhanced.vue
  • portal-client/src/utils/ekyc/MediaPipeFaceMeshWrapper.ts
  • portal-client/vite.config.ts
  • portal-client/mediaPipePlugin.ts

Backend:

  • portal-server/src/services/client/EkycService.ts
  • portal-server/src/services/client/WardService.ts
  • portal-server/src/utils/MyFunction.ts (normalizeVietnameseText)
  • portal-server/src/utils/wards.json

Phản hồi & Đóng góp ​

Tài liệu này được viết dựa trên kinh nghiệm thực tế khi triển khai eKYC.

Nếu bạn:

  • ❓ Có câu hỏi
  • 🐛 Tìm thấy lỗi
  • 💡 Có ý tưởng cải thiện
  • ✅ Muốn bổ sung

→ Liên hệ team hoặc tạo issue.

Giấy phép ​

Tài liệu nội bộ cho dự án portal iNET.

Happy coding! 🚀

Documentation này được viết dựa trên kinh nghiệm thực tế khi implement eKYC.

Nếu bạn:

  • ❓ Có câu hỏi
  • 🐛 Tìm thấy lỗi
  • 💡 Có ý tưởng cải thiện
  • ✅ Muốn bổ sung

→ Contact team hoặc tạo issue.

License ​

Internal documentation for iNET portal project.

Happy coding! 🚀

Internal documentation for iNET Portal

Copyright © 2025 iNET