Enhance POA Request Filtering, Sorting, and Validation

- Refactored `index` method in `PowerOfAttorneyRequestsController` to improve parameter handling and validation.
- Introduced sorting support (`sorted_by`) for `PowerOfAttorneyRequest` model.
- Moved `Statuses` constants to `ParamsSchema` for centralized validation.
- Updated `ParamsSchema` to enforce allowed sort fields and default sorting behavior.
- Improved `decisioned` scope with `left_outer_joins` for better query handling.
- Added comprehensive RSpec tests for sorting, status filtering, and schema validation.
- Ensured proper handling of invalid parameters with meaningful error messages.

Author: ojbucao

modules/accredited_representative_portal/app/controllers/accredited_representative_portal/v0/power_of_attorney_requests_controller.rb

@@ -16,29 +16,32 @@ class PowerOfAttorneyRequestsController < ApplicationController
 
       # rubocop:disable Metrics/MethodLength
       def index
-        # Validate and normalize pagination parameters
-        validated_params = PowerOfAttorneyRequestService::ParamsSchema.validate_and_normalize!(params.to_unsafe_h)
-        page_params = validated_params[:page]
+        schema = PowerOfAttorneyRequestService::ParamsSchema
+        validated_params = schema.validate_and_normalize!(params.to_unsafe_h)
+        page_params = validated_params.fetch(:page, {})
+        sort_params = validated_params.fetch(:sort, {})
+        status = validated_params.fetch(:status, nil)
 
         relation = policy_scope(PowerOfAttorneyRequest)
