Device Phase A In-progress

Device lets an organization register, monitor, and control the physical and software endpoints that run BANA — POS terminals, mobile and web apps — and connect peripherals such as receipt printers, barcode scanners, and the VNPAY SoundBox. Owners track their equipment; cashiers operate on it daily.

1. Identity

Property	Value
Module ID	CORE-04
Tier	Core
Status	In-progress
Phase	P1 (Apps + SoundBox), P2 (POS + peripherals), P3 (SoftPOS / advanced)
Priority	HIGH
Primary users	Owner, Manager, Cashier

2. Purpose & Scope

Included	Excluded
Device registration, status lifecycle, search	VNPAY Terminal backend wiring (table exists, API not connected)
Hardware / software / maintenance info tracking	Label printer integration (Planned)
Mobile, web, and POS terminal client apps	Windows POS terminal (Planned)
Peripheral integration (printer, scanner, SoundBox, SoftPOS, external display)	Kitchen display / waiter / delivery apps (Planned)
Health monitoring (heartbeat, online/offline, remote deactivation)	Cash drawer control (Planned)
CSV import/export of device records	Payment gateway internals (see Payment)

3. Capabilities

Capability	What the user can do	Status
Device registration & CRUD	Register hardware with i18n name, type, organization; optional merchant + code	In-progress
Status lifecycle	Move a device through NEW → ACTIVATED → DEACTIVATED → SUSPENDED → ARCHIVED	In-progress
Equipment inventory	Record hardware, software, and maintenance details per device	Built
Health monitoring	See online/offline status via 5-min heartbeat; offline after 15 min silence	In-progress
Remote deactivation	Disable a device and revoke its session remotely	In-progress
Mobile app	Run POS and management on iOS 14+ / Android 8+ (Tauri)	Built
Web app	Run back-office and basic POS in modern browsers	Built
POS terminal app	Run full-screen POS on dedicated Android hardware	In-progress
Receipt printing	Print ESC/POS receipts via USB / network, Vietnamese code page 28, 58/80mm	In-progress
Barcode scanning	Scan via HID keyboard-wedge or mobile camera/QR	In-progress
SoundBox	Hear Vietnamese/English voice payment confirmations over Bluetooth	Built
SoftPOS (NFC)	Accept contactless card payments on Android (VNPAY KYC)	Planned

4. Module Dependencies

Depends on	Why
Commerce	Organization owns devices; optional merchant assignment; owns the Device entity
Orders	POS sessions run on devices; receipts and invoice lookup
Payment	SoundBox confirmations and SoftPOS card acceptance

5. Backend Packages

Implementation detail lives in the developer docs — this section only maps the module to the services and apps that power it.

Package / App	Role	Developer docs
@nx/commerce	Owns the Device entity, hardware/software info, status lifecycle	commerce
@nx/signal	Real-time edge — pushes payment/device events to clients over encrypted WebSocket	signal
client	Back-office device & terminal management UI	client
sale-renderer	POS UI — scanning, printing, SoundBox, SoftPOS flows	sale-renderer
sale-main	Tauri native layer — USB/NFC/printer/scanner plugins, offline SQLite	sale-main

6. Key User Flows

7. Roles & Permissions

Role	Can	Cannot
Owner	Register, edit, activate, suspend, archive, remotely deactivate devices; configure peripherals	—
Manager	View devices, monitor health, configure peripherals within scope	Archive or remotely deactivate (scope-dependent)
Cashier	Operate POS on an activated device; pair and use peripherals	Register, archive, or remotely deactivate devices

8. Status & Roadmap

Phase	Capabilities
P1	Mobile app, web app, SoundBox, offline mode, minimum-version enforcement
P2	Device registration CRUD, hardware/software/maintenance info, POS terminal app, receipt printer, barcode scanner, health monitoring
P3	SoftPOS (NFC), kitchen display, external customer display, label printing, Windows POS

9. Related Pages

• URD
• Test Cases
• PRDs
• Features: Mobile App · Web App · POS Terminal · Barcode Scanner · Printer · SoundBox
• Orders · Payment · Commerce