PRD: Cấu hình Nhóm thuế (Back Office)
| Module | Thuế & Hóa đơn | PRD ID | PRD-GRP-001 |
| Trạng thái | Sẵn sàng dev | FEAT | GRP |
| Epic | BANA-1318 | Plane | BANA-1740 |
| Ngày | 2026-06-30 | Phiên bản | v1.1 |
| Gói | @nx/taxation | URD | GRP |
| Surface | BO · Vận hành | ||
| Phụ trách | Phát Nguyễn | ||
TL;DR
Cho Đội vận hành (NEXPANDO & VNPAY) soạn các nhóm thuế tái sử dụng từ Back Office: mỗi nhóm khai một phương pháp thuế (Khấu trừ / Trực tiếp) và gom nhiều dòng thuế suất (loại thuế, thuế suất %, đã gồm trong giá hay chưa, chiều Bán/Mua, bên chịu thuế, thứ tự ưu tiên) - engine thuế cấp các dòng này lên sản phẩm được gán nhóm và đối soát lại mỗi khi sản phẩm thay đổi.
1. Bối cảnh & Vấn đề
Mọi sản phẩm phải mang đúng bộ thuế đã khai (VAT, tiêu thụ đặc biệt, môi trường…), nhưng đặt thuế từng sản phẩm thì dễ sai và khó bảo trì. Một nhóm thuế là một template tái sử dụng: khai một lần các dòng thuế suất của nhóm, rồi gán nhóm cho sản phẩm lúc thiết lập sản phẩm - sản phẩm nhận trọn bộ dòng thuế của nhóm, không phải nhập tay từng loại.
Tăng tiến này là màn cấu hình nhóm thuế phía Back Office: Đội vận hành soạn nhóm qua ba khối - danh sách nhóm, form nhóm, và khối dòng thuế suất trong màn sửa. Việc cấp thuế lên sản phẩm và đối soát khi sản phẩm đổi là xử lý nền của engine thuế, không phải thao tác trên màn.
2. Mục tiêu / Ngoài phạm vi
Mục tiêu
- Soạn nhóm thuế: mã định danh, tên song ngữ, phương pháp thuế (Khấu trừ / Trực tiếp), trạng thái.
- Soạn dòng thuế suất trong từng nhóm: loại thuế (5 phân loại), thuế suất %, đã gồm trong giá, thứ tự ưu tiên, chiều áp dụng, bên chịu thuế.
- Engine thuế cấp các dòng thuế của nhóm lên sản phẩm được gán và đối soát khi sản phẩm thay đổi (xử lý nền).
- Ràng nhóm thuế theo phương pháp thuế của merchant - nhóm chỉ gán được nơi cùng phương pháp (chưa dựng, xem FR-6).
Ngoài phạm vi
- Định danh thuế và hồ sơ e-invoice của merchant (Tax identity).
- Xuất hóa đơn hay khai thuế (Invoice lifecycle, Tax declaration).
- Ghi đè thuế thủ công từng sản phẩm ngoài cơ chế nhóm.
3. Success Metrics
| Chỉ số | Mục tiêu / tín hiệu |
|---|---|
| Thuế theo template | Sản phẩm được gán nhóm nhận đủ các dòng thuế của nhóm, không phải nhập tay từng loại |
| Nhất quán | Đổi hoặc xóa sản phẩm thì thuế đã cấp được engine tính lại; không còn thuế của cấu hình cũ |
| Tương thích | 🚧 Nhóm thuế chỉ gán được cho merchant cùng phương pháp thuế (chưa dựng - FR-6) |
4. Personas & Tình huống
| Persona | Mục tiêu ở tính năng này |
|---|---|
| Đội vận hành (NEXPANDO & VNPAY) | Soạn nhóm thuế và dòng thuế suất để sản phẩm được tính thuế thống nhất theo template |
Tình huống chính: Đội vận hành tạo nhóm "VAT bán lẻ" theo phương pháp Khấu trừ; lưu xong, mở lại nhóm ở màn sửa để thêm dòng thuế "VAT 10%, đã gồm trong giá, chiều Bán, khách hàng chịu"; sản phẩm được gán nhóm nhận dòng thuế đó tự động; khi sản phẩm đổi hoặc bị xóa, engine đối soát lại thuế đã cấp.
5. User Stories
- Là Đội vận hành, tôi muốn soạn một nhóm thuế kèm các dòng thuế suất, để sản phẩm được gán nhóm nhận đủ thuế mà không nhập tay.
- Là Đội vận hành, tôi muốn khai mỗi dòng thuế theo % kèm cờ đã gồm trong giá, chiều Bán/Mua và bên chịu thuế, để mô tả đúng nghĩa vụ thuế của từng loại.
- Là Đội vận hành, tôi muốn đặt thứ tự ưu tiên cho từng dòng, để khi một sản phẩm khớp nhiều dòng thì dòng có số ưu tiên nhỏ nhất áp trước.
- Là Đội vận hành, tôi muốn nhóm thuế chỉ gán được cho merchant cùng phương pháp thuế, để không cấu hình sai thuế (chưa dựng).
6. Functional Requirements
Thao tác trên màn
| # | Yêu cầu | Trạng thái | URD ref |
|---|---|---|---|
| FR-1 | Danh sách nhóm thuế - 4 cột, lọc được cả 4, kèm hành động sửa / xóa | ✅ đã dựng | URD-GRP-001 |
| FR-2 | Tạo / sửa nhóm thuế - form 5 trường kèm validation và giá trị mặc định | ✅ đã dựng | URD-GRP-001 |
| FR-3 | Dòng thuế suất của nhóm - mỗi nhóm gồm nhiều dòng thuế, thêm / sửa / xóa qua hộp thoại ở màn sửa | ✅ đã dựng | URD-GRP-001 |
Hành vi hệ thống (xử lý nền - không phải thao tác trên màn)
| # | Yêu cầu | Trạng thái | URD ref |
|---|---|---|---|
| FR-4 | Cấp thuế lên sản phẩm - sản phẩm được gán nhóm nhận đủ các dòng thuế của nhóm | ✅ đã dựng (engine) | URD-GRP-002 |
| FR-5 | Đối soát khi sản phẩm đổi - đổi hoặc xóa sản phẩm thì thuế đã cấp được tính lại | ✅ đã dựng (engine) | URD-GRP-003 |
| FR-6 | Tương thích phương pháp thuế - nhóm thuế chỉ gán được cho merchant cùng phương pháp thuế | 🚧 chưa dựng | URD-GRP-004 |
FR-1 - Danh sách nhóm thuế ✅
- Cột: Tên (song ngữ) · Mô tả (song ngữ) · Phương pháp thuế · Trạng thái.
- Lọc: cả 4 cột - Tên và Mô tả tìm theo chuỗi gần đúng; Phương pháp thuế và Trạng thái chọn theo giá trị.
- Hành động từng dòng: Sửa (mở màn sửa) · Xóa (hộp xác nhận nêu mã định danh của nhóm).
FR-2 - Tạo / sửa nhóm thuế ✅
| Trường | Bắt buộc | Quy tắc |
|---|---|---|
| Mã định danh | bắt buộc | chuỗi tự do (hiện chưa ràng định dạng / độ dài) |
| Tên | bắt buộc | song ngữ EN/VI, mỗi ngôn ngữ ≤ 200 ký tự |
| Mô tả | tùy chọn | song ngữ EN/VI, mỗi ngôn ngữ ≤ 400 ký tự |
| Phương pháp thuế | bắt buộc | 2 giá trị: Khấu trừ (mặc định) · Trực tiếp |
| Trạng thái | bắt buộc | 3 giá trị: Đang hoạt động (mặc định) · Ngừng hoạt động · Lưu trữ |
- Rời màn khi form đang sửa dở → cảnh báo mất thay đổi.
- Lưu xong (cả tạo lẫn sửa) quay về danh sách.
FR-3 - Dòng thuế suất của nhóm ✅
Một nhóm thuế gồm nhiều dòng thuế suất; các dòng được quản lý trong màn sửa nhóm - tạo nhóm xong phải mở lại nhóm để thêm dòng.
| Trường | Bắt buộc | Quy tắc |
|---|---|---|
| Loại thuế | bắt buộc | chọn 1 trong 5 phân loại: VAT · Tiêu thụ đặc biệt · Môi trường · Xa xỉ · TNCN - chỉ phân loại đang hoạt động mới được chào |
| Thuế suất | bắt buộc | nhập theo %; lưu chính xác 4 chữ số thập phân; hiển thị 2 chữ số (vd 10.00%) |
| Đã gồm trong giá | bật / tắt | mặc định chưa gồm |
| Thứ tự ưu tiên | bắt buộc | số nguyên ≥ 1 (mặc định 1); sản phẩm khớp nhiều dòng thì dòng có số ưu tiên nhỏ nhất áp trước |
| Chiều áp dụng | bắt buộc | Bán (mặc định) · Mua |
| Bên chịu thuế | bắt buộc | Khách hàng (mặc định) · Merchant |
- Thêm / sửa dòng qua hộp thoại; xóa dòng có hộp xác nhận nêu thuế suất của dòng.
- Bảng dòng thuế hiển thị: Loại thuế (nhãn màu theo phân loại) · Thuế suất % · Đã gồm trong giá (Có/Không) · Ưu tiên · Chiều áp dụng · Bên chịu thuế.
- Phía trên bảng có dòng tóm tắt các thuế suất của nhóm, vd
VAT 10.00% đã gồm · Môi trường 2.00% chưa gồm.
FR-4 - Cấp thuế lên sản phẩm (nền) ✅
Khi một sản phẩm được gán nhóm thuế (lúc tạo hoặc cập nhật sản phẩm), engine thuế cấp toàn bộ dòng thuế của nhóm lên sản phẩm. Không có thao tác nào trên màn này - màn chỉ soạn template.
FR-5 - Đối soát khi sản phẩm đổi (nền) ✅
Khi sản phẩm bị đổi hoặc xóa, engine tính lại thuế đã cấp theo nhóm hiện hành - không để sản phẩm giữ thuế của cấu hình cũ.
FR-6 - Tương thích phương pháp thuế 🚧
Rule cần dựng: một nhóm thuế chỉ được gán cho merchant có cùng phương pháp thuế - nhóm Khấu trừ chỉ cho merchant khai theo khấu trừ, nhóm Trực tiếp chỉ cho merchant khai trực tiếp. Hiện màn chưa có kiểm tra nào: mọi nhóm gán được cho mọi merchant, đúng/sai phụ thuộc thao tác của Đội vận hành. Cần chặn ở nơi gán nhóm và cảnh báo khi soạn nhóm.
Tiêu chí nghiệm thu
- Tạo nhóm thiếu mã định danh, tên, phương pháp thuế hoặc trạng thái → form báo lỗi, không lưu; tên dài hơn 200 ký tự → báo lỗi.
- Nhóm mới mặc định phương pháp Khấu trừ, trạng thái Đang hoạt động.
- Danh sách lọc được theo cả 4 cột; xóa nhóm luôn qua hộp xác nhận nêu mã định danh.
- Dòng thuế chỉ thêm được sau khi nhóm đã lưu (ở màn sửa nhóm).
- Nhập thuế suất
10→ bảng hiển thị10.00%; giá trị lưu giữ đúng 4 chữ số thập phân. - Thứ tự ưu tiên
0hoặc số âm → báo lỗi (tối thiểu 1). - Dropdown loại thuế chỉ chào các phân loại đang hoạt động, đủ 5 nhóm VAT / Tiêu thụ đặc biệt / Môi trường / Xa xỉ / TNCN.
- Xóa dòng thuế luôn qua hộp xác nhận nêu thuế suất của dòng; dòng tóm tắt cập nhật theo.
- 🚧 (khi dựng FR-6) Gán nhóm Khấu trừ cho merchant khai trực tiếp → bị chặn kèm thông báo.
7. Non-Functional Requirements
| Khía cạnh | Yêu cầu |
|---|---|
| Nhất quán | Thuế đã cấp được engine đối soát khi sản phẩm đổi; không còn thuế của cấu hình cũ |
| Tương thích | 🚧 Nhóm thuế chỉ gán được cho merchant cùng phương pháp thuế (FR-6, chưa dựng) |
| Phân quyền | Chỉ tài khoản Back Office có quyền cấu hình thuế mới thao tác được màn này |
| i18n | Tên và mô tả nhóm thuế nhập song ngữ EN/VI; nhãn phương pháp / trạng thái / loại thuế hiển thị song ngữ |
8. UX & Flows
Đội vận hành soạn một nhóm thuế như thế nào:
Cấu trúc màn và phần chạy nền:
Màn nằm trong mục "Cấu hình hệ thống" của Back Office.
9. Data & Domain
| Khái niệm | Vai trò trong màn này |
|---|---|
| Nhóm thuế | Template tái sử dụng: một phương pháp thuế + nhiều dòng thuế suất |
| Dòng thuế suất | Một dòng trong nhóm: loại thuế, %, đã gồm trong giá, ưu tiên, chiều áp dụng, bên chịu thuế |
| Loại thuế | Phân loại thuế một dòng thuộc về: VAT / Tiêu thụ đặc biệt / Môi trường / Xa xỉ / TNCN |
| Phương pháp thuế | Khấu trừ hoặc Trực tiếp - khai trên nhóm; phải khớp phương pháp của merchant (FR-6 🚧) |
| Thuế đã áp | Thuế engine cấp lên sản phẩm theo các dòng của nhóm được gán |
Chỉ ở mức khái niệm - việc cấp và đối soát chạy trong engine thuế; mô hình dữ liệu ở tài liệu developer.
10. Dependencies & Assumptions
Phụ thuộc
- Định danh / phương pháp thuế (Tax identity) - nguồn phương pháp thuế của merchant mà FR-6 cần đối chiếu.
- Sản phẩm - nơi nhóm thuế được gán và nhận thuế (Products).
Giả định
- Đội vận hành đã đăng nhập với quyền cấu hình thuế.
- Các phân loại thuế (VAT, Tiêu thụ đặc biệt…) đã được khai và đang hoạt động để dropdown loại thuế có dữ liệu.
11. Risks & Open Questions
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Nhiều dòng thuế cùng khớp một sản phẩm | Mỗi dòng có thứ tự ưu tiên; dòng số nhỏ nhất áp trước |
| Chưa có kiểm tra tương thích phương pháp thuế | 🚧 FR-6 - hiện dựa vào thao tác đúng của Đội vận hành |
| Nhập nhầm thuế suất (lẫn % với phần thập phân) | Nhập theo %, bảng và dòng tóm tắt hiển thị lại xx.xx% ngay để soát mắt |
12. Release Plan & Launch Criteria
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P1 - đã có trong Back Office |
| Rollout | User cấu hình thuế; không feature flag |
| Migration | Không - nó cấu hình engine thuế hiện có |
| Tiêu chí ra mắt | Soạn được nhóm đủ 5 trường + dòng thuế đủ 6 trường; danh sách lọc theo 4 cột; sản phẩm được gán nhóm nhận đủ dòng thuế; đổi sản phẩm được engine đối soát |
| Theo dõi | Sửa nhóm thuế / dòng thuế; kết quả đối soát của engine |
13. FAQ
Nhóm thuế là gì? Một template tái sử dụng: một phương pháp thuế + nhiều dòng thuế suất (loại thuế, %, đã gồm trong giá…), gán cho sản phẩm để thuế áp tự động.
Vì sao tạo nhóm xong chưa thêm được dòng thuế ngay? Dòng thuế quản lý trong màn sửa - lưu nhóm xong quay về danh sách, mở lại nhóm để thêm dòng.
Thay đổi một sản phẩm thì xảy ra gì? Engine đối soát lại thuế đã cấp theo nhóm hiện hành, nên không còn thuế của cấu hình cũ.
Vì sao không dùng được một nhóm thuế trên một merchant? Theo thiết kế, nhóm chỉ gán được cho merchant cùng phương pháp thuế - kiểm tra này chưa dựng (FR-6), hiện chưa bị chặn.
References
- URD: Tax -
GRP(Tax Groups) ·TAX(Tax Identity) - Module: Tax & Invoice - URD · Lộ trình: Phase 2 - Theo tháng
- Developer: @nx/taxation