Skip to main content

Phase 1 Go-Live — Action Plan

Date: 2026-04-24 Derived from: phase1-gap-analysis Target: first property live on KeyNova via QA → Prod promotion.

TL;DR — the ask​

The 10 business flows the business team signed off on already have flow-test specs (hmp-infrastructure/testing/flow-tests/src/flows/flow-1..10-*.spec.ts). 2 flows are fully green, 7 partial, 1 effectively uncovered (Night Audit). The gap analysis found 5 cross-flow blockers plus dozens of smaller gaps.

This doc converts those findings into 3 priority tiers with concrete tasks, owners, and definition-of-done (DoD) per task.

P0 — Must fix before go-live (blockers)​

P0-1 — roomId back-sync after check-in (Q4-FINDING-001)​

Blocks: Flow 7 end-to-end (all POS room-charge attempts return 403 SAFEGUARD_BLOCKED), cascades into Flow 8's mid-stay-spend scenarios.

Tasks:

  1. Add updateRoomId(reservationId, roomId) to ReservationServiceClient in hmp-shared-packages/packages/service-clients/.
  2. Add PATCH /api/reservations/:id/room internal endpoint on reservation-service (service-account JWT gated, not @Public).
  3. Call reservationClient.updateRoomId at the end of CheckinService.checkIn() in hmp-frontdesk-service.
  4. Publish @hmp/service-clients@1.10.0; bump all services' package.json.
  5. Flip Flow 7 S1/S2 soft-skip to hard-fail assertion.

DoD: flow-7-pos-to-folio.spec.ts passes without console.warn on room-charge.

Est. effort: 4-6h (single engineer, one session).

P0-2 — Gateway routing for PATCH /api/rooms/:id/status (Q4-FINDING-002)​

Blocks: Flow 5 Sub-flow C (HK DIRTY via REST) + any dashboard UI calling the REST path.

Tasks:

  1. Register /rooms/*/status pattern → housekeeping-service in hmp-api-gateway/src/config/services.config.ts.
  2. Add matching @All('rooms/*/status') decorator to ProxyController (two-file rule).
  3. Verify via curl + gateway startup log (_RouterExplorer ... Mapped).
  4. Remove Flow 5 S3 soft-skip.

DoD: flow-5-fd-hk-updates.spec.ts Sub-flow C passes; dashboard HK status button works.

Est. effort: 2-3h.

P0-3 — Night Audit real posting + business-date advance + double-run lock (Flow 9)​

Blocks: Flow 9 — the single most operationally-critical batch. Currently describe('S3 post room charges'), describe('S4 advance business date'), describe('S6 double-run lock') are empty shells with no it blocks.

Tasks:

  1. Implement the missing code in reservation-service + frontdesk-service (ST-005-004 is in-progress — complete it):
    • Real room-charge posting when night audit runs (not dry-run)
    • Business-date advance with atomic write to property-service
    • Pessimistic lock preventing concurrent start calls (409 on second start)
  2. Add it blocks to all three describe shells in flow-9-night-audit.spec.ts:
    • S3: assert folio.totalAmount increased by exactly roomRate + GST
    • S4: assert property.businessDate advanced by +1 day
    • S6: assert HTTP 409 on second concurrent start
  3. Flip ST-005-004 status in-progress → built in registry.

DoD: flow-9-night-audit.spec.ts runs 8/8 scenarios green with hard assertions.

Est. effort: 12-18h (real product work, not just test work). If this can't ship Phase 1, explicitly scope-reduce the user-facing Flow 9 claim to "dry-run only, manual trigger" and defer real-mode to Phase 1.5.

P0-4 — Numeric correctness in Flow 10 analytics reports​

Blocks: Go-live claim that "reports show correct data" — currently shape-only assertions, so empty reports pass.

Tasks:

  1. In jest.globalSetup.ts seed:
    • 3 reservations with known sources (DIRECT, BOOKING_COM, WALKIN), known rate amounts, known nights
    • Run night audit (dry or real) to populate MVs
  2. In flow-10-reports.spec.ts add numeric assertions:
    • reports/revenue/daily: row total === sum(seeded rate amounts) ± GST
    • reports/source-wise: DIRECT count === 1, BOOKING_COM count === 1, WALKIN count === 1
    • dashboard/today: occupancy = checkedInRooms / sellableRooms
  3. Enforce SKIP_EVENT_SUBSCRIPTIONS=false for every non-gateway service in docker-compose.qa-aws.yml and docker-compose.prod-aws.yml (per CLAUDE.md gotcha).

