feat: Surface has_failed_stations in v2 prescriptions response meta (#27043)

* Surface has_failed_stations in v2 prescriptions response meta

PrescriptionsAdapter#parse now always returns a Hash:
  { prescriptions: Array<Prescription>, metadata: Hash }

The metadata hash includes :has_failed_stations (boolean), which is
true when VistA reports a failedStationList or Oracle Health returns
an OperationOutcome with error-severity issues.

Controller changes:
- v2 PrescriptionsController#index merges metadata into response opts
- v2 show/list_refillable_prescriptions extract [:prescriptions]
- Mobile v1 PrescriptionsController extracts [:prescriptions]

Also adds VCR cassette for VistA partial-failure scenario and
updates OpenAPI spec with has_failed_stations in PrescriptionList meta.

* Address Copilot review: align VCR placeholder and improve OpenAPI description

* Fix OpenAPI: make has_failed_stations optional, fix recently_requested type

- Remove has_failed_stations from required array since V1 endpoints
  don't include it (only V2 does)
- Change recently_requested items type from string to PrescriptionDetail
  ref to match actual response (both V1 and V2 return prescription objects)

* Split PrescriptionList schema into V1/V2-specific schemas

Replace the monolithic PrescriptionList OpenAPI schema with
version-specific definitions that accurately reflect each endpoint:

- V1PrescriptionList: includes updated_at, failed_station_list, and
  V1PrescriptionFilterCount (5 status keys)
- V2PrescriptionList: includes has_failed_stations boolean and
  V2PrescriptionFilterCount (8 status keys)
- Shared schemas: PrescriptionSortMeta, PaginationMeta, PaginationLinks
- V1 list_refillable: inline schema with updated_at, failed_station_list,
  recently_requested (array of PrescriptionDetail)
- V2 list_refillable: fixed recently_requested items type from object
  to PrescriptionDetail ref

Addresses Copilot review feedback about V1/V2 meta shape divergence.

* Split OpenAPI PrescriptionList into V1/V2 schemas; fail loud on nil body

- Replace monolithic PrescriptionList.yml with version-specific schemas:
  - V1PrescriptionList.yml: updated_at, failed_station_list, 5 filter keys
  - V2PrescriptionList.yml: has_failed_stations boolean, 8 filter keys
- Update openapi.yaml route refs to use V1/V2 schemas
- Regenerate openapi_merged.yaml via redocly bundle
- Change nil body guard from silent empty return to ArgumentError
- Update specs to expect ArgumentError on nil input

* Address review: fix misleading spec name, align VCR placeholder

* Align oracle_health_failed? with OperationOutcomeDetector::ERROR_SEVERITIES

Author: acrollet

lib/unified_health_data/adapters/prescriptions_adapter.rb

@@ -4,6 +4,7 @@
 require_relative 'oracle_health_prescription_adapter'
 require_relative 'v2_status_mapping'
 require_relative '../source_constants'
+require_relative '../operation_outcome_detector'
 
 module UnifiedHealthData
   module Adapters
@@ -16,8 +17,11 @@ def initialize(current_user = nil)
         @oracle_adapter = OracleHealthPrescriptionAdapter.new
       end
 
+      # @param body [Hash] The raw UHD response body
+      # @param current_only [Boolean] When true, excludes discontinued/expired meds older than 180 days
+      # @return [Hash] Hash with :prescriptions (Array) and :metadata (Hash) keys
       def parse(body, current_only: false)
-        return [] if body.nil?
+        raise ArgumentError, 'UHD returned an empty response body' if body.nil?
 
         prescriptions = []
 
@@ -37,7 +41,9 @@ def parse(body, current_only: false)
 
         # Apply V2 status mapping to all prescriptions when Cerner pilot flag is enabled
         # This is the single point where V2 status mapping is applied for both VistA and Oracle Health
-        apply_v2_status_mapping_if_enabled(prescriptions)
+        prescriptions = apply_v2_status_mapping_if_enabled(prescriptions)
+
+        { prescriptions:, metadata: { has_failed_stations: any_source_failed?(body) } }
       end
 
       private
@@ -126,6 +132,38 @@ def apply_v2_status_mapping_if_enabled(prescriptions)
 
         apply_v2_status_mapping_to_all(prescriptions)
       end
+
+      # Checks whether either data source reported a failure in the UHD response.
+      # VistA: failedStationList is a non-empty string (comma-separated station numbers).
+      # Oracle Health: entry array contains an OperationOutcome resource with error-severity issues.
+      def any_source_failed?(body)
+        vista_failed?(body) || oracle_health_failed?(body)
+      end
+
+      def vista_failed?(body)
+        body.dig(SourceConstants::VISTA, 'failedStationList').present?
+      end
+
+      # Defense-in-depth: today the Client raises UpstreamPartialFailure for
+      # error/fatal OperationOutcomes before the adapter runs, so this branch
+      # is not reachable. We keep it aligned with OperationOutcomeDetector's
+      # ERROR_SEVERITIES so the flag stays correct if that upstream flow changes.
+      def oracle_health_failed?(body)
+        oracle_data = body[SourceConstants::ORACLE_HEALTH]
+        return false if oracle_data.blank?
+
+        entries = oracle_data['entry']
+        return false unless entries.is_a?(Array) && entries.present?
+
+        entries.any? do |e|
+          next false unless e.dig('resource', 'resourceType') == 'OperationOutcome'
+
+          issues = e.dig('resource', 'issue')
+          issues.is_a?(Array) && issues.any? do |i|
+            OperationOutcomeDetector::ERROR_SEVERITIES.include?(i['severity'])
+          end
+        end
+      end
     end
   end
 end

lib/unified_health_data/service.rb

@@ -92,7 +92,8 @@ def get_single_condition(condition_id)
     # @param current_only [Boolean] When true, applies filtering logic to exclude:
     #   - Discontinued/expired medications older than 180 days
     #   Defaults to false to return all prescriptions without filtering
-    # @return [Array<UnifiedHealthData::Prescription>] Array of prescription objects
+    # @return [Hash] Hash with :prescriptions (Array<UnifiedHealthData::Prescription>) and
+    #   :metadata (Hash including :has_failed_stations Boolean)
     def get_prescriptions(current_only: false)
       with_monitoring do
         start_date = default_start_date
@@ -101,16 +102,16 @@ def get_prescriptions(current_only: false)
         body = response.body
 
         adapter = UnifiedHealthData::Adapters::PrescriptionsAdapter.new(@user)
-        prescriptions = adapter.parse(body, current_only:)
+        result = adapter.parse(body, current_only:)
 
         Rails.logger.info(
           message: 'UHD prescriptions retrieved',
-          total_prescriptions: prescriptions.size,
+          total_prescriptions: result[:prescriptions].size,
           current_filtering_applied: current_only,
           service: 'unified_health_data'
         )
 
-        prescriptions
+        result
       end
     end
 

modules/mobile/app/controllers/mobile/v1/prescriptions_controller.rb

@@ -86,7 +86,7 @@ def oh_transition_filter
       end
 
       def fetch_prescriptions
-        unified_health_service.get_prescriptions(current_only: true)
+        unified_health_service.get_prescriptions(current_only: true)[:prescriptions]
       end
 
       def filtered_prescriptions(list)

modules/mobile/spec/requests/mobile/v1/health/prescriptions_spec.rb

@@ -136,7 +136,7 @@
 
             before do
               allow_any_instance_of(UnifiedHealthData::Service).to receive(:get_prescriptions)
-                .and_return([rx_va, rx_non_va])
+                .and_return({ prescriptions: [rx_va, rx_non_va], metadata: { has_failed_stations: false } })
             end
 
             it 'filters out Non-VA meds and sets hasNonVaMeds meta true' do
@@ -180,7 +180,7 @@
 
             before do
               allow_any_instance_of(UnifiedHealthData::Service).to receive(:get_prescriptions)
-                .and_return([rx_va1, rx_va2])
+                .and_return({ prescriptions: [rx_va1, rx_va2], metadata: { has_failed_stations: false } })
             end
 
             it 'does not set hasNonVaMeds meta flag' do

modules/my_health/app/controllers/my_health/v2/prescriptions_controller.rb

@@ -70,7 +70,10 @@ def refill
       def index
         return unless validate_feature_flag
 
-        prescriptions = service.get_prescriptions(current_only: false).compact
+        result = service.get_prescriptions(current_only: false)
+        prescriptions = result[:prescriptions].compact
+        source_metadata = result[:metadata]
+
         recently_requested = get_recently_requested_prescriptions(prescriptions)
         raw_data = prescriptions.dup
         prescriptions = resource_data_modifications(prescriptions).compact
@@ -79,6 +82,7 @@ def index
         prescriptions, sort_metadata = apply_filters_and_sorting(prescriptions)
 
         records, options = build_response_data(prescriptions, filter_count, recently_requested, sort_metadata)
+        options[:meta] = options[:meta].merge(source_metadata)
 
         log_prescriptions_access
         render json: MyHealth::V2::PrescriptionDetailsSerializer.new(records, options)
@@ -89,7 +93,7 @@ def show
 
         raise Common::Exceptions::ParameterMissing, 'station_number' if params[:station_number].blank?
 
-        prescriptions = service.get_prescriptions(current_only: false).compact
+        prescriptions = service.get_prescriptions(current_only: false)[:prescriptions].compact
         prescription = prescriptions.find do |p|
           p.prescription_id.to_s == params[:id].to_s &&
             p.station_number.to_s == params[:station_number].to_s
@@ -103,7 +107,7 @@ def show
       def list_refillable_prescriptions
         return unless validate_feature_flag
 
-        prescriptions = service.get_prescriptions(current_only: false).compact
+        prescriptions = service.get_prescriptions(current_only: false)[:prescriptions].compact
         recently_requested = get_recently_requested_prescriptions(prescriptions)
         refillable_prescriptions = filter_data_by_refill_and_renew(prescriptions)
 

modules/my_health/docs/openapi.yaml

@@ -1870,7 +1870,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ./schemas/PrescriptionList.yml
+                $ref: ./schemas/V1PrescriptionList.yml
           description: OK
         "401":
           content:
@@ -1956,7 +1956,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ./schemas/PrescriptionList.yml
+                $ref: ./schemas/V1PrescriptionList.yml
           description: OK
         "401":
           content:
@@ -2283,7 +2283,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ./schemas/PrescriptionList.yml
+                $ref: ./schemas/V2PrescriptionList.yml
           description: OK
         "401":
           content: