PRD: Ngữ cảnh ca làm việc theo thiết bị & liên kết máy in

Module	Thiết bị	PRD ID	PRD-DSX-001
Trạng thái	Sẵn sàng dev	FEAT	DSX
Epic	—	Plane	BANA-1538
Ngày	2026-07-17	Phiên bản	v1.1
Gói	@nx/sale · @nx/commerce · @nx/core	URD	DSX
Surface	Sale · POSClient · Chủ/QL
Phụ trách	Phát Nguyễn

Thiết bị là điểm neo runtime của một trạm bán hàng

Biến thiết bị đã đăng ký thành điểm neo runtime của một trạm bán hàng. Mọi hành động ca mang định danh thiết bị; nền tảng phân giải thiết bị đó, suy ra merchant từ bản ghi thiết bị (không bao giờ tin merchant do client gửi lên), và áp dụng quyền truy cập tenant trước khi chạy bất cứ gì. Mở một ca sẽ mở hoặc tham gia ca mở duy nhất của kênh bán mà thiết bị thuộc về - các lần mở đồng thời hội tụ về một ca, không bao giờ tạo bản trùng. Ngăn kéo tiền theo thiết bị chỉ được tạo cho thiết bị bật ngăn kéo tiền, và lời gọi ngữ cảnh hiện tại báo cáo ai đang tham gia (thiết bị đang hoạt động, đã tham gia, còn chờ) cùng tiền dự kiến trừ khi bật đếm mù (blind-count). Lệnh in định tuyến tới máy in liên kết theo từng trạm bếp (máy in, số bản, tự in). Kết quả: một thiết bị đăng ký một lần với một merchant, và ca, ngăn kéo, báo cáo, biên lai đều neo vào một điểm neo đó.

Vấn đề mà gia tăng này khép lại

Một merchant vận hành nhiều trạm vật lý - máy POS, ứng dụng di động, quầy phụ - trên cùng một merchant. Gia tăng đăng ký thiết bị (PRD-DEV-001) cho mỗi trạm một bản ghi và một định danh ổn định, nhưng không định nghĩa cách bản ghi đó trở thành điểm neo vận hành mà một ca, một ngăn kéo tiền, một báo cáo và một máy in cùng neo vào.

Thiếu điểm neo đó, client sẽ phải tự khai báo merchant nào và ca nào nó đang hành động - nên hai máy có thể mở hai ca cho cùng một kênh, một ngăn kéo có thể được tạo cho thiết bị không có ngăn kéo, và một lệnh in sẽ không có nơi để định tuyến. Tin merchant do client gửi cũng phá vỡ cách ly tenant.

Gia tăng này khép lại khoảng trống: định danh thiết bị phân giải mọi hành động ca về một thiết bị, merchant được suy ra từ bản ghi thiết bị, ca của kênh được mở hoặc tham gia (không bao giờ trùng), ngăn kéo và sự tham gia theo dõi theo thiết bị, và đích in được liên kết theo từng trạm. Định danh của trạm, thiết lập lúc đăng ký, nay điều phối toàn bộ runtime của nó.

1. Mục tiêu & Ngoài mục tiêu

Mục tiêu

• Phân giải mọi hành động ca theo thiết bị từ định danh thiết bị, suy ra merchant từ bản ghi thiết bị và áp dụng quyền truy cập tenant.
• Mở-hoặc-tham-gia ca mở duy nhất theo kênh bán - các lần mở đồng thời hội tụ về một ca.
• Ghi danh thiết bị mở và check-in nhân viên mở; tạo ngăn kéo tiền theo thiết bị chỉ cho thiết bị bật ngăn kéo tiền.
• Trả về góc nhìn sự tham gia thiết bị (đang hoạt động / đã tham gia / còn chờ) và tiền dự kiến, bỏ tiền dự kiến khi có chính sách đếm mù.
• Sinh báo cáo X (giữa ca) và Z (cuối ca) theo thiết bị và theo ca, khóa theo thiết bị đã phân giải.
• Giữ thiết bị là bản ghi thuộc phạm vi merchant, đã xác thực, cách ly tìm kiếm; liên kết máy in theo trạm (máy in, số bản, tự in) và mang cờ ngăn kéo tiền trên thiết bị.

Ngoài mục tiêu

• Đăng ký thiết bị, vòng đời, và bề mặt quản lý đội thiết bị back-office - đặc tả tại PRD-DEV-001 (URD-DEV).
• Bản thân engine in hóa đơn - rasterize, hỗ trợ ký tự tiếng Việt, khổ giấy - đặc tả dưới PRN.
• Toán đối soát tiền, dung sai đếm mù, và nội dung các mục báo cáo - được tiêu thụ ở đây, không đặc tả ở đây.
• Heartbeat / giám sát tình trạng và vô hiệu hóa từ xa (MON).
• Chứng nhận phần cứng POS Point (POS).

