EP-012C: Tax & Compliance Reports
Parent Epic: EP-012 Analytics, Reporting & Night Audit Split Note: EP-012 has been split into sub-epics EP-012A, EP-012B, EP-012C, EP-012D, EP-012E. This file covers GSTR-1, GSTR-3B, regional tax management, STR export, and audit log integrity.
| Field | Value |
|---|---|
| Epic ID | EP-012C |
| Epic Name | Tax & Compliance Reports |
| Parent Epic | EP-012 Analytics, Reporting & Night Audit |
| Owner | Product — Revenue Intelligence & Operations |
| Created | 2026-03-27 |
| Last Updated | 2026-03-27 |
| Status | Partial |
| Target Release | R3 (Q2 2026) — P0 compliance deadline |
1. Business Objective
Indian hotels with turnover > ₹20 lakh/year are legally required to file GSTR-1 by the 11th of each month and GSTR-3B by the 20th. Manual filing errors attract penalties of ₹50-200/day plus interest. For a 100-room hotel doing ₹50L/month, a single filing error with wrong HSN codes can trigger a ₹5-10L tax demand. HMP must generate GST returns that pass the government portal's schema validation on first upload — zero manual correction required.
2. Audience
| Role | Interaction |
|---|---|
| Finance Manager | Generates and downloads GSTR-1, GSTR-3B; uploads to GST portal |
| Super Admin | Configures GST rates, HSN codes, GSTIN for properties |
| External CA | Downloads compliance reports for audit |
| Chain Admin | Manages state-wise GST registrations for multi-property operations |
3. Scope
3.1 In Scope
- GSTR-1 export: outward supplies JSON in GST portal upload schema (B2B, B2C, CDNR, exports)
- GSTR-3B export: summary return JSON with tax liability, ITC, and net payable
- HSN code mapping: 9963 (accommodation services), 996311-996329 (room category sub-codes), 9996 (restaurant), 9997 (laundry, spa)
- GST rate tiers: 0%, 5%, 12%, 18% based on room tariff (< ₹1,000/night: 0%, ₹1,000-₹7,500: 12%, > ₹7,500: 18%)
- IGST computation for inter-state bookings
- Regional tax management: state-specific surcharges (luxury tax, tourism levy) by property location
- Audit log with hash-chain integrity: SHA-256 chain linking for tamper-evident financial trail
- STR (Smith Travel Research) data export: occupancy, ADR, RevPAR in STR-compatible CSV format (no live feed; export only)
- Compliance dashboard: filing calendar, due-date alerts, last-filed status
3.2 Out of Scope
- Direct API submission to GST portal (portal does not offer public API; export only)
- Tally / Zoho Books push integration (EP-020)
- E-invoice IRN generation (EP-005B — handled at billing point)
- Income Tax / TDS compliance
- State-specific form 60/61 (PAN-less transactions)
4. Current Implementation Status
4.1 Backend — analytics-service
| Controller / Endpoint | Status | Notes |
|---|---|---|
GET /gst/gstr1 | Partial | Structure built; HSN code mapping not validated against schema |
GET /gst/gstr3b | Partial | Summary rows exist; ITC section incomplete |
GET /gst/hsn-summary | Built | HSN-wise taxable value and tax amounts |
GET /gst/b2b | Partial | B2B invoices with GSTIN; some records missing counterparty |
GET /gst/b2c | Partial | B2C large (> ₹2.5L) and small invoice grouping |
GET /gst/cdnr | Not Started | Credit/debit note register (for cancellation invoices) |
GET /compliance/calendar | Not Started | Filing due dates and status |
GET /auditlog | Built | Hash-chained audit log with integrity verification |
GET /auditlog/verify | Built | Verify chain integrity; returns first tampered entry if found |
GET /reports/str-export | Not Started | STR-compatible CSV export |
4.2 Dashboard — 02-hmp-web-dashboard
| Component | Status | Notes |
|---|---|---|
| GST Reports page | Partial | GSTR-1 download button exists; schema not validated |
| Compliance Calendar | Not Started | Due-date view missing |
| Audit Log Viewer | Built | Chain viewer with integrity status indicator |
5. Gap Analysis
| # | Gap | Impact | Effort | Priority |
|---|---|---|---|---|
| 1 | GSTR-1 JSON not validated against government schema (portal rejection) | High | M | P0 |
| 2 | GSTR-3B ITC section requires purchase invoice data (not yet captured) | High | L | P0 |
| 3 | CDNR (credit/debit note register) endpoint missing | High | S | P0 |
| 4 | GST rate tier logic (0/12/18% by tariff band) needs unit tests | High | S | P0 |
| 5 | Compliance calendar with due-date alerts not built | Medium | M | P1 |
| 6 | STR export format not implemented | Low | M | P3 |
6. User Stories
| Story ID | Title | Priority | Points | Sprint | Status |
|---|---|---|---|---|---|
| US-012-04 | GST GSTR-1 Report Generation | P0 | 13 | 2 | Partial |
| US-012-05 | GST GSTR-3B Summary Report | P0 | 8 | 2 | Partial |
| US-012-14 | Audit Log with Integrity Chain | P0 | 8 | 1 | Built |
| US-012C-01 | CDNR (Credit/Debit Note Register) | P0 | 5 | 3 | Not Started |
| US-012C-02 | GST Rate Tier Configuration | P0 | 5 | 2 | Partial |
| US-012C-03 | Regional Tax Management (Luxury Tax) | P1 | 5 | 4 | Not Started |
| US-012C-04 | Compliance Calendar & Due-Date Alerts | P1 | 5 | 4 | Not Started |
| US-012C-05 | STR Data Export | P3 | 8 | 6 | Not Started |
| US-012C-06 | IGST for Inter-State Bookings | P1 | 5 | 3 | Partial |
7. Detailed User Stories
US-012-04: GST GSTR-1 Report Generation
As a Finance Manager, I want to generate a GSTR-1 JSON file that I can directly upload to the GST portal without manual correction, So that the hotel files its outward supplies return on time and avoids late filing penalties.
Priority: P0 | Points: 13 | Sprint: 2 | Status: Partial
Implementation Status
GET /gst/gstr1 generates the JSON structure. However, schema validation against the government's published JSON schema has not been implemented. CDNR (credit notes) are missing from the output. B2B entries require counterparty GSTIN which is sometimes absent in historical records.
Acceptance Criteria
Scenario: Generate GSTR-1 for February 2026
Given the hotel has GSTIN "06AAACH8719R1ZH" (Haryana)
And there are 145 B2C invoices and 23 B2B invoices for February 2026
When the Finance Manager generates GSTR-1 for the period
Then the JSON output passes schema validation against the GST government schema v3.4
And B2B section includes all 23 invoices with counterparty GSTIN
And B2C section correctly groups invoices < ₹2.5L by state
And HSN summary shows: SAC 9963, taxable value INR 42,60,000, CGST INR 2,55,600, SGST INR 2,55,600
And a JSON file is available for download
Scenario: GSTR-1 with credit notes
Given 3 invoices were cancelled with credit notes issued
When GSTR-1 is generated
Then the CDNR section includes all 3 credit notes with original invoice reference
And the net taxable value is correctly reduced
US-012-05: GST GSTR-3B Summary Report
As a Finance Manager, I want to generate the GSTR-3B summary return showing total tax liability and Input Tax Credit (ITC), So that I can verify the net GST payable and submit to the portal by the 20th of the month.
Priority: P0 | Points: 8 | Sprint: 2 | Status: Partial
Implementation Status
Output tax liability rows (Table 3.1) are partially built from folio data. ITC section (Table 4) requires purchase invoice data that is not yet captured in HMP. This is a known gap.
Acceptance Criteria
Scenario: Generate GSTR-3B for February 2026
Given total outward taxable supply is INR 42,60,000 with CGST INR 2,55,600, SGST INR 2,55,600
And ITC available on purchases is INR 45,000
When Finance Manager generates GSTR-3B
Then Table 3.1 shows correct outward supply breakdown
And Table 4 shows ITC available: INR 45,000
And Net tax payable = INR 2,55,600 + INR 2,55,600 − INR 45,000 = INR 4,66,200
And the summary is exportable as PDF for CA review
US-012-14: Audit Log with Integrity Chain
As a Super Admin, I want to view a tamper-evident audit log of all financial transactions, So that any unauthorized modification to historical records is immediately detectable.
Priority: P0 | Points: 8 | Sprint: 1 | Status: Built
Implementation Status
Audit log is fully built in analytics-service. Each log entry includes a SHA-256 hash of the previous entry (chain linking). GET /auditlog/verify traverses the chain and returns the first entry where the computed hash does not match the stored hash.
Acceptance Criteria
Scenario: Audit log integrity verification passes
Given 1,247 audit log entries exist for the property
When the Super Admin runs integrity verification
Then all 1,247 hash links are valid
And the result shows "Integrity check passed: 1,247 entries verified"
Scenario: Tampered entry detected
Given an entry was modified directly in the database by bypassing the application
When the Super Admin runs integrity verification
Then the system returns: "Integrity violation at entry #823: hash mismatch"
And all subsequent entries are flagged as "chain broken after entry #823"
US-012C-03: Regional Tax Management (Luxury Tax / Tourism Levy)
As a Finance Manager, I want to configure and apply state-specific taxes (e.g., Maharashtra luxury tax, Goa tourism levy) in addition to GST, So that the hotel's invoices comply with both central and state tax regulations.
Priority: P1 | Points: 5 | Sprint: 4 | Status: Not Started
Implementation Notes
- Regional taxes vary by state: Goa (5% tourism development levy), Maharashtra (luxury tax on tariff > ₹7,500), Rajasthan (tourism development fee)
POST /gst/regional-taxes— configure per-property regional tax rules- Applied on top of GST during folio charge posting
- Shown as separate line item on invoice: "State Tourism Levy: INR 125"
- Included in GSTR-1 as "Other Taxes" (not GST)
Acceptance Criteria
Scenario: Apply Goa tourism levy
Given property "Sunrise Beach Resort, Goa" has a 5% tourism levy configured
When a room charge of INR 8,000 is posted
Then the folio shows:
- Room Charge: INR 8,000
- GST (18%): INR 1,440
- Goa Tourism Levy (5%): INR 400
- Total: INR 9,840
And the tourism levy appears as a separate line on the e-invoice
8. Dependencies
| Dependency | Type | Epic / Service | Status |
|---|---|---|---|
| Folio charges and e-invoices (GST source) | Upstream | EP-005B / frontdesk | Available |
| Property GSTIN and state configuration | Upstream | EP-002 / property | Available |
GSTIN validator (@IsGSTIN() decorator) | Internal | libs/common | Built |
| SAC code library | Internal | libs/common | Built |
| Night audit (period close for GST period) | Peer | EP-005C / frontdesk | Available |
| Purchase invoice data (for ITC in GSTR-3B) | External | Manual entry / Tally feed | Not Started |
| Auth (Finance Manager role) | Upstream | EP-001 / auth | Available |
9. Acceptance Criteria (Sub-Epic Level)
- AC-EP-012C-01: GSTR-1 JSON output passes schema validation against the GST government schema (v3.4 or current); portal acceptance rate = 100%.
- AC-EP-012C-02: GSTR-3B summary report correctly computes net tax payable (output tax − ITC) with all required table sections.
- AC-EP-012C-03: CDNR section includes all credit notes linked to original invoices with correct IRN references.
- AC-EP-012C-04: GST rate tiers (0/12/18%) are correctly applied based on room tariff per night.
- AC-EP-012C-05: Audit log hash chain is verified to be intact; any tampered entry is identified by entry ID.
- AC-EP-012C-06: Regional taxes (luxury tax, tourism levy) are calculated and shown as separate invoice line items.
10. Technical Notes
- GST controller:
01-hmp-backend/apps/analytics-service/src/gst/gst.controller.ts - Audit log controller:
01-hmp-backend/apps/analytics-service/src/auditlog/auditlog.controller.ts - GSTIN validator:
01-hmp-backend/libs/common/src/lib/gstin/— 15-digit Luhn-mod-36 position-specific validation - SAC code library:
01-hmp-backend/libs/common/src/lib/sac-codes/—getSacCodeForService()maps accommodation, restaurant, laundry etc. - GST schema: Download latest JSON schema from
https://www.gst.gov.in/download/returns— validate usingajvorzod - IGST rule: Applied when hotel state (GSTIN digits 1-2) ≠ guest company GSTIN state (for B2B); all B2C is CGST+SGST by hotel's state
- STR export format: CSV with columns: Property ID, Date, Rooms Available, Rooms Sold, Occupancy%, ADR, RevPAR — see STR Destination Report template
- Audit log Prisma model:
AuditLog { id, entryHash, previousHash, eventType, payload, createdAt }—entryHash= SHA-256 of(previousHash + eventType + payload + createdAt)