PRD: Tax Declaration for the 1-3B Band
| Module | Tax & Invoice | PRD ID | PRD-DCL-001 |
| Status | Ready to dev | FEAT | DCL · BANA-1421 |
| Epic | BANA-1318 | Plane | BANA-1565 |
| Date | 2026-06-11 | Version | v0.2 |
| Packages | @nx/ledger · @nx/taxation | URD | DCL |
| Surface | Client · Owner/Mgr | ||
| Owner | Việt Võ · Phát Nguyễn | ||
TL;DR
- Household businesses in the 1-3B revenue band file their tax inside BANA, no accountant needed.
- Book S2a already runs on real data - it aggregates revenue, VAT, and PIT by the merchant's tax group, and exports to PDF/XLSX. Tax rates are also already industry-driven, through configurable tax groups in Back Office, and PIT is already computed automatically at the moment of sale, not batched at period close.
- What's still missing: generating the 01/CNKD declaration form (PDF/XML) from the S2a numbers, and submitting via T-VAN with status tracking to authority acknowledgement. T-VAN today only supports lookups, not submission.
- Once complete, the owner opens the tax screen on the Client, reviews the period's S2a book, taps "Prepare 01/CNKD" to preview the form, confirms, submits - and tracks the status (submitted → authority acknowledged) right on that same screen.
1. Context & Problem
The book engine is further along than the board suggests: S1a and S2a both generate from real sales (not sample data), aggregated by tax group, with PDF/XLSX export. Tax rates are no longer something the merchant types by hand either - tax groups (TaxGroup/TaxGroupItem) already map industry (Distribution, Services, Manufacturing, Other) to VAT and PIT percentages, configurable through Back Office, and every completed sale already computes PIT at the moment of payment using that tax group's rate.
What's missing is everything from the book to the authority: the 01/CNKD form doesn't exist in any shape - no template, no PDF or XML generation. The T-VAN integration is lookup-only (buyer tax-ID query) - there's no submission endpoint and no tracking of the authority's response. On the Client, the owner can view and download the S2a book, but the screen stops there - no "Prepare 01/CNKD" action, no confirm-and-submit step.
This PRD specifies what's still missing: wiring the working S2a book into a complete filing flow - generate the form, confirm, submit via T-VAN, and track to authority acknowledgement - for the 1-3B revenue band.
2. Goals / Non-Goals
Goals
- Verify the S2a book renders correct revenue, VAT, and PIT for a real 1-3B merchant, period by period (already runs; needs verification against live data).
- Tax rates apply per the merchant's registered industry, through a configurable tax group - no manual percentage entry (already runs).
- PIT is computed automatically at the moment of sale using the tax group's rate, and rolls up into the period's S2a book (already runs).
- Generate the standard 01/CNKD declaration (PDF/XML) from a period's S2a numbers (new).
- Submit the declaration via T-VAN and track status to authority acknowledgement (new).
- Client tax screen: view the book → preview 01/CNKD → submit, without leaving BANA or using an outside tool.
- Submission history per period, retrievable later.
Non-Goals
- Books S2b-e (more detailed than S2a) and the 3-50B revenue band - Phase 3.
- VAT deduction / corporate income tax for enterprises (as opposed to household businesses) - Phase 3.
- Changes to the existing e-invoice issuance flow (INV, ISS) - untouched; that's per-transaction invoicing, distinct from this periodic tax filing.
- Multiple T-VAN providers beyond the current VNPAY integration.
- Unattended auto-submission - the owner always confirms the form preview before it's sent to the tax authority.
3. Success Metrics
| Metric | Target / signal |
|---|---|
| One full tax period end-to-end | A real 1-3B merchant files a declaration and receives authority acknowledgement (target: August) |
| No manual rate entry | 100% of merchants in the 1-3B band get their tax rate from the industry mapping - nobody types a percentage |
| Numbers match | Figures on the 01/CNKD form match exactly what the S2a book shows for the same period - no recomputation drift |
4. Personas & Use Cases
| Persona | Goal in this feature |
|---|---|
| Household-business owner (1-3B band, no accountant) | File tax quarterly/monthly inside BANA, without outside help |
| Tax authority (CQT) | Receive and acknowledge the declaration over the T-VAN network |
Core scenario: at period close, the owner opens the tax screen on the Client and immediately sees the S2a book already aggregating that period's real revenue, VAT, and PIT at their industry's rates. They tap "Prepare 01/CNKD", preview the form pre-filled with those numbers, confirm, and submit. The system sends it via T-VAN and shows the status right on the screen - from "submitted" to "authority acknowledged" - without leaving BANA or calling an accountant.
5. User Stories
- As an owner, I open the tax screen and immediately see the current period's S2a book, so I don't have to reconcile revenue from somewhere else.
- As an owner, tax rates apply to me automatically based on my registered industry, so I never pick a percentage by hand and can't get it wrong.
- As an owner, I preview the 01/CNKD form before submitting, so I can be sure the numbers are right before they go to the tax authority.
- As an owner, I submit the declaration inside BANA and track its status to authority acknowledgement, so I don't file manually or hire an accountant.
- As an owner, I review past periods' submission history, so I can look things up when needed.
6. Functional Requirements
| # | Requirement | Status | URD ref |
|---|---|---|---|
FR-001 | S2a book from real revenue - aggregates revenue, VAT, PIT by tax group for a period, exports PDF/XLSX | ✅ | URD-DCL-001 |
FR-002 | Industry-driven tax rates - tax groups map industry (Distribution, Services, Manufacturing, Other) to VAT/PIT %, configurable in Back Office | ✅ | URD-DCL-002 |
FR-003 | Automatic PIT computation at the moment of sale, using the tax group's rate for that transaction, rolled up into the period's S2a book | ✅ | URD-DCL-003 |
FR-004 | Generate the 01/CNKD form (PDF/XML) from a period's S2a numbers | 🚧 not built | URD-DCL-004 |
FR-005 | Submit via T-VAN and track status to authority acknowledgement | 🚧 not built - T-VAN today is lookup-only | URD-DCL-005 |
FR-006 | Client tax screen: view S2a book → preview 01/CNKD → submit | 🔶 book-viewing only | URD-DCL-006 |
FR-007 | Submission history per period | 🚧 not built - only batch-generation status exists today | URD-DCL-007 |
FR-001 - S2a book from real revenue. For a period (month/quarter), the system aggregates a merchant's real revenue, VAT, and PIT from completed orders in that period, rolled up by the tax group applied to each line item. The book exports to PDF and XLSX. This is the currently-running book engine (scheduled or on-demand generation job); this PRD doesn't rebuild it - it verifies the engine on a real 1-3B merchant.
FR-002 - Industry-driven tax rates. A tax group is a configurable rule template (via Back Office) mapping business industry to VAT % and PIT % - e.g. Distribution, Services, Manufacturing, Other, each with its own default rates. Merchants don't type a percentage; the rate follows whichever tax group matches the merchant's registered industry.
FR-003 - Automatic PIT computation. Every completed sale computes PIT right then, using the rate from the tax group applied to that transaction - not a separate calculation step at declaration time. The period's S2a book is the sum of these PIT amounts.
FR-004 - Generate the 01/CNKD form. Not built. Needs a 01/CNKD declaration template (matching the authority's required form for household businesses) that takes a period's S2a numbers and produces a PDF for preview plus an XML for T-VAN submission. Figures on the form must match exactly what the S2a book shows for the same period - no recomputation under a different formula.
FR-005 - Submit via T-VAN. Not built. The current T-VAN integration only supports tax-ID lookup; it needs a submission endpoint (sending the XML generated in FR-004) and a status-tracking mechanism - from "submitted" to the authority's "acknowledged" response, or rejection with a reason.
FR-006 - Client tax screen. The book-viewing part (table, drill-down to orders, PDF/XLSX export, trigger regeneration for a period) already exists on the Client. Still missing: a "Prepare 01/CNKD" action that opens a preview, a confirmation step, a submit button, and a status chip (submitted → acknowledged) on the same screen.
FR-007 - Submission history. Not built. Today there's only batch-generation status (processing / done / failed) for the book, not a history of filings with the tax authority. Needs a list of past periods with their submitted declarations and corresponding authority status.
6.1 Acceptance Criteria
- Open the tax screen for a 1-3B merchant, select a period with real transactions → the S2a book shows revenue, VAT, and PIT aggregated by tax group, matching the real orders in that period.
- Two merchants registered under different industries → each merchant's transactions apply the rate from their own industry's tax group, with no crossover.
- A sale completes → its PIT amount is added to the current period's PIT total immediately, with no additional action.
- From the tax screen, tap "Prepare 01/CNKD" for a period with an existing S2a book → the generated PDF/XML matches that period's numbers exactly (FR-004, not built).
- Preview the form, confirm, then submit → the declaration is sent via T-VAN; status moves to "submitted" then "authority acknowledged" once a response arrives (FR-005, not built).
- The authority rejects the declaration → the status records the rejection reason, visible right on the tax screen (FR-005, not built).
- Open the submission history → past periods appear with their submitted declarations and authority status (FR-007, not built).
7. Non-Functional Requirements
| Area | Requirement |
|---|---|
| Immutable after submission | A submitted filing record can't be edited; every status change is written to the audit trail |
| Rate correctness over time | The rate that applies is the one in effect at the moment the transaction occurred - a mid-period industry change doesn't retroactively touch already-computed transactions |
| Numeric integrity | The generated 01/CNKD form must match exactly what the S2a book shows for the same period |
| Tenancy | A merchant's book and declarations are viewable and submittable only by that merchant |
8. UX & Flows
- Tax screen: pick a period → review the S2a book (drill to orders) → "Prepare 01/CNKD" (book-viewing already exists, the rest is not built).
- Preview the form (PDF) → confirm → submit via T-VAN → status chip (submitted → acknowledged).
- History: past periods with their filings and statuses.
9. Data & Domain
| Entity | Role |
|---|---|
| S2a book | A merchant's real revenue, VAT, PIT aggregated by period and tax group (exists) |
Tax group (TaxGroup/TaxGroupItem) | Maps industry → VAT/PIT %, configurable in Back Office (exists) |
Revenue tier (TaxTier) | Maps revenue bands (0-1B, 1-3B, 3-50B, 50B+) - determines whether a merchant is in the 1-3B band (exists) |
| 01/CNKD declaration | The filing document generated from a period's S2a book - a PDF for preview, an XML for submission (new) |
| T-VAN submission record | One submission attempt: the sent declaration, status, authority response (new) |
Conceptual only - full schema lives in the developer domain model and taxation.
10. Dependencies & Assumptions
Depends on
- Ledger (@nx/ledger) - the S2a data source, book-generation job, PDF/XLSX export.
- Tax groups (@nx/taxation, GRP) - the source of industry-driven rates and per-transaction PIT.
- Retail Business Type (E2) - the merchant's correct industry/business type drives which rate applies.
- T-VAN submission credentials/spec (VNPAY) - the submit leg is third-party; needs credentials and the provider's submission API documentation.
Assumptions
- The merchant's industry and 1-3B revenue-band membership are already established before this feature is used.
- The period's S2a book has already finished generating (via the existing job) before a declaration is prepared.
11. Risks & Open Questions
| Risk / question | Mitigation / status |
|---|---|
| T-VAN submission spec/credentials not yet available | Biggest schedule risk - T-VAN today is lookup-only, no submission API; chase VNPAY early in July |
| Which rate applies on a mid-period industry change? | Already handled at the transaction level - PIT is computed using the rate in effect at the moment of sale (FR-003), no retroactive changes |
| No fully-matching preview guaranteed before submission | Mitigated by a mandatory PDF preview + confirm step before sending to the authority (FR-004, FR-006) |
12. Release Plan & Launch Criteria
| Aspect | Plan |
|---|---|
| Phase | P2 - DCL in URD DCL, targeting Jul-Aug |
| Rollout | Only merchants in the 1-3B revenue band with the tax-declaration flow enabled; no other band |
| Migration | None for the already-running parts (S2a, tax groups); new: 01/CNKD template, T-VAN submission-record table |
| Launch criteria | AC-DCL-01 passes with at least one real merchant: correct book, correct declaration, T-VAN accepts, authority acknowledges |
| Monitoring | Submission success rate, time-to-acknowledgement, retry count on T-VAN/authority rejection |
13. FAQ
Is the S2a book being rebuilt? No - it already runs on real data; it just needs verification against a live merchant and wiring into the filing flow.
Are tax rates already industry-driven? Yes - tax groups already map industry to VAT/PIT %, configurable in Back Office; merchants don't pick a percentage themselves.
So what's actually missing? The 01/CNKD form (no template or PDF/XML generation yet) and T-VAN submission (lookup-only today, no submit capability) - that's the focus of this PRD.
Which rate applies if the industry changes mid-period? The rate in effect at the moment the transaction occurred - PIT was already computed with that rate at the time of sale, so a later industry change doesn't retroactively touch it.
Which revenue band does this cover? Only the 1-3B band. The 3-50B band and books S2b-e are Phase 3.
References
URD DCL · Phase 2 - By Month · Epic BANA-1318 · Tax Policy Developer: @nx/ledger · @nx/taxation · @nx/invoice (T-VAN)