[Feature]: Customer Display: align feature branch with main POSNext architecture + second screen support

[shuhain85]

Search Confirmation

• I have searched existing issues and this feature has not been requested before

Problem Statement

The current feature/customer-display implementation is a strong starting point, but during integration with the latest POSNext architecture we identified several gaps that make it difficult to use safely in production retail environments.

A major reason is that parts of the customer display flow appear to have originally been built around another backend app / service structure, so some assumptions no longer align with the current main POSNext backend and store lifecycle.

Main limitations observed:

• customer display sync payload currently allows profile objects to flow into currency fields, causing incorrect totals rendering
• some customer display components still rely on hardcoded currency fallback assumptions
• backend display settings API assumes schema fields already exist, which can break older installations
• popup open flow is currently basic and not optimized for real dual-screen cashier environments
• realtime socket payload structure is not fully aligned with the current POS cart store architecture
• reconnect flow can leave stale cart state after popup reopen or shift switch
• some API and store assumptions suggest the feature was initially designed around another backend app flow, which causes drift from the current POSNext architecture

These issues make it harder to adopt the customer display feature branch as a production-ready upstream feature.

Proposed Solution

Align the customer display feature branch with the current main POSNext architecture before merge.

Recommended improvements:

1) Backend alignment with main POSNext APIs

Refactor customer display APIs so they fully follow current POSNext backend patterns instead of assumptions from the earlier external backend app flow.

This includes:

• consistent current cart payload structure
• POS opening state recovery
• schema-safe settings fallback
• normalized session lifecycle

2) Store-aligned sync payload

Use the POS store as the single source of truth and ensure customer display sync receives:

• shiftStore.profileCurrency
• normalized cart payloads
• safe customer/session state

3) Safe currency normalization

Replace hardcoded fallback assumptions with shared formatter utilities that support:

• string currency
• object payloads
• null-safe fallback
• formatter failure fallback

This avoids runtime errors such as:
Invalid currency code: [object Object]

4) Better second-screen support

Improve openCustomerDisplay() to:

• open as reusable popup window
• support Chromium second-screen APIs where available
• fallback safely on unsupported browsers

This is important for real retail dual-monitor POS workflows.

5) Realtime socket lifecycle alignment

Update useCustomerDisplaySync.js to align with the latest POS cart lifecycle:

• shift switch
• cart clear after invoice submit
• reconnect after popup reopen
• stale cart recovery
• socket payload normalization

UI Mockups / Screenshots

Attached screenshots and short demo video show the alignment changes required from the original feature/customer-display implementation to work correctly with the latest POSNext app.

Included:

• before/after currency issue fix
• popup customer display flow
• second-screen behavior
• realtime cart sync updates
• cart clear after invoice
• reconnect after popup reopen

09.04.2026_23.41.58_REC.mp4

Alternatives Considered

I first tried integrating the original feature/customer-display branch directly.

However, to make it work safely with the current POSNext app, several architecture-alignment changes were required.

A major issue is that parts of the original implementation appear to have been built together with another backend app / service flow.

Because of that, some models and assumptions expected by the feature were not fully available in the current POSNext app.

One example observed during integration was that the original flow expected generated models / structures similar to the restaurant-style customer display model flow, but those supporting pieces were not fully added when syncing the feature into the current app.

This caused drift in:

• API expectations
• store state assumptions
• sync payload structure
• realtime socket lifecycle
• popup reconnect behavior

Main changes needed from the original implementation:

Frontend alignment

POS/src/pages/POSSale.vue

• corrected customer display sync payload
• changed currency source from full profile object to shiftStore.profileCurrency
• improved popup / second-screen open behavior
• aligned button flow with current shift lifecycle

POS/src/pages/CustomerDisplay.vue

• removed hardcoded currency fallback assumptions
• added safe formatter normalization for string/object/null currency payloads

POS/src/components/customer-display/DisplayCart.vue

• fixed repeated currency formatter crash
• removed hardcoded "EUR"
• aligned totals rendering with normalized currency

POS/src/stores/customerDisplay.js

• aligned auth and session restore logic
• removed assumptions inherited from the earlier external backend app flow
• improved safe cart state reset

POS/src/composables/useCustomerDisplaySync.js

• corrected realtime socket payload structure
• aligned cart sync with current POS store lifecycle
• fixed reconnect after popup reopen
• fixed stale cart after invoice submit

Backend alignment

pos_next/api/customer_display.py

• refactored get_display_settings() with schema-safe defaults
• normalized current cart payload
• aligned API behavior with current POSNext backend patterns
• removed assumptions from the earlier external backend app flow

Component registration

POS/components.d.ts

• added customer display component typings for proper integration

So while the upstream branch is a great feature base, it currently needs several architecture-alignment changes before it can be used directly in the latest POSNext app.

Feature Area

Cart / Item Management

Business Priority

Critical - Blocking our operations

Current POS Next Version

1.15.0

Additional Context

For easier local review, these are the git commands used to isolate the customer display alignment changes from the original feature/customer-display implementation.

1) Checkout upstream feature branch

git checkout feature/customer-display

2) Compare against current aligned branch / commit

git diff feature/customer-display..b1a1936 --
POS/src/pages/POSSale.vue
POS/src/pages/CustomerDisplay.vue
POS/src/components/customer-display/DisplayCart.vue
POS/src/stores/customerDisplay.js
POS/src/composables/useCustomerDisplaySync.js
pos_next/api/customer_display.py
POS/components.d.ts

3) Generate isolated patch files

git diff feature/customer-display..b1a1936 --
POS/src/pages/POSSale.vue
POS/src/pages/CustomerDisplay.vue
POS/src/components/customer-display/DisplayCart.vue \

customer_display_router.diff

git diff feature/customer-display..b1a1936 --
pos_next/api/customer_display.py \

customer_display_backend.diff

git diff feature/customer-display..b1a1936 --
POS/src/composables/useCustomerDisplaySync.js
POS/src/stores/customerDisplay.js \

customer_display_realtime.diff

git diff feature/customer-display..b1a1936 --
POS/components.d.ts \

customer_display_components.diff

git diff feature/customer-display..b1a1936 -- POS/src/pages/POSSale.vue
git diff feature/customer-display..b1a1936 -- pos_next/api/customer_display.py
git diff feature/customer-display..b1a1936 -- POS/src/composables/useCustomerDisplaySync.js

customerdisplay.zip

Contribution

• I would be willing to submit a PR to implement this feature
• I would be willing to test/review a PR for this feature
• I can provide detailed requirements or domain expertise