Spec — Cashier, Shift, Device & Cash Reconciliation

1. Cashier Account Management

Shop Manager có thể tạo Cashier với các thông tin:

Field	Bắt buộc	Ghi chú
Full name	✅
Username	✅
Email	✅
Phone number	✅
Shop	✅	Mỗi Cashier chỉ thuộc một Shop
Account status	✅	Active / Suspended / Terminated
Login method	✅	Email, username hoặc phone
Note		Tùy chọn

Cashier sử dụng Shop Portal với quyền hạn giới hạn theo role.

1.1 Trạng thái tài khoản

Status	Mô tả
Active	Đăng nhập và làm việc bình thường
Suspended	Không đăng nhập; xử lý shift đang active
Terminated	Vô hiệu hóa vĩnh viễn

1.2 Suspend Cashier

Khi Cashier bị suspend:

1. Toàn bộ session hiện tại bị revoke.
2. Cashier không đăng nhập trên bất kỳ device nào.
3. Device vẫn có thể được Cashier khác sử dụng.
4. Nếu Cashier đang có active shift → shift chuyển sang Suspended – Pending Reconciliation.
5. Shop Manager nhận notification.
6. Shop Manager kiểm đếm cash drawer và thực hiện closing reconciliation.
7. Hệ thống ghi nhận thời điểm suspend, người thực hiện và giao dịch cuối cùng.

---

2. Shift Management

Shop phải tạo shift trước khi Cashier bắt đầu làm việc.

2.1 Thông tin shift

Bắt buộc khi tạo:

Field	Mô tả
Shift date	Ngày làm việc
Scheduled start time	Giờ bắt đầu dự kiến
Scheduled end time	Giờ kết thúc dự kiến
Assigned Cashier	Cashier được phân công
Assigned active device	Thiết bị được assign
Late grace minutes	Thời gian chấp nhận trễ
Note	Tùy chọn

Hệ thống tự ghi nhận:

shiftId, shopId, createdBy, createdAt, assignedBy, actualStartAt, actualEndAt, openingCash, expectedClosingCash, actualClosingCash, discrepancy, closedBy, reviewedBy, status

2.2 Scheduled Time vs Actual Time

Hệ thống phải lưu riêng biệt:

• Scheduled Start/End Time — thời gian dự kiến do Shop cấu hình.
• Actual Start/End Time — thời gian Cashier thực sự bắt đầu và kết thúc.

Không được ghi đè scheduled time bằng actual time.

2.3 Shift Assignment Validation

Cashier overlap — KHÔNG hợp lệ:

Shift 1: 08:00–16:00  } Cùng Cashier → CHẶN
Shift 2: 15:00–23:00  }

Device overlap — KHÔNG hợp lệ:

Cashier A: 08:00–16:00, POS-01  }
Cashier B: 15:00–23:00, POS-01  } → CHẶN

Device reuse — HỢP LỆ:

Cashier A: 08:00–16:00, POS-01
Cashier B: 16:00–00:00, POS-01

2.4 Shift Status

Giai đoạn	Status
Trước khi bắt đầu	Draft, Scheduled, Cancelled, No-Show
Trong shift	Active, Suspended, Auto-Locked
Kết thúc	Pending Reconciliation, Pending Manager Review, Completed, Completed with Discrepancy

Luồng thông thường:

Scheduled → Active → Pending Reconciliation → Completed

---

3. Start Shift

Cashier chỉ được start shift khi:

• Cashier đang Active.
• Shift được assign cho đúng Cashier.
• Shift chưa bị Cancelled hoặc No-Show.
• Cashier đăng nhập trên đúng device được assign.
• Device có trạng thái Active.
• Cashier không có active shift khác.
• Shift trước đã đóng hoặc Manager cho phép tiếp tục.

Khi start shift:

1. Cashier mở shift được assign.
2. Hệ thống xác nhận Cashier và Device.
3. Cashier nhập opening cash theo denomination.
4. Hệ thống tự tính tổng opening cash.
5. Cashier submit → hệ thống ghi actualStartAt → shift chuyển Active.

---

4. Opening Cash & Denomination Count

Shop chấp nhận tiền giấy và tiền xu Mỹ.

Tiền giấy

$1 · $2 · $5 · $10 · $20 · $50 · $100

Tiền xu

$0.01 · $0.05 · $0.10 · $0.25 · $0.50 · $1.00

Total Amount = Denomination × Quantity

Tất cả cash amount hỗ trợ hai chữ số thập phân.

---

5. Cash Transactions

5.1 Cash Deposit

Player đưa tiền mặt để mua Credit:

1. Cashier tìm Player.
2. Cashier nhập số tiền mặt nhận được.
3. Hệ thống kiểm tra transaction limit.
4. Cashier xác nhận → Credit cộng cho Player → Cash In tăng.

