URD: Thanh toán & Giao dịch
| Module | CORE-08 | Phiên bản | v0.5 |
|---|---|---|---|
| Trạng thái | In-progress | Ngày | 2026-06-04 |
Tài liệu nghiệp vụ. URD này là danh sách tính năng của Thanh toán & Giao dịch - mỗi tính năng dưới đây là một Lĩnh vực Chức năng (
<AREA>). Cùng<AREA>đó làm khóa cho PRD (PRD-<AREA>-NNN) và test (TC-<AREA>-NNN) của tính năng, và mỗi tính năng được liệt kê trong danh mục tính năng Delivery. Xem quy ước Feature Spine.
1. Mục đích
Định nghĩa các yêu cầu hướng người dùng cho việc thu thanh toán và ghi nhận khoản tiền phát sinh. Module kết nối các nhà cung cấp thanh toán của một merchant với KICKO, hiển thị trạng thái thanh toán theo thời gian thực, và ghi sổ mọi khoản thanh toán, mua hàng và biến động tồn kho đã hoàn tất vào một sổ cái tài chính ghi sổ kép để chủ có thể xem số dư và đối chiếu sổ sách.
2. Phạm vi
| Bao gồm | Loại trừ |
|---|---|
| Thông tin xác thực của nhà cung cấp thanh toán theo từng merchant (VNPAY QR MMS, PhonePOS) | Code tích hợp gateway trực tiếp (thuộc về lập trình viên) |
| Trạng thái thanh toán thời gian thực (webhook + WebSocket) | Giao diện thanh toán / chia nhỏ khoản thanh toán (module Đơn hàng) |
| Đăng ký webhook gửi ra ngoài theo từng merchant | Lưu trữ dữ liệu thẻ / token |
| Tài khoản / ví Tài chính + tài khoản đối ứng | Quy đổi đa tiền tệ |
| Voucher ghi sổ kép (RECEIPT / PAYMENT / TRANSFER / ADJUSTMENT) | Phát hành hóa đơn thuế (module Thuế & Hóa đơn) |
| Tự động ghi sổ từ các sự kiện bán hàng, mua hàng và kho | Hoàn tiền nhà cung cấp có cấu trúc (Dự kiến) |
| Phân cấp nhóm (tạo sẵn + tùy chỉnh) | Đối chiếu tiền mặt theo từng ca (Dự kiến) |
3. Định nghĩa
| Thuật ngữ | Định nghĩa |
|---|---|
| Nhà cung cấp thanh toán (Payment provider) | Một service bên ngoài (ví dụ VNPAY) xử lý khoản thanh toán của khách hàng |
| Webhook | Một thông báo gửi ra ngoài mà KICKO gửi tới subscriber khi một khoản thanh toán đổi trạng thái |
| Tài khoản / Ví (Account / Wallet) | Một nơi tiền nằm: tiền mặt, ngân hàng, thu qua QR, POS di động, hoặc một tài khoản đối ứng nội bộ |
| Voucher | Một bút toán cân đối thuộc một loại (RECEIPT, PAYMENT, TRANSFER, ADJUSTMENT) |
| Giao dịch (dòng sổ cái) | Một dòng DEBIT hoặc CREDIT trong một voucher, tác động đến số dư của một tài khoản |
| Nhóm (Category) | Một nhãn thu hoặc chi phân loại tiền đến từ đâu hoặc đi đâu |
| Tự động ghi sổ (Auto-posting) | Một voucher được hệ thống tạo tự động để phản ứng với một sự kiện nghiệp vụ |
4. Mô hình Khái niệm
Chỉ ở mức khái niệm - schema đầy đủ nằm trong mô hình miền lập trình viên của payment và finance.
5. Danh mục Tính năng
Danh sách tính năng của module này. Mỗi dòng là một tính năng (một Lĩnh vực Chức năng). Chi tiết ở §6. Được phản chiếu trong danh mục tính năng Delivery.
| Feature ID | Tính năng | Phase | Trạng thái | Ưu tiên |
|---|---|---|---|---|
PAY | Vòng đời Thanh toán | P1 | Built | High |
PRV | Thông tin xác thực Nhà cung cấp | P1 | Built | High |
WAL | Tài khoản & Ví | P2 | Built | High |
VCH | Voucher & Sổ cái | P2 | Built | High |
CAT | Nhóm | P2 | Built | High |
Trạng thái: live từ Plane nếu có map, còn lại do registry khai báo. Vocabulary đồng nhất với Plane (state-group / phase).
6. Tính năng
Mỗi tính năng một mục con, theo thứ tự danh mục. Mỗi tính năng giữ chung mô tả, yêu cầu và tiêu chí chấp nhận. Mức ưu tiên = MoSCoW (Must / Should / Could / Won't).
PAY - Vòng đời Thanh toán Built
Feature ID: payment/PAY · Phase: P1 · PRDs: - · Dev: @nx/payment
Làm gì cho người dùng: một khoản thanh toán chuyển từ pending sang paid, failed, hoặc expired theo thời gian thực; thu ngân thấy thay đổi ngay lập tức và sale sở hữu đơn được thông báo ngay khi thanh toán thành công.
Yêu cầu
| ID | P | Yêu cầu |
|---|---|---|
| URD-PAY-001 | M | Hệ thống nhận kết quả thanh toán từ nhà cung cấp và cập nhật trạng thái của khoản thanh toán |
| URD-PAY-002 | M | Khi thanh toán thành công, hệ thống thông báo cho subscriber (ví dụ sale tất toán đơn) |
| URD-PAY-003 | M | Trạng thái thanh toán được phát sóng theo thời gian thực tới thu ngân (pending → paid / failed / expired) |
| URD-PAY-004 | M | Cùng một kết quả thanh toán chỉ được áp dụng một lần, dù được gửi nhiều lần (idempotent) |
| URD-PAY-005 | S | Chủ có thể đăng ký các endpoint webhook theo loại sự kiện, có thử lại khi gửi thất bại |
| URD-PAY-006 | W | Hoàn tiền có cấu trúc qua nhà cung cấp gốc (Dự kiến - xem §7) |
Tiêu chí Chấp nhận
AC-PAY-01: Cập nhật trạng thái thanh toán
| Cho trước | Khi | Thì |
|---|---|---|
| Một khoản thanh toán pending | Nhà cung cấp báo thành công | Trạng thái thành paid, subscriber được thông báo, thu ngân thấy cập nhật ngay lập tức |
| Một khoản thanh toán pending | Nhà cung cấp báo thất bại / hết hạn | Trạng thái thành failed / expired; đơn vẫn để mở |
| Một kết quả đã áp dụng | Cùng kết quả được gửi lại | Bị bỏ qua; không gây hiệu ứng trùng lặp |
PRV - Thông tin xác thực Nhà cung cấp Built
Feature ID: payment/PRV · Phase: P1 · PRDs: - · Dev: @nx/payment
Làm gì cho người dùng: chủ kết nối một nhà cung cấp thanh toán (VNPAY QR MMS, PhonePOS) theo từng merchant; thông tin xác thực được lưu mã hóa, che bớt trong response, và không bao giờ dùng được bởi merchant khác.
Yêu cầu
| ID | P | Yêu cầu |
|---|---|---|
| URD-PRV-001 | M | Chủ có thể kết nối một nhà cung cấp thanh toán (VNPAY QR MMS, PhonePOS) theo từng merchant |
| URD-PRV-002 | M | Thông tin xác thực của nhà cung cấp được lưu mã hóa và không bao giờ hiển thị đầy đủ |
| URD-PRV-003 | S | Thông tin xác thực được giới hạn theo từng merchant nên một merchant không thể dùng của merchant khác |
Tiêu chí Chấp nhận
AC-PRV-01: Kết nối nhà cung cấp an toàn
| Cho trước | Khi | Thì |
|---|---|---|
| Một chủ của một merchant | Kết nối một nhà cung cấp thanh toán | Thông tin xác thực được lưu mã hóa và che bớt trong response |
| Một merchant khác | Thử dùng thông tin xác thực đó | Bị từ chối truy cập; thông tin xác thực giới hạn theo từng merchant |
WAL - Tài khoản & Ví Built
Feature ID: payment/WAL · Phase: P2 · PRDs: - · Dev: @nx/finance
Làm gì cho người dùng: chủ tạo các tài khoản nơi tiền nằm - tiền mặt, ngân hàng, thu qua QR, POS di động - mỗi tài khoản theo dõi một số dư đầu kỳ và số dư hiện hành; hệ thống cũng tự động giữ các tài khoản đối ứng nội bộ, và một tài khoản mặc định nhận khoản thu bán hàng được ghi tự động.
Yêu cầu
| ID | P | Yêu cầu |
|---|---|---|
| URD-WAL-001 | M | Chủ có thể tạo tài khoản loại CASH, BANK, mã QR, hoặc POS di động |
| URD-WAL-002 | M | Hệ thống tự động duy trì các tài khoản đối ứng nội bộ (ví dụ inventory, COGS) |
| URD-WAL-003 | M | Mỗi tài khoản theo dõi một số dư đầu kỳ và một số dư hiện hành |
| URD-WAL-004 | M | Mỗi merchant có một tài khoản mặc định nhận khoản thu bán hàng được ghi tự động |
| URD-WAL-005 | S | Các vai trò không phải chủ chỉ thấy tài khoản của những merchant họ được cấp quyền truy cập |
Tiêu chí Chấp nhận
AC-WAL-01: Tài khoản và số dư
| Cho trước | Khi | Thì |
|---|---|---|
| Một chủ | Tạo một tài khoản với một số dư đầu kỳ | Tài khoản hiển thị số dư đầu kỳ đó là số dư hiện hành |
| Một voucher đã ghi | Nó ghi nợ/ghi có một tài khoản | Số dư hiện hành của tài khoản cập nhật tương ứng |
VCH - Voucher & Sổ cái Built
Feature ID: payment/VCH · Phase: P2 · PRDs: - · Dev: @nx/finance
Làm gì cho người dùng: mọi biến động tiền là một voucher ghi sổ kép cân đối (RECEIPT, PAYMENT, TRANSFER, ADJUSTMENT); các khoản bán hàng hoàn tất, đơn mua hàng đã nhận, và biến động tồn kho được ghi tự động đúng một lần mỗi loại, và chủ có thể tạo hoặc huỷ voucher thủ công mà không bao giờ xóa lịch sử tài chính.
Yêu cầu
| ID | P | Yêu cầu |
|---|---|---|
| URD-VCH-001 | M | Mọi voucher đều cân đối: tổng DEBIT bằng tổng CREDIT |
| URD-VCH-002 | M | Các loại voucher là RECEIPT, PAYMENT, TRANSFER, ADJUSTMENT |
| URD-VCH-003 | M | Một khoản thanh toán bán hàng hoàn tất tự động ghi một voucher RECEIPT vào tài khoản mặc định |
| URD-VCH-004 | M | Nhận một đơn mua hàng tự động ghi một voucher PAYMENT |
| URD-VCH-005 | M | Một lần xuất/điều chỉnh tồn kho tự động ghi voucher sổ cái tương ứng |
| URD-VCH-006 | M | Mỗi voucher ghi lại sự kiện nguồn của nó nên cùng một sự kiện chỉ ghi một lần (idempotent) |
| URD-VCH-007 | M | Voucher được đánh số theo từng merchant và loại (ví dụ PT / PC / PCK / PKT) |
| URD-VCH-008 | S | Chủ có thể tạo một voucher thủ công (nháp → phát hành) |
| URD-VCH-009 | S | Chủ có thể huỷ một voucher bằng một bút toán đảo ngược cân đối (không xóa cứng) |
| URD-VCH-010 | C | Chuyển khoản giữa hai tài khoản được ghi như một voucher tổng bằng không |
Tiêu chí Chấp nhận
AC-VCH-01: Tự động ghi sổ từ sự kiện
| Cho trước | Khi | Thì |
|---|---|---|
| Một khoản thanh toán bán hàng thành công | Sự kiện được xử lý | Một voucher RECEIPT cân đối được ghi vào tài khoản mặc định |
| Một đơn mua hàng đã nhận | Sự kiện được xử lý | Một voucher PAYMENT cân đối được ghi |
| Cùng một sự kiện nguồn | Nó được gửi lại | Không voucher thứ hai nào được tạo (idempotent) |
AC-VCH-02: Voucher thủ công và huỷ
| Cho trước | Khi | Thì |
|---|---|---|
| Một chủ | Tạo và phát hành một voucher thủ công | Một voucher cân đối xuất hiện trong sổ cái với một số thứ tự |
| Một voucher đã phát hành | Chủ huỷ nó | Một voucher đảo ngược cân đối được ghi; bản gốc được giữ lại |
CAT - Nhóm Built
Feature ID: payment/CAT · Phase: P2 · PRDs: - · Dev: @nx/finance
Làm gì cho người dùng: thu và chi được phân loại theo nhóm; 14 nhóm hệ thống được tạo sẵn và bảo vệ, và chủ có thể thêm các nhóm tùy chỉnh theo từng merchant, gồm cả phân cấp cha.
Yêu cầu
| ID | P | Yêu cầu |
|---|---|---|
| URD-CAT-001 | M | 14 nhóm hệ thống được tạo sẵn và không thể gỡ bỏ |
| URD-CAT-002 | M | Nhóm có kiểu INCOME hoặc EXPENSE |
| URD-CAT-003 | S | Chủ có thể thêm các nhóm tùy chỉnh theo từng merchant, gồm cả phân cấp cha |
Tiêu chí Chấp nhận
AC-CAT-01: Nhóm tạo sẵn và tùy chỉnh
| Cho trước | Khi | Thì |
|---|---|---|
| Một merchant mới | Sổ cái tài chính khởi tạo | 14 nhóm hệ thống có kiểu (INCOME / EXPENSE) tồn tại và không thể gỡ bỏ |
| Một chủ | Thêm một nhóm tùy chỉnh theo từng merchant | Nó sẵn sàng để phân loại tiền, tùy chọn đặt dưới một nhóm cha |
7. Ràng buộc & Phi mục tiêu
Ràng buộc
| ID | Ràng buộc |
|---|---|
| C-01 | Mọi voucher phải cân đối (tổng DEBIT = tổng CREDIT) |
| C-02 | 14 nhóm tạo sẵn không thể gỡ bỏ |
| C-03 | Thông tin xác thực của nhà cung cấp được mã hóa khi lưu và che bớt trong response |
| C-04 | Mỗi sự kiện nghiệp vụ ghi tối đa một voucher (idempotent qua id sự kiện nguồn) |
| C-05 | Bản ghi dùng soft-delete / đảo ngược - không xóa cứng lịch sử tài chính |
| C-06 | Mỗi merchant có một tài khoản mặc định cho khoản thu bán hàng được ghi tự động |
Phi mục tiêu
- Luồng SoftPOS / NFC tap-to-pay
- Các nhà cung cấp ví điện tử bổ sung (Momo, ZaloPay)
- Hoàn / đảo khoản phí của nhà cung cấp bên ngoài có cấu trúc
- Quy đổi đa tiền tệ và đối chiếu liên tiền tệ
- Dashboard đối chiếu tiền mặt theo từng ca
8. Lịch sử Phiên bản
| Ngày | Tác giả | Mô tả | Ver |
|---|---|---|---|
| 2026-02-26 | P. Do - Product Owner | User story ban đầu | v0.1 |
| 2026-04-16 | P. Do - Product Owner | Ví tài chính, giao dịch, nhóm | v0.3 |
| 2026-05-30 | Migration | Tái cấu trúc theo quy ước module; căn chỉnh các lĩnh vực (PAY/PRV/WAL/VCH/CAT) theo thực tế hai package; hoàn tiền + đối chiếu được đánh dấu Dự kiến | v0.4 |
| 2026-06-04 | Claude (AI pair) | Tổ chức lại theo tính năng (Feature Spine); mỗi tính năng mang yêu cầu + tiêu chí chấp nhận riêng; CON chuyển sang Ràng buộc | v0.5 |