2. Chỉ số Thành công

Chỉ số	Mục tiêu / tín hiệu
Phủ điểm neo	100% hành động ca phân giải về một thiết bị qua định danh thiết bị; merchant không bao giờ đọc từ client
Không trùng ca	Một ca mở mỗi kênh bán kể cả khi nhiều thiết bị mở đồng thời
Đúng ngăn kéo	Ngăn kéo tiền chỉ tồn tại cho thiết bị bật ngăn kéo tiền
Đúng sự tham gia	Số thiết bị đang hoạt động / đã tham gia / còn chờ khớp với thiết bị đã ghi danh trong ca
Cách ly tenant	Thiết bị thuộc merchant khác không thể hành động trong, hoặc bị thấy bởi, merchant này

3. Đối tượng & Tình huống sử dụng

Đối tượng	Mục tiêu trong tính năng này
Thu ngân	Mở hoặc tham gia ca của trạm, thả/thanh toán tiền, chạy báo cáo X, đóng ca - tất cả từ một thiết bị
Chủ sở hữu / Quản lý	Xem thiết bị nào đang tham gia ca của một kênh và xem báo cáo Z theo thiết bị/ca
Back-office	Liệt kê ca cho một merchant không cần thiết bị, dùng phạm vi merchant đang hoạt động

Tình huống cốt lõi: một thu ngân đăng nhập trên máy POS đã đăng ký và mở ca trưa cho kênh tại bàn. Request mang thiết bị; nền tảng suy ra merchant từ bản ghi thiết bị, không thấy ca mở cho kênh, nên tạo một ca - rồi ghi danh thiết bị và check-in thu ngân. Vì thiết bị bật ngăn kéo tiền, một ngăn kéo được tạo với tiền đầu ca. Máy thứ hai trên cùng kênh mở và tham gia cùng ca đó; lời gọi ngữ cảnh hiện tại nay hiển thị hai thiết bị đã tham gia. Khi đóng, thiết bị chạy báo cáo Z khóa theo chính bản ghi của nó. Máy của merchant thứ hai không bao giờ xuất hiện trong cả hai danh sách.

4. Câu chuyện Người dùng

• Là thu ngân, tôi mở ca từ máy của mình mà không cần khai báo merchant nào, nên tôi không thể hành động sai tenant.
• Là thu ngân, khi đồng nghiệp đã mở ca của kênh, lần mở của tôi tham gia vào nó thay vì tạo ca thứ hai.
• Là thu ngân, ngăn kéo của tôi chỉ được tạo vì thiết bị của tôi điều khiển ngăn kéo tiền, nên thiết bị không ngăn kéo không bao giờ có ngăn kéo ma.
• Là quản lý, tôi thấy thiết bị nào đang hoạt động, đã tham gia, và còn chờ trên ca của một kênh.
• Là quản lý, tôi chạy báo cáo X và Z cho một thiết bị hoặc cả ca.
• Là back-office, tôi liệt kê ca của một merchant không cần giữ thiết bị, dùng phạm vi merchant.
• Là chủ sở hữu, tôi liên kết mỗi trạm bếp với máy in của nó cùng số bản và tự in, để phiếu định tuyến đúng máy in.

5. Yêu cầu Chức năng