Ghi nhận: cashierId, shiftId, shopId, deviceId, playerId, transactionId, amount, createdAt

• Deposit do Cashier không yêu cầu Player OTP.
• Cashier không được sửa, hủy hoặc reverse sau khi hoàn thành.

5.2 Cash Redemption

Player đổi Credit lấy tiền mặt:

1. Cashier tìm Player, nhập số Credit cần redeem.
2. Hệ thống tính tiền mặt phải trả.
3. Kiểm tra limit và approval rule.
4. Nếu cần approval → Pending Approval → Shop Manager approve/reject.
5. Sau approve → Cashier trả tiền → Cash Out tăng.

Giới hạn có thể áp dụng theo transaction và theo ngày.

5.3 Cash Drop

Cashier chuyển tiền từ cash drawer cho Shop Manager hoặc két:

1. Cashier tạo Cash Drop, nhập denomination và số tiền.
2. Hệ thống tạo Cash Drop ID.
3. Cashier giao tiền offline.
4. Người nhận kiểm đếm và xác nhận online trên Shop Portal.
5. Cash Drop → Confirmed → Expected Cash Drawer giảm.

Status	Mô tả
Draft	Mới tạo
Pending Handover	Chờ bàn giao
Pending Receiver Confirmation	Chờ người nhận xác nhận
Confirmed	Đã xác nhận — trừ khỏi Expected Closing Cash
Rejected	Bị từ chối
Cancelled	Đã hủy
Disputed	Tranh chấp

Chỉ Cash Drop Confirmed mới được trừ khỏi Expected Closing Cash.

---

6. Expected Closing Cash

Expected Closing Cash = Opening Cash + Cash In − Cash Out − Confirmed Cash Drops ± Approved Adjustments

Thành phần	Mô tả
Opening Cash	Tiền đầu ca
Cash In	Tiền mặt nhận từ Player
Cash Out	Tiền mặt trả cho Player
Cash Drops	Tiền đã bàn giao khỏi drawer (Confirmed)
Approved Adjustments	Điều chỉnh được Shop Manager phê duyệt

Cashier không được sửa Expected Closing Cash.

---

7. Blind Closing Count & Discrepancy

7.1 Blind Closing

1. Cashier đếm tiền theo denomination.
2. Cashier nhập Actual Closing Cash.
3. Cashier không thấy Expected Closing Cash trước khi submit.
4. Sau submit, hệ thống hiển thị Expected, Actual và Discrepancy.
5. Cashier không được sửa Actual Closing Cash sau submit.

7.2 Discrepancy

Discrepancy = Actual Closing Cash − Expected Closing Cash

Kết quả	Ý nghĩa
Negative	Shortage
Positive	Overage
Zero	Balanced

Nếu có discrepancy → shift chuyển Pending Manager Review → notify Shop Manager.

7.3 Manager Review & Resolution

Shop Manager có thể:

• Yêu cầu recount
• Xác nhận Actual Closing Cash
• Ghi nhận discrepancy reason
• Thêm note hoặc attachment
• Tạo adjustment có audit log
• Close shift with discrepancy
• Suspend Cashier
• Escalate investigation
• Finalize shift

Resolution options:

No Action Required · Recount Confirmed · Data Entry Error · Missing Transaction · Missing Cash Drop Confirmation · Shortage Assigned to Cashier · Overage Recorded · Manager Adjustment Approved · Escalated for Investigation · Shift Closed with Discrepancy

Sau khi shift được finalize, dữ liệu tài chính không sửa trực tiếp. Mọi thay đổi sau đó phải tạo adjustment transaction mới.

---

8. No-Show

Nếu Cashier không sign-in trước Scheduled Start Time + Late Grace Minutes:

1. Shift → No-Show; ghi noShowDetectedAt.
2. Notify Shop Manager (không notify Admin).
3. Release device để assign shift khác.
4. Cho phép Shop reassign Cashier khác.

Shop Manager có thể: Reassign Cashier · Cancel shift · Tạo replacement shift · Ghi chú lý do.

Không được xóa shift No-Show khỏi lịch sử.

---

9. Automatic Lock

Khi đến Scheduled End Time:

1. Cảnh báo Cashier.
2. Trong Closing Grace Period — hoàn tất giao dịch đang xử lý.
3. Hết grace period — chặn giao dịch mới.
4. Shift → Auto-Locked → notify Cashier và Shop Manager.
5. Shift → Pending Reconciliation.

Hệ thống không được tự động điền Actual Closing Cash bằng Expected Closing Cash.

---

10. Shift Handover

Áp dụng khi Cashier sau nhận cash drawer từ Cashier trước:

