Shop/Cashier → Player (Counter Deposit)

Phase 2 trong chuồi Cash Settlement — sau Phase 1 hierarchy (Admin → SA → Agent → Shop).

Player đưa tiền tại quầy → Shop/Cashier xác nhận → credit cộng vào player wallet, shop CDN wallet bị trừ tương ứng.

Player đưa cash → Cashier/Shop xác nhận → credit vào Player → ghi sổ đối soát (Cash In)

Luồng redemption (Player đổi credit lấy tiền mặt) là Phase 3 riêng: Player → Shop/Cashier.

Mockup: Phase 2 — Deposits tab · Cashier spec: Cashier Management spec

---

Vị trí trong hệ thống

flowchart LR
  subgraph P1["Phase 1"]
    AG[Agent] --> SH[Shop CDN wallet]
  end
  subgraph P2["Phase 2"]
    SH --> P[Player wallet]
  end
  subgraph P3["Phase 3"]
    P --> SH2[Shop — redemption]
  end
  P1 --> P2
  P2 -.-> P3

Shop phải có đủ credit trong CDN wallet (từ Phase 1 Agent→Shop) trước khi cấp credit cho Player.

Khác Phase 1 hierarchy: deposit counter auto-settled khi complete — cash và credit di chuyển đồng thời, V1 không công nợ tạm.

---

Ai làm gì

Vai trò	Hành động
Player	Đưa tiền tại quầy; nhận credit ngay sau khi Cashier/Shop xác nhận
Cashier	Tìm player, nhập số tiền/credit, xác nhận deposit (cash only, trong active shift)
Shop Manager	Có thể add credit thủ công từ Shop portal (cash / card / bank transfer)
Hệ thống	Debit shop CDN wallet, credit player wallet, ghi audit, cập nhật shift Cash In

---

Hai kênh thực hiện

Kênh	Vai trò	Điều kiện	API
Cashier portal	Cashier tại quầy	Active shift bắt buộc; cash only	POST /cashier/players/:id/deposit
Shop portal	Shop Manager	Không bắt buộc shift	POST /shop/players/:id/credits (action: add)

Cashier path ghi cashier_transactions (shift reconciliation). Shop Manager path ghi shop_action_logs. Cả hai chưa ghi cash_transactions ledger (target Phase 2).

---

Thông tin bắt buộc

Cashier portal (V1)

Trường	Bắt buộc	Mô tả
Player	✅	Player thuộc shop
Số credit / số tiền	✅	V1: 1:1 — 50 credits = $50 cash
Hình thức	✅ (cố định)	cash
Shift / Cashier / Device	✅ (hệ thống)	Tự gắn từ session + active shift

Shop portal (manual add)

Trường	Bắt buộc	Mô tả
Player	✅	Player thuộc shop
Số credit	✅	Số dương, > 0
payment_method	✅	cash | card | bank transfer
action	✅	add

---

Công thức tiền & margin

V1 counter deposit: 1 credit = $1 USD (face value cho Player).

Chỉ số	Công thức
Cash received (expected)	credit_amount
Shop CDN cost	credit_amount × shop.costRate (snapshot)
Shop gross margin	credit_amount × (1 − shop.costRate) — metadata báo cáo

Ví dụ: cost rate 0.80, deposit 50 credits:

Mục	Giá trị
Cash received	$50.00
Shop CDN cost	$40.00
Gross margin	$10.00
Shop CDN wallet	−50
Player wallet	+50

Counter deposit luôn debit wallet shop hiện tại — effectiveLevel chỉ snapshot báo cáo.

---

Quy tắc nghiệp vụ

1. Player thuộc shop, không bị ban.
2. Shop có đủ credit CDN wallet.
3. Cashier: active shift bắt buộc; không OTP.
4. Sau complete: không sửa / hủy / reverse.
5. cashDelta = +amount (cash) → Cash In trong shift.

---

Ledger đề xuất (cash_transactions)

Field	Value
flow	shop_player_deposit
seller	shop / shop uuid
buyer	player / player uuid
expected_cash	= credit_amount (1:1 V1)
status	paid_full (auto)

Links: payment_transaction_id, wallet txs, cashier_transaction_id (cashier path), shift_id.

---

Backend hiện tại

Cashier: cashierTransactionBizService.depositCredits
  → playerCreditPort.transferCreditsAtCounter (deposit)
  → shopPlayerBizService._adjustCreditsAdd
  → walletTransferService (shop → player)
  → PaymentTransaction (provider: shop_player_cash)
  → CashierTransaction (type: deposit_credits)

Shop: shopPlayerBizService.adjustPlayerCredits (action: add)
  → cùng _adjustCreditsAdd (không qua shift)

---

API

Đã có

Method	Endpoint	Body
POST	/api/cashier/players/:id/deposit	{ "amount": number }
POST	/api/shop/players/:id/credits	{ "action": "add", "amount": N, "payment_method": "cash" }

Target Phase 2

Method	Endpoint	Mô tả
GET	/api/shop/cash-transactions?flow=shop_player_deposit	List deposits
GET	/api/shop/cash-transactions/:id	Detail
GET	/api/shop/cash-transactions/export	CSV

---

UI đề xuất (Shop portal)

Tab Receivable — Deposits trên mockup phase2-counter:

• Summary: Counter Cash In, Gross margin (today)
• Bảng: player, cashier, credits, cash received, margin, receipt
• Detail view-only

Cashier portal: tx nằm trong Active Shift — không cần ledger riêng V1.

---

Hiện trạng

Thành phần	Trạng thái
Wallet transfer shop → player	✅
payment_transactions + cashier_transactions	✅
cash_transactions flow shop_player_deposit	❌
Shop portal deposit ledger	❌

Tasks: tasks-shop-cashier-to-player

---

Liên quan

• Phase 1: Agent → Shop
• Phase 3: Player → Shop/Cashier (Redemption)
• Schema: schema-cash-transactions