M2 — HIP Linking & Care-Context Flow: Test Cases

 HIP counter / CMS
   │  1. staff enters patient ABHA address
   │  2. POST /integration/abdm/link_requests/fetch_modes      → LinkService#fetch_modes
   ▼        └─► gateway  v3/link/.../auth-modes  (auth modes for the ABHA)
   │  3. POST /integration/abdm/link_requests/auth_init         → LinkService#auth_init (OTP)
   ▼        └─► gateway  sends OTP to patient's phone
   │  4. patient tells staff the OTP
   │  5. POST /integration/abdm/link_requests/auth_confirm      → LinkService#auth_confirm
   ▼        └─► gateway  validates OTP ─► on success returns link token
   │  6. token stored on integration.abdm_link_requests (link_token, valid_to)
   │  7. POST /integration/abdm/link_requests/add_contexts      → LinkService#add_contexts
   ▼        └─► gateway  hip/v3/link/carecontext   (care contexts grouped by hiType ⚠ U9)
   │  8. gateway ─► callback /webhooks/hip/on_add_contexts      → HipLinkHandler#on_add_contexts
   ▼        (acknowledgement: SUCCESS / ERRORED)
   │  9. (optional) CareContextNotifyService / SmsNotifyService → patient notified in PHR  ⚠ U10
   ▼
 DONE — patient ABHA linked, care contexts visible in PHR app

 Patient PHR app                          ABDM gateway                       Kulcare HIP
   │  search facility / scan QR   ───────►│                                   │
   │                                      │  POST /webhooks/discovery/discover│
   │                                      │ ─────────────────────────────────►│ HipDiscoveryHandler#discover
   │                                      │                                   │  ⚠ reads X-HIP-ID header (U10)
   │                                      │ ◄── on-discover  (care contexts) ─│ DiscoveryService#on_discover
   │                                      │     ⚠ needs hiType+count+matchedBy (U10)
   │  patient picks care contexts         │                                   │
   │  ──────────────────────────────────►│  POST /webhooks/discovery/link_init│
   │                                      │ ─────────────────────────────────►│ HipDiscoveryHandler#link_init
   │                                      │ ◄── on-init (linking token) ──────│
   │  patient consents                    │                                   │
   │  ──────────────────────────────────►│  POST /webhooks/discovery/link_confirm│
   │                                      │ ─────────────────────────────────►│ HipDiscoveryHandler#link_confirm
   │                                      │ ◄── on-confirm (linked contexts) ─│ DiscoveryService#on_confirm
   │                                      │     ⚠ needs hiType+count (U10)    │
   ▼  records now linked & visible in PHR │                                   │

 Encounter status → 'finished'
   │
   ▼  EnqueueCareContextLinkJob
 CareContextLinkingService
   │  • build visit-centric care contexts (U9)  • build FHIR bundle per hiType (U1–U8)
   │  • POST hip/v3/link/carecontext  (grouped by hiType, key 'hiTypes' ⚠ U9)
   ▼
 (patient already linked? yes →) CareContextNotifyService
   │  • POST hip/v3/link/context/notify  { hip:{id,name,type} ⚠ U10, REQUEST-ID ⚠ U10 }
   │  • OR SmsNotifyService  /patient/links/sms/notify2  (REQUEST-ID ⚠ U10)
   ▼
 gateway ─► patient's PHR app shows the new care contexts

-- Link requests for an ABHA (token delivered?)
SELECT id, patient_id, abha_address, status, link_token IS NOT NULL AS has_token,
       valid_to, created_at
FROM integration.abdm_link_requests
WHERE abha_address = 'simmi@sbx' ORDER BY created_at DESC;

-- Care contexts created for a patient (and their FHIR bundles — must be non-empty after U1–U8)
SELECT cc.id, cc.resource_type, cc.reference, (cc.fhir_bundle IS NOT NULL AND cc.fhir_bundle::text <> '{}') AS has_real_bundle
FROM integration.abdm_care_contexts cc
JOIN clinical.patients p ON p.id = cc.patient_id
JOIN phr.abha_profiles ap ON ap.id = p.phr_abha_profile_id
WHERE ap.abha_address = 'simmi@sbx';

-- Outbound M2 API calls + their REQUEST-ID correlation
SELECT endpoint, status_code, request_payload->>'requestId' AS req_id,
       response_payload->>'requestId' AS echoed_req_id, created_at
FROM integration.abdm_api_logs
WHERE endpoint LIKE '%/link/%' OR endpoint LIKE '%/token/%'
ORDER BY created_at DESC LIMIT 30;

# Both live add_contexts paths (must both group by hiTypes after U9)
grep -rn "hiType\|hiTypes\|add_contexts" backend/domains/integration/services/abdm/hip/*.rb

# REQUEST-ID correlation (one id = header + stored + callback lookup)
grep -rn "request_id\|REQUEST-ID\|last_notify_request_id" backend/domains/integration/services/abdm/hip/{care_context_notify,sms_notify}_service.rb

# Discovery facility source (must be X-HIP-ID after U10)
grep -rn "X-HIP-ID\|dig('hip'" backend/domains/integration/services/abdm/webhooks/hip_discovery_handler.rb

# FHIR dispatch (must cover all 8 types after U9)
grep -n "when '\|generate_fhir_bundle" backend/domains/integration/services/abdm/hip/care_context_linking_service.rb