URD: Thiết bị
| Module | CORE-04 | Phiên bản | v0.3 |
|---|---|---|---|
| Trạng thái | In-progress | Ngày | 2026-06-15 |
Tài liệu nghiệp vụ. URD này là danh sách tính năng của Thiết bị - mỗi tính năng bên dưới là một Vùng Chức năng (
<AREA>). Cùng mã<AREA>đó định danh PRD (PRD-<AREA>-NNN) và test (TC-<AREA>-NNN) của tính năng, và mỗi tính năng được liệt kê trong danh mục tính năng Delivery. Xem quy ước Feature Spine.
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. Danh mục Tính năng
Danh sách tính năng của module này. Mỗi dòng là một tính năng (một Vùng Chức năng). Chi tiết tại §6. Phản chiếu trong danh mục tính năng Delivery.
| Feature ID | Tính năng | Phase | Trạng thái | Ưu tiên |
|---|---|---|---|---|
DEV | Đăng ký & Quản lý Thiết bị | P2 | In-progress | High |
MOB | Ứng dụng Di động | P1 | Built | High |
WEB | Ứng dụng Web | P1 | Built | High |
POS | Máy POS | P2 | In-progress | High |
PRN | Máy in | P2 | In-progress | High |
SCN | Máy quét Mã vạch | P2 | In-progress | High |
SBX | SoundBox | P1 | Built | High |
NFC | SoftPOS / NFC | P3 | Planned | High |
DSX | Ca làm việc theo Thiết bị & Liên kết Máy in | P2 | Built | High |
MON | Định danh & Giám sát Tình trạng Thiết bị | P2 | In-progress | High |
Trạng thái: live từ Plane nếu có map, còn lại do registry khai báo. Vocabulary đồng nhất với Plane (state-group / phase).
6. Tính năng
Mỗi tính năng một mục con, theo thứ tự danh mục. Mỗi tính năng giữ phần mô tả, yêu cầu và tiêu chí chấp nhận cùng nhau. Mức ưu tiên = MoSCoW (Must / Should / Could / Won't).
DEV - Đăng ký & Quản lý Thiết bị In-progress
Mã Tính năng: device/DEV · Phase: P2 · PRDs: - · Dev: @nx/commerce
Tính năng này mang lại gì cho người dùng: chủ sở hữu đăng ký từng thiết bị phần cứng với tên i18n, loại và tổ chức; đưa nó qua một vòng đời trạng thái; ghi nhận chi tiết phần cứng, phần mềm và bảo trì; và tìm kiếm, nhập, xuất danh sách thiết bị của mình.
Yêu cầu
| 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 |
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 |
MOB - Ứng dụng Di động Built
Mã Tính năng: device/MOB · Phase: P1 · PRDs: - · Dev: sale-renderer
Tính năng này mang lại gì cho người dùng: chủ sở hữu và thu ngân chạy POS, đơn hàng, thanh toán, lập hóa đơn và báo cáo trên ứng dụng iOS/Android xây bằng Tauri, với thiết bị ngoại vi Bluetooth và chế độ offline đồng bộ khi kết nối lại.
Ứng dụng iOS/Android xây bằng Tauri; ứng dụng chính cho chủ sở hữu và thu ngân.
Yêu cầu
| 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) |
Chấp nhận
AC-MOB-01: Đăng nhập & phiên di động
| Cho | Khi | Thì |
|---|---|---|
| Chủ sở hữu hoặc thu ngân trên iOS 14+ / Android 8+ | Đăng nhập vào ứng dụng | Một phiên thiết bị được tạo và liên kết với bản ghi thiết bị (tự đăng ký nếu mới) |
WEB - Ứng dụng Web Built
Mã Tính năng: device/WEB · Phase: P1 · PRDs: - · Dev: client
Tính năng này mang lại gì cho người dùng: chủ sở hữu chạy quản lý back-office đầy đủ - thiết bị, sản phẩm, đơn hàng, báo cáo, cài đặt - và Web POS cơ bản trên trình duyệt hiện đại, qua HTTPS với hết hạn phiên.
Yêu cầu
| 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 |
Chấp nhận
AC-WEB-01: Truy cập back-office
| Cho | Khi | Thì |
|---|---|---|
| Chủ sở hữu trên trình duyệt hiện đại | Đăng nhập qua HTTPS | Quản lý back-office đầy đủ khả dụng; phiên hết hạn/đăng xuất theo chính sách |
POS - Máy POS In-progress
Mã Tính năng: device/POS · Phase: P2 · PRDs: - · Dev: sale-renderer
Tính năng này mang lại gì cho người dùng: 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; thiết bị phải được gán vào một POS Point và giữ một phiên hoạt động trước khi xử lý bán hàng.
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.
Yêu cầu
| 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ị |
Chấp nhận
AC-POS-01: Gán POS Point
| Cho | Khi | Thì |
|---|---|---|
| Thiết bị đã kích hoạt trên Android 8+ | Được gán vào một POS Point | Thiết bị có thể xử lý bán hàng với một phiên hoạt động tại một thời điểm |
PRN - Máy in In-progress
Mã Tính năng: device/PRN · Phase: P2 · PRDs: - · Dev: sale-main
Tính năng này mang lại gì cho người dùng: hệ thống in hóa đơn ESC/POS qua máy in nhiệt USB và mạng - chữ, hình ảnh, QR và mã vạch - với code page 28 tiếng Việt, khổ giấy 58/80mm, tự cắt giấy và kích hoạt ngăn kéo tiền.
Máy in nhiệt USB (Tauri/WebUSB) và mạng (WebSocket); ESC/POS với code page 28 tiếng Việt.
Yêu cầu
| 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 |
Chấp nhận
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 |
SCN - Máy quét Mã vạch In-progress
Mã Tính năng: device/SCN · Phase: P2 · PRDs: - · Dev: sale-main
Tính năng này mang lại gì cho người dùng: quét HID keyboard-wedge và camera/QR di động đối chiếu với Product Identifier - một lần quét thành công trên màn hình POS thêm sản phẩm khớp vào giỏ hàng.
HID keyboard-wedge (USB/Bluetooth) và quét camera/QR di động đối chiếu với Product Identifier.
Yêu cầu
| 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) |
Chấp nhận
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 |
SBX - SoundBox Built
Mã Tính năng: device/SBX · Phase: P1 · PRDs: - · Dev: sale-renderer
Tính năng này mang lại gì cho người dùng: loa Bluetooth VNPAY phát xác nhận thanh toán bằng tiếng Việt/tiếng Anh - số tiền và phương thức - theo từng thiết bị, với âm lượng cấu hình được, trạng thái LED và xử lý mất kết nối mượt mà.
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ị.
Yêu cầu
| 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à |
Chấp nhận
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 |
NFC - SoftPOS / NFC Planned
Mã Tính năng: device/NFC · Phase: P3 · PRDs: - · Dev: sale-main
Tính năng này mang lại gì cho người dùng: điện thoại Android chấp nhận thanh toán thẻ không tiếp xúc qua NFC bằng VNPAY sau khi kích hoạt KYC; tùy chọn bị ẩn trên iOS và bị chặn khi NFC không khả dụng.
Chấp nhận NFC không tiếp xúc trên Android qua VNPAY; yêu cầu KYC.
Yêu cầu
| 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 |
Chấp nhận
AC-NFC-01: Kích hoạt SoftPOS
| Cho | Khi | Thì |
|---|---|---|
| Thiết bị Android có NFC khả dụng, đã hoàn tất KYC | SoftPOS được kích hoạt | Chấp nhận thẻ không tiếp xúc được bật |
| NFC không khả dụng hoặc bị tắt | Thử kích hoạt | Kích hoạt bị chặn kèm thông báo rõ ràng |
MON - Định danh & Giám sát Tình trạng Thiết bị In-progress
Mã Tính năng: device/MON · Phase: P2 · PRDs: - · Dev: @nx/commerce · @nx/signal
Tính năng này mang lại gì cho người dùng: quản trị viên xem trạng thái online/offline, lần thấy cuối và phiên bản app của từng thiết bị qua heartbeat 5 phút, và có thể vô hiệu hóa hoặc xóa dữ liệu từ xa thiết bị bị xâm phạm.
Yêu cầu
| 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) |
Chấp nhận
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ị |
DSX - Ca làm việc theo Thiết bị & Liên kết Máy in Built
Mã Tính năng: device/DSX · Phase: P2 · PRDs: PRD-DSX-001 · Dev: @nx/sale · @nx/commerce
Tính năng này mang lại gì cho người dùng: thiết bị đã đăng ký trở thành điểm neo runtime của một trạm bán hàng - header x-device-info phân giải mọi hành động ca về một thiết bị và suy ra merchant, một ca duy nhất được mở hoặc tham gia theo kênh bán, thiết bị bật ngăn kéo tiền nhận ngăn kéo theo thiết bị, ngữ cảnh hiện tại báo cáo sự tham gia thiết bị, báo cáo X/Z khóa theo thiết bị, và mỗi trạm liên kết với máy in riêng của nó.
Yêu cầu
| ID | P | Yêu cầu |
|---|---|---|
| URD-DSX-001 | M | Mọi hành động ca theo thiết bị phân giải thiết bị từ header x-device-info; merchant được suy ra từ bản ghi thiết bị đó, không bao giờ do client cung cấp |
| URD-DSX-002 | M | Thiếu header x-device-info trên hành động theo thiết bị bị từ chối với lỗi rõ ràng; back-office đọc (vd. danh sách ca) có thể chạy không cần thiết bị dùng phạm vi merchant đang hoạt động |
| URD-DSX-003 | M | Thiết bị phải tồn tại, được gán merchant, và (khi có merchant cung cấp) khớp với nó; nếu không, hành động bị từ chối |
| URD-DSX-004 | M | Quyền truy cập tenant được áp dụng trên merchant đã phân giải cho mọi hành động ca |
| URD-DSX-005 | M | Mở một ca sẽ mở hoặc tham gia ca mở duy nhất của kênh bán mà thiết bị thuộc về; lần mở đồng thời bởi thiết bị khác tham gia cùng ca thay vì tạo bản trùng |
| URD-DSX-006 | M | Kênh bán cung cấp khi mở phải thuộc về merchant đã phân giải |
| URD-DSX-007 | M | Thiết bị mở/tham gia được ghi danh trong ca, và nhân viên mở được check-in cùng nó |
| URD-DSX-008 | S | Ngăn kéo tiền theo thiết bị chỉ được tạo khi mở cho thiết bị bật ngăn kéo tiền; thiết bị khác tham gia mà không có ngăn kéo |
| URD-DSX-009 | M | Endpoint ngữ cảnh hiện tại trả về ca của thiết bị, ghi danh, ngăn kéo tùy chọn, tiền dự kiến, và sự tham gia thiết bị (số đang hoạt động, số đã tham gia, thiết bị còn chờ) |
| URD-DSX-010 | M | Tiền dự kiến bị bỏ khỏi ngữ cảnh khi chính sách đếm mù của merchant bật hoặc không có ngăn kéo |
| URD-DSX-011 | M | Báo cáo X (giữa ca) và Z (cuối ca) có thể sinh theo thiết bị và theo ca, khóa theo thiết bị đã phân giải |
| URD-DSX-012 | M | Một thiết bị được đăng ký với một merchant; bản ghi thiết bị là điểm neo thuộc phạm vi merchant mà mọi ca, ngăn kéo, báo cáo neo vào |
| URD-DSX-013 | M | Truy cập API thiết bị thuộc phạm vi merchant và đã xác thực (JWT hoặc Basic Auth); tìm kiếm thiết bị giới hạn theo các merchant người dùng đã tham gia |
| URD-DSX-014 | M | Một thiết bị khai báo nó có điều khiển ngăn kéo tiền hay không; cờ này điều phối việc tạo ngăn kéo khi mở ca |
| URD-DSX-015 | S | Đích in được liên kết theo từng trạm bếp (máy in, số bản, tự in); lệnh in định tuyến tới máy in liên kết |
Chấp nhận
AC-DSX-01: Phân giải ca theo thiết bị
| Cho | Khi | Thì |
|---|---|---|
Thiết bị đã đăng ký, có header x-device-info | Một hành động ca được gọi | Thiết bị được phân giải, merchant suy ra từ nó, và quyền tenant được áp dụng |
| Thiếu header trên hành động theo thiết bị | Hành động được gọi | Bị từ chối với lỗi rõ ràng |
| Thiết bị thuộc merchant khác | Hành động được gọi | Bị từ chối - merchant không khớp / cấm |
AC-DSX-02: Mở hoặc tham gia một ca mỗi kênh
| Cho | Khi | Thì |
|---|---|---|
| Không có ca mở cho kênh | Một thiết bị mở ca | Ca mở mới được tạo và thiết bị được ghi danh |
| Có ca mở cho kênh | Thiết bị khác mở | Nó tham gia cùng ca; không tạo bản trùng |
| Hai thiết bị mở cùng kênh đồng thời | Cả hai mở | Chúng hội tụ về một ca |
AC-DSX-03: Ngăn kéo & sự tham gia
| Cho | Khi | Thì |
|---|---|---|
| Thiết bị bật ngăn kéo tiền | Mở một ca | Ngăn kéo theo thiết bị được tạo với tiền đầu ca |
| Thiết bị không ngăn kéo | Mở / tham gia một ca | Nó tham gia mà không có ngăn kéo |
| Merchant bật đếm mù | Đọc ngữ cảnh hiện tại | Tiền dự kiến bị bỏ; sự tham gia vẫn trả về |
AC-DSX-04: Liên kết máy in
| Cho | Khi | Thì |
|---|---|---|
| Một trạm bếp liên kết với máy in (máy in, số bản, tự in) | Một lệnh in được tạo cho trạm đó | Lệnh định tuyến tới máy in liên kết với số bản đã cấu hình |
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 |
| 2026-06-04 | Claude (AI pair) | Tổ chức lại theo tính năng (Feature Spine) | v0.2 |
| 2026-06-15 | Nhóm Sale | Thêm DSX - Ca làm việc theo Thiết bị & Liên kết Máy in (Built) | v0.3 |