BANA

English

Tiếng Việt

English

Tiếng Việt

Appearance

URD: Device ​

ModuleVersionUpdated
CORE-04v0.52026-07-21

What the Device module does

Defines user-facing requirements for device management and hardware integration - how an organizer 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).

A device is not just a management record - it is the runtime anchor that a login session, a sales shift, a cash drawer, and a report all attach to (see the DSX chapter). That's why a device must be recognized correctly, and exactly once, per physical hardware unit - misrecognition spawns duplicate devices, loses shift history, and fragments reporting.

Four things to understand first

This is the most important part of the document. Understanding the four points below is understanding the core of the module.

1. One device, one durable identifier

Every device carries a Device Identifier (D_YYYYMMDD_<snowflakeId>) generated exactly once when the device is created, and unchanged across app uninstall/reinstall on the same hardware. This is the module's single most important invariant: if the identifier drifts on every reinstall, the same POS terminal gets misread as multiple different devices - a new record, a new lifecycle, a fragmented shift history each time.

The identifier therefore cannot live only in the app's local storage (which is wiped on uninstall or when a browser clears its data) - it must either be derivable from the hardware itself, or recoverable through a mechanism that doesn't depend on local storage (see point 3).

2. Login is check-first, create-second

A device does not automatically exist in the system just because someone installed the app on it. On every login, the app calls an API that asks: "does this identifier already belong to the current merchant?"

  • Yes → the device is already known, everything works normally, nothing new is created.
  • No → the system creates a new device record, in status NEW (not yet activated).

This check runs on every client type (POS, mobile, browser), not just one platform.

3. Activation is a discrete action, not a hidden step

This is the point most likely to be misunderstood: creating a new device does not mean activating it. A NEW device becomes ACTIVATED through exactly one path: someone scans or enters that device's Activation Code and presses "Activate."

When a new device is created, the system auto-generates an Activation Code in two parallel forms - a QR code (scanned by camera) and a Barcode (scanned by a barcode scanner or typed by hand). There are two forms for two different reasons:

  • Not every device has a camera to scan a QR code - the Barcode serves exactly that group (dedicated POS hardware, webcam-less machines).
  • A browser sometimes cannot retain the identifier because of ITP (Intelligent Tracking Prevention) - a policy that blocks cookies or scripts tracking behavior across different websites, which in turn limits client-side storage duration - when that happens, the automatic check in point 2 isn't reliable, and code-based activation gives a path to completing activation that doesn't depend on browser storage.

Every Activation Code is single-use - reusing it is rejected, even on the same device.

4. Operational lifecycle and physical condition are two different axes

Operational Status (NEW → ACTIVATED → DEACTIVATED → SUSPENDED → ARCHIVED) answers "is this device allowed to transact." Physical Condition (Working / Under Maintenance / Faulty) answers a completely different question: "is this machine actually running well." A device can be ACTIVATED (authorized to sell) while Faulty (physically broken) - and that exact gap is why Device Condition exists as its own axis, separate from operational Status.

Proprietary and Confidential. Unauthorized copying, distribution, or use of this software is strictly prohibited.

Copyright © 2025-present NEXPANDO. All rights reserved.