hotfix/APPEALS-27124: Add Support for "derived" destination_type for "ro-colocated" PacMan Recipients

app/controllers/api/docs/pacman/idt-pacman-spec.yml

@@ -187,10 +187,27 @@ paths:
             schema:
               oneOf:
                 - $ref: '#/components/schemas/UploadDocumentRequestWithRecipientInformation'
+                - $ref: '#/components/schemas/UploadDocumentRequestWithRoColocatedRecipientInformation'
                 - $ref: '#/components/schemas/UploadDocumentRequest'
             examples:
               "With recipient information for Package Manager":
                 $ref: '#/components/schemas/UploadDocumentRequestWithRecipientInformation'
+              "With ro-colocated recipient information for Package Manager":
+                value:
+                  veteran_identifier: '555555555'
+                  document_type: 'BVA Decision'
+                  document_subject: 'Test'
+                  document_name: 'Test Doc'
+                  file: 'VGhpcyBpcyBhIHRlc3QuIERvIG5vdCBiZSBhbGFybWVkLgo='
+                  recipient_info:
+                   - {
+                     recipient_type: "ro-colocated",
+                     name: "POA Name",
+                     claimant_station_of_jurisdiction: "123",
+                     poa_code: "02A",
+                     destination_type: "derived",
+                     copies: 1
+                   }
               "Without recipient information for Package Manager":
                 value:
                   veteran_identifier: '555555555'
@@ -389,10 +406,27 @@ paths:
             schema:
               oneOf:
                 - $ref: '#/components/schemas/UploadDocumentRequestWithRecipientInformation'
+                - $ref: '#/components/schemas/UploadDocumentRequestWithRoColocatedRecipientInformation'
                 - $ref: '#/components/schemas/UploadDocumentRequest'
             examples:
               "With recipient information for Package Manager":
                 $ref: '#/components/schemas/UploadDocumentRequestWithRecipientInformation'
+              "With ro-colocated recipient information for Package Manager":
+                value:
+                  veteran_identifier: '555555555'
+                  document_type: 'BVA Decision'
+                  document_subject: 'Test'
+                  document_name: 'Test Doc'
+                  file: 'VGhpcyBpcyBhIHRlc3QuIERvIG5vdCBiZSBhbGFybWVkLgo='
+                  recipient_info:
+                   - {
+                     recipient_type: "ro-colocated",
+                     name: "POA Name",
+                     claimant_station_of_jurisdiction: "123",
+                     poa_code: "02A",
+                     destination_type: "derived",
+                     copies: 1
+                   }
               "Without recipient information for Package Manager":
                 value:
                   veteran_identifier: '555555555'
@@ -600,10 +634,26 @@ paths:
             schema:
               oneOf:
                 - $ref: '#/components/schemas/OutcodeRequestWithRecipientInformation'
+                - $ref: '#/components/schemas/OutcodeRequestWithRoColocatedRecipientInformation'
                 - $ref: '#/components/schemas/OutcodeRequest'
             examples:
               "With recipient information for Package Manager":
                 $ref: '#/components/schemas/OutcodeRequestWithRecipientInformation'
+              "With ro-colocated recipient information for Package Manager":
+                value:
+                  citation_number: "A19062122"
+                  decision_date: "December 21, 2022"
+                  redacted_document_location: "\\path.va.gov\\archdata$\\some-file.pdf"
+                  file: "VGVzdGluZyAxMjMK"
+                  recipient_info:
+                   - {
+                     recipient_type: "ro-colocated",
+                     name: "POA Name",
+                     claimant_station_of_jurisdiction: "123",
+                     poa_code: "02A",
+                     destination_type: "derived",
+                     copies: 1
+                   }
               "Without recipient information for Package Manager":
                 value:
                   citation_number: "A19062122"
@@ -960,6 +1010,16 @@ components:
               items:
                 type: object
                 $ref: '#/components/schemas/RecipientRequestInformation'
+    UploadDocumentRequestWithRoColocatedRecipientInformation:
+      allOf:
+        - $ref: '#/components/schemas/UploadDocumentRequest'
+        - type: object
+          properties:
+            recipient_info:
+              type: array
+              items:
+                type: object
+                $ref: '#/components/schemas/RoColocatedRecipientRequestInformation'
     UploadDocumentRequest:
       type: object
       properties:
@@ -992,6 +1052,38 @@ components:
               items:
                 type: object
                 $ref: '#/components/schemas/RecipientRequestInformation'
+    OutcodeRequestWithRoColocatedRecipientInformation:
+      allOf:
+        - $ref: '#/components/schemas/OutcodeRequest'
+        - type: object
+          properties:
+            recipient_info:
+              type: array
+              items:
+                type: object
+                $ref: '#/components/schemas/RoColocatedRecipientRequestInformation'
+    RoColocatedRecipientRequestInformation:
+      type: object
+      properties:
+        recipient_type:
+          type: string
+          example: 'ro-colocated'
+        name:
+          description: 'Required if recipient_type is organization, system, or ro-colocated. Unused for people.'
+          type: string
+          example: "POA Name"
+        claimant_station_of_jurisdiction:
+          type: string
+          description: 'Required if recipient_type is ro-colocated.'
+          example: "123"
+        postal_code:
+          type: string
+        destination_type:
+          type: string
+          example: "derived"
+        copies:
+          type: integer
+          example: 1
     RecipientRequestInformation:
       type: object
       properties:

app/validators/mail_request_validator.rb

@@ -35,6 +35,18 @@ module DistributionDestination
         validates :country_name, if: -> { destination_type == "internationalAddress" }
       end
 
+      # If destination type is derived:
+      #   - The recipient type of associated distribution must be ro-colocated
+      #   - All physical address fields must be null/blank
+      with_options if: -> { destination_type == "derived" } do
+        validate :recipient_type_ro_colocated?
+        validates(*PHYSICAL_ADDRESS_FIELDS, absence: true)
+      end
+      # And vice versa: if recipient type is ro-colocated, destination type must be derived
+      validates :destination_type,
+                inclusion: { in: ["derived"], message: "must be derived if recipient type is ro-colocated" },
+                if: -> { ro_colocated? }
+
       validates :treat_line_2_as_addressee,
                 inclusion: { in: [true], message: "cannot be false if line 3 is treated as addressee" },
                 if: -> { treat_line_3_as_addressee == true }
@@ -49,10 +61,32 @@ def physical_mail?
       %w[domesticAddress internationalAddress militaryAddress].include?(destination_type)
     end
 
+    PHYSICAL_ADDRESS_FIELDS = [
+      :address_line_1, :address_line_2, :address_line_3, :address_line_4, :address_line_5, :address_line_6,
+      :treat_line_2_as_addressee, :treat_line_3_as_addressee, :city, :state, :postal_code, :country_name,
+      :country_code
+    ].freeze
+
     def us_address?
       %w[domesticAddress militaryAddress].include?(destination_type)
     end
 
+    def ro_colocated?
+      case self
+      when MailRequest then recipient_type == "ro-colocated"
+      when VbmsDistributionDestination then vbms_distribution&.recipient_type == "ro-colocated"
+      else
+        false
+      end
+    end
+
+    def recipient_type_ro_colocated?
+      unless ro_colocated?
+        errors.add(:destination_type,
+                   "cannot be derived unless recipient type of associated distribution is ro-colocated")
+      end
+    end
+
     def valid_country_code?
       unless iso_country_codes.include?(country_code)
         errors.add(:country_code, "is not a valid ISO 3166-2 code")

db/migrate/20230731194341_make_address_line_1_nullable.rb

@@ -0,0 +1,5 @@
+class MakeAddressLine1Nullable < Caseflow::Migration
+  def change
+    change_column_null(:vbms_distribution_destinations, :address_line_1, true)
+  end
+end

db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema.define(version: 2023_06_29_184615) do
+ActiveRecord::Schema.define(version: 2023_07_31_194341) do
 
   # These are extensions that must be enabled in order to support this database
   enable_extension "plpgsql"
@@ -1809,7 +1809,7 @@
   end
 
   create_table "vbms_distribution_destinations", force: :cascade do |t|
-    t.string "address_line_1", null: false, comment: "PII. If destination_type is domestic, international, or military then Must not be null."
+    t.string "address_line_1", comment: "PII. If destination_type is domestic, international, or military then Must not be null."
     t.string "address_line_2", comment: "PII. If treatLine2AsAddressee is [true] then must not be null"
     t.string "address_line_3", comment: "PII. If treatLine3AsAddressee is [true] then must not be null"
     t.string "address_line_4", comment: "PII."

db/scripts/audit/tables/create_vbms_distribution_destinations_audit.rb

@@ -8,7 +8,7 @@
               type_of_change CHAR(1) not null,
               vbms_distribution_destinations_id bigint not null,
               destination_type varchar NOT NULL,
-              address_line_1 varchar NOT NULL,
+              address_line_1 varchar NULL,
               address_line_2 varchar NULL,
               address_line_3 varchar NULL,
               address_line_4 varchar NULL,

db/scripts/audit/tables/create_vbms_distribution_destinations_audit.sql

