Device Phase A In-progress
Device lets an organization register, monitor, and control the physical and software endpoints that run KICKO - 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 |
|---|---|
| Device registration & CRUD | Register hardware with i18n name, type, organization; optional merchant + code |
| Status lifecycle | Move a device through NEW → ACTIVATED → DEACTIVATED → SUSPENDED → ARCHIVED |
| Equipment inventory | Record hardware, software, and maintenance details per device |
| Health monitoring | See online/offline status via 5-min heartbeat; offline after 15 min silence |
| Remote deactivation | Disable a device and revoke its session remotely |
| Mobile app | Run POS and management on iOS 14+ / Android 8+ (Tauri) |
| Web app | Run back-office and basic POS in modern browsers |
| POS terminal app | Run full-screen POS on dedicated Android hardware |
| Receipt printing | Print ESC/POS receipts via USB / network, Vietnamese code page 28, 58/80mm |
| Barcode scanning | Scan via HID keyboard-wedge or mobile camera/QR |
| SoundBox | Hear Vietnamese/English voice payment confirmations over Bluetooth |
| SoftPOS (NFC) | Accept contactless card payments on Android (VNPAY KYC) |
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 |
Engineering Mapping (Feature ⇄ Package)
The horizontal axis of the Feature Spine - each business feature (
<AREA>in the URD) maps to its engineering home. Reciprocal: the package docs link back here.
| Feature | Dev package | Status |
|---|---|---|
MOB Mobile App | sale-renderer | Built |
WEB Web Application | client | Built |
SBX SoundBox | sale-renderer | Built |
DEV Device Registration & Management | @nx/commerce | In-progress |
POS POS Terminal | sale-renderer | In-progress |
PRN Printer | sale-main | In-progress |
SCN Barcode Scanner | sale-main | In-progress |
DSX Device Shift & Printer Binding | @nx/sale · @nx/commerce · @nx/core | Built |
MON Device Identity & Health Monitoring | @nx/commerce · @nx/signal | In-progress |
NFC SoftPOS / NFC | sale-main | Planned |
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
- PRDs
- Features: Mobile App · Web App · POS Terminal · Barcode Scanner · Printer · SoundBox
- Orders · Payment · Commerce