PRD: Device shift context & printer binding

Module	Device	PRD ID	PRD-DSX-001
Status	Ready to dev	FEAT	DSX
Epic	—	Plane	BANA-1538
Date	2026-07-17	Version	v1.1
Packages	@nx/sale · @nx/commerce · @nx/core	URD	DSX
Surface	Sale · POSClient · Owner/Mgr
Owner	Phát Nguyễn

The device is the runtime anchor of a sales station

Makes the registered device the runtime anchor of a sales station. Every shift action carries the device identity; the platform resolves that device, derives the merchant from the device record (never from a client-supplied value), and asserts tenant access before anything runs. Opening a shift opens or joins the single open shift for the device's sale channel - concurrent opens converge on one shift, never a duplicate. A cash drawer is created only for cash-drawer-enabled devices, and the current-context call reports who is participating (active, joined, pending) plus expected cash - unless blind-count is on. Print jobs route to the printer bound per kitchen station. Net result: a device is registered once against a merchant, and shifts, drawers, reports, and receipts all bind to that single anchor.

The problem this increment closes

A merchant runs several physical stations - POS terminals, mobile apps, a back counter - all under one merchant. The device registration increment (PRD-DEV-001) gives each station a record and a stable identity, but it does not define how that record becomes the operational anchor a shift, a cash drawer, a report, and a printer all hang off.

Without that anchor, a client would have to tell the server which merchant and which shift it is acting in - so two terminals could open two shifts for the same channel, a cash drawer could be created for a device that has no drawer, and a print job would have nowhere to route. Trusting a client-supplied merchant also breaks tenant isolation.

This increment closes the gap: the device identity resolves every shift action to a device, the merchant is derived from the device record, the channel's shift is opened or joined (never duplicated), drawers and participation track per device, and a print destination is bound per station. The station's identity, set at registration, now governs its whole runtime.

1. Goals & Non-Goals

Goals

• Resolve every device-scoped shift action from the device identity, deriving the merchant from the device record and asserting tenant access.
• Open-or-join the single open shift per sale channel - concurrent opens converge on one shift.
• Enroll the opening device, check in the opening employee, and create a cash drawer only for cash-drawer-enabled devices.
• Return a device participation view (active / joined / pending) and expected cash, omitting expected cash under a blind-count policy.
• Generate X (mid-shift) and Z (end-of-shift) reports per device and per shift, keyed on the resolved device.
• Keep the device a merchant-scoped, authenticated, search-isolated record; bind a printer per station (printer, copies, auto-print) and carry the cash-drawer flag.

Non-Goals

• Device registration, lifecycle, and the back-office fleet surface - specified in PRD-DEV-001 (URD-DEV).
• The receipt print engine itself - rasterization, Vietnamese character support, paper widths - specified under PRN.
• Cash-reconciliation math, blind-count tolerance, and report section contents - consumed here, not specified here.
• Heartbeat / health monitoring and remote deactivation (MON).
• POS Point hardware certification (POS).

2. Success Metrics

Metric	Target / signal
Anchor coverage	Every shift action resolves to a device via the device identity; merchant is never read from the client
No duplicate shifts	One open shift per sale channel, even under concurrent opens from multiple devices
Drawer correctness	A cash drawer exists only for cash-drawer-enabled devices
Participation accuracy	Active / joined / pending counts match the devices enrolled in the shift
Tenant isolation	A device assigned to another merchant cannot act in, or be seen by, this merchant

3. Personas & Use Cases

Persona	Goal in this feature
Cashier	Open or join the station's shift, drop/pay cash, run an X read, close the shift - all from one device
Owner / Manager	See which devices are participating in a channel's shift and review device/shift Z reports
Back-office	List a merchant's shifts without a device, using the active-merchant scope

Core scenario: a cashier signs in on a registered POS terminal and opens the lunch shift for the dine-in channel. The request carries the device; the platform derives the merchant, finds no open shift, and creates one - then enrolls the device and checks in the cashier. Because the device is cash-drawer-enabled, a drawer is created with the opening float. A second terminal on the same channel opens and joins the same shift; the current-context call now shows two joined devices. At close, the device runs a Z report keyed on its own record. A second merchant's terminal never appears in either list.

4. User Stories

• As a cashier, I open a shift from my terminal without telling the system which merchant I am, so I cannot act in the wrong tenant.
• As a cashier, when a teammate already opened the channel's shift, my open joins it instead of creating a second one.
• As a cashier, my drawer is created only because my device drives a cash drawer, so a drawer-less device never gets a phantom drawer.
• As a manager, I see which devices are active, joined, and still pending on a channel's shift.
• As a manager, I run X and Z reports for a single device or the whole shift.
• As back-office, I list a merchant's shifts without holding a device, using the merchant scope.
• As an owner, I bind each kitchen station to its printer with a copy count and auto-print, so tickets route to the right printer.

5. Functional Requirements