#	Yêu cầu	Trạng thái	Tham chiếu URD
FR-1	Mọi hành động ca theo thiết bị phân giải thiết bị từ định danh thiết bị và suy ra merchant từ bản ghi thiết bị đó	Đã dựng	URD-DSX-001
FR-2	Thiếu định danh thiết bị trên một hành động theo thiết bị bị từ chối; back-office đọc có thể chạy không cần thiết bị qua phạm vi merchant đang hoạt động	Đã dựng	URD-DSX-002
FR-3	Thiết bị phải tồn tại, được gán merchant, và khớp với merchant cung cấp (nếu có); nếu không, hành động bị từ chối	Đã dựng	URD-DSX-003
FR-4	Quyền truy cập tenant được áp dụng trên merchant đã phân giải cho mọi hành động ca	Đã dựng	URD-DSX-004
FR-5	Mở một ca sẽ mở hoặc tham gia ca mở duy nhất của kênh bán mà thiết bị thuộc về; các lần mở đồng thời hội tụ về một ca	Đã dựng - bên thua khi mở đồng thời bị từ chối rồi gọi tham gia tiếp theo (không phải một endpoint mở-hoặc-tham-gia trong suốt duy nhất)	URD-DSX-005
FR-6	Kênh bán cung cấp khi mở phải thuộc về merchant đã phân giải	Đã dựng	URD-DSX-006
FR-7	Thiết bị mở/tham gia được ghi danh và nhân viên mở được check-in cùng nó	Đã dựng	URD-DSX-007
FR-8	Ngăn kéo tiền theo thiết bị chỉ được tạo khi mở cho thiết bị bật ngăn kéo tiền	Đã dựng	URD-DSX-008 · URD-DSX-014
FR-9	Ngữ cảnh hiện tại trả về ca, ghi danh, ngăn kéo tùy chọn, tiền dự kiến, và sự tham gia thiết bị (đang hoạt động / đã tham gia / còn chờ)	Đã dựng - đã tham gia/đang hoạt động là số đếm, còn chờ là một danh sách	URD-DSX-009
FR-10	Tiền dự kiến bị bỏ khi chính sách đếm mù của merchant bật hoặc không có ngăn kéo	Đã dựng	URD-DSX-010
FR-11	Báo cáo X và Z có thể sinh theo thiết bị và theo ca, khóa theo thiết bị đã phân giải	Đã dựng	URD-DSX-011
FR-12	Thiết bị là bản ghi thuộc phạm vi merchant, đã xác thực; tìm kiếm thiết bị giới hạn theo các merchant người dùng đã tham gia	Đã dựng	URD-DSX-012..013
FR-13	Đích in được liên kết theo từng trạm bếp (máy in, số bản, tự in); lệnh định tuyến tới máy in liên kết	Một phần - liên kết (máy in / số bản / tự in) được lưu trên trạm bếp và phiếu liên kết tới trạm, nhưng không có định tuyến backend đọc nó; lệnh in do app POS native điều phối	URD-DSX-015

Toàn văn yêu cầu và tiêu chí chấp nhận nằm trong URD Thiết bị - DSX. PRD này tham chiếu thay vì lặp lại.

6. Yêu cầu Phi Chức năng

Lĩnh vực	Yêu cầu
Tenancy & phân quyền	Merchant được suy ra từ bản ghi thiết bị, không bao giờ từ client; quyền truy cập tenant được khẳng định trên mọi hành động; truy cập API thiết bị yêu cầu xác thực
Cách ly tìm kiếm	Tìm kiếm thiết bị chỉ trả về các merchant người dùng đã tham gia
Đồng thời	Mở-hoặc-tham-gia an toàn với đua - một lần tạo đồng thời hội tụ về ca mở duy nhất, không bao giờ trùng
Nguyên tử	Một lần mở ca (ca + ghi danh + check-in nhân viên + ngăn kéo) là một giao dịch toàn-hoặc-không
Nhất quán	Ngăn kéo chỉ tồn tại cho thiết bị bật ngăn kéo tiền; số đếm sự tham gia phản ánh thiết bị đã ghi danh
i18n	Tên thiết bị và tên trạm song ngữ (Anh & Việt)

7. UX & Luồng

Bề mặt chính: màn hình mở/hiện tại/đóng POS mang định danh thiết bị; panel ngữ cảnh hiện tại hiển thị thiết bị đang hoạt động / đã tham gia / còn chờ và tiền dự kiến; danh sách ca back-office chạy dưới phạm vi merchant không cần thiết bị; liên kết trạm-tới-máy-in được cấu hình theo từng trạm bếp.

8. Dữ liệu & Miền

Thực thể	Vai trò
Bản ghi thiết bị	Bản ghi trạm thuộc phạm vi merchant; mang cờ ngăn kéo tiền và là điểm neo mà mọi ca, ngăn kéo, báo cáo neo vào
Ca	Phiên mở-hoặc-tham-gia theo kênh bán; một ca mở mỗi kênh
Sự tham gia ca	Sự tham gia của một thiết bị (và nhân viên) trong một ca
Ngăn kéo tiền	Ngăn kéo tiền theo thiết bị, chỉ tạo cho thiết bị bật ngăn kéo tiền
Trạm bếp	Mang liên kết máy in theo trạm (máy in, số bản, tự in); liên kết được lưu và được app POS native tiêu thụ (không có định tuyến backend)

Chỉ ở mức khái niệm - schema và bất biến đầy đủ nằm trong mô hình miền commerce và tài liệu package sale.

9. Phụ thuộc & Giả định

Phụ thuộc vào

