Thanh toán & Giao dịch Phase A In-progress
Kết nối nhà cung cấp thanh toán của merchant tới BANA và biến thanh toán hoàn tất thành tiền mà merchant có thể theo dõi. Nó trải qua hai backend service: Thanh toán (credential nhà cung cấp + dispatch webhook/event) và Tài chính (ví ghi sổ kép, tài khoản, và sổ cái giao dịch tự-post). Được dùng bởi thu ngân (người thu thanh toán) và chủ (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 (event 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), Chủ / Quản lý (đối chiếu) |
Hai package, một business module. Thu một thanh toán và ghi nhận tiền của 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 live (nhà cung cấp, webhook, trạng thái real-time); service Tài chính ghi sổ thu/chi kết quả 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ừ |
|---|---|
| Credential nhà cung cấp thanh toán theo từng merchant (VNPAY QR MMS, VNPAY PhonePOS) | Code tích hợp trực tiếp nhà cung cấp/gateway (nằm trong payment engine) |
| Trạng thái thanh toán real-time (webhook + broadcast WebSocket) | UX checkout / tách-thanh-toán (do module Đơn hàng sở hữu) |
| Subscription webhook outbound theo từng merchant | 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 control nội bộ | Quy đổi đa tiền tệ (một 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) |
| Thu/chi tự-post từ event bán, mua, và kho | Settlement / đối chiếu cross-merchant |
| Phân cấp nhóm thu/chi (14 nhóm seed + tùy chỉnh) | Hoàn / đảo charge nhà cung cấp ngoài |
3. Năng lực
| Năng lực | Người dùng có thể làm gì | Trạng thái |
|---|---|---|
| Credential nhà cung cấp thanh toán | Chủ kết nối VNPAY QR MMS / PhonePOS với credential mã hóa theo từng merchant | Built |
| Trạng thái thanh toán live | Thu ngân thấy một thanh toán đi từ pending tới paid/failed/expired real-time | Built |
| Subscription webhook | Cấu hình endpoint nào nhận event thanh toán, với loại event và retry | Built |
| Tài khoản / ví Tài chính | Chủ tạo ví (cash, bank, QR, POS di động) và theo dõi số dư chạy | Built |
| Tự thu khi thanh toán | Một thanh toán bán hoàn tất tự động post một voucher RECEIPT cân bằng | Built |
| Tự chi khi mua / kho | Nhận một đơn mua hàng hoặc điều chỉnh tồn post voucher khớp | Built |
| Sổ cái giao dịch | Chủ xem sổ cái ghi sổ kép, số dư tài khoản, và lịch sử voucher | Built |
| Voucher thủ công | Chủ ghi một receipt/payment/transfer/adjustment thủ công và void bằng đảo ngược | Built |
| Nhóm | 14 nhóm thu/chi seed cộng các nhóm tùy chỉnh theo từng merchant | Built |
| Hoàn / đảo charge ngoài | Hoàn tiền có cấu trúc qua nhà cung cấp gốc | Planned |
| Đối chiếu tiền mặt theo từng ca | Kỳ vọng vs. thực tế tiền mặt với chênh lệch | Planned |
4. Phụ thuộc Module
| Phụ thuộc vào | Lý do |
|---|---|
| Đơn hàng | Một sale order là thứ kích một thanh toán; thanh toán hoàn tất settle đơn |
| Kho | Event xuất/điều chỉnh tồn điều khiển post chi vào sổ cái |
| Thuế & Hóa đơn | Một thanh toán thành công có thể kích phát hành hóa đơn downstream |
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: credential nhà cung cấp, dispatch webhook, broadcast trạng thái real-time | payment |
@nx/finance | Ghi sổ kép: tài khoản/ví, voucher, sổ cái giao dịch, nhóm | finance |
6. Luồng Người dùng Chính
Thu một thanh toán (service Thanh toán)
Ghi nhận tiền (service Tài chính)
7. Vai trò & Quyền hạn
| Vai trò | Có thể | Không thể |
|---|---|---|
| Chủ | Kết nối nhà cung cấp, quản lý ví/tài khoản, tạo voucher thủ công, xem sổ cái | — |
| Quản lý | Xem sổ cái, quản lý tài khoản, tạo voucher thủ công | Đổi credential nhà cung cấp (chủ-gated) |
| Thu ngân | Thu thanh toán, xem trạng thái thanh toán live | Quản lý tài khoản hoặc post voucher thủ công |
8. Trạng thái & Lộ trình
| Phase | Năng lực |
|---|---|
| P1 | Credential nhà cung cấp thanh toán, trạng thái thanh toán webhook + WebSocket, subscription webhook |
| P2 | Tài khoản/ví Tài chính, voucher ghi sổ kép, tự-post từ event bán/mua/kho, nhóm, voucher thủ công + void |
| 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 với chênh lệch |
9. Trang Liên quan
- URD
- Test Cases
- PRDs
- Đơn hàng · Kho · Thuế & Hóa đơn
- Lập trình viên: payment · finance