PRD: Định danh thuế & nhóm thuế
| Module | Thuế & Hóa đơn | PRD ID | PRD-TAX-001 |
| Trạng thái | Sẵn sàng dev | FEAT | TAX |
| Epic | — | Plane | BANA-1522 |
| Ngày | 2026-05-31 | Phiên bản | v1.0 |
| Gói | @nx/taxation | URD | TAX |
| Surface | Client · Chủ/QL | ||
| Phụ trách | Phát Nguyễn | ||
TL;DR
Nền tảng thuế mà mọi hóa đơn điện tử đều đứng trên: merchant đăng ký một MST hợp lệ, các nhóm thuế dùng lại được phân loại thuế nào áp cho sản phẩm nào, và một invoice profile nối nó với nhà cung cấp. Thuế tự áp lên sản phẩm khớp và luôn đồng bộ khi danh mục đổi - nên merchant đã đúng thuế trước cả hóa đơn đầu tiên.
1. Bối cảnh & Vấn đề
Bán hàng tại Việt Nam cần ba thứ trước khi xuất được hóa đơn: một MST hợp lệ in trên mọi hóa đơn, đúng quy tắc thuế cho từng sản phẩm, và một invoice profile gắn nhà cung cấp để phát hành. Chưa thứ nào trong số này thành một lớp mạch lạc - dữ liệu thuế nằm rải rác ở các trường tùy biến, sản phẩm chưa được phân loại thuế, chưa có invoice profile để nối nhà cung cấp. Vòng đời phát hành vì thế không có chỗ đứng: không người bán để in, không thuế theo sản phẩm để tính, không profile để phát hành.
Bước tăng này dựng nền tảng đó. Taxation lo định danh thuế người bán, dữ liệu hành chính Việt Nam, và các nhóm thuế dùng lại được tự áp thuế lên sản phẩm khớp; Invoice lo invoice profile và cấu hình nhà cung cấp, giữ đồng bộ với định danh thuế người bán qua change-data-capture (CDC).
2. Mục tiêu & Loại trừ
Mục tiêu
- Đăng ký định danh thuế người bán (MST, tên doanh nghiệp, địa chỉ) và dùng nó làm người bán in trên hóa đơn phát hành.
- Cung cấp dữ liệu tham chiếu hành chính Việt Nam (tỉnh, phường/xã, đơn vị) để nhập địa chỉ, cùng việc giải mã và kiểm tra định dạng mã số thuế.
- Định nghĩa các mẫu quy tắc nhóm thuế dùng lại được, phân loại thuế nào áp cho sản phẩm nào, và tự áp thuế đó lên các sản phẩm khớp.
- Tự đồng bộ thuế đã áp khi một sản phẩm được tạo, cập nhật, hoặc gỡ bỏ (seam CDC theo sự kiện giữa taxation và commerce).
- Tạo merchant invoice profile gắn với định danh thuế người bán, kèm cấu hình nhà cung cấp, được giữ đồng bộ qua merchant CDC.
Loại trừ
- Sổ đăng ký mã số thuế có thẩm quyền (do cơ quan thuế sở hữu).
- Tính thuế suất tại thời điểm bán (do pricing sở hữu).
- Toàn bộ vòng đời phát hành hóa đơn, thử lại, nộp cơ quan thuế (CQT), và dấu vết kiểm toán - do Vòng đời hóa đơn (
INV) sở hữu. - Yêu cầu hóa đơn / người mua tự nhận và các chế độ phát hành (tính năng
REQ/MOD). - Các yêu cầu
CFGvề sau (serial / policy theo loại, định tuyến kênh, chính sách thử lại, chia sẻ profile, wizard onboarding).
3. Thước đo thành công
| Thước đo | Mục tiêu / tín hiệu |
|---|---|
| Độ phủ định danh thuế | 100% merchant phát hành hóa đơn đều có mã số thuế + tên doanh nghiệp + địa chỉ đã đăng ký |
| Tính hợp lệ địa chỉ | Lựa chọn tỉnh / phường-xã / đơn vị giải mã được theo dữ liệu tham chiếu VN; mã số thuế qua kiểm tra định dạng trước khi lưu |
| Độ đúng khi áp thuế | Các sản phẩm khớp nhóm thuế mang đúng thuế đã áp; không sản phẩm khớp nào bị bỏ sót chưa áp thuế |
| Độ trễ đồng bộ | Thuế đã áp được đồng bộ trong cửa sổ của seam CDC sau khi sản phẩm tạo / cập nhật / gỡ bỏ |
| Mức sẵn sàng của profile | Merchant có định danh thuế cũng có invoice profile đã đồng bộ trước khi thử phát hành |
4. Persona & Tình huống
| Persona | Mục tiêu |
|---|---|
| Owner | Đăng ký định danh thuế của merchant, định nghĩa nhóm thuế, kết nối invoice profile/nhà cung cấp |
| Manager | Duy trì các nhóm thuế và xem sản phẩm nào mang thuế nào |
| Nhân viên sản phẩm | Tạo / sửa sản phẩm và tin rằng thuế đúng được áp tự động |
Tình huống chính: đăng ký định danh thuế người bán (với tra cứu địa chỉ VN) → định nghĩa một nhóm thuế → nó áp thuế lên các sản phẩm khớp → thay đổi sản phẩm tự đồng bộ thuế đã áp → invoice profile, gắn với định danh thuế, kết nối tới nhà cung cấp và giữ đồng bộ.
5. User Story
- Là một owner, tôi muốn đăng ký định danh thuế của merchant (MST, tên, địa chỉ), để nó in làm người bán trên mọi hóa đơn phát hành.
- Là một owner, tôi muốn tra cứu tỉnh / phường-xã / đơn vị VN khi nhập địa chỉ, để định danh thuế mang dữ liệu hành chính hợp lệ.
- Là một owner, tôi muốn mã số thuế được kiểm tra đúng định dạng Việt Nam trước khi được chấp nhận, để một mã số thuế sai định dạng không bao giờ tới được hóa đơn.
- Là một manager, tôi muốn định nghĩa một mẫu nhóm thuế dùng lại được, để thuế đúng được phân loại và áp cho đúng sản phẩm.
- Là một nhân viên sản phẩm, tôi muốn thuế được áp tự động khi tôi tạo hoặc cập nhật sản phẩm, để tôi không phải đặt thuế thủ công trên từng mặt hàng.
- Là một manager, tôi muốn thuế đã áp được đồng bộ khi một sản phẩm thay đổi hoặc bị gỡ bỏ, để thuế không bao giờ lệch khỏi danh mục.
- Là một owner, tôi muốn một merchant invoice profile gắn với định danh thuế và một nhà cung cấp, để merchant sẵn sàng phát hành hóa đơn.
6. Yêu cầu chức năng
| # | Yêu cầu | URD ref |
|---|---|---|
| FR-1 | Đăng ký định danh thuế người bán (MST, tên doanh nghiệp, địa chỉ) dùng làm người bán trên hóa đơn phát hành | URD-TAX-001 |
| FR-2 | Tra cứu tỉnh, phường/xã, và đơn vị hành chính Việt Nam khi nhập địa chỉ | URD-TAX-002 |
| FR-3 | Kiểm tra mã số thuế đúng định dạng Việt Nam trước khi chấp nhận; giải mã địa chỉ VN và đồng bộ thông tin thuế | URD-TAX-003 |
| FR-4 | Định nghĩa một mẫu quy tắc nhóm thuế phân loại thuế nào áp cho sản phẩm nào | URD-GRP-001 |
| FR-5 | Áp một nhóm thuế sẽ tự áp thuế đúng lên các sản phẩm khớp của nó | URD-GRP-002 |
| FR-6 | Thay đổi hoặc gỡ bỏ một sản phẩm tự đồng bộ thuế đã áp của nó (seam CDC, taxation ⇄ commerce) | URD-GRP-003 |
| FR-7 | Một nhóm thuế chỉ dùng được khi tương thích với phương pháp thuế của merchant | URD-GRP-004 |
| FR-8 | Tạo một merchant invoice profile gắn với định danh thuế người bán | URD-CFG-001 |
| FR-9 | Kết nối một nhà cung cấp (VNPAY) với thông tin xác thực lưu mã hóa; giữ profile đồng bộ với thông tin thuế qua merchant CDC | URD-CFG-002 |
Toàn văn requirement và tiêu chí chấp nhận nằm trong URD Thuế & Hóa đơn. PRD này tham chiếu chúng thay vì lặp lại.
7. Yêu cầu phi chức năng
| Lĩnh vực | Yêu cầu |
|---|---|
| Toàn vẹn dữ liệu | Định danh thuế của merchant là nguồn có thẩm quyền; invoice profile được giữ nhất quán với nó qua merchant CDC - không lệch giữa người bán in ra và mã số thuế đã đăng ký |
| Tenancy & authz | Mọi thao tác giới hạn trong merchant của chính người dùng; thiết lập định danh thuế và nhà cung cấp do owner kiểm soát |
| Nhất quán | Áp thuế và đồng bộ thuế dựa trên CDC và idempotent - phát lại sẽ hội tụ về cùng một thuế đã áp |
| Bảo mật | Thông tin xác thực nhà cung cấp trên invoice profile được lưu mã hóa |
| Hiệu năng | Dữ liệu tham chiếu hành chính VN giải mã đủ nhanh cho việc nhập địa chỉ trực tiếp |
| i18n | Nhãn hiển thị cho người dùng song ngữ (Tiếng Anh / Tiếng Việt); dữ liệu hành chính theo cách đặt tên VN |
8. UX & Luồng
Các màn hình chính (ứng dụng quản lý): thiết lập định danh thuế với bộ chọn địa chỉ VN, trình soạn nhóm thuế, màn xem thuế theo sản phẩm, và biểu mẫu kết nối invoice profile / nhà cung cấp.
9. Dữ liệu & Miền nghiệp vụ
| Entity | Vai trò |
|---|---|
| Định danh thuế người bán | Định danh thuế người bán (MST, tên doanh nghiệp, địa chỉ) - quan hệ từ merchant, là nguồn có thẩm quyền |
| Nhóm thuế | Một mẫu quy tắc dùng lại được phân loại thuế nào áp cho sản phẩm nào |
| Dòng thuế đã áp | Mục thuế đã áp liên kết một nhóm thuế với các sản phẩm khớp |
| Phương pháp thuế của merchant | Phương pháp thuế của merchant mà một nhóm thuế phải tương thích |
| Nhóm thuế của sản phẩm | Nhóm thuế đã áp lên một sản phẩm |
| Merchant invoice profile | Thiết lập hóa đơn của merchant gắn định danh thuế với một nhà cung cấp |
| Cấu hình nhà cung cấp | Nhà cung cấp đã kết nối (VNPAY) với thông tin xác thực mã hóa |
Chỉ ở mức khái niệm - schema và bất biến đầy đủ nằm trong domain model taxation và domain model invoice.
10. Phụ thuộc & Giả định
Phụ thuộc
- Commerce / Merchant - bản ghi merchant mang định danh thuế do owner nhập.
- Products (Sản phẩm) - nhóm thuế áp thuế lên sản phẩm; thay đổi sản phẩm kích hoạt đồng bộ.
- Seam CDC - seam theo sự kiện lan truyền thay đổi sản phẩm và merchant vào taxation và invoice.
- Năng lực hóa đơn - cho merchant invoice profile và cấu hình nhà cung cấp.
Giả định
- Merchant đã nhập một định danh thuế trước khi thử phát hành.
- Một phương pháp thuế đã được đặt trên merchant để có thể đánh giá tính tương thích của nhóm thuế.
- Có sẵn một nhà cung cấp được hỗ trợ (VNPAY) để kết nối.
11. Rủi ro & Câu hỏi mở
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Định danh thuế và invoice profile có thể lệch nhau | Profile được giữ đồng bộ với định danh thuế của merchant qua merchant CDC |
| Thuế đã áp lệch khi danh mục thay đổi | Seam CDC đồng bộ thuế trên mọi lần tạo / cập nhật / gỡ bỏ sản phẩm; idempotent nên phát lại hội tụ |
| Nhóm thuế không tương thích với phương pháp thuế của merchant | Tính tương thích được kiểm soát trước khi một nhóm dùng được |
| Mã số thuế sai định dạng tới được hóa đơn | Mã số thuế được kiểm tra định dạng trước khi được chấp nhận |
| Lộ thông tin xác thực nhà cung cấp | Thông tin xác thực lưu mã hóa trên profile |
12. Kế hoạch phát hành & Tiêu chí
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P1 (nền tảng) - xem danh mục tính năng URD |
| Rollout | Tất cả merchant; không feature flag |
| Migration | Tax group / item được migrate vào schema thuế; taxation chạy như một dependent service |
| Tiêu chí ra mắt | Định danh thuế đăng ký được với địa chỉ VN + kiểm tra; nhóm thuế áp thuế lên sản phẩm khớp; thay đổi sản phẩm đồng bộ thuế đã áp; invoice profile được tạo và đồng bộ với định danh thuế |
| Giám sát | Tỷ lệ thành công áp / đồng bộ thuế, độ trễ CDC, độ phủ định danh thuế, tính nhất quán đồng bộ profile |
13. FAQ
Định danh thuế của merchant đến từ đâu? Owner nhập nó trên merchant; đó là người bán có thẩm quyền in trên hóa đơn phát hành và được phản chiếu vào invoice profile qua merchant CDC.
Tôi có phải đặt thuế trên từng sản phẩm thủ công không? Không - một nhóm thuế tự áp thuế đúng lên các sản phẩm khớp của nó, và tự đồng bộ khi một sản phẩm thay đổi hoặc bị gỡ bỏ.
Điều gì xảy ra khi tôi sửa hoặc xóa một sản phẩm? Seam CDC tự đồng bộ thuế đã áp; bạn không cần áp lại thuế thủ công.
Mọi nhóm thuế có áp được cho mọi merchant không? Không - một nhóm thuế chỉ dùng được khi tương thích với phương pháp thuế của merchant.
Bước này có phát hành hóa đơn không? Không - đây là nền tảng định danh thuế, nhóm thuế, và invoice profile. Vòng đời phát hành (hàng đợi, thử lại, nộp CQT, dấu vết kiểm toán) do Vòng đời hóa đơn sở hữu.
Tham chiếu
- URD: Thuế & Hóa đơn - Tax Identity · Tax Groups · Invoice Configuration
- PRD liên quan: Vòng đời & phát hành hóa đơn · Tích hợp nhà cung cấp hóa đơn điện tử
- Module: Thuế & Hóa đơn - URD
- Developer: @nx/taxation · domain model · @nx/invoice