PRD: Trải nghiệm Xuất Hóa đơn
| Module | Thuế & Hóa đơn | PRD ID | PRD-ISS-001 |
| Trạng thái | Sẵn sàng dev | FEAT | ISS · BANA-1422 |
| Epic | BANA-1318 | Plane | BANA-1564 |
| Ngày | 2026-06-11 | Phiên bản | v1.0 |
| Gói | @nx/invoice | URD | ISS |
| Surface | Sale · POSClient · Chủ/QL | ||
| Phụ trách | Việt Võ · Phát Nguyễn | ||
TL;DR
- Thu ngân xuất hóa đơn điện tử ngay lúc thanh toán tại POS - một thao tác, hoặc tự động theo cấu hình merchant - không cần rời màn thanh toán (🚧 chưa dựng; engine phát hành đã sẵn sàng phía sau, chỉ thiếu nút bấm/trạng thái trên màn hình).
- Trên Client, một màn quản lý hóa đơn mới cho chủ quán thấy mọi hóa đơn kèm trạng thái phát hành và mã cơ quan thuế (CQT) - khác với tab "Hóa đơn" hiện có ở POS, thực chất chỉ là danh sách đơn hàng mang tên trùng (🚧 chưa dựng).
- Chủ quán điều chỉnh một hóa đơn phát hành sai ngay từ màn chi tiết (🔶 hạ tầng xử lý đã sẵn, chưa có màn thao tác); thay thế hóa đơn thì chưa có ở bất kỳ tầng nào, kể cả bên dưới giao diện.
- Khách công ty xin hóa đơn VAT được chọn từ hồ sơ khách hàng doanh nghiệp có sẵn MST - hóa đơn phát hành mang đúng MST và tên công ty đó, phụ thuộc tính năng Khách hàng doanh nghiệp (
BIZ) ra mắt cùng tháng (🔶 hệ thống đã nhận và lưu được MST rời rạc, chưa có hồ sơ để chọn).- Một hóa đơn phát hành lỗi hiển thị và thử lại được từ màn quản lý, không "biến mất" khỏi tầm nhìn của chủ quán (🚧 chưa dựng).
- In/chia sẻ hóa đơn đã phát hành, và xác minh kết nối nhà cung cấp (VNPAY) từ màn cấu hình, là hai việc nhỏ hơn còn để sau - cả hai hiện chưa có bề mặt nào (🚧).
1. Bối cảnh & Vấn đề
Vòng đời hóa đơn (hàng đợi → phát hành → trạng thái), tích hợp nhà cung cấp VNPAY (thao tác gốc/điều chỉnh/hủy), và định danh thuế/nhóm thuế đều đã ship ở Phase 1. Hệ thống phát hành đã lắng nghe sự kiện thanh toán thành công và có thể tự tạo hàng đợi hóa đơn ngay khi đơn được thanh toán. Merchant đang sở hữu một cỗ máy phát hành chạy tốt phía sau - nhưng gần như không có cách nào để nhìn thấy hay điều khiển nó từ giao diện.
Cái chưa xây là trải nghiệm phía trước: màn thanh toán thành công tại POS chưa có bất kỳ thao tác xuất hóa đơn nào (chỉ có in hóa đơn bán hàng và phiếu bếp); Client chưa có màn nào hiển thị trạng thái phát hành hay mã CQT của một hóa đơn. Đáng chú ý, tab "Hóa đơn" hiện có ở POS dễ gây hiểu lầm - nó hiển thị trạng thái đơn hàng (nháp/đang xử lý/hoàn tất/đã hủy), không phải trạng thái phát hành hóa đơn điện tử; hai khái niệm khác nhau đang dùng chung một cái tên.
Hóa đơn điều chỉnh có hạ tầng xử lý sẵn sàng (kiểm tra trạng thái gốc, khóa tránh xử lý trùng, gọi nhà cung cấp) nhưng chưa có màn thao tác nào gọi tới; hóa đơn thay thế thì chưa có ở bất kỳ tầng nào - chỉ là một khái niệm được đặt tên trong mô hình dữ liệu. Hóa đơn công ty đã nhận và lưu được mã số thuế (MST) người mua qua thông tin đính kèm đơn hàng, nhưng chưa có hồ sơ khách hàng doanh nghiệp nào để chọn cho tới khi tính năng Khách hàng doanh nghiệp (BIZ) ra mắt, cùng khung tháng 7.
2. Mục tiêu / Ngoài phạm vi
Mục tiêu
- Thu ngân xuất hóa đơn ngay tại POS lúc thanh toán bằng một thao tác, hoặc tự động theo cấu hình merchant.
- Client có một màn quản lý hóa đơn: danh sách lọc theo trạng thái phát hành + kỳ, chi tiết kèm mã CQT và lịch sử đầy đủ các bước xử lý.
- Chủ quán xuất được hóa đơn điều chỉnh cho một hóa đơn đã phát hành sai.
- Hóa đơn công ty mang đúng MST và tên công ty của khách hàng doanh nghiệp đã chọn.
- Hóa đơn lỗi hiển thị và thử lại được từ màn quản lý - không có hóa đơn nào "biến mất" vì lỗi kỹ thuật.
- Hóa đơn đã phát hành in/chia sẻ được cho khách.
- Kết nối tới nhà cung cấp hóa đơn điện tử xác minh được từ màn cấu hình.
Ngoài phạm vi
- Thay thế hóa đơn - khái niệm đã đặt tên trong mô hình dữ liệu, chưa có luồng xử lý hay màn thao tác ở bất kỳ tầng nào; nằm ngoài tăng tiến này (FR-003, §11).
- Kê khai/nộp thuế (PRD-DCL-001).
- Nhà cung cấp hóa đơn ngoài VNPAY.
- Quy tắc xuất hóa đơn theo ngành vượt quá những gì nhóm thuế đã định nghĩa.
- Xây hồ sơ khách hàng doanh nghiệp - thuộc tính năng Khách hàng doanh nghiệp (
BIZ, PRD-BIZ-001); PRD này chỉ tiêu thụ hồ sơ đó khi chọn khách hàng công ty. - Hiển thị PDF hóa đơn - do nhà cung cấp đảm nhiệm; hình thức chia sẻ chính xác còn là câu hỏi mở (§11).
- Toàn bộ màn cấu hình/onboarding nhà cung cấp hóa đơn (
CFG) - PRD này chỉ cần bước xác minh kết nối, không dựng lại luồng cấu hình đầy đủ.
3. Thước đo thành công
| Thước đo | Mục tiêu |
|---|---|
| Xuất tại POS | Thu ngân xuất hóa đơn lúc thanh toán bằng một thao tác, trên merchant thật |
| Không lỗi câm | Mọi hóa đơn lỗi hiển thị trên màn quản lý và thử lại được từ đó |
| Đúng MST công ty | Hóa đơn công ty phát hành mang đúng MST đã chọn, không cần sửa tay sau khi xuất |
4. Persona & Tình huống
| Persona | Mục tiêu trong tính năng này |
|---|---|
| Thu ngân | Xuất hóa đơn lúc thanh toán mà không cần biết gì về thuế |
| Chủ quán | Soát hóa đơn, sửa sai bằng điều chỉnh, phục vụ khách công ty |
| Khách công ty | Nhận hóa đơn VAT hợp lệ mang đúng MST công ty mình |
Tình huống cốt lõi: một thu ngân hoàn tất thanh toán tại POS, hóa đơn được xuất tự động hoặc bằng một chạm. Nếu khách báo sai số tiền sau đó, chủ quán mở lại hóa đơn đó trên Client và tạo một hóa đơn điều chỉnh ngay từ màn chi tiết - không cần biết quy trình thuế phía sau, không cần liên hệ hỗ trợ kỹ thuật.
5. User Story
- Là thu ngân, tôi hoàn tất thanh toán và xuất hóa đơn bằng một chạm; khách nhận ngay.
- Là chủ quán, khách báo sai tiền - tôi xuất hóa đơn điều chỉnh từ màn chi tiết.
- Là chủ quán, công ty xin HĐ VAT - tôi chọn KH doanh nghiệp và hóa đơn mang MST của họ.
- Là chủ quán, một hóa đơn phát hành lỗi - tôi thấy lý do ngay trên màn quản lý và thử lại mà không cần liên hệ hỗ trợ.
- Là chủ quán, khách hỏi xin lại hóa đơn - tôi in hoặc chia sẻ hóa đơn đã phát hành từ màn chi tiết.
6. Yêu cầu chức năng
| # | Yêu cầu | Trạng thái | URD ref |
|---|---|---|---|
FR-001 | Xuất một-thao-tác tại POS lúc thanh toán, tự động hoặc thủ công theo cấu hình merchant | 🚧 | URD-ISS-001 |
FR-002 | Màn quản lý hóa đơn - danh sách lọc theo trạng thái/kỳ + chi tiết kèm mã CQT và lịch sử | 🚧 | URD-ISS-002 |
FR-003 | Hóa đơn điều chỉnh & thay thế cho hóa đơn đã phát hành | 🔶 điều chỉnh có hạ tầng, thay thế thì không | URD-ISS-003 |
FR-004 | Hóa đơn công ty mang MST + tên công ty của khách hàng doanh nghiệp đã chọn | 🔶 chờ BIZ | URD-ISS-004 |
FR-005 | Lỗi phát hành hiển thị + thử lại được từ màn quản lý | 🚧 | URD-ISS-005 |
FR-006 | In/chia sẻ hóa đơn đã phát hành cho khách | 🚧 | URD-ISS-006 |
FR-007 | Xác minh kết nối nhà cung cấp (VNPAY) e2e từ màn cấu hình | 🚧 | URD-ISS-007 |
FR-001 - Xuất một-thao-tác tại POS. Thanh toán hoàn tất tại POS kích hoạt phát hành hóa đơn điện tử: theo cấu hình merchant, việc này tự động (ngay khi thanh toán thành công) hoặc bằng một thao tác thủ công của thu ngân - một nút "Xuất hóa đơn" cạnh các thao tác hiện có (in hóa đơn bán hàng, in phiếu bếp). Màn thanh toán thành công hiển thị một chip trạng thái phát hành trên đơn, không cần rời màn hình để biết kết quả. Thu ngân không cần biết gì về thuế - chỉ cần biết hóa đơn đã xuất hay chưa.
FR-002 - Màn quản lý hóa đơn. Một màn mới trên Client: danh sách hóa đơn lọc theo trạng thái phát hành (Chờ xử lý, Đang xử lý, Thành công, Lỗi, Đã hủy) và theo kỳ; chọn một dòng mở màn chi tiết hiện số hóa đơn do nhà cung cấp cấp, mã cơ quan thuế (CQT), và lịch sử đầy đủ các bước (tạo, gửi, ký, gửi CQT, CQT chấp nhận/từ chối, điều chỉnh, thay thế, hủy). Đây là một màn khác với tab "Hóa đơn" hiện có ở POS - tab đó thực chất là danh sách đơn hàng mang trạng thái đơn (nháp/đang xử lý/hoàn tất/đã hủy), không phải trạng thái phát hành hóa đơn điện tử hay mã CQT; hai khái niệm dễ gây nhầm lẫn nếu chỉ nhìn thoáng qua ứng dụng (§11).
FR-003 - Hóa đơn điều chỉnh & thay thế. Từ màn chi tiết một hóa đơn đã phát hành thành công, chủ quán tạo hóa đơn điều chỉnh: nhập lý do điều chỉnh và danh sách dòng cần sửa (số thứ tự, tên, số lượng, đơn giá, thành tiền, thuế); hóa đơn điều chỉnh mới tham chiếu hóa đơn gốc và đi qua đúng vòng đời phát hành như một hóa đơn thường. Hạ tầng xử lý điều chỉnh (kiểm tra trạng thái gốc, khóa tránh xử lý trùng, gọi nhà cung cấp) đã sẵn sàng theo PRD-INV-003 - chỉ thiếu màn thao tác. Cùng đợt backend đó cũng đã dựng xong luồng hủy hóa đơn kèm lý do bắt buộc, dù URD-ISS không liệt kê hủy như một yêu cầu riêng của trải nghiệm (§11). Thay thế hóa đơn - dùng khi cần hủy toàn bộ và phát hành lại thay vì sửa một phần - hiện chưa khả dụng ở bất kỳ tầng nào: không có luồng xử lý, không có API, không có màn hình; chỉ tồn tại như một khái niệm được đặt tên trong mô hình dữ liệu hóa đơn.
FR-004 - Hóa đơn công ty mang MST người mua. Tại checkout hoặc lúc xuất hóa đơn, chủ quán/thu ngân chọn một khách hàng doanh nghiệp đã có hồ sơ (tên công ty, MST) - hóa đơn phát hành mang đúng MST và tên công ty đó thay vì tên người mua lẻ. Khi không chọn khách hàng doanh nghiệp, hóa đơn dùng tên mặc định cho người tiêu dùng không lấy hóa đơn theo tên (theo quy định hiện hành). Hệ thống hóa đơn đã nhận và lưu được MST người mua qua thông tin đính kèm đơn hàng; phần còn thiếu là hồ sơ khách hàng doanh nghiệp để chọn - phụ thuộc tính năng Khách hàng doanh nghiệp (BIZ, ra mắt cùng tháng 7).
FR-005 - Lỗi phát hành hiển thị + thử lại. Một hóa đơn phát hành lỗi hiển thị trạng thái Lỗi kèm lý do trên màn quản lý hóa đơn, không "biến mất" khỏi tầm nhìn của chủ quán. Hệ thống tự động thử lại theo lịch cho các lỗi được xác định là tạm thời; chủ quán cũng cần thử lại được từ màn chi tiết (cần xác nhận thêm việc này là một hành động thủ công riêng hay chỉ hiển thị trạng thái đang tự động thử lại, xem §11). Thử lại - dù tự động hay thủ công - không bao giờ tạo ra hai hóa đơn cho cùng một đơn hàng.
FR-006 - In/chia sẻ hóa đơn đã phát hành. Từ màn chi tiết, chủ quán in hoặc chia sẻ hóa đơn đã phát hành thành công cho khách. Đây khác với việc in hóa đơn bán hàng/phiếu bếp đã có sẵn ở POS. Hình thức chia sẻ chính xác (đường dẫn tra cứu theo mã CQT hay hình thức khác) là quyết định còn mở, vì hiển thị PDF hóa đơn không thuộc phạm vi PRD này (do nhà cung cấp đảm nhiệm).
FR-007 - Xác minh kết nối nhà cung cấp. Từ màn cấu hình, đội vận hành/chủ merchant xác minh được kết nối tới nhà cung cấp hóa đơn điện tử (VNPAY) đang hoạt động - khác với cấu hình VNPAY cho thanh toán QR/Phone POS đã có sẵn. Mục này phụ thuộc một màn cấu hình nhà cung cấp hóa đơn tồn tại trước - hiện chưa có màn nào trên Client hay Back Office đọc/ghi cấu hình này, dù phần backend (kết nối, chính sách thử lại) đã ship.
6.1 Tiêu chí nghiệm thu
- Thanh toán hoàn tất tại POS → hóa đơn được đưa vào hàng đợi phát hành (tự động hoặc qua một thao tác) → trạng thái phát hành hiển thị ngay trên màn thanh toán thành công (FR-001).
- Mở màn quản lý hóa đơn trên Client, lọc theo trạng thái Lỗi → thấy đúng các hóa đơn lỗi kèm lý do; mở một hóa đơn → thấy mã CQT và lịch sử đầy đủ (FR-002).
- Từ một hóa đơn Thành công, tạo hóa đơn điều chỉnh với lý do + dòng sửa → hóa đơn điều chỉnh mới xuất hiện, tham chiếu đúng hóa đơn gốc (FR-003 điều chỉnh).
- Thử tạo hóa đơn thay thế → không có thao tác nào khả dụng ở màn chi tiết, đúng như phạm vi hiện tại (FR-003 thay thế, 🚧 ngoài phạm vi).
- Chọn một khách hàng doanh nghiệp có MST lúc checkout → hóa đơn phát hành mang đúng MST và tên công ty đó, không cần sửa tay (FR-004).
- Không chọn khách hàng doanh nghiệp → hóa đơn dùng tên mặc định cho người mua lẻ, không mang MST (FR-004).
- Giả lập một hóa đơn phát hành lỗi → hóa đơn hiển thị trạng thái Lỗi kèm lý do trên màn quản lý; thử lại → phát hành thành công, không tạo hóa đơn trùng (FR-005).
- Từ một hóa đơn Thành công, in hoặc lấy đường dẫn chia sẻ → khách nhận được hóa đơn hợp lệ (FR-006).
- Từ màn cấu hình nhà cung cấp, xác minh kết nối → thấy kết quả kết nối thành công hoặc lỗi thực từ nhà cung cấp (FR-007).
7. Yêu cầu phi chức năng
| Khía cạnh | Yêu cầu |
|---|---|
| Không chặn checkout | Phát hành hóa đơn chạy nền (bất đồng bộ) - thanh toán không chờ kết quả phát hành |
| Idempotent | Thử lại (tự động hoặc thủ công) không bao giờ tạo hai hóa đơn cho cùng một đơn hàng |
| Toàn vẹn trạng thái | Một hóa đơn đang xử lý không bị hủy hay sửa cho tới khi có kết quả từ nhà cung cấp |
| Hiển thị theo thời gian thực | Trạng thái hóa đơn trên màn quản lý cập nhật mà không cần tải lại màn hình |
8. UX & Luồng
Xuất hóa đơn tại POS lúc thanh toán:
Xử lý một hóa đơn từ màn quản lý:
9. Dữ liệu & Miền nghiệp vụ
| Thực thể | Vai trò |
|---|---|
| Hóa đơn phát hành | Bản ghi một lần phát hành - trạng thái, mã CQT, lịch sử sự kiện |
| Yêu cầu hóa đơn | Thông tin người mua đính kèm trước khi phát hành - tên, MST (nếu có), địa chỉ |
| Hồ sơ khách hàng doanh nghiệp | Sở hữu bởi tính năng Khách hàng doanh nghiệp (BIZ) - nguồn MST/tên công ty để chọn |
| Cấu hình nhà cung cấp | Kết nối + chính sách thử lại tới nhà cung cấp hóa đơn điện tử (VNPAY) theo merchant |
Chỉ ở mức khái niệm - schema đầy đủ nằm trong developer domain model.
10. Phụ thuộc & Giả định
Phụ thuộc vào
- Khách hàng doanh nghiệp (
BIZ, PRD-BIZ-001) - hồ sơ MST + tên công ty để chọn lúc xuất hóa đơn công ty (FR-004). - Cấu hình nhà cung cấp theo merchant (
CFG, backend đã ship) - kết nối + chính sách thử lại cho phát hành (FR-001, FR-005, FR-007). - Retail chuẩn (PRD-RTL-001) - merchant bán lẻ xuất đúng hành vi thuế.
Giả định
BIZra mắt cùng khung thời gian tháng 7 vớiISS; nếu trễ, FR-004 giữ nguyên đường ad-hoc hiện có (không có hồ sơ để chọn, phải nhập tay MST nếu có) cho tới khiBIZsẵn sàng.- Chính sách tự động thử lại (số lần tối đa, độ trễ) đã cấu hình sẵn theo merchant; PRD này không định nghĩa lại chính sách, chỉ hiển thị kết quả.
11. Rủi ro & Câu hỏi mở
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Tab "Hóa đơn" hiện có ở POS dùng chung tên với màn hóa đơn điện tử mới, dễ khiến người xem nhầm là tính năng đã có sẵn | Đổi tên hoặc thay thế tab hiện có khi màn quản lý hóa đơn (FR-002) ra mắt - quyết định còn treo |
| Thay thế hóa đơn (FR-003) chưa có ở bất kỳ tầng nào - xa hơn mức "đã mô hình hóa, chưa phát hành" ghi nhận ở bản trước | Đã xếp ngoài phạm vi (§2); xác nhận lại nếu có yêu cầu đưa vào tăng tiến này |
| Thử lại phát hành lỗi (FR-005) mới có cơ chế tự động theo lịch; chưa rõ có cần một hành động thử-lại-thủ-công riêng | Xác nhận với đội backend trước khi cam kết "thử lại từ màn hình" là một nút bấm hay chỉ hiển thị trạng thái đang tự thử lại |
| Hình thức "chia sẻ" hóa đơn (FR-006) chưa được quyết định ở tầng dữ liệu - có thể là đường dẫn tra cứu theo mã CQT hoặc hình thức khác | Chốt thiết kế trước khi viết tiêu chí nghiệm thu chi tiết cho FR-006 |
Xác minh kết nối nhà cung cấp (FR-007) phụ thuộc một màn cấu hình CFG hiện chưa tồn tại trên bất kỳ bề mặt nào | Xác nhận FR-007 gồm cả việc dựng màn cấu hình tối thiểu, hoặc tách thành phụ thuộc chờ CFG xây riêng |
| Hai điểm vào "Xuất hóa đơn" cũ trong Client hiện đang bị vô hiệu hóa (một quick-action, một mục trong module Tài chính) | Quyết định phục hồi hay xóa hẳn khi FR-001/FR-002 được xây, tránh hai điểm vào mâu thuẫn nhau |
| Hủy hóa đơn đã có đầy đủ hạ tầng backend kèm lý do bắt buộc (PRD-INV-003), nhưng URD-ISS-003 chỉ nêu điều chỉnh & thay thế, không nhắc tới hủy như một yêu cầu riêng của trải nghiệm | Xác nhận thao tác hủy có thuộc phạm vi màn quản lý hóa đơn (FR-002) trong tăng tiến này hay để lại cho một PRD khác |
12. Kế hoạch phát hành & Tiêu chí
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P2 - tháng 7 (WK27-31), song song BIZ |
| Rollout | Ra mắt trực tiếp cho merchant thật khi đạt tiêu chí; engine đã ship từ Phase 1, không cần feature flag riêng cho phần này |
| Migration | Không cần migration dữ liệu - chỉ xây bề mặt thao tác mới trên hạ tầng đã có |
| Tiêu chí ra mắt | AC-ISS-01 (URD) đạt trên merchant thật - một hóa đơn xuất tại POS, một hóa đơn công ty mang MST, một lần phục hồi lỗi; toàn bộ tiêu chí §6.1 đạt, trừ phần thay thế hóa đơn (FR-003, ngoài phạm vi) |
| Giám sát | Tỷ lệ xuất hóa đơn thành công lúc thanh toán; số hóa đơn lỗi còn treo trên màn quản lý; thời gian trung bình từ lỗi tới thử lại thành công |
13. FAQ
Có xây lại engine hóa đơn không? Không - vòng đời, tích hợp VNPAY và định danh thuế đã ship ở Phase 1; PRD này chỉ xây bề mặt thao tác cho người dùng.
Tab "Hóa đơn" hiện có ở POS có phải là màn quản lý hóa đơn của PRD này không? Không - tab đó hiển thị trạng thái đơn hàng, không phải trạng thái phát hành hay mã CQT; sẽ được thay thế hoặc đổi tên khi FR-002 ra mắt (§11).
Thay thế hóa đơn có làm trong tăng tiến này không? Không - xếp ngoài phạm vi vì chưa có hạ tầng ở bất kỳ tầng nào, khác với hóa đơn điều chỉnh vốn đã có hạ tầng xử lý (§2, §11).
Nếu Khách hàng doanh nghiệp (BIZ) chưa kịp ra mắt thì sao? Hóa đơn công ty vẫn xuất được qua đường ad-hoc hiện có - không có hồ sơ để chọn, phải nhập tay MST nếu khách cung cấp - cho tới khi BIZ sẵn sàng.
"Chia sẻ hóa đơn" nghĩa là gì? Chưa chốt - nhiều khả năng là đường dẫn tra cứu theo mã CQT từ nhà cung cấp, không phải PDF tự dựng (§11).
References
- URD: Thuế & Hóa đơn -
ISS - Liên quan: PRD-INV-001 - Vòng đời & Phát hành hóa đơn · PRD-INV-002 - Tích hợp nhà cung cấp HĐĐT · PRD-INV-003 - Luồng điều chỉnh & hủy hóa đơn · PRD-BIZ-001 - Khách hàng doanh nghiệp · PRD-RTL-001 - Retail Business Type
- Module: Thuế & Hóa đơn - URD · Lộ trình: Phase 2 - Theo tháng
- Developer: @nx/invoice