URD: Device

Module	CORE-04	Version	v0.1
Status	In-progress	Date	2026-02-28

1. Purpose

This document defines user-facing requirements for Device management and hardware integration. It covers how an organization registers, manages, and monitors physical devices (POS terminals, mobile apps, web clients), and how the platform integrates peripherals (printers, barcode scanners, SoundBox, SoftPOS/NFC, external displays).

2. Scope

Included	Excluded
Device registration, lifecycle, search, soft-delete	VNPAY Terminal backend wiring (table exists, API not connected — QE finding)
Hardware / software / maintenance info	Label printer integration (Planned)
Device identity (machine UID, x-device-info header)	Windows POS terminal (Planned)
Mobile, web, POS terminal apps + offline mode	Kitchen display, waiter, delivery apps (Planned)
Printer (USB/network, ESC/POS), scanner (HID/camera)	Cash drawer control (Planned)
SoundBox, SoftPOS/NFC, external display	Technical API specifications
Heartbeat / health monitoring, remote deactivation	Payment gateway internals (see Payment URD)
CSV import/export; role-based access	—

3. Definitions

Term	Definition
Device	A registered hardware unit (POS terminal, mobile device, workstation) that interacts with the platform
Device Identifier	System-generated unique string D_YYYYMMDD_<snowflakeId> assigned at registration
Device Code	Optional human-readable code, unique within the organization
Organization	Top-level owner of one or more merchants and devices
Merchant	A business unit within an organization; a device may be optionally assigned to one
Hardware Info	Manufacturer, model, serial number, IMEI, MAC, processor, RAM, storage, screen, battery
Software Info	OS, OS version, app version, firmware, last update, peripheral drivers
Device Status	Lifecycle state: NEW → ACTIVATED → DEACTIVATED → SUSPENDED → ARCHIVED
Heartbeat	Periodic online ping (every 5 min); offline after 15 min of silence
Machine UID	Hardware-derived identifier sent in the x-device-info HTTP header
ESC/POS	Thermal-printer command language; Vietnamese support via code page 28
HID Keyboard-Wedge	USB/Bluetooth scanner mode that emulates keyboard input
SoftPOS	NFC contactless card acceptance on an Android phone, activated via VNPAY KYC
SoundBox	VNPAY Bluetooth speaker announcing payment confirmations
POS Point	Logical sales station a device must be assigned to before processing sales

4. Conceptual Model

Conceptual only — full schema lives in the Commerce domain model.

5. Functional Requirements

