PRD: Kê khai Thuế dải 1-3 tỷ
| Module | Thuế & Hóa đơn | PRD ID | PRD-DCL-001 |
| Trạng thái | Sẵn sàng dev | FEAT | DCL · BANA-1421 |
| Epic | BANA-1318 | Plane | BANA-1565 |
| Ngày | 2026-06-11 | Phiên bản | v0.2 |
| Gói | @nx/ledger · @nx/taxation | URD | DCL |
| Surface | Client · Chủ/QL | ||
| Phụ trách | Việt Võ · Phát Nguyễn | ||
TL;DR
- Hộ kinh doanh dải doanh thu 1-3 tỷ nộp thuế ngay trong BANA, không cần thuê kế toán.
- Sổ S2a đã chạy thật - tổng hợp doanh thu, VAT, TNCN theo nhóm thuế của merchant, xuất được PDF/XLSX. Thuế suất cũng đã áp theo ngành của merchant qua nhóm thuế cấu hình được ở Back Office, và TNCN đã được tính tự động ngay lúc bán, không phải chờ tới cuối kỳ.
- Phần chưa xây: sinh tờ khai 01/CNKD (PDF/XML) từ số liệu sổ S2a, và nộp qua T-VAN kèm theo dõi trạng thái tới khi CQT xác nhận. Hiện T-VAN mới tra cứu được, chưa nộp được.
- Khi hoàn tất, chủ hộ mở màn thuế trên trang Client, xem sổ S2a của kỳ, bấm "Lập 01/CNKD" để xem trước tờ khai, xác nhận rồi nộp - và theo dõi trạng thái (đã nộp → CQT xác nhận) ngay trên màn đó.
1. Bối cảnh & Vấn đề
Engine sổ sách đã đi xa hơn board tưởng: sổ S1a và S2a đều sinh từ doanh thu thật của merchant (không phải dữ liệu mẫu), tổng hợp theo nhóm thuế, và xuất được PDF/XLSX. Thuế suất cũng không còn là con số merchant tự gõ tay - nhóm thuế (TaxGroup/TaxGroupItem) đã ánh xạ ngành (Phân phối, Dịch vụ, Sản xuất, Khác) sang % VAT và TNCN, cấu hình được qua Back Office, và mỗi giao dịch bán hàng đã tự tính TNCN ngay lúc thanh toán theo thuế suất của nhóm thuế đó.
Đoạn còn thiếu là từ sổ tới cơ quan thuế: tờ khai 01/CNKD chưa tồn tại ở bất kỳ hình thức nào - không có template, không sinh được PDF hay XML. Tích hợp T-VAN hiện chỉ tra cứu mã số thuế, chưa có endpoint nộp và cũng chưa theo dõi được trạng thái CQT phản hồi. Trên trang Client, chủ hộ xem và tải sổ S2a được, nhưng màn dừng lại ở đó - không có nút "Lập 01/CNKD", không có bước xác nhận và nộp.
PRD này đặc tả phần còn thiếu: nối sổ S2a đã chạy vào một luồng khai thuế trọn vẹn - sinh tờ khai, xác nhận, nộp qua T-VAN, và theo dõi tới khi CQT xác nhận - cho đúng dải doanh thu 1-3 tỷ.
2. Mục tiêu / Ngoài phạm vi
Mục tiêu
- Kiểm chứng sổ S2a hiển thị đúng doanh thu, VAT, TNCN thật của một merchant 1-3 tỷ theo từng kỳ (đã chạy, cần xác nhận với dữ liệu thật).
- Thuế suất áp cho merchant theo đúng ngành đã đăng ký, qua nhóm thuế cấu hình được - không cần merchant tự chọn phần trăm (đã chạy).
- TNCN tính tự động ngay lúc bán theo thuế suất nhóm thuế, gộp vào sổ S2a theo kỳ (đã chạy).
- Sinh tờ khai 01/CNKD chuẩn (PDF/XML) từ số liệu sổ S2a của một kỳ (mới).
- Nộp tờ khai qua T-VAN và theo dõi trạng thái tới khi CQT xác nhận (mới).
- Màn thuế trên trang Client: xem sổ → xem trước 01/CNKD → nộp, không cần rời khỏi BANA hay dùng công cụ ngoài.
- Lịch sử nộp theo từng kỳ, tra cứu lại được sau này.
Ngoài phạm vi
- Sổ S2b-e (chi tiết hơn S2a) và dải doanh thu 3-50 tỷ - dành cho Giai đoạn 3.
- VAT khấu trừ / thuế TNDN cho doanh nghiệp (khác hộ kinh doanh) - Giai đoạn 3.
- Thay đổi luồng phát hành hóa đơn điện tử đang chạy (INV, ISS) - không đụng tới, đây là luồng kê khai thuế định kỳ, khác với hóa đơn từng giao dịch.
- Đa nhà cung cấp T-VAN ngoài VNPAY hiện tại.
- Tự động nộp không người duyệt - chủ hộ luôn phải xác nhận xem trước tờ khai trước khi gửi CQT.
3. Thước đo thành công
| Chỉ số | Mục tiêu / tín hiệu |
|---|---|
| Trọn một kỳ thuế end-to-end | Một merchant 1-3 tỷ thật nộp tờ khai và được CQT xác nhận (mục tiêu T8) |
| Không cần chọn tay | 100% merchant dải 1-3 tỷ được áp thuế suất theo ngành - không ai tự gõ phần trăm |
| Khớp số liệu | Số trên tờ khai 01/CNKD khớp đúng số đã hiển thị trên sổ S2a của cùng kỳ, không lệch do tính lại |
4. Persona & Tình huống
| Persona | Mục tiêu trong tính năng này |
|---|---|
| Chủ hộ kinh doanh (dải 1-3 tỷ, không kế toán) | Nộp thuế theo quý/tháng ngay trong BANA, không thuê ngoài |
| Cơ quan thuế (CQT) | Nhận và xác nhận tờ khai qua mạng T-VAN |
Tình huống cốt lõi: cuối kỳ, chủ hộ mở màn thuế trên trang Client, thấy ngay sổ S2a đã tổng hợp sẵn doanh thu, VAT, TNCN thật của kỳ đó theo đúng thuế suất ngành của mình. Họ bấm "Lập 01/CNKD", xem trước tờ khai đã điền sẵn số liệu, xác nhận rồi nộp. Hệ thống gửi qua T-VAN và hiện trạng thái ngay trên màn - từ "đã nộp" tới "CQT đã xác nhận" - không cần rời BANA, không cần gọi kế toán.
5. User Story
- Là chủ hộ kinh doanh, tôi mở màn thuế và thấy ngay sổ S2a của kỳ hiện tại, để không phải tự tổng hợp doanh thu từ nơi khác.
- Là chủ hộ kinh doanh, thuế suất áp cho tôi tự động theo ngành đã đăng ký, để tôi không phải tự chọn phần trăm và không có rủi ro chọn sai.
- Là chủ hộ kinh doanh, tôi xem trước tờ khai 01/CNKD trước khi nộp, để chắc chắn số liệu đúng trước khi gửi cơ quan thuế.
- Là chủ hộ kinh doanh, tôi nộp tờ khai ngay trong BANA và theo dõi trạng thái tới khi CQT xác nhận, để không phải nộp thủ công hay thuê kế toán.
- Là chủ hộ kinh doanh, tôi xem lại lịch sử nộp của các kỳ trước, để tra cứu khi cần đối chiếu.
6. Yêu cầu chức năng
| # | Yêu cầu | Trạng thái | URD ref |
|---|---|---|---|
FR-001 | Sổ S2a từ doanh thu thật - tổng hợp doanh thu, VAT, TNCN theo nhóm thuế của merchant cho một kỳ, xuất được PDF/XLSX | ✅ | URD-DCL-001 |
FR-002 | Thuế suất theo ngành - nhóm thuế ánh xạ ngành (Phân phối, Dịch vụ, Sản xuất, Khác) sang % VAT/TNCN, cấu hình được ở Back Office | ✅ | URD-DCL-002 |
FR-003 | Tính TNCN tự động ngay lúc bán, theo thuế suất nhóm thuế áp cho giao dịch, gộp vào sổ S2a của kỳ | ✅ | URD-DCL-003 |
FR-004 | Sinh tờ khai 01/CNKD (PDF/XML) từ số liệu sổ S2a của một kỳ | 🚧 chưa xây | URD-DCL-004 |
FR-005 | Nộp qua T-VAN và theo dõi trạng thái tới khi CQT xác nhận | 🚧 chưa xây - T-VAN hiện chỉ tra cứu mã số thuế | URD-DCL-005 |
FR-006 | Màn thuế Client: xem sổ S2a → xem trước 01/CNKD → nộp | 🔶 chỉ phần xem sổ | URD-DCL-006 |
FR-007 | Lịch sử nộp theo từng kỳ | 🚧 chưa xây - hiện chỉ có trạng thái theo lô sinh sổ | URD-DCL-007 |
FR-001 - Sổ S2a từ doanh thu thật. Cho một kỳ (tháng/quý), hệ thống tổng hợp doanh thu, VAT và TNCN thật của merchant từ các đơn hàng đã hoàn tất trong kỳ, gộp theo nhóm thuế áp cho từng dòng hàng. Sổ xuất được PDF và XLSX. Đây là engine sổ sách đang chạy (job sinh sổ theo lịch hoặc theo yêu cầu); PRD này không xây lại phần này mà kiểm chứng nó chạy đúng trên merchant thật thuộc dải 1-3 tỷ.
FR-002 - Thuế suất theo ngành. Nhóm thuế là một mẫu quy tắc cấu hình được (qua Back Office) ánh xạ ngành kinh doanh sang % VAT và % TNCN - ví dụ ngành Phân phối, Dịch vụ, Sản xuất, Khác, mỗi ngành một bộ thuế suất mặc định. Merchant không tự gõ phần trăm; thuế suất theo đúng nhóm thuế khớp ngành đã đăng ký của merchant.
FR-003 - Tính TNCN tự động. Mỗi giao dịch bán hàng hoàn tất tính TNCN ngay lúc đó, theo thuế suất của nhóm thuế áp cho giao dịch - không phải một bước tính riêng lúc lập tờ khai. Sổ S2a của kỳ là tổng của các khoản TNCN này.
FR-004 - Sinh tờ khai 01/CNKD. Chưa xây. Cần một template tờ khai 01/CNKD (đúng mẫu cơ quan thuế yêu cầu cho hộ kinh doanh) nhận số liệu từ sổ S2a của một kỳ và sinh ra bản PDF để xem trước, cùng bản XML để nộp qua T-VAN. Số trên tờ khai phải khớp tuyệt đối với số đã hiển thị trên sổ S2a của cùng kỳ - không tính lại theo công thức khác.
FR-005 - Nộp qua T-VAN. Chưa xây. Tích hợp T-VAN hiện tại chỉ có tra cứu mã số thuế; cần thêm một endpoint nộp tờ khai (gửi bản XML đã sinh ở FR-004) và một cơ chế theo dõi trạng thái - từ "đã nộp" tới khi CQT phản hồi "đã xác nhận" hoặc từ chối kèm lý do.
FR-006 - Màn thuế Client. Phần xem sổ S2a (bảng, drill xuống đơn, xuất PDF/XLSX, kích hoạt sinh lại theo kỳ) đã có trên trang Client. Phần còn thiếu: nút "Lập 01/CNKD" mở bản xem trước, bước xác nhận, nút nộp, và chip trạng thái (đã nộp → đã xác nhận) ngay trên cùng màn.
FR-007 - Lịch sử nộp. Chưa xây. Hiện chỉ có trạng thái theo lô sinh sổ (đang xử lý / xong / lỗi) - không phải lịch sử nộp cho cơ quan thuế. Cần một danh sách các kỳ trước kèm tờ khai đã nộp và trạng thái CQT tương ứng.
6.1 Tiêu chí nghiệm thu
- Mở màn thuế của một merchant 1-3 tỷ, chọn một kỳ đã có giao dịch → sổ S2a hiện đúng doanh thu, VAT, TNCN gộp theo nhóm thuế của kỳ đó, khớp với các đơn hàng thật trong kỳ.
- Merchant đăng ký ngành có thuế suất khác merchant khác → thuế suất áp cho giao dịch của mỗi merchant đúng theo nhóm thuế của ngành mình, không lẫn lộn.
- Một giao dịch bán hàng hoàn tất → khoản TNCN của giao dịch đó cộng ngay vào tổng TNCN của kỳ hiện tại, không cần thao tác thêm.
- Từ màn thuế, bấm "Lập 01/CNKD" cho một kỳ có sổ S2a → tờ khai PDF/XML sinh ra khớp đúng số liệu của kỳ đó (FR-004, chưa xây).
- Xem trước tờ khai, xác nhận rồi bấm nộp → tờ khai gửi qua T-VAN; trạng thái chuyển "đã nộp" rồi "CQT đã xác nhận" khi có phản hồi (FR-005, chưa xây).
- CQT từ chối tờ khai → trạng thái ghi rõ lý do từ chối, chủ hộ xem được ngay trên màn thuế (FR-005, chưa xây).
- Mở lịch sử nộp → thấy các kỳ trước kèm tờ khai đã nộp và trạng thái CQT (FR-007, chưa xây).
7. Yêu cầu phi chức năng
| Khía cạnh | Yêu cầu |
|---|---|
| Bất biến sau khi nộp | Hồ sơ tờ khai đã nộp không sửa được; mọi thay đổi trạng thái ghi vào dấu vết kiểm toán |
| Thuế suất đúng thời điểm | Thuế suất áp dụng là thuế suất tại thời điểm phát sinh giao dịch - đổi ngành giữa kỳ không hồi tố các giao dịch đã tính trước đó |
| Toàn vẹn số liệu | Tờ khai 01/CNKD sinh ra phải khớp tuyệt đối số đã hiển thị trên sổ S2a của cùng kỳ |
| Tenancy | Sổ và tờ khai của một merchant chỉ merchant đó xem và nộp được |
8. UX & Luồng
- Màn thuế: chọn kỳ → xem sổ S2a (drill xuống đơn) → "Lập 01/CNKD" (đã có phần xem sổ, còn lại chưa xây).
- Xem trước tờ khai (PDF) → xác nhận → nộp qua T-VAN → chip trạng thái (đã nộp → đã xác nhận).
- Lịch sử: các kỳ trước với tờ khai và trạng thái.
9. Dữ liệu & Miền nghiệp vụ
| Thực thể | Vai trò |
|---|---|
| Sổ S2a | Bản tổng hợp doanh thu, VAT, TNCN thật của merchant theo kỳ và nhóm thuế (đã có) |
Nhóm thuế (TaxGroup/TaxGroupItem) | Ánh xạ ngành → % VAT/TNCN, cấu hình được ở Back Office (đã có) |
Bậc doanh thu (TaxTier) | Ánh xạ dải doanh thu (0-1 tỷ, 1-3 tỷ, 3-50 tỷ, 50 tỷ+) - xác định merchant có thuộc dải 1-3 tỷ hay không (đã có) |
| Tờ khai 01/CNKD | Tài liệu tờ khai sinh từ sổ S2a của một kỳ - bản PDF để xem trước, bản XML để nộp (mới) |
| Hồ sơ nộp T-VAN | Bản ghi một lần nộp: tờ khai đã gửi, trạng thái, phản hồi CQT (mới) |
Chỉ ở mức khái niệm - schema đầy đủ nằm trong developer domain model và taxation.
10. Phụ thuộc & Giả định
Phụ thuộc vào
- Sổ sách (@nx/ledger) - nguồn dữ liệu S2a, job sinh sổ, xuất PDF/XLSX.
- Nhóm thuế (@nx/taxation, GRP) - nguồn thuế suất theo ngành và tính TNCN per-transaction.
- Retail Business Type (E2) - ngành/loại hình đúng của merchant quyết định thuế suất áp dụng.
- Credential/spec nộp T-VAN (VNPAY) - khâu nộp là bên thứ ba, cần thông tin xác thực và tài liệu API nộp từ nhà cung cấp.
Giả định
- Merchant đã được xác định đúng ngành và thuộc dải doanh thu 1-3 tỷ trước khi dùng tính năng này.
- Sổ S2a của kỳ đã sinh xong (qua job hiện có) trước khi lập tờ khai.
11. Rủi ro & Câu hỏi mở
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Spec/credential nộp T-VAN chưa sẵn sàng | Rủi ro tiến độ lớn nhất - T-VAN hiện mới tra cứu, chưa có API nộp; cần chốt với VNPAY ngay đầu T7 |
| Đổi ngành giữa kỳ, thuế suất nào áp dụng? | Đã xử lý ở mức giao dịch - TNCN tính theo thuế suất tại thời điểm phát sinh (FR-003), không hồi tố |
| Chưa có bước xem trước 100% khớp trước khi nộp | Giảm thiểu bằng bước xác nhận preview PDF bắt buộc trước khi gửi CQT (FR-004, FR-006) |
12. Kế hoạch phát hành & Tiêu chí
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P2 - DCL trong URD DCL, mục tiêu T7-T8 |
| Rollout | Chỉ merchant dải doanh thu 1-3 tỷ đã bật flow kê khai thuế; không mở rộng dải khác |
| Migration | Không cần cho phần đã chạy (S2a, nhóm thuế); mới: template 01/CNKD, bảng hồ sơ nộp T-VAN |
| Tiêu chí ra mắt | AC-DCL-01 đạt với ít nhất một merchant thật: sổ đúng, tờ khai đúng, T-VAN nhận, CQT xác nhận |
| Giám sát | Tỷ lệ nộp thành công, thời gian tới khi CQT xác nhận, số lần thử lại khi T-VAN/CQT từ chối |
13. FAQ
Có xây lại sổ S2a không? Không - nó đã chạy thật, chỉ cần kiểm chứng với dữ liệu merchant thật rồi nối vào luồng nộp.
Thuế suất đã tự động theo ngành chưa? Rồi - nhóm thuế đã ánh xạ ngành sang % VAT/TNCN, cấu hình được ở Back Office; merchant không tự chọn phần trăm.
Vậy còn thiếu gì? Tờ khai 01/CNKD (chưa có template hay sinh PDF/XML) và nộp qua T-VAN (hiện chỉ tra cứu, chưa nộp được) - đây là trọng tâm của PRD này.
Đổi ngành giữa kỳ thì áp thuế suất nào? Thuế suất tại thời điểm phát sinh giao dịch - TNCN đã tính theo thuế suất đó ngay lúc bán, không hồi tố khi ngành đổi sau đó.
Áp dụng cho dải doanh thu nào? Chỉ dải 1-3 tỷ. Dải 3-50 tỷ và sổ S2b-e thuộc Giai đoạn 3.
Tham chiếu
URD DCL · Giai đoạn 2 - Theo tháng · Epic BANA-1318 · Chính sách thuế Developer: @nx/ledger · @nx/taxation · @nx/invoice (T-VAN)