Implement return reasons model and distribution pipeline

- Add ReturnReason Ruby model with validation
- Add return reason dist serializers (JSON, TXT)
- Add return reason data serializers (YAML, localizations)
- Update Category model to load and validate return_reasons
- Update category serializers to include return_reasons field
- Integrate return reasons into generate_dist command
- Generate dist files: return_reasons.json, return_reasons.txt
- Regenerate categories.json and taxonomy.json with return_reasons

Author: ricardotejedorsanz

dev/lib/product_taxonomy.rb

@@ -24,6 +24,7 @@ def data_path = DATA_PATH
 require_relative "product_taxonomy/models/attribute"
 require_relative "product_taxonomy/models/extended_attribute"
 require_relative "product_taxonomy/models/value"
+require_relative "product_taxonomy/models/return_reason"
 require_relative "product_taxonomy/models/category"
 require_relative "product_taxonomy/models/taxonomy"
 require_relative "product_taxonomy/models/mapping_rule"
@@ -46,6 +47,13 @@ def data_path = DATA_PATH
 require_relative "product_taxonomy/models/serializers/value/data/localizations_serializer"
 require_relative "product_taxonomy/models/serializers/value/dist/json_serializer"
 require_relative "product_taxonomy/models/serializers/value/dist/txt_serializer"
+require_relative "product_taxonomy/models/serializers/return_reason/dist/json_serializer"
+require_relative "product_taxonomy/models/serializers/return_reason/dist/txt_serializer"
+require_relative "product_taxonomy/models/serializers/return_reason/data/localizations_serializer"
+require_relative "product_taxonomy/models/serializers/return_reason/data/data_serializer"
+require_relative "product_taxonomy/models/serializers/return_reason/docs/base_serializer"
+require_relative "product_taxonomy/models/serializers/return_reason/docs/reversed_serializer"
+require_relative "product_taxonomy/models/serializers/return_reason/docs/search_serializer"
 require_relative "product_taxonomy/commands/command"
 require_relative "product_taxonomy/commands/generate_dist_command"
 require_relative "product_taxonomy/commands/find_unmapped_external_categories_command"
@@ -54,9 +62,12 @@ def data_path = DATA_PATH
 require_relative "product_taxonomy/commands/dump_categories_command"
 require_relative "product_taxonomy/commands/dump_attributes_command"
 require_relative "product_taxonomy/commands/dump_values_command"
+require_relative "product_taxonomy/commands/dump_return_reasons_command"
 require_relative "product_taxonomy/commands/dump_integration_full_names_command"
 require_relative "product_taxonomy/commands/sync_en_localizations_command"
 require_relative "product_taxonomy/commands/add_category_command"
 require_relative "product_taxonomy/commands/add_attribute_command"
 require_relative "product_taxonomy/commands/add_attributes_to_categories_command"
 require_relative "product_taxonomy/commands/add_value_command"
+require_relative "product_taxonomy/commands/add_return_reason_command"
+require_relative "product_taxonomy/commands/add_return_reasons_to_categories_command"

dev/lib/product_taxonomy/commands/generate_dist_command.rb

@@ -42,7 +42,7 @@ def execute
     def generate_dist_files(locale)
       logger.info("Generating files for #{locale}")
       FileUtils.mkdir_p("#{OUTPUT_PATH}/#{locale}")
-      ["categories", "attributes", "taxonomy", "attribute_values"].each do |type|
+      ["categories", "attributes", "taxonomy", "attribute_values", "return_reasons"].each do |type|
         generate_txt_file(locale:, type:)
         generate_json_file(locale:, type:)
       end
@@ -54,6 +54,7 @@ def generate_txt_file(locale:, type:)
       when "categories" then Serializers::Category::Dist::TxtSerializer.serialize_all(version: @version, locale:)
       when "taxonomy" then return
       when "attribute_values" then Serializers::Value::Dist::TxtSerializer.serialize_all(version: @version, locale:)
+      when "return_reasons" then Serializers::ReturnReason::Dist::TxtSerializer.serialize_all(version: @version, locale:)
       end
 
       File.write("#{OUTPUT_PATH}/#{locale}/#{type}.txt", txt_data + "\n")
@@ -75,6 +76,8 @@ def generate_json_file(locale:, type:)
         @categories_json_by_locale[locale].merge(@attributes_json_by_locale[locale])
       when "attribute_values"
         Serializers::Value::Dist::JsonSerializer.serialize_all(version: @version, locale:)
+      when "return_reasons"
+        Serializers::ReturnReason::Dist::JsonSerializer.serialize_all(version: @version, locale:)
       end
 
       File.write("#{OUTPUT_PATH}/#{locale}/#{type}.json", JSON.pretty_generate(json_data) + "\n")

dev/lib/product_taxonomy/models/category.rb

@@ -22,6 +22,7 @@ def load_from_source(source_data)
             id: item["id"],
             name: item["name"],
             attributes: Array(item["attributes"]).map { Attribute.find_by(friendly_id: _1) || _1 },
