Skip to content

0026 — Product HSN/GST: one authorized, verified person enters, checks and approves

Status: proposed (2026-10-20) — implemented on branch feat/single-person-product-tax (GitHub issue #103); not merged, not deployed. Supersedes ADR 0025 §2.B (tax maker ≠ checker, checker ≠ verifier) and the matching parts of ADR 0024 (a separate verification step before the invoice engine may use a rate). Nothing here switches an issuance flag on, creates a series, approves a rate or issues an invoice. The historical-backfill rule (ADR 0025 §2.A) is not changed.

Decision (the owner's, 2026-10-20)

A product's HSN/SAC and GST rate need one authorized person. The same person may

  1. enter the HSN/SAC and the GST rate in the existing Product Add/Edit page,
  2. check them against the supplier's genuine GST invoice and the applicable tax rules, and
  3. save and approve them in the same workflow.

There is no second approver, no second login, no approval queue and no mandatory supplier-invoice upload.

What changed

Before (ADR 0025) Now
Who may approve a different verified person than the maker and the last editor (by person and by account) any authorized approver role (Super Admin, Accounts Admin, GST Accountant) who has confirmed their own mobile number — including the person who entered the values
Database trg_product_tax_configs_maker_checker refused approver = maker / last editor (migration 104) migration 108 removes only those two comparisons; every other check stays
Verification a separate record by a third person, after the approval, before the engine used the rate the approval is the verification: the engine uses a configuration approved by a verified person on a written basis (repository.TaxConfigVerifiedSQL). The older product_tax_verifications record still exists and can still be added (e.g. the CA's letter) but the engine no longer waits for it
Product screen Save → wait → someone else approves Save & approve now (one request: PUT …/tax-config with approve: true and approval_basis); the plain Save and the separate Approve button still exist

What does not change (the safeguards)

  • Roles are enforced on the server. A role that may not approve (CanApprove) is refused (ErrNotAllowed) before anything is written. Save & approve checks the role, the approver's verified identity and the written basis before it writes the proposal, so a refused caller leaves nothing behind.
  • Identity. The person must have confirmed their own mobile number (a "verified person"). The maker and the last editor of the values must be verified persons too (an edit by an unverified account is an edit by nobody known). One person confirming one number once is all it takes.
  • Written basis of at least five visible characters (at most 300) is required on every approval — what the values were checked against.
  • Validation: HSN/SAC 4, 6 or 8 digits; GST rate from the supported set; a valid effective date; the classification; the I checked these values confirmation unless the values are exactly a verified recommendation. Overlapping windows are refused.
  • Audit. Every save writes CREATE/UPDATE with the previous value; every approval writes APPROVE (High) with the approved values, the basis, the maker's and approver's persons and enteredAndApprovedBySamePerson. Refusals (unverified person, unknown role) are denied rows.
  • History is immutable. An approved row's values, classification, people and basis are frozen by the database; a change is a new version with a later start date, which closes the earlier window (never deletes it). Invoices already issued are never touched.
  • Nothing is promoted automatically. A configuration approved before migration 104 (no approver principal — the Hoodie / Evoque samples) stays unusable until an approver withdraws it, the values are entered again at the same dates and one authorized, verified person approves them with a basis. The readiness check tax_configs_self_approved still blocks while such a row is in force.
  • Invoice issuance is blocked for a product with a missing, invalid or unapproved configuration (the order is held for tax review; no number is used). Automatic issuance and journal posting stay off; this ADR changes neither flag.

Residual risk, stated

The separation of duties that used to be enforced on tax values is gone by decision: one compromised or careless authorized login can now put a wrong rate into force. What remains between that and an invoice is the audit trail (who, when, previous value, basis), the immutability of history, the role and identity checks, and the owner's and the CA's after-the-fact review of the Approved by the person who entered them line in the audit. The CA's written confirmation is best attached as a verification record and in the basis text. A wrong rate that was approved but not yet used is withdrawn on the Product screen.

Historical backfill (issue #103, part 1) — unchanged, still separate

The backfill rule is not touched: an approval needs a verified person; the run needs a different verified person and a different account (SEPARATION_OF_DUTIES, IDENTITY_NOT_VERIFIED); every refusal is a denied audit row; the database guard refuses a slot without the approver's person. Two login ids are not assumed to be two people: the comparison is on the proven mobile number.

Recommendation for the owner (not implemented): keep it as it is. The simplest secure improvement, if a historical backfill is ever actually run, is for the owner to give the approval and a different named, verified person (the GST accountant or the Accounts Admin, who already hold the run role) to run it — which needs no new code. A single-Super-Admin company can run an individual old order only with an approval someone else can use, so for a one-off the owner should plan the backfill with the accountant present.

Readiness (owner decision, 2026-10-20): two-person identity enrolment must not block normal Product HSN/GST work. identity_enrolment is now BLOCKING only when nobody is verified (no tax setting can then be approved); with exactly one verified person it is a non-blocking warning saying that a historical backfill needs a second, different verified person; with two or more it passes. The backfill itself is still refused at run time unless a different verified person runs it.

Migration and rollback

108_single_person_product_tax.sql is CREATE OR REPLACE FUNCTION of the existing guard plus re-creation of the same trigger: no table, no column, no row is changed. rollback_108.sql restores migration 104's guard (approved rows stay approved; it only checks rows becoming approved). Deploy order: backend (applies 108) → account-admin portal → admin app. No data backfill; nothing becomes usable by itself.

Owner decisions still open

  1. (Decided 2026-10-20: Super Admin, Accounts Admin and GST Accountant keep tax approval; identity_enrolment no longer blocks with one verified person.)
  2. Hoodie / Evoque: when to withdraw the two pre-104 sample rows and enter the CA-confirmed values (one authorized person can do it in one step now).

"Tax Ready" means what the invoice engine means (follow-up, 2026-10-21)

The Product screen and product list used to call any approved configuration covering today TAX_READY, including a legacy approval (made before identity verification existed: the Hoodie / Evoque samples) that the invoice engine refuses. Both now ask the engine's own question (repository.TaxConfigVerifiedSQL, mirrored row by row in Go as ConfigView.Usable and pinned by a database test):

Situation Status shown
nothing configured, expired, or only future-dated Tax Setup Required
a proposal is waiting Awaiting approval
an approved row in force that the engine will use Tax Ready
an approved row in force that the engine will NOT use (legacy) and nothing waits to replace it Approval must be replaced (TAX_APPROVAL_REPLACEMENT_REQUIRED)

The product dialog says "On file but NOT used for invoices" for such a row instead of "In use today". Nothing is approved, verified or changed by this.

Credit / debit notes are protected like invoices (migration 112)

accounting.credit_debit_notes had no database guard (production verification: "NO trigger"). Migration 112 adds one: a draft is editable and deletable; once issued, the number, date, links, amounts and lines are frozen, the row is never deleted, status only moves forward (issued to adjusted_in_gstr1 or cancelled), and the table cannot be truncated. production-accounting-verify has a tax-and-notes tier (108 and 112) and now ends with RESULT: PASS | WARNING | BLOCKER.

Pre-launch test orders (migration 111, 2026-10-21)

The owner's first four orders were paid with the owner's own money through the real payment gateway, with nothing delivered and no refund asked for. They are not customer sales, and their money records stay exactly as they are. Migration 111 adds the missing middle step between "do nothing" and the all-or-nothing never-invoice mark, as records only:

  • A label (owner_funded_prelaunch_test) with the person's note. Owner, Super Admin or Accounts Admin may label an order; it is never applied automatically.
  • A separately stated financial treatment (10 to 500 characters: what it is and the advice or document it rests on). Only the owner or Super Admin may state it, once; the database refuses any rewrite. The system invents no treatment and infers none from the facts above.
  • Revoking a label (owner / Super Admin, with a reason) keeps the row; a revoked label cannot be edited, and a recorded treatment is not erased.

Compliance hold (follow-up, 2026-10-22). A live label also keeps the order out of every issuance path (automatic trigger, sweep, retry, manual issue, backfill) and out of the awaiting queues, until an authorised person revokes it; it is scoped to the labelled order ids and is not a never-invoice exclusion. Neither record touches an order, payment, refund, ledger or invoice, and neither issues, excludes, refunds or posts anything. One rule uses them: an order with a gateway payment can be marked never-invoice only after its treatment is on record (409 TREATMENT_NOT_ESTABLISHED); orders with no gateway money keep the old path. The Sales Invoices screen (Historical orders) has a "Pre-launch test orders" panel: the order, its payment status, masked gateway reference, refunds, the label, the treatment (or "pending"), who and when, and a warning before every action. Readiness shows a non-blocking prelaunch_test_orders check.

Deploy / rollback. Additive, idempotent, no data written. Deploy backend (applies 111) then the account-admin portal. To roll back, redeploy the previous backend first, then run rollback_111.sql (it drops the records, so export the table first). Verified in production by production-accounting-verify tier tax-and-notes.

To see the four orders' payment facts (read-only, no database password needed): dispatch the production-gateway-orders-report workflow. It lists each order that has a gateway payment (status, payment status, mode, amount in paise, the last six characters of the gateway reference, refund count and total, invoice and never-invoice state) from a read-only session, and says plainly that capture and settlement at the gateway are confirmed in the gateway dashboard, not in our database.