-        status = params[:status].presence
-        relation =
-          case status
-          when Statuses::PENDING
-            pending(relation)
-          when Statuses::PROCESSED
-            processed(relation)
-          when NilClass
-            relation
-          else
-            raise ActionController::BadRequest, <<~MSG.squish
-              Invalid status parameter.
-              Must be one of (#{Statuses::ALL.join(', ')})
-            MSG
-          end
 
-        poa_requests = relation.includes(scope_includes)
-                               .paginate(page: page_params[:number], per_page: page_params[:size])
+        relation = case status
+                   when schema::Statuses::PENDING
+                     pending(relation)
+                   when schema::Statuses::PROCESSED
+                     processed(relation)
+                   when NilClass
+                     relation
+                   else
+                     raise ActionController::BadRequest, <<~MSG.squish
+                       Invalid status parameter.
+                       Must be one of (#{Statuses::ALL.join(', ')})
+                     MSG
+                   end
+
+        poa_requests = relation
+                       .then { |it| sort_params.present? ? it.sorted_by(sort_params[:by], sort_params[:order]) : it }
+                       .includes(scope_includes)
+                       .paginate(page: page_params[:number], per_page: page_params[:size])
 
         serializer = PowerOfAttorneyRequestSerializer.new(poa_requests)
         render json: {
@@ -55,13 +58,6 @@ def show
 
       private
 
-      module Statuses
-        ALL = [
-          PENDING = 'pending',
-          PROCESSED = 'processed'
-        ].freeze
-      end
-
       def pending(relation)
         relation
           .not_processed

modules/accredited_representative_portal/app/models/accredited_representative_portal/power_of_attorney_request.rb

@@ -104,11 +104,25 @@ def mark_replaced!(superseding_power_of_attorney_request)
     scope :resolved, -> { joins(:resolution) }
 
     scope :decisioned, lambda {
-      where(
-        resolution: {
-          resolving_type: PowerOfAttorneyRequestDecision.to_s
-        }
-      )
+      left_outer_joins(:resolution)
+        .where(
+          resolution: {
+            resolving_type: PowerOfAttorneyRequestDecision.to_s
+          }
+        )
+    }
+
+    scope :sorted_by, lambda { |sort_column, direction = :asc|
+      case sort_column
+      when 'created_at'
+        order(created_at: direction)
+      when 'resolved_at'
+        includes(:resolution)
+          .references(:resolution)
+          .order(Arel.sql("ar_power_of_attorney_request_resolutions.created_at #{direction} NULLS LAST"))
+      else
+        raise ArgumentError, "Invalid sort column: #{sort_column}"
+      end
     }
 
     concerning :ProcessedScopes do

modules/accredited_representative_portal/app/services/accredited_representative_portal/power_of_attorney_request_service/params_schema.rb

@@ -7,6 +7,8 @@ module ParamsSchema
       Dry::Schema.load_extensions(:json_schema)
       Dry::Schema.load_extensions(:hints)
 
+      ALLOWED_SORT_FIELDS = %w[created_at updated_at].freeze
+
       module Page
         module Size
           MIN = 10
@@ -15,6 +17,19 @@ module Size
         end
       end
 
+      module Sort
+        ALLOWED_FIELDS = %w[created_at].freeze
+        ALLOWED_ORDERS = %w[asc desc].freeze
+        DEFAULT_ORDER = 'desc'
+      end
+
+      module Statuses
+        ALL = [
+          PENDING = 'pending',
+          PROCESSED = 'processed'
+        ].freeze
+      end
+
       Schema = Dry::Schema.Params do
         optional(:page).hash do
           optional(:number).value(:integer, gteq?: 1)
@@ -24,7 +39,13 @@ module Size
             lteq?: Page::Size::MAX
           )
         end
-        # Future PR: Add filter and sort schemas
+
+        optional(:sort).hash do
+          optional(:by).value(:string, included_in?: Sort::ALLOWED_FIELDS)
+          optional(:order).value(:string, included_in?: Sort::ALLOWED_ORDERS)
+        end
+
+        optional(:status).value(:string, included_in?: Statuses::ALL)
       end
 
       class << self
@@ -46,6 +67,10 @@ def apply_defaults(validated_params)
           validated_params[:page] ||= {}
           validated_params[:page][:number] ||= 1
           validated_params[:page][:size] ||= Page::Size::DEFAULT
+
+          if validated_params[:sort].present? && validated_params[:sort][:by].present?
+            validated_params[:sort][:order] ||= Sort::DEFAULT_ORDER
+          end
         end
       end
     end

modules/accredited_representative_portal/spec/models/accredited_representative_portal/power_of_attorney_request_spec.rb

@@ -3,22 +3,109 @@
 require 'rails_helper'
 
 RSpec.describe AccreditedRepresentativePortal::PowerOfAttorneyRequest, type: :model do
-  it 'validates its form and claimant type' do
-    poa_request =
-      build(
-        :power_of_attorney_request,
-        power_of_attorney_form: build(
-          :power_of_attorney_form,
-          data: {}.to_json
-        ),
-        power_of_attorney_holder_type: 'abc'
+  describe 'associations' do
+    it 'validates its form and claimant type' do
+      poa_request =
+        build(
+          :power_of_attorney_request,
+          power_of_attorney_form: build(
+            :power_of_attorney_form,
+            data: {}.to_json
+          ),
+          power_of_attorney_holder_type: 'abc'
+        )
+
+      expect(poa_request).not_to be_valid
+      expect(poa_request.errors.full_messages).to contain_exactly(
+        'Claimant type is not included in the list',
+        'Power of attorney holder type is not included in the list',
+        'Power of attorney form data does not comply with schema'
       )
+    end
+  end
+
+  describe 'scopes' do
+    let(:time) { Time.zone.parse('2024-12-21T04:45:37.000Z') }
+
+    let(:poa_code) { 'x23' }
+
+    let(:pending1) { create(:power_of_attorney_request, created_at: time, poa_code:) }
+    let(:pending2) { create(:power_of_attorney_request, created_at: time + 1.day, poa_code:) }
+    let(:pending3) { create(:power_of_attorney_request, created_at: time + 2.days, poa_code:) }
+
+    let(:accepted_request) do
+      create(:power_of_attorney_request, :with_acceptance,
+             resolution_created_at: time,
+             created_at: time,
+             poa_code:)
+    end
+
+    let(:declined_request) do
+      create(:power_of_attorney_request, :with_declination,
+             resolution_created_at: time + 1.day,
+             created_at: time + 1.day,
+             poa_code:)
+    end
+
+    let(:expired_request) do
+      create(:power_of_attorney_request, :with_expiration,
+             resolution_created_at: time + 2.days,
+             created_at: time + 2.days,
+             poa_code:)
+    end
+
+    describe '.sorted_by' do
+      context 'using created_at column' do
+        before do
+          pending1
+          pending2
+          pending3
+        end
+
+        it 'sorts by creation date ascending' do
+          result = described_class.sorted_by('created_at', :asc)
+
+          expect(result.first).to eq(pending1)
+          expect(result.last).to eq(pending3)
+        end
+
+        it 'sorts by creation date descending' do
+          result = described_class.sorted_by('created_at', :desc)
+
+          expect(result.first).to eq(pending3)
+          expect(result.last).to eq(pending1)
+        end
+      end
+
+      context 'using resolution date' do
+        before do
+          accepted_request
+          declined_request
+          expired_request
+        end
+
+        it 'sorts by resolution date ascending' do
+          result = described_class.where.not(resolution: nil).sorted_by('resolved_at', :asc)
+
+          expect(result.first).to eq(accepted_request)
+          expect(result.second).to eq(declined_request)
+          expect(result.third).to eq(expired_request)
+        end
+
+        it 'sorts by resolution date descending' do
+          result = described_class.where.not(resolution: nil).sorted_by('resolved_at', :desc)
+
+          expect(result.first).to eq(expired_request)
+          expect(result.second).to eq(declined_request)
+          expect(result.third).to eq(accepted_request)
+        end
+      end
 
-    expect(poa_request).not_to be_valid
-    expect(poa_request.errors.full_messages).to contain_exactly(
-      'Claimant type is not included in the list',
-      'Power of attorney holder type is not included in the list',
-      'Power of attorney form data does not comply with schema'
-    )
+      context 'with invalid column' do
+        it 'raises argument error' do
+          expect { described_class.sorted_by('invalid_column') }.to raise_error(ArgumentError)
+        end
+      end
+    end
   end
 end

modules/accredited_representative_portal/spec/requests/accredited_representative_portal/v0/power_of_attorney_requests_spec.rb

@@ -69,7 +69,61 @@ def load_response_fixture(path_suffix)
         expect(parsed_response['data'].map { |p| p['id'] }).not_to include(other_poa_request.id)
       end
 
-      describe 'a variety of POA request configurations' do
+      describe 'sorting' do
+        let!(:poa_requests) do
+          [
+            create(:power_of_attorney_request, :with_veteran_claimant,
+                   created_at: time.to_time - 2.days,
+                   poa_code:),
+            create(:power_of_attorney_request, :with_veteran_claimant,
+                   created_at: time.to_time - 1.day,
+                   poa_code:),
+            create(:power_of_attorney_request, :with_veteran_claimant,
+                   created_at: time.to_time - 3.days,
+                   poa_code:)
+          ]
+        end
+
+        it 'sorts by created_at in ascending order' do
+          get('/accredited_representative_portal/v0/power_of_attorney_requests',
+              params: { sort: { by: 'created_at', order: 'asc' } })
+
+          expect(response).to have_http_status(:ok)
+
+          # check that they're sorted by created_at in ascending order
+          ids = parsed_response.to_h['data'].map { |item| item['id'] }[0..2]
+          expect(ids).to eq([poa_requests[2].id, poa_requests[0].id, poa_requests[1].id])
+        end
+
+        it 'sorts by created_at in descending order' do
+          get('/accredited_representative_portal/v0/power_of_attorney_requests',
+              params: { sort: { by: 'created_at', order: 'desc' } })
+
+          expect(response).to have_http_status(:ok)
+
+          # check that they're sorted by created_at in descending order
+          ids = parsed_response.to_h['data'].map { |item| item['id'] }[1..3]
+          expect(ids).to eq([poa_requests[1].id, poa_requests[0].id, poa_requests[2].id])
+        end
+
+        it 'returns error for invalid sort field' do
+          get('/accredited_representative_portal/v0/power_of_attorney_requests',
+              params: { sort: { by: 'invalid_field' } })
+
+          expect(response).to have_http_status(:bad_request)
+          expect(parsed_response.to_h['errors']).to include(/Invalid parameters/)
+        end
+
+        it 'returns error for invalid sort order' do
+          get('/accredited_representative_portal/v0/power_of_attorney_requests',
+              params: { sort: { by: 'created_at', order: 'invalid' } })
+
+          expect(response).to have_http_status(:bad_request)
+          expect(parsed_response.to_h['errors']).to include(/Invalid parameters/)
+        end
+      end
+
+      describe 'a variety of poa request configurations' do
         let(:poa_requests) do
           [].tap do |memo|
             memo <<