+            return_reasons: Array(item["return_reasons"]).map { ReturnReason.find_by(friendly_id: _1) || _1 },
           )
         end
 
@@ -74,6 +75,7 @@ def add_children(type:, item:, parent:)
     validates :id, format: { with: /\A[a-z]{2}(-\d+)*\z/ }, on: :create
     validates :name, presence: true, on: :create
     validate :attributes_found?, on: :create
+    validate :return_reasons_found?, on: :create
     validates_with ProductTaxonomy::Indexed::UniquenessValidator, attributes: [:id], on: :create
 
     # Validations that can only be performed after the category tree has been loaded.
@@ -84,19 +86,21 @@ def add_children(type:, item:, parent:)
 
     localized_attr_reader :name, keyed_by: :id
 
-    attr_reader :id, :children, :secondary_children, :attributes
+    attr_reader :id, :children, :secondary_children, :attributes, :return_reasons
     attr_accessor :parent, :secondary_parents
 
     # @param id [String] The ID of the category.
     # @param name [String] The name of the category.
     # @param attributes [Array<Attribute>] The attributes of the category.
+    # @param return_reasons [Array<ReturnReason>] The return reasons for the category.
     # @param parent [Category] The parent category of the category.
-    def initialize(id:, name:, attributes: [], parent: nil)
+    def initialize(id:, name:, attributes: [], return_reasons: [], parent: nil)
       @id = id
       @name = name
       @children = []
       @secondary_children = []
       @attributes = attributes
+      @return_reasons = return_reasons
       @parent = parent
       @secondary_parents = []
     end
@@ -286,6 +290,18 @@ def attributes_found?
       end
     end
 
+    def return_reasons_found?
+      return_reasons&.each do |return_reason|
+        next if return_reason.is_a?(ReturnReason)
+
+        errors.add(
+          :return_reasons,
+          :not_found,
+          message: "not found for friendly ID \"#{return_reason}\"",
+        )
+      end
+    end
+
     def children_found?
       children&.each do |child|
         next if child.is_a?(Category)

dev/lib/product_taxonomy/models/return_reason.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  class ReturnReason
+    include ActiveModel::Validations
+    include FormattedValidationErrors
+    extend Localized
+    extend Indexed
+
+    class << self
+      # Load return reasons from source data. By default, this data is deserialized from a YAML file in the `data` directory.
+      #
+      # @param source_data [Array<Hash>] The source data to load return reasons from.
+      def load_from_source(source_data)
+        raise ArgumentError, "source_data must be an array" unless source_data.is_a?(Array)
+
+        source_data.each do |return_reason_data|
+          raise ArgumentError, "source_data must contain hashes" unless return_reason_data.is_a?(Hash)
+
+          return_reason = return_reason_from(return_reason_data)
+          ReturnReason.add(return_reason)
+          return_reason.validate!(:create)
+        end
+      end
+
+      # Reset all class-level state
+      def reset
+        @localizations = nil
+        @hashed_models = nil
+      end
+
+      # Get the next ID for a newly created return reason.
+      #
+      # @return [Integer] The next ID.
+      def next_id = (all.max_by(&:id)&.id || 0) + 1
+
+      private
+
+      def return_reason_from(return_reason_data)
+        ReturnReason.new(
+          id: return_reason_data["id"],
+          name: return_reason_data["name"],
+          description: return_reason_data["description"],
+          friendly_id: return_reason_data["friendly_id"],
+          handle: return_reason_data["handle"],
+        )
+      end
+    end
+
+    validates :id, presence: true, numericality: { only_integer: true }, on: :create
+    validates :name, presence: true, on: :create
+    validates :friendly_id, presence: true, on: :create
+    validates :handle, presence: true, on: :create
+    validates :description, presence: true, on: :create
+    validates_with ProductTaxonomy::Indexed::UniquenessValidator, attributes: [:friendly_id], on: :create
+
+    localized_attr_reader :name, :description
+
+    attr_reader :id, :friendly_id, :handle
+
+    # @param id [Integer] The ID of the return reason.
+    # @param name [String] The name of the return reason.
+    # @param description [String] The description of the return reason.
+    # @param friendly_id [String] The friendly ID of the return reason.
+    # @param handle [String] The handle of the return reason.
+    def initialize(id:, name:, description:, friendly_id:, handle:)
+      @id = id
+      @name = name
+      @description = description
+      @friendly_id = friendly_id
+      @handle = handle
+    end
+
+    # The global ID of the return reason
+    #
+    # @return [String]
+    def gid
+      "gid://shopify/ReturnReasonDefinition/#{id}"
+    end
+  end
+end
+

dev/lib/product_taxonomy/models/serializers/category/data/data_serializer.rb

@@ -14,11 +14,19 @@ def serialize_all(root = nil)
             # @param [Category] category
             # @return [Hash]
             def serialize(category)