DoD: Flow 10 fails loudly if MVs are empty; numbers match seeds.

Est. effort: 6-8h.

P0-5 — Aadhaar-at-rest masking assertion (Flow 6 Sub-flow A)​

Blocks: DPDP Act 2023 compliance. ST-004-003 + ST-005-001 AC requires Aadhaar stored masked; test only validates the input format.

Tasks:

  1. After Indian guest check-in in flow-6-check-in.spec.ts, fetch GET /api/guests/:id/identity or GET /api/folios/:id and assert persisted Aadhaar matches XXXX-XXXX-NNNN (last 4 visible).
  2. If not masked → fix in @hmp/security field-level encryption config on the Guest entity.

DoD: Flow 6 Sub-flow A asserts Aadhaar-at-rest is masked; decryption paths remain intact for eGovt DSAR access.

Est. effort: 3-4h.

P1 — Important, ship in Phase 1 if feasible​

P1-1 — Flow 2 Google Maps pin + photo upload chain (sub-items i + ii)​

Gap: UpdatePropertyDto has no latitude/longitude fields. Photo upload only tests presigned URL, not actual S3 PUT or gallery reorder.

Tasks:

  1. Add latitude: number | null + longitude: number | null to UpdatePropertyDto + Prisma Property model.
  2. In Flow 2 S1 assertions, include lat/lng.
  3. In Flow 2 S2, after presigned URL fetch: upload a small test image (1×1 PNG buffer) to the URL, then GET /properties/:id/photos and assert 1 entry. Add reorder step: PATCH /properties/:id/photos/reorder with array.
  4. Add dashboard screen test for the map-pin UI at /settings/property.

DoD: Flow 2 asserts all 7 sub-items end-to-end.

Est. effort: 8-10h (backend DTO + frontend map component + test).

P1-2 — Register POST /api/tenants/signup in API registry​

Gap: Signup endpoint has no registry entry. Drift-check won't notice if it disappears.

Tasks:

  1. Add registry/apis/AP-auth-POST-tenants-signup.yaml with path, method, auth=public, module=auth.
  2. Link to ST-001-011 or new story ST-019-001 (Tenant Management — already exists in EP-019).
  3. Add the endpoint to the Flow 1 APIs-touched list.

DoD: validate-yaml + check-cross-links clean; drift-check doesn't flag signup as unowned.

Est. effort: 30 min.

P1-3 — /allowed-transitions endpoint + gateway arrivals route (Flow 4)​

Gap: Flow 4 S2 + S3 are soft-skipped.

