Hoá đơn & Thuế Phase A In-progress
Tài liệu nghiệp vụ (BA)
UC — Use Case · SRS — Đặc tả yêu cầu · UI — Đặc tả giao diện
Giữ cho cơ sở sân tuân thủ pháp luật khi giao dịch: ghi nhận định danh thuế của người bán, áp đúng thuế suất lên sản phẩm và dịch vụ, rồi biến một thanh toán đã hoàn tất thành hoá đơn điện tử VAT hợp pháp theo chuẩn Việt Nam có thể gửi cho người mua và cơ quan thuế. Áp cho cả đơn bán hàng (FNB · dụng cụ) và đơn đặt sân. Được dùng bởi Chủ sân (thiết lập thuế và nhà cung cấp hoá đơn), Thu ngân (phát hành hoá đơn tại quầy), và người chơi (tự yêu cầu hoá đơn của mình).
Trạng thái: Built (P1 receipt) · In-progress (P2 VAT điện tử) · Owner: Việt Võ · Phase: 1-2 · Rà soát: 2026-06-15
Chuỗi Liên kết Roadmap Giai đoạn 2 - Theo tháng Epic BANA-1318 - Thuế S2a · 01/CNKD · T-VAN URD URD - increment mới: DCL·ISSPRD PRD-INV-003 Điều chỉnh & hủy · PRD-DCL-001 Kê khai thuế 1-3 tỷ · PRD-ISS-001 Xuất hoá đơn (danh mục) Tài liệu dev @nx/invoice · @nx/ledger Nhật ký giao Ma trận truy vết
1. Định danh
| Thuộc tính | Giá trị |
|---|---|
| Module ID | SYS-01 |
| Hạng | Core |
| Trạng thái | In-progress |
| Giai đoạn | P1 (receipt nội bộ tại quầy) · P2 (hoá đơn điện tử VAT + nộp cơ quan thuế) |
| Ưu tiên | HIGH |
| Người dùng chính | Chủ sân / Quản lý ca (thiết lập), Thu ngân (phát hành), Người chơi (tự yêu cầu) |
Hai dịch vụ, một module nghiệp vụ. Áp thuế lên sản phẩm/dịch vụ và phát hành hoá đơn là hai nửa của cùng một câu chuyện tuân thủ. Dịch vụ Taxation sở hữu quy tắc nhóm thuế và đẩy đúng thuế lên từng dòng hàng (sân · FNB · dụng cụ); dịch vụ Invoice phát hành hoá đơn điện tử VAT hợp pháp theo Nghị định 123/2020/NĐ-CP qua một nhà cung cấp T-VAN. Kết nối tới cơ quan thuế chạy qua hai adapter tích hợp - iiapi (cổng nhà cung cấp) và t-van (mạng cơ quan thuế). Xem §5 Backend Packages.
2. Mục đích & Phạm vi
| Bao gồm | Loại trừ |
|---|---|
| Định danh thuế người bán (mã số thuế / MST, tên cơ sở sân, địa chỉ) | Sổ đăng ký mã số thuế chính thức (do cơ quan thuế cấp) |
| Receipt nội bộ in tại quầy cho đơn bán hàng & đơn đặt sân | Tính thuế suất tại thời điểm bán (do engine Bảng giá sở hữu) |
| Hoá đơn điện tử VAT theo Nghị định 123/2020, ký số qua T-VAN | Render PDF của hoá đơn (do nhà cung cấp T-VAN tạo) |
| Hồ sơ hoá đơn cơ sở sân + thông tin xác thực nhà cung cấp (mã hoá) | Thu thanh toán (do Thanh toán sở hữu) |
| Phát hành hoá đơn cho đơn bán hàng (FNB · dụng cụ) và đơn đặt sân | Vòng đời đơn hàng (do Bán Hàng POS sở hữu) |
| Tích hợp nhà cung cấp T-VAN: VNPT / Viettel / MISA qua iiapi | Đa nhà cung cấp ngoài bộ iiapi/T-VAN hiện tại |
| Nộp lên cơ quan thuế (CQT) và theo dõi trạng thái | Tự động hoá kê khai / nộp thuế |
| Điều chỉnh, thay thế, và huỷ hoá đơn theo quy định (huỷ trong 7 ngày) | Đối soát liên-chi-nhánh |
| Người chơi tự yêu cầu hoá đơn (QR trên receipt + token + thời hạn) | |
| Dấu vết kiểm toán bất biến cho mọi sự kiện hoá đơn (lưu trữ 5 năm) |
3. Năng lực
| Năng lực | Người dùng có thể làm gì |
|---|---|
| Định danh thuế người bán | Chủ sân đăng ký MST, tên, và địa chỉ cơ sở dùng làm người bán trên hoá đơn |
| Receipt nội bộ | Thu ngân in receipt nhiệt cho đơn bán hàng & đơn đặt sân ngay sau thanh toán |
| In lại / tra cứu receipt | Tìm receipt theo số / ngày / tên người chơi và in lại khi được yêu cầu |
| Quy tắc nhóm thuế | Chủ sân định nghĩa mẫu nhóm thuế tự động áp đúng thuế suất (8% VAT) lên sân, FNB, dụng cụ |
| Hồ sơ hoá đơn & nhà cung cấp | Chủ sân kết nối một nhà cung cấp T-VAN với thông tin xác thực mã hoá và chính sách số/phát hành |
| Định tuyến kênh | Chủ sân ánh xạ từng chi nhánh / loại đơn tới cấu hình nhà cung cấp phát hành hoá đơn của nó |
| Tự phát hành khi thanh toán | Một thanh toán hoàn tất tự động đưa vào hàng đợi và phát hành hoá đơn |
| Phát hành thủ công / theo lịch | Thu ngân phát hành theo yêu cầu, hoặc hệ thống phát hành theo lô đã lên lịch |
| Phát hành VAT điện tử | Nhập MST / tên công ty / địa chỉ người mua, ký số qua T-VAN, gửi email hoá đơn |
| Nộp lên cơ quan thuế | Hoá đơn đã phát hành được gửi tới cơ quan thuế (CQT) qua T-VAN, có theo dõi trạng thái |
| Điều chỉnh / thay thế / huỷ | Chủ sân sửa, thay thế, hoặc huỷ một hoá đơn đã phát hành kèm lý do (huỷ VAT trong 7 ngày) |
| Người chơi tự yêu cầu hoá đơn | Người chơi quét QR trên receipt và gửi thông tin của mình trước thời hạn để nhận hoá đơn |
| Dấu vết kiểm toán | Mọi sự kiện hoá đơn (tạo, phát hành, thử lại, nộp, chấp nhận/từ chối) đều được ghi nhận, lưu trữ 5 năm |
4. Phụ thuộc Module
| Phụ thuộc vào | Vì sao |
|---|---|
| Bảng giá | Quy tắc nhóm thuế áp lên giá sân và sản phẩm; thay đổi bảng giá điều hoà lại thuế đã áp |
| Đặt sân | Đơn đặt sân cung cấp dòng hàng (sân · khung giờ) để điền vào hoá đơn |
| Bán Hàng POS | Đơn bán hàng cung cấp các dòng FNB/dụng cụ và tổng để điền vào hoá đơn |
| Thanh toán | Một thanh toán thành công là thứ kích hoạt phát hành hoá đơn tự động |
5. Backend Packages
Module này được vận hành bởi hai dịch vụ và hai adapter tích hợp. Chi tiết triển khai nằm trong tài liệu nhà phát triển - phần này chỉ ánh xạ module sang chúng.
| Package | Vai trò | Tài liệu nhà phát triển |
|---|---|---|
@nx/taxation | Mẫu quy tắc nhóm thuế, cấp thuế lên sân/FNB/dụng cụ, dữ liệu tham chiếu VN | taxation |
@nx/invoice | Phát hành hoá đơn điện tử VAT, nhà cung cấp/hồ sơ, yêu cầu, điều chỉnh/hủy, dấu vết kiểm toán | invoice |
@nx/iiapi | Adapter cổng nhà cung cấp T-VAN (VNPT / Viettel / MISA) cho vòng đời hoá đơn và webhook | iiapi |
@nx/t-van | Adapter mạng cơ quan thuế (CQT) cho nộp, ký số, và tra cứu hoá đơn | t-van |
Ánh xạ Kỹ thuật (Tính năng ⇄ 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 triển khai kỹ thuật của nó. Có chiều ngược lại: tài liệu package liên kết trở lại đây.
| Tính năng | Package | Trạng thái |
|---|---|---|
TAX Định danh thuế | @nx/taxation | Built |
GRP Nhóm thuế | @nx/taxation | Built |
CFG Cấu hình hóa đơn | @nx/invoice | Built |
INV Vòng đời hóa đơn | @nx/invoice | Built |
REQ Yêu cầu hóa đơn & Khách tự yêu cầu | @nx/invoice | Built |
MOD Chế độ phát hành | @nx/invoice | Built |
DCL Kê khai thuế (HKD 1-3 tỷ) | @nx/ledger · @nx/taxation | Planned |
ISS Trải nghiệm xuất hóa đơn | @nx/invoice | Planned |
6. Luồng người dùng chính
Phát hành hoá đơn khi thanh toán
Người chơi tự yêu cầu hoá đơn
7. Vai trò & Phân quyền
| Vai trò | Được phép | Không được phép |
|---|---|---|
| Chủ sân (Owner) | Đăng ký định danh thuế, định nghĩa nhóm thuế, kết nối nhà cung cấp T-VAN, cấu hình phát hành, điều chỉnh/huỷ hoá đơn | - |
| Quản lý ca (Manager) | Xem hoá đơn và dấu vết kiểm toán, phát hành và điều chỉnh hoá đơn VAT | Đổi thông tin xác thực nhà cung cấp (do Chủ sân kiểm soát) |
| Thu ngân (Cashier) | In/gửi receipt, phát hành hoá đơn sau thanh toán, thu thông tin người mua | Quản lý nhóm thuế hoặc thông tin xác thực nhà cung cấp |
| Người chơi | Tự yêu cầu hoá đơn của mình qua QR | Truy cập dữ liệu của cơ sở hoặc người mua khác |
8. Trạng thái & Lộ trình
| Giai đoạn | Năng lực |
|---|---|
| P1 | Định danh thuế người bán, receipt nội bộ in tại quầy cho đơn sân & đơn bán hàng, tra cứu/in lại receipt, quy tắc nhóm thuế + cấp thuế, phiếu hoàn tiền (credit note), export danh sách hoá đơn |
| P2 | Hồ sơ/nhà cung cấp T-VAN, phát hành hoá đơn VAT điện tử (Nghị định 123/2020) + ký số, nộp lên cơ quan thuế, điều chỉnh/thay thế/huỷ, người chơi tự yêu cầu hoá đơn qua QR, dấu vết kiểm toán |
| P3 | Thêm nhà cung cấp ngoài bộ iiapi/T-VAN hiện tại; hỗ trợ kê khai / nộp thuế; đẩy dữ liệu sang phần mềm kế toán |
Ghi chú trạng thái. Receipt nội bộ đã chạy ở P1. Phát hành VAT điện tử chạy trên bộ nhà cung cấp T-VAN (VNPT / Viettel / MISA) qua iiapi. Quy tắc nhóm thuế và cấp thuế cho sân/FNB/dụng cụ do taxation xử lý. Một số chi tiết định danh vận hành cho dịch vụ hoá đơn vẫn đang được điều hoà trước khi lên production (xem trang nhà phát triển vận hành invoice).
9. Trang liên quan
- URD
- PRDs
- Bảng giá · Đặt sân · Bán Hàng POS · Thanh toán
- Nhà phát triển: taxation · invoice · iiapi · t-van