#	Requirement	Status	URD ref
FR-1	Every device-scoped shift action resolves its device from the device identity and derives the merchant from that device record	Built	URD-DSX-001
FR-2	A missing device identity on a device-scoped action is rejected; back-office reads may run without a device via the active-merchant scope	Built	URD-DSX-002
FR-3	The device must exist, be assigned to a merchant, and match any supplied merchant; otherwise the action is rejected	Built	URD-DSX-003
FR-4	Tenant access is enforced on the resolved merchant for every shift action	Built	URD-DSX-004
FR-5	Opening a shift opens or joins the single open shift for the device's sale channel; concurrent opens converge on one shift	Built - the loser of a concurrent open is rejected, then follows up by joining (not a single transparent open-or-join endpoint)	URD-DSX-005
FR-6	A sale channel supplied on open must belong to the resolved merchant	Built	URD-DSX-006
FR-7	The opening/joining device is enrolled and the opening employee checked in alongside it	Built	URD-DSX-007
FR-8	A per-device cash drawer is created on open only for cash-drawer-enabled devices	Built	URD-DSX-008 · URD-DSX-014
FR-9	Current context returns shift, enrollment, optional drawer, expected cash, and device participation (active / joined / pending)	Built - joined/active as counts, pending as a list	URD-DSX-009
FR-10	Expected cash is omitted when the merchant's blind-count policy is on or there is no drawer	Built	URD-DSX-010
FR-11	X and Z reports can be generated per device and per shift, keyed on the resolved device	Built	URD-DSX-011
FR-12	The device is a merchant-scoped, authenticated record; device search is limited to the merchants the user has joined	Built	URD-DSX-012..013
FR-13	A print destination is bound per kitchen station (printer, copies, auto-print); jobs route to the bound printer	Partial - the binding (printer / copies / auto-print) is persisted on the kitchen station and tickets link to stations, but no backend routing reads it; jobs are dispatched by the native POS client	URD-DSX-015

Full requirement text and acceptance criteria live in the Device URD - DSX. This PRD references them rather than restating them.

6. Non-Functional Requirements

Area	Requirement
Tenancy & authz	Merchant is derived from the device record, never the client; tenant access is asserted on every action; device API access requires authentication
Search isolation	Device search returns only the merchants the signed-in user has joined
Concurrency	Open-or-join is race-safe - a concurrent create converges on the single open shift, never a duplicate
Atomicity	A shift open (shift + enrollment + employee check-in + drawer) is one all-or-nothing transaction
Consistency	A drawer exists only for cash-drawer-enabled devices; participation counts reflect enrolled devices
i18n	Device name and station name are bilingual (English & Vietnamese)

7. UX & Flows

Key surfaces: the POS open/current/close screens carry the device identity; the current-context panel shows active / joined / pending devices and expected cash; the back-office shift list runs under the merchant scope without a device; station-to-printer binding is configured per kitchen station.

8. Data & Domain

Entity	Role
Device record	The merchant-scoped station record; carries the cash-drawer flag and is the anchor every shift, drawer, and report binds to
Shift	The open-or-join session per sale channel; one open shift per channel
Shift participation	A device's (and employee's) participation in a shift
Cash drawer	The per-device cash drawer, created only for cash-drawer-enabled devices
Kitchen station	Carries the per-station printer binding (printer, copies, auto-print); the binding is persisted and consumed by the native POS client (no backend routing)

Conceptual only - full schema and invariants live in the commerce domain model and the sale package docs.

9. Dependencies & Assumptions

Depends on

• Device registration (PRD-DEV-001, URD-DEV) - the device record and its merchant assignment must exist before it can anchor a shift.
• Shift management - the open-or-join, enrollment, drawer, and report behavior.
• Commerce domain - owns the device record, the cash-drawer flag, and merchant-scoped device management/search.
• Sale channels - a channel supplied on open must belong to the resolved merchant.

Assumptions

• The app sends the device identity on every device-scoped shift action.
• A device is assigned to exactly one merchant before it transacts.
• The merchant's shift-management and blind-count policies are configured.

10. Release Plan & Launch Criteria

Aspect	Plan
Phase	P2 - DSX in the URD feature catalog, alongside DEV / POS / PRN
Rollout	All merchants; no feature flag
Migration	Cash-drawer flag added on the device model; no data backfill required
Launch criteria	Shift actions resolve the device and derive the merchant; open-or-join yields one shift per channel under concurrency; drawers appear only for cash-drawer-enabled devices; participation and expected-cash (blind-count aware) return correctly; device/shift X and Z reports generate; station print binding is persisted (routing is client-side)
Monitoring	Duplicate-open rate, missing-identity rejection rate, drawer-vs-flag consistency, cross-merchant access attempts

References

• URD: Device - DSX · DEV · POS · PRN
• Sibling PRDs: Device registration, management & peripherals · Device signal & notifications
• Module: Device - URD
• Developer: @nx/sale · @nx/commerce · @nx/core
• Apps: sale-renderer · client

Risks & Open Questions

Risk / question	Mitigation / status
Two devices open the same channel concurrently	Open-or-join converges on the single open shift; the loser joins, never duplicates
Client supplies a wrong or foreign merchant	Merchant is derived from the device record and tenant access is asserted; a mismatched supplied merchant is rejected
Drawer created for a drawer-less device	Drawer creation is gated on the device's cash-drawer flag
Expected cash leaks under blind count	Expected cash is omitted from the context when blind-count is on or there is no drawer
Action runs without a device identity	Device-scoped actions reject a missing identity; only explicit back-office reads run device-less under the merchant scope

FAQ

Question	Answer
Who decides which merchant a shift belongs to?	The device does - the merchant is derived from the device record resolved via the device identity. The client never supplies it for device-scoped actions.
What happens when two terminals open the same channel's shift at once?	They converge on one shift - the first creates it, the second joins it. There is never a duplicate open shift per channel.
Does every device get a cash drawer?	No - a drawer is created at open only for cash-drawer-enabled devices. Other devices join the shift without a drawer.
Why is expected cash sometimes missing from the context?	It is omitted when the merchant's blind-count policy is on, or when the device has no drawer.
Can I run a report without a device?	The shift list runs back-office under the merchant scope without a device. Device and shift X/Z reports are keyed on the resolved device and need the device identity.
How does a ticket reach the right printer?	Each kitchen station stores a printer binding (printer, copy count, auto-print flag). The binding is persisted on the backend; the actual print-job routing is done by the native POS client - there is no backend print router.