+              return_reason_ids = category.return_reasons.map(&:friendly_id)
+              special_reasons = return_reason_ids.select { |r| ['unknown', 'other'].include?(r) }
+              regular_reasons = return_reason_ids.reject { |r| ['unknown', 'other'].include?(r) }
+              sorted_return_reasons = AlphanumericSorter.sort(regular_reasons) + 
+                                     (special_reasons.include?('unknown') ? ['unknown'] : []) +
+                                     (special_reasons.include?('other') ? ['other'] : [])
+              
               {
                 "id" => category.id,
                 "name" => category.name,
                 "children" => category.children.sort_by(&:id_parts).map(&:id),
                 "attributes" => AlphanumericSorter.sort(category.attributes.map(&:friendly_id), other_last: true),
+                "return_reasons" => sorted_return_reasons,
               }
             end
           end

dev/lib/product_taxonomy/models/serializers/category/dist/json_serializer.rb

@@ -38,6 +38,14 @@ def serialize(category, locale: "en")
                     "extended" => attr.is_a?(ExtendedAttribute),
                   }
                 end,
+                "return_reasons" => category.return_reasons.map do |return_reason|
+                  {
+                    "id" => return_reason.gid,
+                    "name" => return_reason.name(locale:),
+                    "handle" => return_reason.handle,
+                    "description" => return_reason.description(locale:),
+                  }
+                end,
                 "children" => category.children.map do |child|
                   {
                     "id" => child.gid,

dev/lib/product_taxonomy/models/serializers/return_reason/data/data_serializer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  module Serializers
+    module ReturnReason
+      module Data
+        module DataSerializer
+          class << self
+            def serialize_all
+              ProductTaxonomy::ReturnReason.all.sort_by(&:id).map { serialize(_1) }
+            end
+
+            # @param [ReturnReason] return_reason
+            # @return [Hash]
+            def serialize(return_reason)
+              {
+                "id" => return_reason.id,
+                "name" => return_reason.name,
+                "description" => return_reason.description,
+                "friendly_id" => return_reason.friendly_id,
+                "handle" => return_reason.handle,
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+
+
+

dev/lib/product_taxonomy/models/serializers/return_reason/data/localizations_serializer.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  module Serializers
+    module ReturnReason
+      module Data
+        class LocalizationsSerializer
+          class << self
+            # @param locale [String]
+            # @return [Hash]
+            def serialize_all(locale: "en")
+              {
+                locale => {
+                  "return_reasons" => ProductTaxonomy::ReturnReason.all.sort_by(&:friendly_id).each_with_object({}) do |return_reason, hash|
+                    hash[return_reason.friendly_id] = serialize(return_reason, locale:)
+                  end,
+                },
+              }
+            end
+
+            # @param return_reason [ReturnReason]
+            # @param locale [String]
+            # @return [Hash]
+            def serialize(return_reason, locale: "en")
+              {
+                "name" => return_reason.name(locale:),
+                "description" => return_reason.description(locale:),
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+
+
+

dev/lib/product_taxonomy/models/serializers/return_reason/dist/json_serializer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  module Serializers
+    module ReturnReason
+      module Dist
+        class JsonSerializer
+          class << self
+            def serialize_all(version:, locale: "en")
+              {
+                "version" => version,
+                "return_reasons" => ProductTaxonomy::ReturnReason.all.sort_by(&:name).map { serialize(_1, locale:) },
+              }
+            end
+
+            # @param return_reason [ReturnReason]
+            # @param locale [String] The locale to use for localized return reasons.
+            # @return [Hash]
+            def serialize(return_reason, locale: "en")
+              {
+                "id" => return_reason.gid,
+                "name" => return_reason.name(locale:),
+                "handle" => return_reason.handle,
+                "description" => return_reason.description(locale:),
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end
+

dev/lib/product_taxonomy/models/serializers/return_reason/dist/txt_serializer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  module Serializers
+    module ReturnReason
+      module Dist
+        class TxtSerializer
+          class << self
+            def serialize_all(version:, locale: "en", padding: longest_gid_length)
+              header = <<~HEADER
+                # Shopify Product Taxonomy - Return Reasons: #{version}
+                # Format: {GID} : {Return reason name}
+
+              HEADER
+
+              return_reasons_txt = ProductTaxonomy::ReturnReason
+                .all
+                .sort_by(&:name)
+                .map { serialize(_1, padding:, locale:) }
+                .join("\n")
+
+              header + return_reasons_txt
+            end
+
+            # @param return_reason [ReturnReason]
+            # @param padding [Integer] The padding to use for the GID.
+            # @param locale [String] The locale to use for localized return reasons.
+            # @return [String]
+            def serialize(return_reason, padding: 0, locale: "en")
+              "#{return_reason.gid.ljust(padding)} : #{return_reason.name(locale:)}"
+            end
+
+            private
+
+            def longest_gid_length
+              ProductTaxonomy::ReturnReason.all.map { _1.gid.length }.max || 0
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+
+
+