PRD: Invoice Issuance Experience

Module	Tax & Invoice (CORE-10)	PRD ID	PRD-ISS-001
Status	Planned	Owner	Việt Võ · Phát Nguyễn
Date	2026-06-11	Version	v0.1 (draft)
Packages	@nx/invoice · apps/client · apps/sale-renderer	URD	ISS
Epic	BANA-1318	Window	July 2026

TL;DR

Merchants issue e-invoices as part of selling, not as an afterthought: one action at the POS at payment (MTT), a screen that shows every invoice with its authority code, adjustment/replacement when something was wrong, and company VAT invoices carrying the buyer's MST. The backend already does the heavy lifting - this increment is the user-facing half.

1. Context & Problem

The invoice engine is built: lifecycle (queue → issue → status), the VNPAY provider integration with original/adjustment/replacement operations, and tax identity/groups all shipped in Phase 1. What never fully landed is the experience: the POS instant-issuance UI was left ~80%/in-test, there is no complete invoice management surface on the client, and company invoices can't carry a buyer MST (no business-customer record until July's BIZ). Merchants own an invoice engine they can barely drive.

2. Goals & Non-Goals

Goals - one-action issuance at POS (URD-ISS-001) · invoice list/detail with statuses + authority code (002) · adjustment & replacement flows (003) · company VAT invoice with buyer MST (004) · visible + retryable failures (005) · print/share (006) · provider connection verifiable (007).

Non-Goals - declaration/filing (PRD-DCL-001) · provider integrations beyond VNPAY · invoice issuance rules per industry beyond what tax groups already define.

3. Success Metrics

Metric	Target
POS issuance	A cashier issues at payment in one action, live merchant
Failure handling	No silent failures - every failed invoice visible and retried from the screen

4. Personas & Use Cases

Cashier (issues at payment, no tax knowledge) · Owner (reviews invoices, fixes mistakes, serves company buyers) · Company buyer (needs a compliant VAT invoice with their MST).

5. User Stories

• As a cashier, I finish a payment and issue the invoice with one tap; the customer gets it immediately.
• As an owner, a buyer reports a wrong amount - I issue an adjustment invoice from the detail screen.
• As an owner, a company asks for a VAT invoice - I pick the business customer and the invoice carries their MST.

6. Functional Requirements

Delivers URD ISS URD-ISS-001…007 (Musts 001-005).

7. Non-Functional Requirements

• Issuance must not block checkout (async with visible status); retries idempotent - never double-issue for one sale.

8. UX & Flows

1. POS: payment success → "Issue invoice" (or auto per config) → status chip on the sale.
2. Client: invoice list (filter by status/period) → detail (provider number, authority code, history) → adjust/replace actions.
3. Company invoice: pick business customer at checkout/issuance → MST + company name on the invoice.

9. Data & Domain

• No new engine work expected - consumes the shipped lifecycle (INV), issuance modes (MOD) and provider ops (original/adjustment/replacement). New: the screens + the buyer-MST hand-off from customer/BIZ.

10. Dependencies & Assumptions

Dependency	Why
Business customers BIZ (July, same window)	Buyer MST on company invoices
Provider credentials per merchant (shipped config)	Issuance against VNPAY
Retail correctness (E2)	Retail merchants issue with the right tax behaviour

11. Risks & Open Questions

• The old "~80% in test" POS UI - audit what exists before rebuilding.
• Auto-issue vs ask-per-sale: default per merchant config (proposal: configurable, default ask).

12. Release Plan & Launch Criteria

July (WK27-31), alongside BIZ. Launch: AC-ISS-01 passes on a live merchant - including one company invoice with MST and one recovered failure.

13. FAQ

• Is this rebuilding the invoice engine? No - engine shipped; this is the operating surface plus the company-buyer link.

References

URD ISS · PRD-INV-001 · PRD-INV-002 · Phase 2 - By Month · Epic BANA-1318