PRD: Định danh thuế & nhóm thuế
| Module | Thuế & Hóa đơn (CORE-10) | PRD ID | PRD-TAX-001 |
| Status | Shipped | Owner | Nhóm Thuế & Hóa đơn |
| Date | 2026-05-31 | Version | v1.0 |
| Packages | @nx/taxation · @nx/invoice · @nx/core | URD | TAX · GRP · CFG |
TL;DR
Cho phép merchant đăng ký định danh thuế Việt Nam hợp lệ (MST), phân loại thuế nào áp cho sản phẩm nào thông qua các nhóm thuế dùng lại được, và kết nối một invoice profile với một nhà cung cấp - nền tảng mà mọi hóa đơn điện tử phát hành đều dựa trên. Thuế tự chảy lên các sản phẩm khớp và luôn được đồng bộ khi danh mục thay đổi, nên merchant đã đúng về thuế trước cả khi phát hành hóa đơn đầu tiên.
1. Context & Problem
Bán hàng tại Việt Nam đòi hỏi merchant in một định danh thuế hợp lệ (MST) trên mọi hóa đơn phát hành, áp đúng quy tắc thuế cho từng sản phẩm, và có một thiết lập hóa đơn dựa trên nhà cung cấp trước khi bất kỳ hóa đơn nào được phát hành. Hiện tại không có thứ nào trong số này tồn tại như một lớp mạch lạc: dữ liệu thuế nằm rải rác dưới dạng trường tùy biến, sản phẩm không có phân loại thuế, và không có merchant invoice profile để kết nối một nhà cung cấp. Thiếu nền tảng này thì vòng đời phát hành không có gì để dựa vào - không có người bán để in, không có thuế theo sản phẩm để tính, và không có profile để phát hành dựa trên.
Bước tăng này xây nền tảng đó. Service taxation sở hữu định danh thuế người bán, dữ liệu tham chiếu hành chính Việt Nam, và các nhóm thuế dùng lại được tự áp thuế lên các sản phẩm khớp; service invoice sở hữu merchant invoice profile và cấu hình nhà cung cấp, được giữ đồng bộ với định danh thuế của người bán qua merchant CDC.
2. Goals & Non-Goals
Goals
- Đă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 dựa trên Kafka 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.
Non-Goals
- Sổ đăng ký mã số thuế có thẩm quyền (do cơ quan thuế sở hữu).
- Tính tỷ lệ thuế tại thời điểm bán (do pricing engine sở hữu).
- Toàn bộ vòng đời phát hành hóa đơn, thử lại, nộp CQT / T-VAN, 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 channel, chính sách thử lại, chia sẻ profile, wizard onboarding).
3. Success Metrics
| Metric | Mục tiêu / tín hiệu |
|---|---|
| Độ phủ định danh thuế | 100% merchant phát hành hóa đơn đều có MST + 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. Personas & Use Cases
| 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 |
Core scenarios: đă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ế, được kết nối tới một nhà cung cấp và giữ đồng bộ.
5. User Stories
- 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 MST 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. Functional Requirements
| # | Requirement | 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 Kafka, taxation ⇄ commerce) | URD-GRP-003 |
| FR-7 | Một nhóm thuế chỉ dùng được khi tương thích với tax method 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 / VNIS qua iiapi) với credentials 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. Non-Functional Requirements
| Area | Requirement |
|---|---|
| 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à MST đã đăng ký |
| Tenancy & authz | Mọi thao tác phân tách theo từng merchant (x-merchant-id); 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 | Credentials 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ữ ({ en, vi }); dữ liệu hành chính theo cách đặt tên VN |
8. UX & Flows
Các màn hình chính (trong apps/client): 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. Data & Domain
| Entity | Vai trò |
|---|---|
TaxInfo | Đị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 |
TaxGroup | 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 |
TaxGroupItem | Dòng thuế đã áp liên kết một nhóm thuế với các sản phẩm khớp |
Merchant taxMethod | Tax method của merchant mà một nhóm thuế phải tương thích |
Product taxGroupId | Nhóm thuế đã áp lên một sản phẩm |
MerchantInvoiceProfile | 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 / VNIS qua iiapi) với credentials 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. Dependencies & Assumptions
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ộ.
- Kafka CDC - seam lan truyền thay đổi sản phẩm và merchant vào taxation và invoice.
@nx/invoice- 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 tax method đã đượ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 / VNIS qua iiapi) để kết nối.
11. Risks & Open Questions
| 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 Kafka đồ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 tax method của merchant | Tính tương thích được kiểm soát trước khi một nhóm dùng được |
| MST 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ộ credentials nhà cung cấp | Credentials lưu mã hóa trên profile |
12. Release Plan & Launch Criteria
| Aspect | 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 Kafka 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 tax method 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 (queue, thử lại, nộp CQT, dấu vết kiểm toán) do Vòng đời hóa đơn sở hữu.
References
- 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 - tổng quan + truy vết
- Developer: @nx/taxation · domain model · @nx/invoice