From 072e6a6fd22177e243a638a1dfdd367c5377e27c Mon Sep 17 00:00:00 2001
From: Justin Edmund <justin@jedmund.com>
Date: Wed, 12 Feb 2025 02:07:58 -0800
Subject: [PATCH] Refactor Party model

- Refactors Party model
- Adds tests
- Adds documentation
---
 app/blueprints/api/v1/party_blueprint.rb |   2 +-
 app/models/party.rb                      | 384 ++++++++++++++++-----
 spec/models/party_spec.rb                | 413 ++++++++++++++++++++++-
 3 files changed, 716 insertions(+), 83 deletions(-)

diff --git a/app/blueprints/api/v1/party_blueprint.rb b/app/blueprints/api/v1/party_blueprint.rb
index 3e81bee..0dcbd2e 100644
--- a/app/blueprints/api/v1/party_blueprint.rb
+++ b/app/blueprints/api/v1/party_blueprint.rb
@@ -28,7 +28,7 @@ module Api
 
       # Metadata associations
       field :favorited do |party, options|
-        party.is_favorited(options[:current_user])
+        party.favorited?(options[:current_user])
       end
 
       # For collection views
diff --git a/app/models/party.rb b/app/models/party.rb
index 3cf372c..fb88260 100644
--- a/app/models/party.rb
+++ b/app/models/party.rb
@@ -1,7 +1,86 @@
 # frozen_string_literal: true
 
+##
+# This file defines the Party model which represents a party in the application.
+# It encapsulates the logic for managing party records including associations with
+# characters, weapons, summons, and other related models. The Party model handles
+# validations, nested attributes, preview generation, and various business logic
+# to ensure consistency and integrity of party data.
+#
+# @note The model uses ActiveRecord associations, enums, and custom validations.
+#
+# @!attribute [rw] preview_state
+#   @return [Integer] the current state of the preview, represented as an enum:
+#     - 0: pending
+#     - 1: queued
+#     - 2: in_progress
+#     - 3: generated
+#     - 4: failed
+# @!attribute [rw] element
+#   @return [Integer] the elemental type associated with the party.
+# @!attribute [rw] clear_time
+#   @return [Integer] the clear time for the party.
+# @!attribute [rw] master_level
+#   @return [Integer, nil] the master level of the party.
+# @!attribute [rw] button_count
+#   @return [Integer, nil] the button count, if applicable.
+# @!attribute [rw] chain_count
+#   @return [Integer, nil] the chain count, if applicable.
+# @!attribute [rw] turn_count
+#   @return [Integer, nil] the turn count, if applicable.
+# @!attribute [rw] ultimate_mastery
+#   @return [Integer, nil] the ultimate mastery level, if applicable.
+# @!attribute [rw] visibility
+#   @return [Integer] the visibility of the party:
+#     - 1: Public
+#     - 2: Unlisted
+#     - 3: Private
+# @!attribute [rw] shortcode
+#   @return [String] a unique shortcode for the party.
+# @!attribute [rw] edit_key
+#   @return [String] an edit key for parties without an associated user.
+#
+# @!attribute [r] source_party
+#   @return [Party, nil] the original party if this is a remix.
+# @!attribute [r] remixes
+#   @return [Array<Party>] a collection of parties remixed from this party.
+# @!attribute [r] user
+#   @return [User, nil] the user who created the party.
+# @!attribute [r] raid
+#   @return [Raid, nil] the associated raid.
+# @!attribute [r] job
+#   @return [Job, nil] the associated job.
+# @!attribute [r] accessory
+#   @return [JobAccessory, nil] the accessory used in the party.
+# @!attribute [r] skill0
+#   @return [JobSkill, nil] the primary skill.
+# @!attribute [r] skill1
+#   @return [JobSkill, nil] the secondary skill.
+# @!attribute [r] skill2
+#   @return [JobSkill, nil] the tertiary skill.
+# @!attribute [r] skill3
+#   @return [JobSkill, nil] the quaternary skill.
+# @!attribute [r] guidebook1
+#   @return [Guidebook, nil] the first guidebook.
+# @!attribute [r] guidebook2
+#   @return [Guidebook, nil] the second guidebook.
+# @!attribute [r] guidebook3
+#   @return [Guidebook, nil] the third guidebook.
+# @!attribute [r] characters
+#   @return [Array<GridCharacter>] the characters associated with this party.
+# @!attribute [r] weapons
+#   @return [Array<GridWeapon>] the weapons associated with this party.
+# @!attribute [r] summons
+#   @return [Array<GridSummon>] the summons associated with this party.
+# @!attribute [r] favorites
+#   @return [Array<Favorite>] the favorites that include this party.
 class Party < ApplicationRecord
