auction_fun_core 0.8.7 → 0.8.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3dc7fade29c1849f1e1c8d9a67cd060e0ceeac555290cf9cc3588a27eab72ee0
-  data.tar.gz: 7995c3ca65daa279c8e989771f7989e06695fcbdef4d7472c4f5aee0c02048f1
+  metadata.gz: a93057cdc62225a319b45c2836b5cfd713935664c8a7d9bdf2d39678909dacc7
+  data.tar.gz: 87f51a7eb83f0b47bc13394c36e37f36821a8ef5f4c429ec18e272155d9a1261
 SHA512:
-  metadata.gz: ddfa76b5f57846ed62986520b98c367f46490c6d74aebd55b45ff033f84ddfb31f95dc370afec5159b49e93bdf678b4d63437b58bcc47e63c6461b5963aa6d31
-  data.tar.gz: eddbd9f79955aed50f5ac48605a16454bb93329e3e87fb21eb8437c0af43291b0ec84f3b29099635fa7cb89cab0e4cd0cdc8cfec433b3e003d1b69a94ace1f4a
+  metadata.gz: 70b11f00396f1195ae8e7060eb8316141abbe3e3f30621d80769d94b63b4d1469695b6ca0a35a9910419e7579f047b2bd9d4f7a3ad469803cf47cb3aae4efc75
+  data.tar.gz: 520de3854f324a0e79bca1c4bfdfe69288077e208de37831b3c25cd84e75acb2664f79cf87372cee2ffb4a4a3800398b0fd72c537cb83a330b925c2d0113cdbe

data/.standard.yml

@@ -1,3 +1,5 @@
 # For available configuration options, see:
 #   https://github.com/standardrb/standard
+format: progress
+parallel: true
 ruby_version: 3.0

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 ## [Unreleased]
 
+## [0.8.9] - 2024-04-29
+
+### Added
+
+- Using yadr as a standard documentation tool;
+
+### Changed
+
+- Upgrade README;
+- Updating CI to run lint;
+- Using the heredoc standard to build SQL queries;
+
+## [0.8.8] - 2024-04-25
+
+### Added
+
+- Auction start reminder sent to participants;
+- I18n time format;
+
+### Fixed:
+
+- I18n messages for winner and auction participant emails;
+
 ## [0.8.7] - 2024-04-23
 
 ### Added

data/Procfile

@@ -2,3 +2,4 @@ database: postgres
 redis: redis-server
 mailserver: maildev --hide-extensions STARTTLS
 background: bundle exec sidekiq -r ./config/app.rb
+documentation: bundle exec yard server --reload

data/README.md

@@ -1,6 +1,6 @@
 # AuctionFunCore
 