@@ -3,7 +3,7 @@ create table caseflow_audit.vbms_distribution_destinations_audit (
               type_of_change CHAR(1) not null,
               vbms_distribution_destinations_id bigint not null,
               destination_type varchar NOT NULL,
-              address_line_1 varchar NOT NULL,
+              address_line_1 varchar NULL,
               address_line_2 varchar NULL,
               address_line_3 varchar NULL,
               address_line_4 varchar NULL,

spec/factories/mail_request.rb

@@ -19,6 +19,24 @@
       recipient_type { nil }
     end
 
+    trait :ro_colocated_recipient do
+      recipient_type { "ro-colocated" }
+      first_name { nil }
+      last_name  { nil }
+      name { "WYOMING VETERANS COMMISSION" }
+      poa_code { "869" }
+      claimant_station_of_jurisdiction { "329" }
+      participant_id { nil }
+      destination_type { "derived" }
+      address_line_1 { nil }
+      city { nil }
+      country_code { nil }
+      postal_code { nil }
+      state { nil }
+      treat_line_2_as_addressee { nil }
+      treat_line_3_as_addressee { nil }
+    end
+
     initialize_with { new(attributes) }
   end
 end

spec/models/vbms_distribution_destination_spec.rb

@@ -116,30 +116,17 @@
   end
 
   context "destination type is militaryAddress" do
-    let(:destination) do
-      VbmsDistributionDestination.new(
-        destination_type: "militaryAddress",
-        vbms_distribution: distribution,
-        address_line_1: "address line 1",
-        city: "city",
-        state: "NY",
-        postal_code: "11385",
-        country_code: "US"
-      )
-    end
+    before { destination.destination_type = "militaryAddress" }
 
     include_examples "destination has valid attributes"
     include_examples "destination is a physical mailing address"
     include_examples "destination is a US address"
   end
 
   context "destination type is internationalAddress" do
-    let(:destination) do
-      VbmsDistributionDestination.new(
+    before do
+      destination.update(
         destination_type: "internationalAddress",
-        vbms_distribution: distribution,
-        address_line_1: "address line 1",
-        city: "city",
         country_name: "France",
         country_code: "FR"
       )
@@ -154,4 +141,47 @@
       expect(destination.errors[:country_name]).to eq(["can't be blank"])
     end
   end
+
+  context "destination type is derived" do
+    let(:destination) do
+      VbmsDistributionDestination.new(
+        destination_type: "derived",
+        vbms_distribution: distribution
+      )
+    end
+
+    before { distribution.recipient_type = "ro-colocated" }
+
+    it "the recipient_type of associated vbms_distribution must be ro-colocated" do
+      expect(destination).to be_valid
+
+      distribution.recipient_type = "person"
+      expect(destination).to_not be_valid
+
+      error_msg = destination.errors.messages[:destination_type]
+      expect(error_msg).to eq(["cannot be derived unless recipient type of associated distribution is ro-colocated"])
+    end
+
+    PHYSICAL_ADDRESS_FIELDS = [
+      :address_line_1, :address_line_2, :address_line_3, :address_line_4, :address_line_5, :address_line_6,
+      :treat_line_2_as_addressee, :treat_line_3_as_addressee, :city, :state, :postal_code, :country_name,
+      :country_code
+    ].freeze
+
+    it "physical mailing address fields must be blank" do
+      PHYSICAL_ADDRESS_FIELDS.each do |field|
+        destination[field] = "address info"
+        expect(destination).to_not be_valid
+        expect(destination.errors[field]).to eq(["must be blank"])
+      end
+    end
+
+    context "recipient_type of associated vbms_distribution is ro-colocated" do
+      it "must have a destination_type of derived" do
+        destination.destination_type = "domesticAddress"
+        expect(destination).to_not be_valid
+        expect(destination.errors[:destination_type]).to eq(["must be derived if recipient type is ro-colocated"])
+      end
+    end
+  end
 end

spec/workflows/mail_request_spec.rb

@@ -41,6 +41,20 @@
     end
   end
 
+  shared_examples "Valid mail request called upon creates desired artifacts" do
+    before do
+      RequestStore.store[:current_user] = User.system_user
+    end
+
+    it "creates a vbms_distribution" do
+      expect { subject }.to change(VbmsDistribution, :count).by(1)
+    end
+
+    it "creates a vbms_distribution_destination" do
+      expect { subject }.to change(VbmsDistributionDestination, :count).by(1)
+    end
+  end
+
   let(:mail_request_spec_object_1) { build(:mail_request, :nil_recipient_type) }
   include_examples "mail request has valid attributes"
   it "is not valid without a recipient type" do
@@ -51,17 +65,23 @@
     context "when valid parameters are passed into the mail requests initialize method." do
       subject { described_class.new(mail_request_params).call }
 
-      before do
-        RequestStore.store[:current_user] = User.system_user
-      end
+      include_examples "Valid mail request called upon creates desired artifacts"
+    end
 
-      it "creates a vbms_distribution" do
-        expect { subject }.to change(VbmsDistribution, :count).by(1)
+    context "When the recipient_type param is 'ro-colocated" do
+      let(:ro_colocated_mail_request_params) do
+        ActionController::Parameters.new(
+          recipient_type: "ro-colocated",
+          claimant_station_of_jurisdiction: "123",
+          poa_code: "02A",
+          name: "POA Name",
+          destination_type: "derived"
+        )
       end
 
-      it "creates a vbms_distribution_destination" do
-        expect { subject }.to change(VbmsDistributionDestination, :count).by(1)
-      end
+      subject { described_class.new(ro_colocated_mail_request_params).call }
+
+      include_examples "Valid mail request called upon creates desired artifacts"
     end
 
     context "when invalid parameters are passed into the mail requests initialize method." do