-  ##### ActiveRecord Associations
+  include GranblueEnums
+
+  # Define preview_state as an enum.
+  enum :preview_state, { pending: 0, queued: 1, in_progress: 2, generated: 3, failed: 4 }
+
+  # ActiveRecord Associations
   belongs_to :source_party,
              class_name: 'Party',
              foreign_key: :source_party_id,
@@ -90,7 +169,7 @@ class Party < ApplicationRecord
   after_commit :update_element!, on: %i[create update]
   after_commit :update_extra!, on: %i[create update]
 
-  ##### Amoeba configuration
+  # Amoeba configuration
   amoeba do
     set weapons_count: 0
     set characters_count: 0
@@ -105,45 +184,86 @@ class Party < ApplicationRecord
     include_association :summons
   end
 
-  ##### ActiveRecord Validations
+  # ActiveRecord Validations
   validate :skills_are_unique
   validate :guidebooks_are_unique
 
-  self.enum :preview_state, {
-    pending: 0,
-    queued: 1,
-    in_progress: 2,
-    generated: 3,
-    failed: 4
-  }
+  # For element, validate numericality and inclusion using the allowed values from GranblueEnums.
+  validates :element,
+            numericality: { only_integer: true },
+            inclusion: {
+              in: GranblueEnums::ELEMENTS.values,
+              message: "must be one of #{GranblueEnums::ELEMENTS.map { |name, value| "#{value} (#{name})" }.join(', ')}"
+            },
+            allow_nil: true
+
+  validates :clear_time, numericality: { only_integer: true }
+  validates :master_level, numericality: { only_integer: true }, allow_nil: true
+  validates :button_count, numericality: { only_integer: true }, allow_nil: true
+  validates :chain_count, numericality: { only_integer: true }, allow_nil: true
+  validates :turn_count, numericality: { only_integer: true }, allow_nil: true
+  validates :ultimate_mastery, numericality: { only_integer: true }, allow_nil: true
+
+  # Validate visibility (allowed values: 1, 2, or 3).
+  validates :visibility,
+            numericality: { only_integer: true },
+            inclusion: {
+              in: [1, 2, 3],
+              message: 'must be 1 (Public), 2 (Unlisted), or 3 (Private)'
+            }
 
   after_commit :schedule_preview_generation, if: :should_generate_preview?
 
-  def is_remix
+  #########################
+  # Public API Methods
+  #########################
+
+  ##
+  # Checks if the party is a remix of another party.
+  #
+  # @return [Boolean] true if the party is a remix; false otherwise.
+  def remix?
     !source_party.nil?
   end
 
-  def remixes
-    Party.where(source_party_id: id)
-  end
-
+  ##
+  # Returns the blueprint class used for rendering the party.
+  #
+  # @return [Class] the PartyBlueprint class.
   def blueprint
     PartyBlueprint
   end
 
+  ##
+  # Determines if the party is public.
+  #
+  # @return [Boolean] true if the party is public; false otherwise.
   def public?
     visibility == 1
   end
 
+  ##
+  # Determines if the party is unlisted.
+  #
+  # @return [Boolean] true if the party is unlisted; false otherwise.
   def unlisted?
     visibility == 2
   end
 
+  ##
+  # Determines if the party is private.
+  #
+  # @return [Boolean] true if the party is private; false otherwise.
   def private?
     visibility == 3
   end
 
-  def is_favorited(user)
+  ##
+  # Checks if the party is favorited by a given user.
+  #
+  # @param user [User, nil] the user to check for favoritism.
+  # @return [Boolean] true if the party is favorited by the user; false otherwise.
+  def favorited?(user)
     return false unless user
 
     Rails.cache.fetch("party_#{id}_favorited_by_#{user.id}", expires_in: 1.hour) do
@@ -151,114 +271,216 @@ class Party < ApplicationRecord
     end
   end
 
