Thanh toán & Giao dịch Phase A In-progress
Kết nối các phương thức thanh toán của sân với NexPickle và biến những khoản thanh toán hoàn tất thành tiền mà sân có thể theo dõi. Module trải dài trên hai backend service: Thanh toán (thông tin xác thực của nhà cung cấp + dispatch webhook/sự kiện) và Tài chính (ví ghi sổ kép, tài khoản, và sổ cái giao dịch ghi tự động). Áp dụng cho đơn POS tại sân - đặt sân + FNB + dụng cụ - bởi thu ngân (người thu tiền) và chủ sân (người đối chiếu sổ sách).
1. Định danh
| Thuộc tính | Giá trị |
|---|---|
| Module ID | CORE-08 |
| Tier | Core |
| Trạng thái | In-progress |
| Phase | P1 (sự kiện thanh toán) · P2 (sổ cái tài chính) |
| Mức ưu tiên | HIGH |
| Người dùng chính | Thu ngân (thu tiền), Chủ sân / Quản lý ca (đối chiếu) |
Hai package, một business module. Thu một khoản thanh toán và ghi nhận khoản tiền đó là hai nửa của cùng một câu chuyện. Service Thanh toán xử lý vòng đời thanh toán theo thời gian thực (nhà cung cấp, webhook, trạng thái thời gian thực); service Tài chính ghi sổ khoản thu/chi phát sinh vào một sổ cái ghi sổ kép. Xem §5 Backend Packages.
2. Mục đích & Phạm vi
| Bao gồm | Loại trừ |
|---|---|
| Phương thức thanh toán: tiền mặt, QR VNPAY, thẻ ngân hàng, ví theo từng sân | Code tích hợp trực tiếp với nhà cung cấp/gateway (nằm trong payment engine) |
| Trạng thái thanh toán thời gian thực (webhook + phát sóng qua WebSocket) | Giao diện thanh toán / chia nhỏ khoản thanh toán (do module Đơn hàng sở hữu) |
| Đăng ký webhook gửi ra ngoài theo từng sân | Lưu trữ dữ liệu thẻ / token |
| Tài khoản / ví Tài chính (CASH, BANK, mã QR, POS di động) + tài khoản đối ứng nội bộ | Quy đổi đa tiền tệ (một loại tiền tệ mỗi voucher) |
| Voucher ghi sổ kép (RECEIPT / PAYMENT / TRANSFER / ADJUSTMENT) | Phát hành hóa đơn thuế (do Thuế & Hóa đơn sở hữu) |
| Tự động ghi thu/chi từ sự kiện đơn POS (đặt sân + FNB + dụng cụ), mua hàng và kho | Bù trừ / đối chiếu giữa các sân |
| Phân cấp nhóm thu/chi (14 nhóm tạo sẵn + tùy chỉnh) | Hoàn / đảo khoản phí của nhà cung cấp bên ngoài |
3. Năng lực
| Năng lực | Người dùng có thể làm gì |
|---|---|
| Phương thức thanh toán | Chủ sân kết nối QR VNPAY / thẻ ngân hàng / ví với thông tin xác thực được mã hóa theo từng sân |
| Trạng thái thanh toán thời gian thực | Thu ngân thấy một khoản thanh toán chuyển từ pending sang paid/failed/expired theo thời gian thực |
| Đăng ký webhook | Cấu hình endpoint nào nhận sự kiện thanh toán, với loại sự kiện và số lần thử lại |
| Tài khoản / ví Tài chính | Chủ sân tạo ví (tiền mặt, ngân hàng, QR, POS di động) và theo dõi số dư hiện hành |
| Tự động ghi thu khi thanh toán | Một đơn POS hoàn tất tự động ghi một voucher RECEIPT cân đối |
| Tự động ghi chi khi mua hàng / kho | Nhận một đơn mua hàng hoặc điều chỉnh tồn kho sẽ ghi voucher tương ứng |
| Sổ cái giao dịch | Chủ sân xem sổ cái ghi sổ kép, số dư tài khoản và lịch sử voucher |
| Voucher thủ công | Chủ sân ghi một phiếu thu/chi/chuyển/điều chỉnh thủ công và huỷ bằng cách đảo ngược |
| Nhóm | 14 nhóm thu/chi tạo sẵn cộng các nhóm tùy chỉnh theo từng sân |
| Hoàn / đảo khoản phí bên ngoài | Hoàn tiền có cấu trúc qua nhà cung cấp gốc |
| Đối chiếu tiền mặt theo từng ca | Tiền mặt dự kiến so với thực tế kèm chênh lệch |
4. Phụ thuộc Module
| Phụ thuộc vào | Lý do |
|---|---|
| Đơn hàng | Một đơn POS (đặt sân + FNB + dụng cụ) là thứ kích hoạt một khoản thanh toán; thanh toán hoàn tất sẽ tất toán đơn |
| Kho | Sự kiện xuất/điều chỉnh tồn kho dẫn đến việc ghi khoản chi vào sổ cái |
| Thuế & Hóa đơn | Một khoản thanh toán thành công có thể kích hoạt phát hành hóa đơn ở khâu sau |
5. Backend Packages
Module này được vận hành bởi hai service. Chi tiết triển khai nằm trong tài liệu lập trình viên - phần này chỉ ánh xạ module tới chúng.
| Package | Vai trò | Tài liệu lập trình viên |
|---|---|---|
@nx/payment | Vòng đời thanh toán: cấu hình & dispatch webhook, phát sóng trạng thái thời gian thực (thông tin xác thực nhà cung cấp do @nx/finance pay-integration quản lý) | payment |
@nx/finance | Ghi sổ kép: tài khoản/ví, voucher, sổ cái giao dịch, nhóm | finance |
Engineering Mapping (Feature ⇄ Package)
Trục ngang của Feature Spine - mỗi tính năng nghiệp vụ (
<AREA>trong URD) ánh xạ tới nơi ở kỹ thuật của nó. Đối ứng: tài liệu package liên kết ngược về đây.
| Tính năng | Package | Trạng thái |
|---|---|---|
PAY Vòng đời Thanh toán | @nx/payment | Built |
PRV Thông tin xác thực Nhà cung cấp | @nx/payment | Built |
WAL Tài khoản & Ví | @nx/finance | Built |
VCH Voucher & Sổ cái | @nx/finance | Built |
CAT Nhóm | @nx/finance | Built |
6. Luồng Người dùng Chính
Thu một khoản thanh toán (service Thanh toán)
Ghi nhận khoản tiền (service Tài chính)
7. Vai trò & Quyền hạn
| Vai trò | Có thể | Không thể |
|---|---|---|
| Chủ sân | Kết nối phương thức thanh toán, quản lý ví/tài khoản, tạo voucher thủ công, xem sổ cái | - |
| Quản lý ca | Xem sổ cái, quản lý tài khoản, tạo voucher thủ công | Đổi thông tin xác thực của nhà cung cấp (chỉ chủ sân mới được) |
| Thu ngân | Thu thanh toán (tiền mặt, QR VNPAY, thẻ, ví), xem trạng thái thanh toán thời gian thực | Quản lý tài khoản hoặc ghi voucher thủ công |
8. Trạng thái & Lộ trình
| Phase | Năng lực |
|---|---|
| P1 | Phương thức thanh toán (tiền mặt, QR VNPAY, thẻ, ví), trạng thái thanh toán qua webhook + WebSocket, đăng ký webhook |
| P2 | Tài khoản/ví Tài chính, voucher ghi sổ kép, tự động ghi sổ từ sự kiện đơn POS/mua/kho, nhóm, voucher thủ công + huỷ |
| P3 | Hoàn tiền nhà cung cấp có cấu trúc, đối chiếu tiền mặt theo từng ca kèm chênh lệch |