• Đăng ký thiết bị (PRD-DEV-001, URD-DEV) - bản ghi thiết bị và việc gán merchant phải tồn tại trước khi nó neo một ca.
• Quản lý ca - hành vi mở-hoặc-tham-gia, ghi danh, ngăn kéo, báo cáo.
• Miền commerce - sở hữu bản ghi thiết bị, cờ ngăn kéo tiền, và quản lý/tìm kiếm thiết bị thuộc phạm vi merchant.
• Kênh bán - kênh cung cấp khi mở phải thuộc về merchant đã phân giải.

Giả định

• Ứng dụng gửi định danh thiết bị trên mọi hành động ca theo thiết bị.
• Một thiết bị được gán đúng một merchant trước khi giao dịch.
• Chính sách quản lý ca và đếm mù của merchant đã được cấu hình.

10. Kế hoạch Phát hành & Tiêu chí Ra mắt

Khía cạnh	Kế hoạch
Phase	P2 - DSX trong danh mục tính năng URD, bên cạnh DEV / POS / PRN
Triển khai	Mọi merchant; không cờ tính năng
Migration	Thêm cờ ngăn kéo tiền trên model thiết bị; không cần backfill dữ liệu
Tiêu chí ra mắt	Hành động ca phân giải thiết bị và suy ra merchant; mở-hoặc-tham-gia cho một ca mỗi kênh dưới đồng thời; ngăn kéo chỉ xuất hiện cho thiết bị bật ngăn kéo tiền; sự tham gia và tiền dự kiến (nhận biết đếm mù) trả về đúng; báo cáo X và Z theo thiết bị/ca sinh được; liên kết in theo trạm được lưu (định tuyến ở phía client)
Giám sát	Tỷ lệ mở trùng, tỷ lệ từ chối thiếu định danh, nhất quán ngăn kéo-so-với-cờ, lần thử truy cập chéo merchant

Tham chiếu

• URD: Thiết bị - DSX · DEV · POS · PRN
• PRD liên quan: Đăng ký, quản lý thiết bị & ngoại vi · Tín hiệu & thông báo thiết bị
• Module: Thiết bị - URD
• Developer: @nx/sale · @nx/commerce · @nx/core
• Apps: sale-renderer · client

Rủi ro & Câu hỏi mở

Rủi ro / câu hỏi	Giảm thiểu / trạng thái
Hai thiết bị mở cùng kênh đồng thời	Mở-hoặc-tham-gia hội tụ về ca mở duy nhất; bên thua tham gia, không trùng
Client gửi merchant sai hoặc lạ	Merchant suy ra từ bản ghi thiết bị và quyền tenant được khẳng định; merchant cung cấp không khớp bị từ chối
Ngăn kéo tạo cho thiết bị không ngăn kéo	Tạo ngăn kéo bị chặn theo cờ ngăn kéo tiền của thiết bị
Tiền dự kiến lộ khi đếm mù	Tiền dự kiến bị bỏ khỏi ngữ cảnh khi bật đếm mù hoặc không có ngăn kéo
Hành động chạy không có định danh thiết bị	Hành động theo thiết bị từ chối khi thiếu định danh; chỉ back-office đọc tường minh chạy không thiết bị dưới phạm vi merchant

Câu hỏi thường gặp

Câu hỏi	Trả lời
Ai quyết định ca thuộc về merchant nào?	Thiết bị - merchant được suy ra từ bản ghi thiết bị phân giải qua định danh thiết bị. Client không bao giờ cung cấp nó cho hành động theo thiết bị.
Điều gì xảy ra khi hai máy mở cùng ca của một kênh cùng lúc?	Chúng hội tụ về một ca - máy đầu tạo nó, máy thứ hai tham gia. Không bao giờ có ca mở trùng theo kênh.
Mọi thiết bị đều có ngăn kéo tiền chứ?	Không - ngăn kéo chỉ được tạo khi mở cho thiết bị gắn cờ bật ngăn kéo tiền. Thiết bị khác tham gia ca mà không có ngăn kéo.
Vì sao tiền dự kiến đôi khi vắng khỏi ngữ cảnh?	Nó bị bỏ khi chính sách đếm mù của merchant bật, hoặc khi thiết bị không có ngăn kéo.
Tôi có thể chạy báo cáo không cần thiết bị không?	Danh sách ca chạy back-office dưới phạm vi merchant không cần thiết bị. Báo cáo X/Z theo thiết bị và theo ca khóa theo thiết bị đã phân giải và cần định danh thiết bị.
Phiếu đến đúng máy in bằng cách nào?	Mỗi trạm bếp lưu một liên kết máy in (máy in, số bản, cờ tự in). Liên kết được lưu ở backend; việc định tuyến lệnh in thực tế do app POS native thực hiện - không có bộ định tuyến in ở backend.