+  ##
+  # Determines if the party meets the minimum requirements for preview generation.
+  #
+  # The party must have at least one weapon, one character, and one summon.
+  #
+  # @return [Boolean] true if the party is ready for preview; false otherwise.
   def ready_for_preview?
     return false if weapons_count < 1 # At least 1 weapon
     return false if characters_count < 1 # At least 1 character
     return false if summons_count < 1 # At least 1 summon
+
     true
   end
 
+  ##
+  # Determines whether a new preview should be generated for the party.
+  #
+  # The method checks various conditions such as preview state, expiration, and content changes.
+  #
+  # @return [Boolean] true if a preview generation should be triggered; false otherwise.
   def should_generate_preview?
     return false unless ready_for_preview?
 
-    # Always generate if no preview exists
-    return true if preview_state.nil? || preview_state == 'pending'
-
-    # Generate if failed and enough time has passed for conditions to change
-    return true if preview_state == 'failed' && preview_generated_at < 5.minutes.ago
-
-    # Generate if preview is old
-    return true if preview_state == 'generated' && preview_expired?
-
-    # Only regenerate on content changes if the last generation was > 5 minutes ago
-    # This prevents rapid regeneration during party building
-    if preview_content_changed?
-      return true if preview_generated_at.nil? || preview_generated_at < 5.minutes.ago
-    end
+    return true if preview_pending?
+    return true if preview_failed_and_stale?
+    return true if preview_generated_and_expired?
+    return true if preview_content_changed_and_stale?
 
     false
   end
 
+  ##
+  # Checks whether the current preview has expired based on a predefined expiry period.
+  #
+  # @return [Boolean] true if the preview is expired; false otherwise.
   def preview_expired?
     preview_generated_at.nil? ||
       preview_generated_at < PreviewService::Coordinator::PREVIEW_EXPIRY.ago
   end
 
+  ##
+  # Determines if the content relevant for preview generation has changed.
+  #
+  # @return [Boolean] true if any preview-relevant attributes have changed; false otherwise.
   def preview_content_changed?
     saved_changes.keys.any? { |attr| preview_relevant_attributes.include?(attr) }
   end
 
+  ##
+  # Schedules the generation of a party preview if applicable.
+  #
+  # This method updates the preview state to 'queued' and enqueues a background job
+  # to generate the preview.
+  #
+  # @return [void]
   def schedule_preview_generation
-    return if preview_state == 'queued' || preview_state == 'in_progress'
+    return if %w[queued in_progress].include?(preview_state.to_s)
 
-    update_column(:preview_state, 'queued')
+    update_column(:preview_state, self.class.preview_states[:queued])
     GeneratePartyPreviewJob.perform_later(id)
   end
 
   private
 
-  def update_element!
-    main_weapon = weapons.detect { |gw| gw.position.to_i == -1 }
-    new_element = main_weapon&.weapon&.element
-    if new_element.present? && self.element != new_element
-      update_column(:element, new_element)
+  #########################
+  # Preview Generation Helpers
+  #########################
+
+  ##
+  # Checks if the preview is pending.
+  #
+  # @return [Boolean] true if preview_state is nil or 'pending'.
+  def preview_pending?
+    preview_state.nil? || preview_state == 'pending'
+  end
+
+  ##
+  # Checks if the preview generation failed and the preview is stale.
+  #
+  # @return [Boolean] true if preview_state is 'failed' and preview_generated_at is older than 5 minutes.
+  def preview_failed_and_stale?
+    preview_state == 'failed' && preview_generated_at < 5.minutes.ago
+  end
+
+  ##
+  # Checks if the generated preview is expired.
+  #
+  # @return [Boolean] true if preview_state is 'generated' and the preview is expired.
+  def preview_generated_and_expired?
+    preview_state == 'generated' && preview_expired?
+  end
+
+  ##
+  # Checks if the preview content has changed and the preview is stale.
+  #
+  # @return [Boolean] true if the preview content has changed and preview_generated_at is nil or older than 5 minutes.
+  def preview_content_changed_and_stale?
+    preview_content_changed? && (preview_generated_at.nil? || preview_generated_at < 5.minutes.ago)
+  end
+
+  #########################
+  # Uniqueness Validation Helpers
+  #########################
+
+  ##
+  # Validates uniqueness for a given set of associations.
+  #
+  # @param associations [Array<Object, nil>] an array of associated objects.
+  # @param attribute_names [Array<Symbol>] the corresponding attribute names for each association.
+  # @param error_key [Symbol] the key for a generic error.
+  # @return [void]
+  def validate_uniqueness_of_associations(associations, attribute_names, error_key)
+    filtered = associations.compact
+    return if filtered.uniq.length == filtered.length
+
+    associations.each_with_index do |assoc, index|
+      next if assoc.nil?
+
+      errors.add(attribute_names[index], 'must be unique') if associations[0...index].include?(assoc)
     end