-This lib contains all the business logic necessary to run the auctions. A principle and standard must be strictly followed: The [SRP principle](https://en.wikipedia.org/wiki/Single_responsibility_principle)The principle of single responsibility and some standard [clean architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) concepts.
+This lib contains all the business logic necessary to run the auctions. A principle and standard must be strictly followed: The [The principle of single responsibility](https://en.wikipedia.org/wiki/Single_responsibility_principle) and [clean architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) concepts.
 
 ## Installation
 
@@ -13,13 +13,13 @@ gem 'auction_fun_core'
 And then execute:
 
 ```sh
-user@host:~$ bundle install
+bundle install
 ```
 
 Or install it yourself as:
 
 ```sh
-user@host:~$ gem install auction_fun_core
+gem install auction_fun_core
 ```
 
 ## Getting Started
@@ -27,10 +27,10 @@ user@host:~$ gem install auction_fun_core
 Initially, download the project remotely and copy the templates from the project's environment variables:
 
 ```sh
-user@host:~$ git clone git@github.com:ricardopacheco/auction-fun-core.git core
-user@host:~$ cd core
-user@host:~$ cp .env.development.template .env.development
-user@host:~$ cp .env.test.template .env.test
+git clone git@github.com:ricardopacheco/auction-fun-core.git core
+cd core
+cp .env.development.template .env.development
+cp .env.test.template .env.test
 ```
 
 > As the idea of this project is to be a lib, it was decided to use a specific environment variable called `APP_ENV`, so as not to conflict with others if the lib is used by a framework.
@@ -40,7 +40,7 @@ user@host:~$ cp .env.test.template .env.test
 Configure the `.env.development` file with the values according to your machine or network.
 
 Run the commands below to create the database and its structure, remembering to replace
-the `userdb` by the user of your postgresql service. By default, if `APP_ENV` is not provided
+the `postgres` by the user of your postgresql service. By default, if `APP_ENV` is not provided
 is considered the value `development` by default.
 
 ### OS dependencies
@@ -52,50 +52,50 @@ is considered the value `development` by default.
 #### Database (PostgreSQL)
 
 ```sh
-    user@host:~$ sudo apt install build-essential libssl-dev libreadline-dev zlib1g-dev libcurl4-openssl-dev uuid-dev
-    user@host:~$ asdf plugin add postgres
-    user@host:~$ asdf install postgres 16.1
-    user@host:~$ rm -rf $HOME/.asdf/installs/postgres/16.1/data
-    user@host:~$ initdb -D $HOME/.asdf/installs/postgres/16.1/data -U postgres
+sudo apt install build-essential libssl-dev libreadline-dev zlib1g-dev libcurl4-openssl-dev uuid-dev
+asdf plugin add postgres
+asdf install postgres 16.1
+rm -rf $HOME/.asdf/installs/postgres/16.1/data
+initdb -D $HOME/.asdf/installs/postgres/16.1/data -U postgres
 ```
 
 ```sh
-    user@host:~$ sudo apt install autoconf patch build-essential rustc libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libgmp-dev libncurses5-dev libffi-dev libgdbm6 libgdbm-dev libdb-dev uuid-dev
-    user@host:~$ asdf plugin add ruby
-    user@host:~$ asdf install ruby 3.3.0
-    user@host:~$ gem install pg -v 1.5.5 --verbose -- --with-pg-config=$HOME/.asdf/installs/postgres/16.1/bin/pg_config # Fix pg_config
-    user@host:~$ bin/setup
+sudo apt install autoconf patch build-essential rustc libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libgmp-dev libncurses5-dev libffi-dev libgdbm6 libgdbm-dev libdb-dev uuid-dev
+asdf plugin add ruby
+asdf install ruby 3.3.0
+gem install pg -v 1.5.5 --verbose -- --with-pg-config=$HOME/.asdf/installs/postgres/16.1/bin/pg_config # Fix pg_config
+bin/setup
 ```
 
 #### Overmind (Procfile manager)
 
 ```sh
-    user@host:~$ asdf install golang latest
-    user@host:~$ go install github.com/DarthSim/overmind/v2
-    user@host:~$ asdf reshim
+asdf install golang latest
+go install github.com/DarthSim/overmind/v2
+asdf reshim
 ```
 
 #### Create database for development environment
 
-> **[postgres]** in rake commands is a name of user for postgres. Change if needed
+- **postgres** in rake commands is a name of user for postgres. Change if needed
 
 In current tab:
 
 ```sh
-user@host:~$ overmind s -l database
+overmind s -l database
 ```
 
 Open a new tab and create development database:
 
 ```sh
-user@host:~$ bundle exec rake 'auction_fun_core:db:create_database[postgres]'
-user@host:~$ bundle exec rake 'auction_fun_core:db:migrate'
+bundle exec rake 'auction_fun_core:db:create_database[postgres]'
+bundle exec rake 'auction_fun_core:db:migrate'
 ```
 
 Now come back to overmind tab, kill the current database process using **Ctrl+c**. After that:
 
 ```sh
-user@host:~$ overmind start
+overmind start
 ```
 
 This will start all required services needed to run core application.
@@ -103,7 +103,7 @@ This will start all required services needed to run core application.
 In new tab, you could run seed data for development with
 
 ```sh
-user@host:~$  bundle exec rake 'auction_fun_core:db:seed'
+bundle exec rake 'auction_fun_core:db:seed'
 ```
 
 ## Interactive prompt
@@ -117,9 +117,9 @@ Configure the `.env.test` file with the values according to your machine or netw
 Run the test suite with the coverage report using the command:
 
 ```sh
-user@host:~$ APP_ENV=test bundle exec rake auction_fun_core:db:create_database[userdb]
-user@host:~$ APP_ENV=test bundle exec rake auction_fun_core:db:migrate
-user@host:~$ CI=true APP_ENV=test bundle exec rspec .
+APP_ENV=test bundle exec rake auction_fun_core:db:create_database[postgres]
+APP_ENV=test bundle exec rake auction_fun_core:db:migrate
+CI=true APP_ENV=test bundle exec rspec .
 ```
 
 ## Documentation
@@ -127,10 +127,12 @@ user@host:~$ CI=true APP_ENV=test bundle exec rspec .
 This project uses `yadr` as a documentation tool. To generate documentation and view it, run
 
 ```sh
-    user@host:~$ bundle exec yard server --reload
+bundle exec yard server --reload
 ```
 
-Documentation will be available at `http://localhost:8808`
+Documentation will be available at `http://localhost:8808`.
+
+> If you already use overmind, the documentation server starts automatically.
 
 ## External resources
 

data/Rakefile

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'config/application'
+require_relative "config/application"
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 

data/i18n/en-US/contracts/contracts.en-US.yml

@@ -70,6 +70,9 @@ en-US:
         auction_context:
           create:
             finished_at: "must be after started time"
+          pre_auction:
+            auction_start_reminder:
+              auction_already_started: "auction already started"
           post_auction:
             participant:
               none: "there was no participation from this user in the auction reported"

data/i18n/en-US/mail/application.en-US.yml

@@ -52,6 +52,13 @@ en-US:
       - :year
       - :month
       - :day
+  time:
+    am: am
+    formats:
+      default: "%a, %d %b %Y %H:%M:%S %z"
+      long: "%B %d, %Y %H:%M"
+      short: "%d %b %H:%M"
+    pm: pm
   application:
     general:
       hello: "Hi %{name}"

data/i18n/en-US/mail/auction_context/pre_auction/auction_start_reminder.en-US.yml

@@ -0,0 +1,11 @@
+pt-BR:
+  mail:
+    auction_context:
+      pre_auction:
+        auction_start_reminder_mailer:
+          subject: "The %{title} auction will start soon!"
+          body:
+            description: "We are excited to inform you that the auction you are participating in will begin soon!"
+            auction_date: "Start Time"
+            link_to_auction: "Click the link below to view auction details"
+            thanks: "Thank you for your participation and we wish you good luck!"

data/i18n/pt-BR/contracts/contracts.pt-BR.yml

@@ -70,6 +70,9 @@ pt-BR:
         auction_context:
           create:
             finished_at: "deve ser depois da hora de início"
+          pre_auction:
+            auction_start_reminder:
+              auction_already_started: "leilão já foi iniciado"
           post_auction:
             participant:
               none: "não houve nenhuma participação deste usuário no leilão informado"

data/i18n/pt-BR/mail/application.pt-BR.yml

@@ -52,6 +52,13 @@ pt-BR:
       - :day
       - :month
       - :year
+  time:
+    am: am
+    formats:
+      default: "%a, %d de %B de %Y, %H:%M:%S %z"
+      long: "%d de %B de %Y, %H:%M"
+      short: "%d de %B, %H:%M"
+    pm: pm
   application:
     general:
       hello: "Olá %{name}"

data/i18n/pt-BR/mail/auction_context/pre_auction/auction_start_reminder.pt-BR.yml

@@ -0,0 +1,11 @@
+pt-BR:
+  mail:
+    auction_context:
+      pre_auction:
+        auction_start_reminder_mailer:
+          subject: "O leilão %{title} começará em breve!"
+          body:
+            description: "Estamos entusiasmados em informar que o leilão em que você está participando começará em breve!"
+            auction_date: "Hora de Início"
+            link_to_auction: "Clique no link abaixo para ver os detalhes do leilão"
+            thanks: "Agradecemos pela sua participação e desejamos boa sorte!"

data/lib/auction_fun_core/business/configuration.rb

@@ -2,16 +2,47 @@
 
 module AuctionFunCore
   module Business
+    # The Configuration module contains constants that configure various aspects of auctions,
+    # user settings, and other business rules within the AuctionFun application.
     module Configuration
+      # An array of available auction kinds derived from auction relations.
+      # @return [Array<String>] a list of all possible auction kinds
       AUCTION_KINDS = Relations::Auctions::KINDS.values
+
+      # An array of valid auction statuses derived from auction relations.
+      # @return [Array<String>] a list of all valid auction statuses
       AUCTION_STATUSES = Relations::Auctions::STATUSES.values
+
+      # The minimum length for an auction title.
+      # @return [Integer] the minimum number of characters allowed in an auction title
       AUCTION_MIN_TITLE_LENGTH = 6
+
+      # The maximum length for an auction title.
+      # @return [Integer] the maximum number of characters allowed in an auction title
       AUCTION_MAX_TITLE_LENGTH = 255
+
+      # The minimum value for the auction stopwatch timer.
+      # @return [Integer] the minimum seconds count for the auction stopwatch timer
       AUCTION_STOPWATCH_MIN_VALUE = 15
+
+      # The maximum value for the auction stopwatch timer.
+      # @return [Integer] the maximum seconds count for the auction stopwatch timer
       AUCTION_STOPWATCH_MAX_VALUE = 60
+
+      # The minimum length for a user's name.
+      # @return [Integer] the minimum number of characters allowed in a person's name
       MIN_NAME_LENGTH = 6
+
+      # The maximum length for a user's name.
+      # @return [Integer] the maximum number of characters allowed in a person's name
       MAX_NAME_LENGTH = 128
+
+      # The minimum length for a user's password.
+      # @return [Integer] the minimum number of characters required in a person's password
       MIN_PASSWORD_LENGTH = 6
+
+      # The maximum length for a user's password.
+      # @return [Integer] the maximum number of characters allowed in a person's password
       MAX_PASSWORD_LENGTH = 128
     end
   end

data/lib/auction_fun_core/business/token_generator.rb

@@ -2,13 +2,31 @@
 
 module AuctionFunCore
   module Business
-    # Responsible for generating interaction tokens with system users for general operations.
+    # The TokenGenerator module is responsible for generating interaction tokens
+    # used in various parts of the AuctionFun application for authentication and
+    # verification purposes, particularly in interactions with system users.
     module TokenGenerator
+      # Generates a secure, URL-safe base64 token primarily used for email verification.
+      # This method modifies certain characters to avoid common readability issues.
+      #
+      # @param length [Integer] the desired length of the generated token before modification
+      # @return [String] a URL-safe, base64 encoded string suitable for email verification links
+      # @example Generating an email token
+      #   email_token = AuctionFunCore::Business::TokenGenerator.generate_email_token(20)
+      #   puts email_token  # Output example: "V4Ph2wkJG_bRzs_zuGyJ"
       def self.generate_email_token(length = 20)
         rlength = (length * 3) / 4
         SecureRandom.urlsafe_base64(rlength).tr("lIO0", "sxyz")
       end
 
+      # Generates a numerical token used for phone verification processes.
+      # The token is zero-padded to ensure it meets the required length.
+      #
+      # @param length [Integer] the desired length of the numerical token
+      # @return [String] a string of digits, zero-padded to the specified length
+      # @example Generating a phone token
+      #   phone_token = AuctionFunCore::Business::TokenGenerator.generate_phone_token(6)
+      #   puts phone_token  # Output example: "045673"
       def self.generate_phone_token(length = 6)
         rand(0o00000..999_999).to_s.rjust(length, "0")
       end

data/lib/auction_fun_core/contracts/application_contract.rb

@@ -4,7 +4,10 @@ require "phonelib"
 
 module AuctionFunCore
   module Contracts
-    # Abstract base class for contracts.
+    ##
+    # The class includes several macros for common validation tasks, such as validating email format,
+    # login format, name format, phone number format, and password format. These macros utilize
+    # regular expressions and predefined length ranges to ensure the input data meets specific criteria.
     # @abstract
     class ApplicationContract < Dry::Validation::Contract
       include AuctionFunCore::Business::Configuration
@@ -17,18 +20,21 @@ module AuctionFunCore
       config.messages.top_namespace = "contracts"
       config.messages.load_paths << Application.root.join("i18n/#{I18n.default_locale}/contracts/contracts.#{I18n.default_locale}.yml").to_s
 
+      # Validates whether the provided value matches the standard email format.
       register_macro(:email_format) do
         next if EMAIL_REGEX.match?(value)
 
         key.failure(I18n.t(:email_format, scope: I18N_MACRO_SCOPE))
       end
 
+      # Validates whether the provided value matches either the email format or a valid phone number format using Phonelib.
       register_macro(:login_format) do
         next if EMAIL_REGEX.match?(value) || Phonelib.parse(value).valid?
 
         key.failure(I18n.t(:login_format, scope: I18N_MACRO_SCOPE))
       end
 
+      # Validates whether the length of the provided name falls within the specified range.
       register_macro(:name_format) do
         next if value.length.between?(MIN_NAME_LENGTH, MAX_NAME_LENGTH)
 
@@ -37,12 +43,14 @@ module AuctionFunCore
         )
       end
 
+      # Validates whether the provided value matches a valid phone number format using Phonelib.
       register_macro(:phone_format) do
         next if ::Phonelib.parse(value).valid?
 
         key.failure(I18n.t(:phone_format, scope: I18N_MACRO_SCOPE))
       end
 
+      # Validates whether the length of the provided password falls within the specified range.
       register_macro(:password_format) do
         next if value.length.between?(MIN_PASSWORD_LENGTH, MAX_PASSWORD_LENGTH)
 

data/lib/auction_fun_core/contracts/auction_context/create_contract.rb

@@ -3,15 +3,36 @@
 module AuctionFunCore
   module Contracts
     module AuctionContext
-      # Contract class to create new auctions.
+      # This class is designed to validate the creation of new auctions.
+      # It includes various validations such as staff existence, auction kind, timing, and initial bids.
+      #
+      # @example Creating a new auction
+      #   contract = AuctionFunCore::Contracts::AuctionContext::CreateContract.new
+      #   attributes = {
+      #     staff_id: 1,
+      #     title: "Rare Antique Vase",
+      #     kind: "standard",
+      #     started_at: Time.current + 5.days,
+      #     finished_at: Time.current + 10.days,
+      #     initial_bid_cents: 5000
+      #   }
+      #   result = contract.call(attributes)
+      #   if result.success?
+      #     puts "Auction created successfully."
+      #   else
+      #     puts "Failed to create auction: #{result.errors.to_h}"
+      #   end
+      #
       class CreateContract < Contracts::ApplicationContract
         include AuctionFunCore::Business::Configuration
 
+        # Additional validations specific for non-penny auctions.
         REQUIRED_FINISHED_AT = AUCTION_KINDS - ["penny"]
 
+        # Repository initialized to retrieve staff data for validation.
         option :staff_repo, default: proc { Repos::StaffContext::StaffRepository.new }
 
-        # @param [Hash] opts Sets an allowed list of parameters, as well as some initial validations.
+        # Defines necessary parameters and initializes some default values.
         params do
           required(:staff_id).filled(:integer)
           required(:title).filled(:string, size?: (AUCTION_MIN_TITLE_LENGTH..AUCTION_MAX_TITLE_LENGTH))
@@ -22,7 +43,7 @@ module AuctionFunCore
           optional(:initial_bid_cents).filled(:integer)
           optional(:stopwatch).filled(:integer)
 
-          # Keys with a blank value are discarded.
+          # Parameters specifying the required input types and fields.
           before(:value_coercer) do |result|
             result.to_h.compact
           end
@@ -33,59 +54,53 @@ module AuctionFunCore
           end
         end
 
-        # Validation for staff.
-        # Validate whether the given staff is valid at the database level.
+        # Validates the existence of the staff.
         rule(:staff_id) do |context:|
           context[:staff] ||= staff_repo.by_id(value)
           key.failure(I18n.t("contracts.errors.custom.default.not_found")) unless context[:staff]
         end
 
-        # Validation for started_at.
-        # Validates if the entered date is greater than or equal to the current time.
+        # Validates that the starting time of the auction is in the future.
         rule(:started_at) do
           key.failure(I18n.t("contracts.errors.custom.default.future")) if key? && value <= Time.current
         end
 
-        # Specific validation when the auction type is informed and it is not penny,
-        # it must be mandatory to inform the auction closing date/time
+        # Validates that the finished_at time is specified for auctions types that require it,
+        # and is not specified for "penny" auctions.
         rule(:finished_at, :kind) do
           if key?(:kind) && !key?(:finished_at) && REQUIRED_FINISHED_AT.include?(values[:kind])
             key.failure(I18n.t("contracts.errors.filled?"))
           end
         end
 
-        # Basic specific validation to check if the auction end time
-        # is less than or equal to the start time.
+        # Validates that the auction end time is later than the start time.
         rule(:finished_at, :started_at) do
           if key?(:finished_at) && (values[:finished_at] <= values[:started_at])
             key.failure(I18n.t("contracts.errors.custom.auction_context.create.finished_at"))
           end
         end
 
-        # Validation for initial bid amount.
-        #
+        # Validates the initial bid amount based on auction type.
         rule(:initial_bid_cents) do
-          # Must be filled if auction kind is not type penny.
+          # Must be specified and positive for non-penny auction types.
           key.failure(I18n.t("contracts.errors.filled?")) if !key? && REQUIRED_FINISHED_AT.include?(values[:kind])
 
-          # Must be greater than zero if action kind is not type penny.
           if key? && REQUIRED_FINISHED_AT.include?(values[:kind]) && values[:initial_bid_cents] <= 0
             key.failure(I18n.t("contracts.errors.gt?", num: 0))
           end
 
-          # Must be equal to zero if auction kind is type penny.
+          # Must be zero for penny auctions to ensure fairness.
           if key? && values[:kind] == "penny" && !values[:initial_bid_cents].zero?
             key.failure(I18n.t("contracts.errors.eql?", left: 0))
           end
         end
 
-        # Validation for stopwatch.
-        #
+        # Validates stopwatch settings for penny auctions.
         rule(:stopwatch) do
-          # Must be filled if auction kind is type penny.
+          # Stopwatch must be specified for penny auctions.
           key.failure(I18n.t("contracts.errors.filled?")) if !key? && values[:kind] == "penny"
 
-          # Must be an integer between 15 and 60.
+          # Stopwatch value must fall within the specified range.
           if key? && values[:kind] == "penny" && !value.between?(AUCTION_STOPWATCH_MIN_VALUE, AUCTION_STOPWATCH_MAX_VALUE)
             key.failure(
               I18n.t(

data/lib/auction_fun_core/contracts/auction_context/post_auction/participant_contract.rb

@@ -5,30 +5,52 @@ module AuctionFunCore
     module AuctionContext
       module PostAuction
         ##
-        # Contract class for validate participation auction.
+        # This class is used to validate the participation of users in an auction.
+        # This contract ensures that both the auction and the participant exist and that the participant
+        # has already at least placed a bid. It utilizes repositories to fetch data about auctions, users, and bids.
+        #
+        # @example Using this class to validate a participant
+        #   contract = AuctionFunCore::Contracts::AuctionContext::PostAuction::ParticipantContract.new
+        #   attributes = { auction_id: 1, participant_id: 102 }
+        #   validation_result = contract.call(attributes)
+        #   if validation_result.success?
+        #     puts "Participant validation passed"
+        #   else
+        #     puts "Participant validation failed: #{validation_result.errors.to_h}"
+        #   end
         #
         class ParticipantContract < Contracts::ApplicationContract
+          # Scope for internationalization (i18n) entries specific to errors in this contract.
           I18N_SCOPE = "contracts.errors.custom.auction_context.post_auction.participation"
 
+          # Repository options initialized by default. These repositories handle data retrieval.
           option :auction_repository, default: proc { Repos::AuctionContext::AuctionRepository.new }
           option :user_repository, default: proc { Repos::UserContext::UserRepository.new }
           option :bid_repository, default: proc { Repos::BidContext::BidRepository.new }
 
+          # Defines the data types and required fields for the contract.
           params do
             required(:auction_id).filled(:integer)
             required(:participant_id).filled(:integer)
           end
 
+          # Validation rule for auction_id to ensure the auction exists.
+          # @param context [Hash] Optional context hash to store data and state during validation.
           rule(:auction_id) do |context:|
             context[:auction] ||= auction_repository.by_id(value)
             key.failure(I18n.t("contracts.errors.custom.not_found")) unless context[:auction]
           end
 
+          # Validation rule for participant_id to ensure the participant exists.
+          # @param context [Hash] Optional context hash to store data and state during validation.
           rule(:participant_id) do |context:|
             context[:participant] ||= user_repository.by_id(value)
             key.failure(I18n.t("contracts.errors.custom.not_found")) unless context[:participant]
           end
 
+          # Combined validation rule for auction_id and participant_id to check that the participant
+          # has not already placed a bid in the auction.
+          # @param context [Hash] Context containing the auction and participant objects.
           rule(:auction_id, :participant_id) do |context:|
             next if (rule_error?(:auction_id) || schema_error?(:auction_id)) || (rule_error?(:winner_id) || schema_error?(:winner_id))
             next if bid_repository.exists?(auction_id: values[:auction_id], user_id: values[:participant_id])

data/lib/auction_fun_core/contracts/auction_context/post_auction/winner_contract.rb

@@ -5,29 +5,50 @@ module AuctionFunCore
     module AuctionContext
       module PostAuction
         ##
-        # Contract class for validate winner auction.
+        # This class validates the identification of the winning bidder
+        # in an auction context. It ensures that both the auction and the winner exist
+        # and are correctly associated within the system.
+        #
+        # @example Using this class to validate a winner
+        #   contract = AuctionFunCore::Contracts::AuctionContext::PostAuction::WinnerContract.new
+        #   attributes = { auction_id: 1, winner_id: 102 }
+        #   validation_result = contract.call(attributes)
+        #   if validation_result.success?
+        #     puts "Winner validation passed"
+        #   else
+        #     puts "Winner validation failed: #{validation_result.errors.to_h}"
+        #   end
         #
         class WinnerContract < Contracts::ApplicationContract
+          # Internationalization (i18n) scope for error messages related to winner validation.
           I18N_SCOPE = "contracts.errors.custom.auction_context.post_auction.winner"
 
+          # Repositories initialized by default to handle data retrieval for validation.
           option :auction_repository, default: proc { Repos::AuctionContext::AuctionRepository.new }
           option :user_repository, default: proc { Repos::UserContext::UserRepository.new }
 
+          # Parameters defining the expected input types and required fields.
           params do
             required(:auction_id).filled(:integer)
             required(:winner_id).filled(:integer)
           end
 
+          # Validation rule to ensure the auction exists.
+          # @param context [Hash] Optional context hash to store data and state during validation.
           rule(:auction_id) do |context:|
             context[:auction] ||= auction_repository.by_id(value)
             key.failure(I18n.t("contracts.errors.custom.not_found")) unless context[:auction]
           end
 
+          # Validation rule to ensure the winner exists.
+          # @param context [Hash] Optional context hash to store data and state during validation.
           rule(:winner_id) do |context:|
             context[:winner] ||= user_repository.by_id(value)
             key.failure(I18n.t("contracts.errors.custom.not_found")) unless context[:winner]
           end
 
+          # Combined rule to ensure that the declared winner is the actual winner recorded in the auction.
+          # @param context [Hash] Context containing the auction and winner objects.
           rule(:auction_id, :winner_id) do |context:|
             next if (rule_error?(:auction_id) || schema_error?(:auction_id)) || (rule_error?(:winner_id) || schema_error?(:winner_id))
             next if context[:auction].winner_id == values[:winner_id]