1. Cashier A dừng giao dịch, thực hiện closing count.
2. Cashier B hoặc Shop Manager kiểm đếm tiền bàn giao.
3. Cashier B xác nhận số tiền nhận.
4. Closing Cash của Shift A → Opening Cash của Shift B.
5. Shift A đóng; Shift B được phép bắt đầu.

Handover record lưu:

fromShift, toShift, fromCashier, toCashier, device, cashDrawerOrCounter, denomination details, total cash amount, confirmation time, confirmed by, discrepancy (nếu có)

---

11. Device Management

Một physical device có thể được nhiều Cashier sử dụng ở các shift khác nhau.

Field	Mô tả
Device ID	Định danh thiết bị
Device Name	Tên hiển thị
Shop ID	Shop sở hữu
Device Type	Loại thiết bị
Operating System	Hệ điều hành
Browser / App Version	Phiên bản
Device Fingerprint	Dấu vân tay thiết bị
Last IP	IP gần nhất
First Registered Time	Lần đăng ký đầu
Last Active Time	Hoạt động gần nhất
Status	Trạng thái
Approved By / Approved At	Người duyệt / thời điểm

11.1 Device Status

Pending Approval · Active · Temporarily Blocked · Compromised · Lost · Retired

11.2 Revoke Cashier Access

Chỉ thu hồi quyền một Cashier trên một device. Cashier khác vẫn dùng được; device vẫn Active.

11.3 Block Device

Khóa toàn bộ device. Tất cả session revoke. Không Cashier nào dùng được. Active shift liên quan phải chuyển device hoặc reconcile.

Block Device ≠ Suspend Cashier

---

12. Transaction Visibility

Cashier được xem:

• Giao dịch do mình thực hiện
• Giao dịch thuộc active shift hiện tại
• Giao dịch thuộc shift cũ của mình (nếu Shop cho phép)

Cashier không được xem:

• Tổng balance của Shop
• Giao dịch của Cashier khác
• Toàn bộ transaction history của Shop
• Internal settlement của Shop

---

13. Shift Report

Báo cáo shift phải gồm:

Shift Information

Shift ID · Cashier · Shop · Device · Cash Drawer/Counter · Scheduled Start/End · Actual Start/End · Shift Status

Transaction Summary

Total Transactions · Total Cash Deposits · Total Cash Redemptions · Total Cash In · Total Cash Out · Total Cash Drops · Approved Adjustments

Cash Reconciliation

Opening Cash · Expected Closing Cash · Actual Closing Cash · Discrepancy · Shortage/Overage

Review and Audit

Reviewed By · Resolution · Manager Note · Attachments · Finalized At · Audit History

---

14. Audit Requirements

Hệ thống lưu audit log cho:

Cashier creation · Suspension/termination · Shift creation/assignment/reassignment · Device assignment/transfer · Opening cash · Cash deposit · Cash redemption · Cash drop · Closing cash · Manager review · Adjustment · Shift finalization · Device block/unblock · Cashier-device access revoke

Field	Mô tả
Action	Hành động thực hiện
Actor	Người thực hiện
Previous value	Giá trị trước
New value	Giá trị sau
Reason	Lý do
Timestamp	Thời điểm
Device	Thiết bị
IP address	Địa chỉ IP
Related entity ID	ID entity liên quan

---

15. Notification Requirements

Shop Manager nhận notification khi:

Sự kiện	Notify
Cashier No-Show	✅ Shop Manager
Cashier bị suspend giữa shift	✅ Shop Manager
Shift Auto-Locked	✅ Shop Manager + Cashier
Redemption cần approval	✅ Shop Manager
Cash Drop cần xác nhận	✅ Shop Manager
Closing reconciliation có discrepancy	✅ Shop Manager
Device mới cần approval	✅ Shop Manager
Device bị block / compromised	✅ Shop Manager
Shift handover có discrepancy	✅ Shop Manager
No-Show	❌ Không notify Admin

---

16. Actor Permissions Summary

Shop Manager

Tạo/sửa/suspend/terminate Cashier · Tạo/sửa shift · Assign/reassign Cashier và device · Xử lý no-show · Review closing reconciliation · Xử lý discrepancy · Close/finalize shift · Quản lý device · Block/unblock · Revoke cashier access · Xem báo cáo

Admin

Xem Cashier/Shift theo permission · Assign Cashier vào shift (đúng Shop) · Không xử lý no-show thường ngày · Không thay Shop Manager trong đối soát (trừ escalation)

Cashier

Đăng nhập (email/username/phone) · Xem shift được assign · Start shift · Opening cash · Deposit · Redemption (theo limit) · Cash drop · Xem giao dịch shift mình · Closing count · Submit reconciliation · Handover

Cashier không được: Xem giao dịch Shop/khác · Sửa/hủy/reverse giao dịch · Tự đổi lịch · Tự assign device · Sửa actual closing cash sau submit