BÁO CÁO KỸ THUẬT: MINI-PROJECT 1

HỆ THỐNG PWA & NATIVE ANDROID KHẢO SÁT HIỆN TRƯỜNG CƠ SỞ VẬT CHẤT VKU

(OFFLINE-FIRST FACILITY INSPECTION WITH CAPACITOR BRIDGE)

Đơn vị thực hiện: Khoa Khoa học Máy tính · VKU

Học phần: Phát triển Ứng dụng Di động Hiện đại

Kiến trúc cốt lõi: Offline-First PWA, IndexedDB, Capacitor Bridge

Nền tảng mục tiêu: Web HTTPS (Cloudflare/Vercel) & Android APK

1. Tổng quan & Mục tiêu Kỹ thuật (Executive Summary)

Mục tiêu của dự án là xây dựng một hệ thống phần mềm khảo sát và kiểm tra cơ sở vật chất (phòng thực hành lab, giảng đường, điều hòa, PCCC, điện chiếu sáng) dành cho cán bộ Đại học Công nghệ Thông tin và Truyền thông Việt - Hàn (VKU) hoạt động hoàn hảo trong điều kiện không có kết nối mạng (Zero Network Connectivity) như tầng hầm, phòng kín cách âm hoặc sự cố đứt cáp viễn thông.

Nguyên tắc "Local-First / Zero Data Loss": Mọi biên bản kiểm tra, ảnh hiện trường và chữ ký điện tử đều được xác thực và cam kết vào cơ sở dữ liệu IndexedDB trên thiết bị trước. Quá trình gửi lên Cloud chỉ đóng vai trò đồng bộ hóa thứ cấp khi có Internet.

2. Kiến trúc Hệ thống & Luồng Dữ liệu (System Architecture)

+-----------------------------------------------------------------------------------+ | VKU FIELD SURVEY PWA & CAPACITOR ANDROID CLIENT | | | | [Inspector Auth] [Facility Form] [Watermark Camera] [Digital Signature Pad] | | | | | | | | +-----------------+------------------+---------------------+ | | | (Local Transaction) | | v | | [IndexedDB Client Store: "vku_survey_db"] | | Status: pending | syncing | synced | error | +------------------------------------+----------------------------------------------+ | Auto-Sync / Retry Queue (Online Event Listener) | v +------------------------------------+----------------------------------------------+ | CLOUD BACKEND INFRASTRUCTURE | | | | [Google Apps Script Gateway] ---> [Google Sheets: CSDL (19 Cột dữ liệu chuẩn)] | | \--> [Google Drive: Lưu ảnh hiện trường minh chứng] | | | | [Vercel / Cloudflare Pages]: Cung cấp Host HTTPS PWA, Service Worker Cache Shell | +-----------------------------------------------------------------------------------+

Hệ thống bao gồm 3 tầng kiến trúc độc lập:

Tầng Ứng dụng Thiết bị (Client Tier): Chạy dưới dạng PWA trên trình duyệt hoặc Android APK đóng gói qua Capacitor. Sử dụng Service Worker (`sw.js`) để cache 100% App Shell (HTML, CSS, JS, Manifest, Icons).
Tầng Lưu trữ Cục bộ (Persistence Tier): Cơ sở dữ liệu NoSQL IndexedDB (`vku_survey_db`) lưu trữ các đối tượng biên bản kiểm tra kèm payload Base64 ảnh và chữ ký.
Tầng Đám mây (Cloud Tier): Google Apps Script Web App tiếp nhận dữ liệu đồng bộ, trích xuất ảnh vào Google Drive và ghi thông tin vào Google Sheets.

3. Cơ chế Ngoại tuyến & Chiến lược Đồng bộ (Offline-First Sync)

Hệ thống áp dụng mô hình Event-Driven Asynchronous Queue đảm bảo tính toàn vẹn và chống nghẽn dữ liệu:

Trạng thái (Status)	Hành vi Kỹ thuật	Biện pháp Xử lý Sự cố
`pending`	Biên bản vừa lưu vào IndexedDB khi thiết bị ngoại tuyến hoặc đang xếp hàng chờ.	Lưu vĩnh viễn trên máy, hiển thị cảnh báo số lượng phiên chờ đồng bộ.
`syncing`	Đang gửi HTTP POST tới Google Apps Script với Timeout 30 giây.	Nếu tắt app đột ngột, cơ chế phục hồi (Recovery) tự đưa về `pending` khi mở lại.
`synced`	Máy chủ trả về kết quả `{ result: "ok" }`, đã ghi vào Google Sheets và Drive.	Khóa biên bản, lưu thời gian `syncedAt` và mở tính năng in biên bản PDF.
`error`	Lỗi mạng (Timeout, HTTP 500, đứt kết nối).	Tăng `retryCount`, ghi nhận `lastError`, sẵn sàng thử lại tự động hoặc thủ công.

3.1. Tính Idempotent & Chống Trùng lặp (De-duplication)

Mỗi biên bản kiểm tra sở hữu một khóa chính duy nhất `sessionId` dạng `S-FAC-XXXX` sinh ngẫu nhiên từ timestamp và chuỗi ngẫu nhiên Base36. Phía Google Apps Script kiểm tra hàm `findSessionRow_(sheet, payload.sessionId)`. Nếu phát hiện phiên đã tồn tại, hệ thống trả về mã thành công mà không ghi trùng hàng vào Sheets.