+    errors.add(error_key, 'must be unique')
   end
 
-  def update_extra!
-    new_extra = weapons.any? { |gw| GridWeapon::EXTRA_POSITIONS.include?(gw.position.to_i) }
-    if self.extra != new_extra
-      update_column(:extra, new_extra)
-    end
-  end
-
-  def set_shortcode
-    self.shortcode = random_string
-  end
-
-  def set_edit_key
-    return if user
-
-    self.edit_key ||= Digest::SHA1.hexdigest([Time.now, rand].join)
-  end
-
-  def random_string
-    num_chars = 6
-    o = [('a'..'z'), ('A'..'Z'), (0..9)].map(&:to_a).flatten
-    (0...num_chars).map { o[rand(o.length)] }.join
-  end
-
+  ##
+  # Validates that the selected skills are unique.
+  #
+  # @return [void]
   def skills_are_unique
-    skills = [skill0, skill1, skill2, skill3].compact
-
-    return if skills.uniq.length == skills.length
-
-    skills.each_with_index do |skill, index|
-      next if index.zero?
-
-      errors.add(:"skill#{index + 1}", 'must be unique') if skills[0...index].include?(skill)
-    end
-
-    errors.add(:job_skills, 'must be unique')
+    validate_uniqueness_of_associations([skill0, skill1, skill2, skill3],
+                                        [:skill0, :skill1, :skill2, :skill3],
+                                        :job_skills)
   end
 
+  ##
+  # Validates that the selected guidebooks are unique.
+  #
+  # @return [void]
   def guidebooks_are_unique
-    guidebooks = [guidebook1, guidebook2, guidebook3].compact
-    return if guidebooks.uniq.length == guidebooks.length
-
-    guidebooks.each_with_index do |book, index|
-      next if index.zero?
-
-      errors.add(:"guidebook#{index + 1}", 'must be unique') if guidebooks[0...index].include?(book)
-    end
-
-    errors.add(:guidebooks, 'must be unique')
+    validate_uniqueness_of_associations([guidebook1, guidebook2, guidebook3],
+                                        [:guidebook1, :guidebook2, :guidebook3],
+                                        :guidebooks)
   end
 
+  ##
+  # Provides a list of attributes that are relevant for determining if the preview content has changed.
+  #
+  # @return [Array<String>] an array of attribute names.
   def preview_relevant_attributes
     %w[
       name job_id element weapons_count characters_count summons_count
       full_auto auto_guard charge_attack clear_time
     ]
   end
+
+  #########################
+  # Miscellaneous Helpers
+  #########################
+
+  ##
+  # Updates the party's element based on its main weapon.
+  #
+  # Finds the main weapon (position -1) and updates the party's element if it differs.
+  #
+  # @return [void]
+  def update_element!
+    main_weapon = weapons.detect { |gw| gw.position.to_i == -1 }
+    new_element = main_weapon&.weapon&.element
+    update_column(:element, new_element) if new_element.present? && self.element != new_element
+  end
+
+  ##
+  # Updates the party's extra flag based on weapon positions.
+  #
+  # Sets the extra flag to true if any weapon is in an extra position, otherwise false.
+  #
+  # @return [void]
+  def update_extra!
+    new_extra = weapons.any? { |gw| GridWeapon::EXTRA_POSITIONS.include?(gw.position.to_i) }
+    update_column(:extra, new_extra) if self.extra != new_extra
+  end
+
+  ##
+  # Sets a unique shortcode for the party before creation.
+  #
+  # Generates a random string and assigns it to the shortcode attribute.
+  #
+  # @return [void]
+  def set_shortcode
+    self.shortcode = random_string
+  end
+
+  ##
+  # Sets an edit key for the party before creation if no associated user is present.
+  #
+  # The edit key is generated using a SHA1 hash based on the current time and a random value.
+  #
+  # @return [void]
+  def set_edit_key
+    return if user
+
+    self.edit_key ||= Digest::SHA1.hexdigest([Time.now, rand].join)
+  end
+
+  ##
+  # Generates a random alphanumeric string used for the party shortcode.
+  #
+  # @return [String] a random string of 6 characters.
+  def random_string
+    num_chars = 6
+    o = [('a'..'z'), ('A'..'Z'), (0..9)].map(&:to_a).flatten
+    (0...num_chars).map { o[rand(o.length)] }.join
+  end
 end