One table per functional area. <AREA> codes match the test-case IDs. Priority = MoSCoW (Must / Should / Could / Won't).

5.1 Device Registration & Management (DEV)

ID	P	Requirement
URD-DEV-001	M	Owner can register a device with a name, type, and organization assignment
URD-DEV-002	M	System auto-generates a unique Device Identifier D_YYYYMMDD_<snowflakeId> at registration
URD-DEV-003	M	Device name supports i18n (English + Vietnamese)
URD-DEV-004	M	Device status follows the lifecycle NEW → ACTIVATED → DEACTIVATED → SUSPENDED → ARCHIVED; only valid transitions are permitted
URD-DEV-005	M	Owner can activate a registered device (NEW → ACTIVATED)
URD-DEV-006	M	Owner can deactivate (ACTIVATED → DEACTIVATED) and reactivate (DEACTIVATED → ACTIVATED) a device
URD-DEV-007	M	Owner can suspend a device (ACTIVATED → SUSPENDED) for a security concern
URD-DEV-008	M	Owner can archive a device (permanently read-only, hidden from POS)
URD-DEV-009	M	All device records use soft-delete; records are never physically removed
URD-DEV-010	M	Device API access requires authentication (JWT or Basic Auth)
URD-DEV-011	M	Device code, when provided, must be unique within the organization
URD-DEV-012	S	Owner can record maintenance info (purchase date, warranty expiry, maintenance dates, notes)
URD-DEV-013	M	A device is auto-registered and activated on first app login; existing devices are reused
URD-DEV-014	M	Owner can search devices by name, identifier, code, status, and type
URD-DEV-015	S	Owner can import and export device records via CSV
URD-DEV-016	M	Owner can assign / unassign a device to a merchant; assignment is optional
URD-DEV-017	S	Owner can record hardware information for a device
URD-DEV-018	S	Owner can record software information for a device
URD-DEV-019	S	Owner can set a PIN on a device for local authentication

Device Statuses

Status	Meaning
NEW	Registered, not yet activated (default)
ACTIVATED	Active and authorized to process transactions
DEACTIVATED	Temporarily disabled; reactivatable
SUSPENDED	Suspended pending investigation; cannot transact
ARCHIVED	Permanently retired; read-only

Device Types

Type Code	Label
100_POS_TERMINAL	POS Terminal
101_POS_WORKSTATION	POS Workstation
200_MOBILE_POS	Mobile POS
400_TABLET	Tablet
401_BARCODE_SCANNER	Barcode Scanner Device
999_OTHER	Other

5.2 Mobile App (MOB)

iOS/Android app built with Tauri; primary app for owners and cashiers.

ID	P	Requirement
URD-MOB-001	M	App is available on iOS 14+ and Android 8+
URD-MOB-002	M	Owner can sign in and access POS, orders, payments, invoicing, and reporting
URD-MOB-003	M	Cashier can sign in and access the POS screen (owner-only screens restricted)
URD-MOB-004	S	App supports Bluetooth peripheral connectivity (scanner, printer, SoundBox)
URD-MOB-005	S	App supports offline mode: transactions captured locally and synced on reconnect
URD-MOB-006	M	Login creates a device session linked to the device record (auto-register if new)

5.3 Web Application (WEB)

ID	P	Requirement
URD-WEB-001	M	Web app runs on modern browsers (Chrome, Edge, Firefox, Safari)
URD-WEB-002	M	Web app provides full back-office management (devices, products, orders, reports, settings)
URD-WEB-003	S	Web app supports a basic Web POS mode
URD-WEB-004	M	Web app enforces HTTPS and session expiry/logout
URD-WEB-005	S	Web app is usable at 1024px+ width; warns below the minimum

5.4 POS Terminal (POS)

Dedicated Android hardware running the POS app full-screen with integrated peripherals.

ID	P	Requirement
URD-POS-001	M	POS app runs on Android 8+ with ≥2 GB RAM and ≥16 GB storage
URD-POS-002	M	A device must be assigned to a POS Point before it can process sales; one active session per device
URD-POS-003	M	POS app supports built-in peripherals (card reader, printer, scanner, cash drawer) where present
URD-POS-004	S	POS app runs on certified hardware (VNPAY V-POS, Sunmi T2)
URD-POS-005	M	POS app supports peripheral setup via Settings > Devices

5.5 Printer (PRN)

USB (Tauri/WebUSB) and network (WebSocket) thermal printers; ESC/POS with Vietnamese code page 28.

ID	P	Requirement
URD-PRN-001	M	System connects to printers over Bluetooth, USB, and network
URD-PRN-002	M	System detects USB printers by USB class code 0x07
URD-PRN-003	M	ESC/POS engine prints text, embedded image, QR code, and barcode
URD-PRN-004	M	ESC/POS markup supports alignment, bold, underline, font size, barcode, QR, image
URD-PRN-005	M	System rasterizes PDF content with Floyd–Steinberg dithering for thermal output
URD-PRN-006	M	Vietnamese characters print correctly via code page 28
URD-PRN-007	M	System supports 58mm and 80mm paper widths, configurable per printer
URD-PRN-008	S	System supports auto-cut and a cash drawer triggered on print
URD-PRN-009	S	Cash drawer trigger command is sent via the printer on cash payment
URD-PRN-010	M	Print lifecycle (connect, disconnect, send job) surfaces a clear error on failure; no silent drop
URD-PRN-011	S	System connects to network printers via WebSocket and handles disconnection gracefully
URD-PRN-012	M	System falls back to WebUSB when the Tauri USB plugin is unavailable

5.6 Barcode Scanner (SCN)

HID keyboard-wedge (USB/Bluetooth) and mobile camera/QR scanning resolved against Product Identifiers.

ID	P	Requirement
URD-SCN-001	M	System captures HID keyboard-wedge scanner input automatically (no pairing UI)
URD-SCN-002	M	Scanner input must be 10–20 characters, completed within a 100ms keystroke timeout
URD-SCN-003	M	Enter key (or 100ms pause) triggers the scan and lookup
URD-SCN-004	M	Camera QR scanner is available on mobile via the Tauri barcode plugin
URD-SCN-005	M	On a successful scan in the POS screen, the matched product is added to the cart
URD-SCN-006	S	System supports 1D (EAN-13/8, UPC-A/E, Code 128/39) and 2D (QR, Data Matrix) formats
URD-SCN-007	S	Scanning works across multiple contexts (product search, invoice lookup)

5.7 SoundBox (SBX)

VNPAY Bluetooth speaker announcing payment confirmations in Vietnamese/English, paired per device.

ID	P	Requirement
URD-SBX-001	M	System pairs a VNPAY SoundBox (V1/V2) to a device via Bluetooth
URD-SBX-002	M	On payment confirmation, system triggers a voice announcement; if disconnected, payment still succeeds (no blocking error)
URD-SBX-003	M	Announcement language follows configuration (Vietnamese / English), including amount and method
URD-SBX-004	S	SoundBox LED states reflect status: blue blinking (pairing), blue solid (connected), green (success), red (error/low battery)
URD-SBX-005	S	User can configure volume (1–10) and toggle whether amount / method are announced
URD-SBX-006	S	SoundBox operates within its rated Bluetooth range (~10 m); beyond range, disconnection is handled gracefully

5.8 SoftPOS / NFC (NFC)

NFC contactless acceptance on Android via VNPAY; requires KYC. Planned

ID	P	Requirement
URD-NFC-001	M	System checks NFC hardware availability before enabling SoftPOS
URD-NFC-002	M	SoftPOS requires VNPAY KYC activation before first use
URD-NFC-003	M	SoftPOS activation is blocked when NFC is unavailable or disabled, with a clear message
URD-NFC-004	S	SoftPOS is Android-only; the option is hidden on iOS

5.9 Device Identity & Health Monitoring (MON)

ID	P	Requirement
URD-MON-001	M	Active device sends a heartbeat every 5 minutes; platform records last activity
URD-MON-002	M	Platform marks a device offline after 15 minutes without a heartbeat; back online on next ping
URD-MON-003	M	Administrators can view device health (online/offline, last seen, app version) and filter by status
URD-MON-004	M	System can remotely deactivate a device and revoke its active session
URD-MON-005	S	System supports remote data wipe for a compromised device (queued if offline)

6. Acceptance Criteria

AC-DEV-01: Registration

Given	When	Then
Owner	Registers a device with name + type + organization	Device created with status NEW; unique identifier auto-generated
Code provided		Code is unique within the organization

AC-MON-01: Health Monitoring

Given	When	Then
Active device	Sends a heartbeat	Last-activity timestamp updated
No heartbeat for 15 min		Device marked offline
Admin views device list		Online/offline status visible

AC-PRN-01: Receipt Printing

Given	When	Then
Paired printer	Transaction completed	Receipt printed (auto or manual)
Print fails		Error shown with retry option
Vietnamese content		Code page 28 set automatically

AC-SCN-01: Barcode Scanning

Given	When	Then
HID scanner	Scan a barcode	Product looked up and added to cart
Camera scanner (mobile)	Scan a QR	Product/invoice looked up
Unknown barcode	Scan	Clear error message shown

AC-SBX-01: SoundBox Confirmation

Given	When	Then
Paired SoundBox	Payment confirmed	Amount + method announced in configured language
SoundBox disconnected	Payment confirmed	Payment still succeeds; announcement silently skipped

7. Constraints & Non-Goals

Constraints

ID	Constraint
C-01	All devices must be registered before they can operate
C-02	A device must be assigned to a POS Point before processing sales
C-03	Only one active session is permitted per device at a time
C-04	Device Identifiers are auto-generated and immutable
C-05	Device codes must be unique within the organization
C-06	All device records use soft-delete
C-07	Status transitions follow the defined lifecycle; invalid transitions are rejected
C-08	SoftPOS is Android-only and requires VNPAY KYC
C-09	Each POS should have exactly one default printer
C-10	Maximum devices per organization is configurable by the operator
C-11	Heartbeat is every 5 min; offline threshold is 15 min
C-12	HID scanner input must be 10–20 chars within a 100ms timeout
C-13	USB printer code page 28 (Vietnamese) is set automatically on connection

Non-Goals

• VNPAY Terminal backend API wiring (table exists, no backend connected — QE finding)
• Label printer integration; Windows POS terminal support
• Kitchen display, waiter/service, delivery, and inventory specialized apps
• Cash drawer control; advanced peripheral driver management UI
• Technical API specifications and payment-gateway integration details

8. Version History

Date	Author	Description	Ver
2026-02-28	Q. Do - QE	Initial URD from code-level and documentation analysis	v0.1