4. Minh chứng Thực địa: GPS, Watermarking & Chữ ký Số

Để đáp ứng tính pháp lý và độ chính xác trong kiểm tra cơ sở vật chất thực địa, hệ thống tích hợp 3 tính năng chuyên nghiệp:

Tọa độ GPS & Đo khoảng cách Campus: Ứng dụng dùng Geolocation API lấy tọa độ vệ tinh thực địa, tự động đo khoảng cách tới tọa độ trung tâm trường VKU (15.9753° N, 108.2523° E) qua công thức Haversine để xác thực cán bộ có mặt đúng khuôn viên trường.
Nén ảnh & Đóng dấu Watermark thời gian thực: Ảnh chụp từ hiện trường được giảm độ phân giải xuống tối đa 1280px bằng HTML5 Canvas và nén JPEG (chất lượng 0.78, dung lượng dưới 1.2MB). Hệ thống trực tiếp vẽ watermark (Mã phòng + Thời gian + Tọa độ GPS) lên góc ảnh trước khi chuyển sang Base64.
Chữ ký điện tử Canvas (Digital Signature Pad): Cán bộ kiểm tra ký tên xác nhận trực tiếp bằng ngón tay hoặc bút cảm ứng trên màn hình. Chữ ký được vector hóa và lưu trữ kèm biên bản.

5. Xác thực Cán bộ Ngoại tuyến (Offline Authentication)

Hệ thống trang bị module Đăng nhập phục vụ cán bộ thanh tra VKU hoạt động độc lập cả khi mất mạng:

Hỗ trợ đăng nhập bằng Email cán bộ (`canbo.csvc@vku.udn.vn`), mã PIN 4 chữ số hoặc 3 tài khoản Demo một chạm đại diện cho các phòng ban (Quản trị Thiết bị, Lab Mạng, Thanh tra PCCC).
Thông tin xác thực và hồ sơ cán bộ được mã hóa và lưu vào bộ nhớ cục bộ (`localStorage`), cho phép đăng nhập ngay cả khi điện thoại bật Chế độ Máy bay (Airplane Mode).

6. Đóng gói Android APK qua Capacitor Bridge (Bonus / Next Week)

Hệ thống đáp ứng trọn vẹn yêu cầu đóng gói Native Mobile cho hệ điều hành Android bằng cách thiết lập Capacitor Native Bridge (v8.5.2):

Cấu hình Capacitor Bridge:
• Mã ứng dụng (App ID): com.vku.fieldsurvey
• Tên ứng dụng: VKU Field Survey
• Thư mục Web mục tiêu: www/ (Biên dịch bởi Vite)
• Plugins Native tích hợp: @capacitor/camera, @capacitor/filesystem, @capacitor/core.

6.1. Quy trình Build Tự động

Dự án đã tích hợp các lệnh build tự động trong `package.json`:

$ npm run build --> Vite bundles HTML/CSS/JS thành tài nguyên web production tại www/ $ npm run cap:sync --> Capacitor đồng bộ asset sang android/app/src/main/assets/public/ $ npm run build:apk --> Gradle (Java 21) biên dịch thành file APK: android/app/build/outputs/apk/debug/app-debug.apk (8.27 MB)

7. Đánh giá Hiệu năng & Kết quả Kiểm thử (Test Results)

Kịch bản Kiểm thử	Điều kiện Môi trường	Kết quả Kỳ vọng	Trạng thái Thực tế
Mở ứng dụng lần đầu khi có mạng	4G / Wi-Fi	Service Worker cache toàn bộ App Shell trong 1.5s	ĐẠT (Passed)
Mở ứng dụng khi bật Airplane Mode	Ngoại tuyến hoàn toàn (0 KB/s)	Giao diện tải tức thì từ Cache, banner Offline xuất hiện	ĐẠT (Passed)
Nhập form, chụp ảnh, ký tên và gửi	Ngoại tuyến hoàn toàn	Biên bản lưu vào IndexedDB trong < 80ms, trạng thái Pending	ĐẠT (Passed)
Tắt Airplane Mode (kết nối lại mạng)	Chuyển từ Offline sang Online	Sự kiện `online` kích hoạt, tự động đẩy dữ liệu lên Sheets	ĐẠT (Passed)
Cài đặt và khởi chạy trên Android APK	Thiết bị Android 11 - 15	Ứng dụng chạy mượt mà, camera native hoạt động ổn định	ĐẠT (Passed)

8. Hướng dẫn Triển khai Trực tiếp (Live HTTPS Deployment)

Ứng dụng được đóng gói sẵn cấu hình cho cả Vercel và Cloudflare Pages:

Triển khai Vercel: Chạy lệnh npx vercel --prod hoặc kết nối GitHub repo `TrLy24/vku-field-survey-pwa`. File `vercel.json` đã cấu hình tối ưu header PWA `Cache-Control` và `Service-Worker-Allowed`.
Triển khai Cloudflare Pages: Chọn framework build `Vite`, Build command: `npm run build`, Output directory: `www`. File `public/_headers` tự động cấu hình các tham số bảo mật.

Người lập báo cáo:

Nhóm Sinh viên Khảo sát Thực địa VKU

Xác nhận của Giảng viên / Hội đồng:

Khoa Khoa học Máy tính · Trường ĐH CNTT&TT Việt - Hàn