diff --git a/spec/models/party_spec.rb b/spec/models/party_spec.rb
index bb1a85b..e13d350 100644
--- a/spec/models/party_spec.rb
+++ b/spec/models/party_spec.rb
@@ -1,5 +1,416 @@
 require 'rails_helper'
+include ActiveJob::TestHelper
 
 RSpec.describe Party, type: :model do
-  pending "add some examples to (or delete) #{__FILE__}"
+  describe 'validations' do
+    context 'for element' do
+      it 'is valid when element is nil' do
+        party = build(:party, element: nil)
+        expect(party).to be_valid
+      end
+
+      it 'is valid when element is one of the allowed values' do
+        GranblueEnums::ELEMENTS.values.each do |value|
+          party = build(:party, element: value)
+          expect(party).to be_valid, "expected element #{value} to be valid"
+        end
+      end
+
+      it 'is invalid when element is not one of the allowed values' do
+        party = build(:party, element: 7)
+        expect(party).not_to be_valid
+        expect(party.errors[:element]).to include(/must be one of/)
+      end
+
+      it 'is invalid when element is not an integer' do
+        party = build(:party, element: 'fire')
+        expect(party).not_to be_valid
+        expect(party.errors[:element]).to include(/is not a number/)
+      end
+    end
+
+    context 'for master_level' do
+      it { should validate_numericality_of(:master_level).only_integer.allow_nil }
+      it 'is invalid when master_level is non-integer' do
+        party = build(:party, master_level: 'high')
+        expect(party).not_to be_valid
+        expect(party.errors[:master_level]).to include(/is not a number/)
+      end
+    end
+
+    context 'for clear_time' do
+      it { should validate_numericality_of(:clear_time).only_integer }
+      it 'is invalid when clear_time is non-integer' do
+        party = build(:party, clear_time: 'fast')
+        expect(party).not_to be_valid
+        expect(party.errors[:clear_time]).to include(/is not a number/)
+      end
+    end
+
+    context 'for button_count' do
+      it { should validate_numericality_of(:button_count).only_integer.allow_nil }
+      it 'is invalid when button_count is non-integer' do
+        party = build(:party, button_count: 'ten')
+        expect(party).not_to be_valid
+        expect(party.errors[:button_count]).to include(/is not a number/)
+      end
+    end
+
+    context 'for chain_count' do
+      it { should validate_numericality_of(:chain_count).only_integer.allow_nil }
+      it 'is invalid when chain_count is non-integer' do
+        party = build(:party, chain_count: 'two')
+        expect(party).not_to be_valid
+        expect(party.errors[:chain_count]).to include(/is not a number/)
+      end
+    end
+
+    context 'for turn_count' do
+      it { should validate_numericality_of(:turn_count).only_integer.allow_nil }
+      it 'is invalid when turn_count is non-integer' do
+        party = build(:party, turn_count: 'five')
+        expect(party).not_to be_valid
+        expect(party.errors[:turn_count]).to include(/is not a number/)
+      end
+    end
+
+    context 'for ultimate_mastery' do
+      it { should validate_numericality_of(:ultimate_mastery).only_integer.allow_nil }
+      it 'is invalid when ultimate_mastery is non-integer' do
+        party = build(:party, ultimate_mastery: 'max')
+        expect(party).not_to be_valid
+        expect(party.errors[:ultimate_mastery]).to include(/is not a number/)
+      end
+    end
+
+    context 'for visibility' do
+      it { should validate_numericality_of(:visibility).only_integer }
+      it 'is valid when visibility is one of 1, 2, or 3' do
+        [1, 2, 3].each do |value|
+          party = build(:party, visibility: value)
+          expect(party).to be_valid, "expected visibility #{value} to be valid"
+        end
+      end
+      it 'is invalid when visibility is not in [1, 2, 3]' do
+        party = build(:party, visibility: 0)
+        expect(party).not_to be_valid
+        expect(party.errors[:visibility]).to include(/must be 1 \(Public\), 2 \(Unlisted\), or 3 \(Private\)/)
+      end
+      it 'is invalid when visibility is non-integer' do
+        party = build(:party, visibility: 'public')
+        expect(party).not_to be_valid
+        expect(party.errors[:visibility]).to include(/is not a number/)
+      end
+    end
+
+    context 'for preview_state' do
+      # Since preview_state is now an enum, we test valid enum keys.
+      it 'allows valid preview_state values via enum' do
+        %w[pending queued in_progress generated failed].each do |state|
+          party = build(:party, preview_state: state)
+          expect(party).to be_valid, "expected preview_state #{state} to be valid"
+        end
+      end
+
+      it 'is invalid when preview_state is non-numeric and not a valid enum key' do
+        expect { build(:party, preview_state: 'active') }
+          .to raise_error(ArgumentError, /'active' is not a valid preview_state/)
+      end
+    end
+  end
+
+  describe '#is_remix' do
+    context 'when source_party is nil' do
+      it 'returns false' do
+        party = build(:party, source_party: nil)
+        expect(party.remix?).to be false
+      end
+    end
+
+    context 'when source_party is present' do
+      it 'returns true' do
+        parent = create(:party)
+        remix = build(:party, source_party: parent)
+        expect(remix.remix?).to be true
+      end
+    end
+  end
+
+  describe '#remixes' do
+    it 'returns all parties whose source_party_id equals the party id' do
+      parent = create(:party)
+      remix1 = create(:party, source_party: parent)
+      remix2 = create(:party, source_party: parent)
+      expect(parent.remixes.map(&:id)).to match_array([remix1.id, remix2.id])
+    end
+  end
+
+  describe 'Visibility helpers (#public?, #unlisted?, #private?)' do
+    it 'returns public? true when visibility is 1' do
+      party = build(:party, visibility: 1)
+      expect(party.public?).to be true
+      expect(party.unlisted?).to be false
+      expect(party.private?).to be false
+    end
+
+    it 'returns unlisted? true when visibility is 2' do
+      party = build(:party, visibility: 2)
+      expect(party.unlisted?).to be true
+      expect(party.public?).to be false
+      expect(party.private?).to be false
+    end
+
+    it 'returns private? true when visibility is 3' do
+      party = build(:party, visibility: 3)
+      expect(party.private?).to be true
+      expect(party.public?).to be false
+      expect(party.unlisted?).to be false
+    end
+  end
+
+  describe '#is_favorited' do
+    let(:user) { create(:user) }
+
+    it 'returns false if the passed user is nil' do
+      party = build(:party)
+      expect(party.favorited?(nil)).to be false
+    end
+
+    it 'returns true if the party is favorited by the user' do
+      party = create(:party)
+      create(:favorite, user: user, party: party)
+      Rails.cache.clear
+      expect(party.favorited?(user)).to be true
+    end
+
+    it 'returns false if the party is not favorited by the user' do
+      party = create(:party)
+      Rails.cache.clear
+      expect(party.favorited?(user)).to be false
+    end
+  end
+
+  describe '#ready_for_preview?' do
+    it 'returns false if weapons_count is less than 1' do
+      party = build(:party, weapons_count: 0, characters_count: 1, summons_count: 1)
+      expect(party.ready_for_preview?).to be false
+    end
+
+    it 'returns false if characters_count is less than 1' do
+      party = build(:party, weapons_count: 1, characters_count: 0, summons_count: 1)
+      expect(party.ready_for_preview?).to be false
+    end
+
+    it 'returns false if summons_count is less than 1' do
+      party = build(:party, weapons_count: 1, characters_count: 1, summons_count: 0)
+      expect(party.ready_for_preview?).to be false
+    end
+
+    it 'returns true when all counts are at least 1' do
+      party = build(:party, weapons_count: 1, characters_count: 1, summons_count: 1)
+      expect(party.ready_for_preview?).to be true
+    end
+  end
+
+  describe '#preview_expired?' do
+    it 'returns true if preview_generated_at is nil' do
+      party = build(:party, preview_generated_at: nil)
+      expect(party.preview_expired?).to be true
+    end
+
+    it 'returns true if preview_generated_at is older than the expiry period' do
+      expired_time = PreviewService::Coordinator::PREVIEW_EXPIRY.ago - 1.minute
+      party = build(:party, preview_generated_at: expired_time)
+      expect(party.preview_expired?).to be true
+    end
+
+    it 'returns false if preview_generated_at is recent' do
+      recent_time = Time.current - 1.hour
+      party = build(:party, preview_generated_at: recent_time)
+      expect(party.preview_expired?).to be false
+    end
+  end
+
+  describe '#preview_content_changed?' do
+    it 'returns true if saved_changes include a preview relevant attribute' do
+      party = build(:party)
+      # Stub saved_changes so that it includes a key from preview_relevant_attributes (e.g. "name")
+      allow(party).to receive(:saved_changes).and_return('name' => ['Old', 'New'])
+      expect(party.preview_content_changed?).to be true
+    end
+
+    it 'returns false if saved_changes do not include any preview relevant attributes' do
+      party = build(:party)
+      allow(party).to receive(:saved_changes).and_return('non_relevant' => ['A', 'B'])
+      expect(party.preview_content_changed?).to be false
+    end
+  end
+
+  describe '#should_generate_preview?' do
+    context 'when ready_for_preview? is false' do
+      it 'returns false regardless of preview_state' do
+        party = build(:party, weapons_count: 0, characters_count: 1, summons_count: 1, preview_state: 'pending')
+        expect(party.should_generate_preview?).to be false
+      end
+    end
+
+    context 'when preview_state is nil or pending' do
+      it 'returns true' do
+        party = build(:party, weapons_count: 1, characters_count: 1, summons_count: 1, preview_state: nil)
+        expect(party.should_generate_preview?).to be true
+        party.preview_state = 'pending'
+        expect(party.should_generate_preview?).to be true
+      end
+    end
+
+    context "when preview_state is 'failed'" do
+      it 'returns true if preview_generated_at is more than 5 minutes ago' do
+        past_time = 6.minutes.ago
+        party = build(:party, weapons_count: 1, characters_count: 1, summons_count: 1,
+                      preview_state: 'failed', preview_generated_at: past_time)
+        expect(party.should_generate_preview?).to be true
+      end
+    end
+
+    context "when preview_state is 'generated'" do
+      it 'returns true if preview is expired' do
+        expired_time = PreviewService::Coordinator::PREVIEW_EXPIRY.ago - 1.minute
+        party = build(:party, weapons_count: 1, characters_count: 1, summons_count: 1,
+                      preview_state: 'generated', preview_generated_at: expired_time)
+        expect(party.should_generate_preview?).to be true
+      end
+
+      it 'returns false if preview is recent and no content change is detected' do
+        recent_time = Time.current - 1.minute
+        party = build(:party, weapons_count: 1, characters_count: 1, summons_count: 1,
+                      preview_state: 'generated', preview_generated_at: recent_time)
+        allow(party).to receive(:saved_changes).and_return('non_relevant' => ['A', 'B'])
+        expect(party.should_generate_preview?).to be false
+      end
+
+      it 'returns true if content has changed and preview_generated_at is more than 5 minutes ago' do
+        old_time = 6.minutes.ago
+        party = build(:party, weapons_count: 1, characters_count: 1, summons_count: 1,
+                      preview_state: 'generated', preview_generated_at: old_time)
+        allow(party).to receive(:saved_changes).and_return('name' => ['Old', 'New'])
+        expect(party.should_generate_preview?).to be true
+      end
+    end
+  end
+
+  describe '#schedule_preview_generation' do
+    before(:all) do
+      ActiveJob::Base.queue_adapter = :test
+    end
+
+    it 'enqueues a GeneratePartyPreviewJob and sets preview_state to "queued" if not already queued or in_progress' do
+      # Create a party normally, then force its preview_state to "pending" (the integer value)
+      party = create(:party, weapons_count: 1, characters_count: 1, summons_count: 1)
+      party.update_column(:preview_state, Party.preview_states[:pending])
+
+      clear_enqueued_jobs
+      expect { party.schedule_preview_generation }
+        .to have_enqueued_job(GeneratePartyPreviewJob)
+              .with(party.id)
+      party.reload
+      expect(party.preview_state).to eq('queued')
+    end
+
+    it 'does nothing if preview_state is already "queued"' do
+      party = create(:party, weapons_count: 1, characters_count: 1, summons_count: 1, preview_state: 'queued')
+      clear_enqueued_jobs
+      expect { party.schedule_preview_generation }.not_to(change { enqueued_jobs.count })
+    end
+
+    it 'does nothing if preview_state is "in_progress"' do
+      party = create(:party, weapons_count: 1, characters_count: 1, summons_count: 1, preview_state: 'in_progress')
+      clear_enqueued_jobs
+      expect { party.schedule_preview_generation }.not_to(change { enqueued_jobs.count })
+    end
+  end
+
+  describe '#update_element!' do
+    it 'updates the party element if a main weapon (position -1) with a different element is present' do
+      # Create a party with element 3 (Water) initially.
+      party = create(:party, element: 3)
+      # Create a dummy weapon (using an instance double) with element 2 (Fire).
+      fire_weapon = instance_double('Weapon', element: 2)
+      # Create a dummy grid weapon with position -1 and the fire_weapon.
+      grid_weapon = instance_double('GridWeapon', position: -1, weapon: fire_weapon)
+      allow(party).to receive(:weapons).and_return([grid_weapon])
+      # Expect update_column to be called with the new element.
+      expect(party).to receive(:update_column).with(:element, 2)
+      party.send(:update_element!)
+    end
+
+    it 'does not update the party element if no main weapon is found' do
+      party = create(:party, element: 3)
+      allow(party).to receive(:weapons).and_return([])
+      expect(party).not_to receive(:update_column)
+      party.send(:update_element!)
+    end
+  end
+
+  describe '#update_extra!' do
+    it 'updates the party extra flag to true if any weapon is in an extra position' do
+      party = create(:party, extra: false)
+      grid_weapon = instance_double('GridWeapon', position: 9)
+      allow(party).to receive(:weapons).and_return([grid_weapon])
+      expect(party).to receive(:update_column).with(:extra, true)
+      party.send(:update_extra!)
+    end
+
+    it 'does not update the party extra flag if no weapon is in an extra position' do
+      party = create(:party, extra: false)
+      allow(party).to receive(:weapons).and_return([instance_double('GridWeapon', position: 0)])
+      expect(party).not_to receive(:update_column)
+      party.send(:update_extra!)
+    end
+  end
+
+  describe '#set_shortcode' do
+    it 'sets a shortcode of length 6' do
+      party = build(:party, shortcode: nil)
+      party.send(:set_shortcode)
+      expect(party.shortcode.length).to eq(6)
+    end
+  end
+
+  describe '#set_edit_key' do
+    it 'sets edit_key for an anonymous party (when user is nil)' do
+      party = build(:party, user: nil, edit_key: nil)
+      party.send(:set_edit_key)
+      expect(party.edit_key).not_to be_nil
+    end
+
+    it 'does not set edit_key when a user is present' do
+      party = build(:party, user: create(:user), edit_key: nil)
+      party.send(:set_edit_key)
+      expect(party.edit_key).to be_nil
+    end
+  end
+
+  describe '#random_string' do
+    it 'returns an alphanumeric string of length 6 by default' do
+      party = build(:party)
+      str = party.send(:random_string)
+      expect(str.length).to eq(6)
+      expect(str).to match(/\A[a-zA-Z0-9]+\z/)
+    end
+  end
+
+  describe '#preview_relevant_attributes' do
+    it 'returns an array of expected attribute names' do
+      party = build(:party)
+      expected = %w[name job_id element weapons_count characters_count summons_count full_auto auto_guard charge_attack clear_time]
+      expect(party.send(:preview_relevant_attributes)).to match_array(expected)
+    end
+  end
+
+  # Debug block: print debug info if an example fails.
+  after(:each) do |example|
+    if example.exception
+      puts "\nDEBUG [Party Model Validations]: Failed example: #{example.full_description}"
+    end
+  end
 end