Tasks:

  1. Implement GET /api/reservations/:id/allowed-transitions on reservation-service, returning { next: ['CHECKED_IN', 'CANCELLED', ...] } based on current status.
  2. Register /properties/*/arrivals pattern on gateway (two-file rule) routing to frontdesk-service.
  3. Remove soft-skips from Flow 4.

DoD: Flow 4 passes all 4 scenarios without SOFT_SKIP.

Est. effort: 4-5h.

P1-4 — B2B IRN ≥ ₹50k + PDF invoice fetch + email-invoice (Flow 8)​

Gap: ST-005-002 AC requires all three; spec asserts only generic IRN generation.

Tasks:

  1. Add Flow 8 Scenario 6: book a reservation with rate > ₹50k, check in + out, assert e-invoice b2bThreshold: true and buyerGstin present.
  2. Add Flow 8 Scenario 7: GET /api/folios/:id/invoice-pdf returns 200 + Content-Type application/pdf.
  3. Add Flow 8 Scenario 8: email delivery — check notification-service outbox for invoice email to guest.

DoD: Flow 8 runs 8/8 scenarios.

Est. effort: 6-8h.

P1-5 — Room Move on CHECKED_IN reservations (Flow 5 Sub-flow A)​

Gap: Room move test currently soft-skips because test uses CONFIRMED reservation, but endpoint requires CHECKED_IN.

Tasks:

  1. In Flow 5 setup, do full Check-in before Room Move test.
  2. Ensure a second VACANT_CLEAN room exists for the target (adjust property fixture).
  3. Change Flow 5 Sub-flow A assertion from soft-skip to hard-fail.

DoD: Flow 5 Sub-flow A passes without skip.

Est. effort: 2-3h.

P2 — Defer to Phase 1.5 or Phase 2​

  • Triage 110 unsupervised frontdesk endpoints (FD-2026-04-23-020..044). Service recovery, petty cash, forex, guest portal, hardware (encoder), C-Form (advanced), sponsor, bank deposit, refund ledger, in-room dining, night-audit extras. Create owning stories OR mark "deferred to Phase 2" with triageDecision: wontfix + reason.
  • Booking engine amendment + cancellation flow (guest-facing manage-booking page). Flow 3 only tests booking; amend/cancel aren't in Phase 1 SLA.
  • Flow 3 multi-language + embed-widget + rate-parity. Phase 1 launches with English only.
  • Custom Report Builder UI testing (ST-012-008).
  • Guest 360 + preferences + loyalty automation — Phase 2 CRM wave.

Execution order​

Week 1 (Go-live sprint kickoff)
├─ Day 1-2: P0-1 (roomId sync) + P0-2 (HK gateway routing)
├─ Day 3-4: P0-3 (Night Audit real posting) + P0-5 (Aadhaar masking)
└─ Day 5:   P0-4 (Flow 10 numeric correctness)

Week 2 (Hardening)
├─ Day 1-2: P1-1 (Google Maps + photos)
├─ Day 3:   P1-2 (signup API registry) + P1-3 (allowed-transitions)
├─ Day 4:   P1-4 (B2B IRN) + P1-5 (Room move)
└─ Day 5:   Full flow-test suite pass on local → QA → sign-off

Week 3 (Go-live)
├─ Day 1:   UI screen verification (Playwright E2E on all 10 flows)
├─ Day 2:   QA freeze + exploratory smoke
├─ Day 3:   Production deploy
└─ Day 4+:  Bake period + hypercare

Total effort estimate: ~10 engineering days for P0+P1 if worked full-time in parallel by 2-3 engineers.

Acceptance criteria for "Phase 1 ready"​

  1. ✅ All 10 flow-test specs run with no console.warn soft-skips, no empty describe shells, no SKIP markers.
  2. ✅ validate-yaml + check-cross-links green on master.
  3. ✅ drift-check high-severity count === 0 (currently 0, per SP-4 first cycle).
  4. ✅ Playwright E2E smoke against local + QA passes for dashboards of: /front-desk/arrivals, /front-desk/check-in/:id, /pos/orders, /front-desk/folio/:id, /night-audit, /reports/revenue-daily.
  5. ✅ 2 Indian + 2 international reservations booked on QA via booking engine show up on dashboard with correct pricing, correct tax, correct folio.
  6. ✅ Night audit runs to completion on QA with real room-charge posting; business date advances; reports reflect the day's revenue.
  7. ✅ hmp-infrastructure/scripts/smoke-test.sh http://qa.hmphotel.com runs 13/13 green.
  8. ✅ No blocker-severity drift findings open longer than 24h.

How to track​

  • This plan + gap analysis live in docs/platform-registry/ — visible in the Docusaurus docs portal.
  • Per-task progress tracked via git commits (one commit per P0/P1 task, referencing the task ID in the message).
  • Weekly status posted as an update to the Drift Dashboard's weekly-cadence section.
  • Sign-off captured by a final commit flipping ST-005-001, ST-005-002, ST-005-004, ST-003-001, ST-007-001, ST-007-007, and ST-012-001..005 to status: built.

Commands to run the flow-tests​

# Full suite (local)
cd hmp-infrastructure/testing/flow-tests
npm ci
bash scripts/pretest-reset.sh         # reset all service DBs
npm test                               # 10 flow specs + supporting specs

# Single flow
npm test -- flow-7-pos-to-folio
npm test -- flow-9-night-audit

# Against QA (needs SSH tunnel or direct base URL)
BASE_URL=http://43.204.247.178 npm test

Commands to run UI smoke​

# Dashboard E2E (Playwright)
cd hmp-web-dashboard
npx playwright test e2e-tests/ --project=chromium

# Single flow e2e
npx playwright test e2e-tests/front-desk-checkin.spec.ts
npx playwright test e2e-tests/pos-to-folio.spec.ts