PRD: Tax Declaration for the 1-3B Band
| Module | Tax & Invoice (CORE-10) | PRD ID | PRD-DCL-001 |
| Status | Planned | Owner | Việt Võ · Phát Nguyễn |
| Date | 2026-06-11 | Version | v0.1 (draft) |
| Packages | @nx/ledger · @nx/taxation · apps/client | URD | DCL |
| Epic | BANA-1318 | Window | Jul (core) · Aug (T-VAN e2e) |
TL;DR
A 1-3B household business files its tax inside KICKO: book S2a from real sales, PIT computed at its industry's rates, the official 01/CNKD form generated, submitted via T-VAN, tracked to authority acknowledgement. No accountant.
1. Context & Problem
The book engine is further along than the board suggests: S1a and S2a both generate from real sales with PDF/XLSX export. What's missing is everything from the book to the authority: rates are seed-hardcoded per tax group and hand-picked by the merchant (no industry mapping), form 01/CNKD doesn't exist, and the T-VAN integration is query-only - it can look things up but cannot submit. Client screens stop at viewing/downloading books.
2. Goals & Non-Goals
Goals - verify S2a on live data (URD-DCL-001) · industry → tax-rate mapping (002) · PIT computation (003) · 01/CNKD generation PDF/XML (004) · T-VAN submission + status to acknowledgement (005) · client declaration screens (006) · submission history (007).
Non-Goals - books S2b-e and the 3-50B band (Phase 3) · enterprise VAT-deduction/CIT (Phase 3) · e-invoice issuance changes (already shipped paths).
3. Success Metrics
| Metric | Target |
|---|---|
| One full tax period end-to-end | A real 1-3B merchant files and gets authority acknowledgement (Aug) |
4. Personas & Use Cases
Household-business owner (no accountant; files quarterly/monthly) · Authority (CQT) via T-VAN.
5. User Stories
- As an owner, I open the tax screen, see my S2a book, preview my 01/CNKD, and submit - done in minutes.
- As an owner, my tax rates follow my industry; I don't pick percentages by hand.
6. Functional Requirements
Delivers URD DCL URD-DCL-001…007 (Musts 001-006).
7. Non-Functional Requirements
- Filings are immutable once submitted; every submission auditable per period.
8. UX & Flows
- Tax screen: period picker → S2a review (drill to sales) → "Prepare 01/CNKD".
- Preview form (PDF) → confirm → submit via T-VAN → status chip (submitted → acknowledged).
- History: past periods with filings and statuses.
9. Data & Domain
- Reuse the working ledger pipeline (S2a fetcher + template + export).
- New: industry→rate mapping (config), PIT computation, 01/CNKD template (PDF/XML), T-VAN submit operations + status polling.
10. Dependencies & Assumptions
| Dependency | Why |
|---|---|
| T-VAN submission credentials/spec (VNPAY) | The submit leg is third-party |
| Business-type correctness (E2) | Industry drives the rate |
11. Risks & Open Questions
- T-VAN submit spec availability is the schedule risk - chase credentials in June.
- Mid-period industry change: which rate applies? (proposal: rate at period close).
12. Release Plan & Launch Criteria
Jul: rates + PIT + 01/CNKD + screens. Aug: T-VAN submit + one real period e2e. Launch: AC-DCL-01 passes with a live merchant.
13. FAQ
- Is S2a being rebuilt? No - it works; it gets verified with real data and wired into the filing flow.
References
URD DCL · Phase 2 - By Month · Epic BANA-1318 · Tax Policy