PRD: Ngữ cảnh ca làm việc theo thiết bị & liên kết máy in
| Module | Thiết bị (CORE-04) | PRD ID | PRD-DSX-001 |
| Status | Shipped | Owner | Nhóm Sale |
| Date | 2026-06-15 | Version | v1.0 |
| Packages | @nx/sale · @nx/commerce · @nx/core | URD | DSX · DEV · POS · PRN |
TL;DR
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 thiết bị trong header
x-device-info; 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 đó.
1. Bối cảnh & Vấn đề
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: header x-device-info phân giải mọi hành động ca về một thiết bị, merchant được suy ra từ dòng 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ó.
2. 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ừ header
x-device-info, 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 ESC/POS - rasterize, code page 28, 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).
3. 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 x-device-info; 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 |
4. Đố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. Header 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.
5. 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.
6. Yêu cầu Chức năng
| # | Yêu cầu | Tham chiếu URD |
|---|---|---|
| FR-1 | Mọi hành động ca theo thiết bị phân giải thiết bị từ header x-device-info và suy ra merchant từ bản ghi thiết bị đó | URD-DSX-001 |
| FR-2 | Thiếu header 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 | 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 | 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 | 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 | URD-DSX-005 |
| FR-6 | Kênh bán cung cấp khi mở phải thuộc về merchant đã phân giải | 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ó | 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 | 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ờ) | 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 | 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 | 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 | 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 | 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.
7. 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 JWT hoặc Basic Auth |
| 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 dưới khóa dòng, 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ữ ({ en, vi }) |
8. UX & Luồng
Bề mặt chính: màn hình mở/hiện tại/đóng POS trong sale-renderer mang header 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 trong apps/client 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.
9. Dữ liệu & Miền
| Thực thể | Vai trò |
|---|---|
Device | 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 |
Shift | Phiên mở-hoặc-tham-gia theo kênh bán; một ca mở mỗi kênh |
ShiftEnrollment | Sự tham gia của một thiết bị (và nhân viên) trong một ca |
ShiftDrawer | 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 |
KitchenStation | Mang liên kết máy in theo trạm (máy in, số bản, tự in) định tuyến lệnh in |
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.
10. 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.
- Sale - quản lý ca (
@nx/sale) - các service mở-hoặc-tham-gia, ghi danh, ngăn kéo, báo cáo. - Commerce (
@nx/commerce) - sở hữu thực thểDevice, cờ ngăn kéo tiền, và CRUD/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 thiết bị trong header
x-device-infotrê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.
11. 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 dưới khóa dòng; 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ó header thiết bị | Hành động theo thiết bị từ chối khi thiếu header; chỉ back-office đọc tường minh chạy không thiết bị dưới phạm vi merchant |
12. 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 định tuyến lệnh |
| Giám sát | Tỷ lệ mở trùng, tỷ lệ từ chối thiếu header, nhất quán ngăn kéo-so-với-cờ, lần thử truy cập chéo merchant |
13. FAQ
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 x-device-info. 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 header.
Phiếu đến đúng máy in bằng cách nào? Mỗi trạm bếp liên kết với một máy in cùng số bản và cờ tự in; lệnh in định tuyến tới máy in liên kết.
Tham khảo
- 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ị - tổng quan + khả năng
- Developer: @nx/sale · @nx/commerce · @nx/core
- Apps: sale-renderer · client