URD: Thiết bị
| Module | CORE-04 | Phiên bản | v0.1 |
|---|---|---|---|
| Trạng thái | In-progress | Ngày | 2026-02-28 |
1. Mục đích
Tài liệu này định nghĩa các yêu cầu hướng người dùng cho Quản lý thiết bị và tích hợp phần cứng. Nó bao quát cách một tổ chức đăng ký, quản lý và giám sát thiết bị vật lý (máy POS, ứng dụng di động, client web), và cách nền tảng tích hợp thiết bị ngoại vi (máy in, máy quét mã vạch, SoundBox, SoftPOS/NFC, màn hình phụ).
2. Phạm vi
| Bao gồm | Loại trừ |
|---|---|
| Đăng ký, vòng đời, tìm kiếm, soft-delete thiết bị | Đấu nối backend VNPAY Terminal (bảng đã có, API chưa kết nối — phát hiện QE) |
| Thông tin phần cứng / phần mềm / bảo trì | Tích hợp máy in nhãn (Dự kiến) |
Định danh thiết bị (machine UID, header x-device-info) | Máy POS Windows (Dự kiến) |
| Ứng dụng di động, web, máy POS + chế độ offline | Ứng dụng màn hình bếp, phục vụ, giao hàng (Dự kiến) |
| Máy in (USB/mạng, ESC/POS), máy quét (HID/camera) | Điều khiển ngăn kéo đựng tiền (Dự kiến) |
| SoundBox, SoftPOS/NFC, màn hình phụ | Đặc tả API kỹ thuật |
| Heartbeat / giám sát tình trạng, vô hiệu hóa từ xa | Nội bộ cổng thanh toán (xem URD Thanh toán) |
| Nhập/xuất CSV; truy cập theo vai trò | — |
3. Định nghĩa
| Thuật ngữ | Định nghĩa |
|---|---|
| Device | Một đơn vị phần cứng đã đăng ký (máy POS, thiết bị di động, máy trạm) tương tác với nền tảng |
| Device Identifier | Chuỗi định danh duy nhất do hệ thống sinh D_YYYYMMDD_<snowflakeId>, gán khi đăng ký |
| Device Code | Mã dễ đọc tùy chọn, duy nhất trong tổ chức |
| Organization | Cấp cao nhất sở hữu một hoặc nhiều merchant và thiết bị |
| Merchant | Một đơn vị kinh doanh trong tổ chức; thiết bị có thể được gán tùy chọn vào một merchant |
| Hardware Info | Nhà sản xuất, mẫu mã, số serial, IMEI, MAC, bộ xử lý, RAM, lưu trữ, màn hình, pin |
| Software Info | Hệ điều hành, phiên bản OS, phiên bản app, firmware, lần cập nhật cuối, driver thiết bị ngoại vi |
| Device Status | Trạng thái vòng đời: NEW → ACTIVATED → DEACTIVATED → SUSPENDED → ARCHIVED |
| Heartbeat | Ping online định kỳ (mỗi 5 phút); offline sau 15 phút im lặng |
| Machine UID | Định danh suy ra từ phần cứng, gửi trong header HTTP x-device-info |
| ESC/POS | Ngôn ngữ lệnh máy in nhiệt; hỗ trợ tiếng Việt qua code page 28 |
| HID Keyboard-Wedge | Chế độ máy quét USB/Bluetooth mô phỏng nhập liệu bàn phím |
| SoftPOS | Chấp nhận thẻ không tiếp xúc NFC trên điện thoại Android, kích hoạt qua VNPAY KYC |
| SoundBox | Loa Bluetooth VNPAY phát thông báo xác nhận thanh toán |
| POS Point | Trạm bán hàng logic mà thiết bị phải được gán vào trước khi xử lý bán hàng |
4. Mô hình Khái niệm
Chỉ mang tính khái niệm — schema đầy đủ nằm trong mô hình miền Commerce.
5. Yêu cầu Chức năng
Mỗi vùng chức năng một bảng. Mã
<AREA>khớp với ID test-case. Mức ưu tiên = MoSCoW (Must / Should / Could / Won't).
5.1 Đăng ký & Quản lý Thiết bị (DEV)
| ID | P | Yêu cầu |
|---|---|---|
| URD-DEV-001 | M | Chủ sở hữu có thể đăng ký thiết bị với tên, loại và gán tổ chức |
| URD-DEV-002 | M | Hệ thống tự sinh Device Identifier duy nhất D_YYYYMMDD_<snowflakeId> khi đăng ký |
| URD-DEV-003 | M | Tên thiết bị hỗ trợ i18n (tiếng Anh + tiếng Việt) |
| URD-DEV-004 | M | Trạng thái thiết bị theo vòng đời NEW → ACTIVATED → DEACTIVATED → SUSPENDED → ARCHIVED; chỉ cho phép chuyển trạng thái hợp lệ |
| URD-DEV-005 | M | Chủ sở hữu có thể kích hoạt thiết bị đã đăng ký (NEW → ACTIVATED) |
| URD-DEV-006 | M | Chủ sở hữu có thể vô hiệu hóa (ACTIVATED → DEACTIVATED) và kích hoạt lại (DEACTIVATED → ACTIVATED) thiết bị |
| URD-DEV-007 | M | Chủ sở hữu có thể tạm ngưng thiết bị (ACTIVATED → SUSPENDED) vì lý do bảo mật |
| URD-DEV-008 | M | Chủ sở hữu có thể lưu trữ thiết bị (chỉ đọc vĩnh viễn, ẩn khỏi POS) |
| URD-DEV-009 | M | Mọi bản ghi thiết bị dùng soft-delete; không bao giờ xóa vật lý |
| URD-DEV-010 | M | Truy cập API thiết bị yêu cầu xác thực (JWT hoặc Basic Auth) |
| URD-DEV-011 | M | Mã thiết bị, khi được cung cấp, phải duy nhất trong tổ chức |
| URD-DEV-012 | S | Chủ sở hữu có thể ghi thông tin bảo trì (ngày mua, hết hạn bảo hành, ngày bảo trì, ghi chú) |
| URD-DEV-013 | M | Thiết bị được tự đăng ký và kích hoạt khi đăng nhập app lần đầu; thiết bị đã tồn tại được tái sử dụng |
| URD-DEV-014 | M | Chủ sở hữu có thể tìm thiết bị theo tên, định danh, mã, trạng thái và loại |
| URD-DEV-015 | S | Chủ sở hữu có thể nhập và xuất bản ghi thiết bị qua CSV |
| URD-DEV-016 | M | Chủ sở hữu có thể gán / hủy gán thiết bị vào merchant; việc gán là tùy chọn |
| URD-DEV-017 | S | Chủ sở hữu có thể ghi thông tin phần cứng cho thiết bị |
| URD-DEV-018 | S | Chủ sở hữu có thể ghi thông tin phần mềm cho thiết bị |
| URD-DEV-019 | S | Chủ sở hữu có thể đặt mã PIN trên thiết bị để xác thực cục bộ |
Trạng thái Thiết bị
| Trạng thái | Ý nghĩa |
|---|---|
| NEW | Đã đăng ký, chưa kích hoạt (mặc định) |
| ACTIVATED | Hoạt động và được phép xử lý giao dịch |
| DEACTIVATED | Tạm vô hiệu hóa; có thể kích hoạt lại |
| SUSPENDED | Tạm ngưng chờ điều tra; không thể giao dịch |
| ARCHIVED | Ngừng vĩnh viễn; chỉ đọc |
Loại Thiết bị
| Mã loại | Nhãn |
|---|---|
| 100_POS_TERMINAL | Máy POS |
| 101_POS_WORKSTATION | Máy trạm POS |
| 200_MOBILE_POS | POS Di động |
| 400_TABLET | Máy tính bảng |
| 401_BARCODE_SCANNER | Thiết bị máy quét mã vạch |
| 999_OTHER | Khác |
5.2 Ứng dụng Di động (MOB)
Ứng dụng iOS/Android xây bằng Tauri; ứng dụng chính cho chủ sở hữu và thu ngân.
| ID | P | Yêu cầu |
|---|---|---|
| URD-MOB-001 | M | Ứng dụng có sẵn trên iOS 14+ và Android 8+ |
| URD-MOB-002 | M | Chủ sở hữu có thể đăng nhập và truy cập POS, đơn hàng, thanh toán, lập hóa đơn và báo cáo |
| URD-MOB-003 | M | Thu ngân có thể đăng nhập và truy cập màn hình POS (màn hình chỉ dành cho chủ sở hữu bị hạn chế) |
| URD-MOB-004 | S | Ứng dụng hỗ trợ kết nối thiết bị ngoại vi Bluetooth (máy quét, máy in, SoundBox) |
| URD-MOB-005 | S | Ứng dụng hỗ trợ chế độ offline: giao dịch được lưu cục bộ và đồng bộ khi kết nối lại |
| URD-MOB-006 | M | Đăng nhập tạo một phiên thiết bị liên kết với bản ghi thiết bị (tự đăng ký nếu mới) |
5.3 Ứng dụng Web (WEB)
| ID | P | Yêu cầu |
|---|---|---|
| URD-WEB-001 | M | Ứng dụng web chạy trên trình duyệt hiện đại (Chrome, Edge, Firefox, Safari) |
| URD-WEB-002 | M | Ứng dụng web cung cấp đầy đủ quản lý back-office (thiết bị, sản phẩm, đơn hàng, báo cáo, cài đặt) |
| URD-WEB-003 | S | Ứng dụng web hỗ trợ chế độ Web POS cơ bản |
| URD-WEB-004 | M | Ứng dụng web bắt buộc HTTPS và hết hạn phiên/đăng xuất |
| URD-WEB-005 | S | Ứng dụng web dùng được ở chiều rộng 1024px+; cảnh báo dưới mức tối thiểu |
5.4 Máy POS (POS)
Phần cứng Android chuyên dụng chạy ứng dụng POS toàn màn hình với thiết bị ngoại vi tích hợp.
| ID | P | Yêu cầu |
|---|---|---|
| URD-POS-001 | M | Ứng dụng POS chạy trên Android 8+ với ≥2 GB RAM và ≥16 GB lưu trữ |
| URD-POS-002 | M | Thiết bị phải được gán vào một POS Point trước khi xử lý bán hàng; một phiên hoạt động trên mỗi thiết bị |
| URD-POS-003 | M | Ứng dụng POS hỗ trợ thiết bị ngoại vi tích hợp sẵn (đầu đọc thẻ, máy in, máy quét, ngăn kéo tiền) khi có |
| URD-POS-004 | S | Ứng dụng POS chạy trên phần cứng được chứng nhận (VNPAY V-POS, Sunmi T2) |
| URD-POS-005 | M | Ứng dụng POS hỗ trợ thiết lập thiết bị ngoại vi qua Cài đặt > Thiết bị |
5.5 Máy in (PRN)
Máy in nhiệt USB (Tauri/WebUSB) và mạng (WebSocket); ESC/POS với code page 28 tiếng Việt.
| ID | P | Yêu cầu |
|---|---|---|
| URD-PRN-001 | M | Hệ thống kết nối máy in qua Bluetooth, USB và mạng |
| URD-PRN-002 | M | Hệ thống phát hiện máy in USB qua USB class code 0x07 |
| URD-PRN-003 | M | Engine ESC/POS in chữ, hình ảnh nhúng, mã QR và mã vạch |
| URD-PRN-004 | M | Markup ESC/POS hỗ trợ căn lề, in đậm, gạch chân, cỡ chữ, mã vạch, QR, hình ảnh |
| URD-PRN-005 | M | Hệ thống raster nội dung PDF bằng Floyd–Steinberg dithering cho đầu ra in nhiệt |
| URD-PRN-006 | M | Ký tự tiếng Việt in đúng qua code page 28 |
| URD-PRN-007 | M | Hệ thống hỗ trợ khổ giấy 58mm và 80mm, cấu hình theo từng máy in |
| URD-PRN-008 | S | Hệ thống hỗ trợ tự cắt giấy và ngăn kéo tiền kích hoạt khi in |
| URD-PRN-009 | S | Lệnh kích hoạt ngăn kéo tiền được gửi qua máy in khi thanh toán tiền mặt |
| URD-PRN-010 | M | Vòng đời in (kết nối, ngắt kết nối, gửi lệnh) hiển thị lỗi rõ ràng khi thất bại; không âm thầm bỏ qua |
| URD-PRN-011 | S | Hệ thống kết nối máy in mạng qua WebSocket và xử lý ngắt kết nối một cách mượt mà |
| URD-PRN-012 | M | Hệ thống dự phòng sang WebUSB khi plugin USB Tauri không khả dụng |
5.6 Máy quét Mã vạch (SCN)
HID keyboard-wedge (USB/Bluetooth) và quét camera/QR di động đối chiếu với Product Identifier.
| ID | P | Yêu cầu |
|---|---|---|
| URD-SCN-001 | M | Hệ thống tự bắt input máy quét HID keyboard-wedge (không có giao diện ghép nối) |
| URD-SCN-002 | M | Input máy quét phải dài 10–20 ký tự, hoàn tất trong timeout phím 100ms |
| URD-SCN-003 | M | Phím Enter (hoặc dừng 100ms) kích hoạt quét và tra cứu |
| URD-SCN-004 | M | Máy quét QR bằng camera khả dụng trên di động qua plugin barcode Tauri |
| URD-SCN-005 | M | Khi quét thành công trên màn hình POS, sản phẩm khớp được thêm vào giỏ hàng |
| URD-SCN-006 | S | Hệ thống hỗ trợ định dạng 1D (EAN-13/8, UPC-A/E, Code 128/39) và 2D (QR, Data Matrix) |
| URD-SCN-007 | S | Quét hoạt động trong nhiều ngữ cảnh (tìm sản phẩm, tra cứu hóa đơn) |
5.7 SoundBox (SBX)
Loa Bluetooth VNPAY phát xác nhận thanh toán bằng tiếng Việt/tiếng Anh, ghép nối theo từng thiết bị.
| ID | P | Yêu cầu |
|---|---|---|
| URD-SBX-001 | M | Hệ thống ghép nối VNPAY SoundBox (V1/V2) với thiết bị qua Bluetooth |
| URD-SBX-002 | M | Khi xác nhận thanh toán, hệ thống kích hoạt thông báo giọng nói; nếu mất kết nối, thanh toán vẫn thành công (không có lỗi chặn) |
| URD-SBX-003 | M | Ngôn ngữ thông báo theo cấu hình (tiếng Việt / tiếng Anh), gồm số tiền và phương thức |
| URD-SBX-004 | S | Trạng thái LED của SoundBox phản ánh trạng thái: xanh nhấp nháy (ghép nối), xanh sáng đều (đã kết nối), xanh lá (thành công), đỏ (lỗi/pin yếu) |
| URD-SBX-005 | S | Người dùng có thể cấu hình âm lượng (1–10) và bật/tắt việc đọc số tiền / phương thức |
| URD-SBX-006 | S | SoundBox hoạt động trong phạm vi Bluetooth định mức (~10 m); ngoài phạm vi, mất kết nối được xử lý mượt mà |
5.8 SoftPOS / NFC (NFC)
Chấp nhận NFC không tiếp xúc trên Android qua VNPAY; yêu cầu KYC. Planned
| ID | P | Yêu cầu |
|---|---|---|
| URD-NFC-001 | M | Hệ thống kiểm tra phần cứng NFC khả dụng trước khi bật SoftPOS |
| URD-NFC-002 | M | SoftPOS yêu cầu kích hoạt VNPAY KYC trước lần dùng đầu tiên |
| URD-NFC-003 | M | Kích hoạt SoftPOS bị chặn khi NFC không khả dụng hoặc bị tắt, kèm thông báo rõ ràng |
| URD-NFC-004 | S | SoftPOS chỉ dành cho Android; tùy chọn bị ẩn trên iOS |
5.9 Định danh & Giám sát Tình trạng Thiết bị (MON)
| ID | P | Yêu cầu |
|---|---|---|
| URD-MON-001 | M | Thiết bị đang hoạt động gửi heartbeat mỗi 5 phút; nền tảng ghi lại hoạt động cuối |
| URD-MON-002 | M | Nền tảng đánh dấu thiết bị offline sau 15 phút không có heartbeat; online lại ở ping kế tiếp |
| URD-MON-003 | M | Quản trị viên có thể xem tình trạng thiết bị (online/offline, lần thấy cuối, phiên bản app) và lọc theo trạng thái |
| URD-MON-004 | M | Hệ thống có thể vô hiệu hóa thiết bị từ xa và thu hồi phiên đang hoạt động của nó |
| URD-MON-005 | S | Hệ thống hỗ trợ xóa dữ liệu từ xa cho thiết bị bị xâm phạm (xếp hàng nếu offline) |
6. Tiêu chí Chấp nhận
AC-DEV-01: Đăng ký
| Cho | Khi | Thì |
|---|---|---|
| Chủ sở hữu | Đăng ký thiết bị với tên + loại + tổ chức | Thiết bị được tạo với trạng thái NEW; định danh duy nhất tự sinh |
| Có mã được cung cấp | Mã duy nhất trong tổ chức |
AC-MON-01: Giám sát Tình trạng
| Cho | Khi | Thì |
|---|---|---|
| Thiết bị đang hoạt động | Gửi heartbeat | Dấu thời gian hoạt động cuối được cập nhật |
| Không có heartbeat trong 15 phút | Thiết bị bị đánh dấu offline | |
| Admin xem danh sách thiết bị | Trạng thái online/offline hiển thị |
AC-PRN-01: In Hóa đơn
| Cho | Khi | Thì |
|---|---|---|
| Máy in đã ghép nối | Giao dịch hoàn tất | Hóa đơn được in (tự động hoặc thủ công) |
| In thất bại | Hiển thị lỗi kèm tùy chọn thử lại | |
| Nội dung tiếng Việt | Code page 28 được đặt tự động |
AC-SCN-01: Quét Mã vạch
| Cho | Khi | Thì |
|---|---|---|
| Máy quét HID | Quét một mã vạch | Sản phẩm được tra cứu và thêm vào giỏ hàng |
| Máy quét camera (di động) | Quét một mã QR | Sản phẩm/hóa đơn được tra cứu |
| Mã vạch không xác định | Quét | Hiển thị thông báo lỗi rõ ràng |
AC-SBX-01: Xác nhận SoundBox
| Cho | Khi | Thì |
|---|---|---|
| SoundBox đã ghép nối | Thanh toán được xác nhận | Số tiền + phương thức được đọc bằng ngôn ngữ đã cấu hình |
| SoundBox mất kết nối | Thanh toán được xác nhận | Thanh toán vẫn thành công; thông báo bị bỏ qua âm thầm |
7. Ràng buộc & Mục tiêu Loại trừ
Ràng buộc
| ID | Ràng buộc |
|---|---|
| C-01 | Mọi thiết bị phải được đăng ký trước khi có thể vận hành |
| C-02 | Thiết bị phải được gán vào một POS Point trước khi xử lý bán hàng |
| C-03 | Chỉ cho phép một phiên hoạt động trên mỗi thiết bị tại một thời điểm |
| C-04 | Device Identifier được tự sinh và bất biến |
| C-05 | Mã thiết bị phải duy nhất trong tổ chức |
| C-06 | Mọi bản ghi thiết bị dùng soft-delete |
| C-07 | Chuyển trạng thái theo vòng đời đã định nghĩa; chuyển trạng thái không hợp lệ bị từ chối |
| C-08 | SoftPOS chỉ dành cho Android và yêu cầu VNPAY KYC |
| C-09 | Mỗi POS nên có đúng một máy in mặc định |
| C-10 | Số thiết bị tối đa cho mỗi tổ chức do operator cấu hình |
| C-11 | Heartbeat mỗi 5 phút; ngưỡng offline là 15 phút |
| C-12 | Input máy quét HID phải dài 10–20 ký tự trong timeout 100ms |
| C-13 | Code page 28 (tiếng Việt) của máy in USB được đặt tự động khi kết nối |
Mục tiêu Loại trừ
- Đấu nối API backend VNPAY Terminal (bảng đã có, chưa kết nối backend — phát hiện QE)
- Tích hợp máy in nhãn; hỗ trợ máy POS Windows
- Ứng dụng chuyên biệt cho màn hình bếp, phục vụ, giao hàng và kho
- Điều khiển ngăn kéo tiền; giao diện quản lý driver thiết bị ngoại vi nâng cao
- Đặc tả API kỹ thuật và chi tiết tích hợp cổng thanh toán
8. Lịch sử Phiên bản
| Ngày | Tác giả | Mô tả | Ver |
|---|---|---|---|
| 2026-02-28 | Q. Do - QE | URD ban đầu từ phân tích mức mã nguồn và tài liệu | v0.1 |