Declarations (Payroll Review)

Payroll → Statutory → Declarations (/declarations) — the reviewer's worklist for Form 12BB. Requires payroll:pii (amounts & regime drive TDS/PT). Employees file in HRMS → My Declarations (/tax/my-declarations); payroll owns the data — what is filed lands here directly and what is corrected here is what the next pay run taxes on.

Declarations — everyone and their status for the year

Worklist (/declarations)

Every payroll employee and where their declaration stands for the FY, including those who filed nothing — a reviewer's job is chasing non-filers as much as checking filers. The server sorts SUBMITTED / UNDER_REVIEW first.

Column	Meaning
Employee	employeeName + employeeCode (mono)
Department	From payroll employee
Regime	OLD / NEW (blank if never filed)
Declared	totalDeclared → money (INR, 2 decimals), blank if none
Status	DRAFT / SUBMITTED / UNDER_REVIEW / VERIFIED via STATUS_LABELS + StatusBadge

Controls:

• Search — name / code / department (client-filtered via useMemo on useDeclarationReviewList(financialYear)).
• Financial year (FY_OPTIONS = currentFinancialYear() range: last/current/next, e.g. 2024-25). Changing FY resets page to 0.
• Export CSV — identity for everyone, amounts only where a declaration exists. Fetches GET /employees/:code/tax-declarations?financialYear= per row that has declarationId; unreadable rows still export as template lines. Via exportTaxDeclarationsCsv.
• Import CSV — header amounts only (parseTaxDeclarationsCsv). No items column — the file omits line items so the server leaves proofs alone. Each row PUT /employees/:code/tax-declarations?financialYear= with TaxDeclarationRequest (header fields only). Result shows Rows / Saved / Failed + per-row failures.
• Help overlay (DECLARATION_HELP_SECTIONS) — Form 12BB particulars and required proofs.

Row click → Detail (/declarations/:employeeCode?fy=) even for non-filers (shows empty state).

Detail (/declarations/:employeeCode?fy=)

Layout: pairs, section by section — left: declared figures (Form 12BB boxes), right: proof documents. The two are separate acts.

• Header — employeeName · FY · employeeCode, breadcrumbs Payroll › Declarations › code, HelpOverlay, Back, regime select (OLD/NEW), FY FY, status badge (STATUS_LABELS/VARIANTS), tally: Declared / Approved / Documents (declaredTotal, approvedTotal filtered reviewStatus===APPROVED, X of Y decided).
• Dirty detection (JSON.stringify(form) !== toForm(server)) drives Save Override enable.
• Save Override — if reviewable (!VERIFIED && !DRAFT), calls useAdjustDeclaration (records reviewer touch); else useSaveEmployeeTaxDeclaration. Sends toPayload(form, items) where items (id+section+particulars+amount) are sent back unchanged so proof files don't orphan; verdicts are not sent — this form has no business overturning a document decision.
• Review actions:

Action	API	When
Approve	POST /tax-declarations/:id/review approved:true``	reviewable
Reject / Reopen	approved:false, comments	reviewable → SUBMITTED back to employee; VERIFIED → reopens (Reject label becomes Reopen)

Comments shown in banner (border-l-success/warning) with formatDate(reviewedAt).

Four sections (each a row of two cards)

Each row uses SECTION_ROW = declaration card + documents card, rows=2 for HRA/LTA, rows=3 for home loan and VI-A.

Left (DeclarationCard)	Right (DocumentsCard)
1. HRA — Rent paid, Landlord name, Landlord PAN/Aadhaar, Landlord address	Rent receipts → itemsIn('HRA')
2. LTA — LTA amount	Travel proofs → ('LTA')
3. Home Loan — Interest payable, Lender name/PAN/type/address	Lender certificates → ('INTEREST')
4. VI-A — 80C/80CCC/80CCD/80D + read-only Other (total of VIA_OTHER items)	Investment proofs → ('VIA_80C','VIA_80CCC','VIA_80CCD','VIA_OTHER')

• Proof cards (ProofCard): compact strip thumbnail (image/PDF) + particulars + amount + pill → View button. Image thumbnail via proofUrl when proofContentType starts image/ or IMAGE_FILE regex. Pill ITEM_STATUS_LABELS/PILL (PENDING → warning, APPROVED → success, REJECTED → danger with reviewComments tooltip). If no proofName and reviewable, shows Attach label + hidden <input file accept=ACCEPTED_PROOFS> (uploading disables).
• Overlay (DeclarationProofOverlay): opens per openItemId; actions: review(itemId, amount, status, comments), upload(file), remove(). Each returns the whole TaxDeclaration — both cards refresh off same response.
• Remarks — free text under sections.

:::tip Amounts are live The amounts on this screen are what the next pay run taxes the employee on, whatever the status — a correction here takes effect without anything else having to happen. No re-run needed just for declarations. :::