Creating A Money Value Object In Domain: A Guide

In this article, we will walk you through the process of creating a Money Value Object in the BuscaVoosTeste.Domain project. This is a crucial step in modeling the domain for the BuscaVoosTeste.sln solution, which follows the principles of Clean Architecture. This guide ensures that you understand the context, objectives, and scope of creating this essential component.

Understanding the Context

Before diving into the implementation details, it's important to understand the context of the BuscaVoosTeste.sln solution. This solution is structured using Clean Architecture, which separates the application into distinct layers to ensure maintainability, scalability, and testability. The primary projects within this solution include:

• BuscaVoosTeste.Domain: This project houses the core domain logic and entities.
• BuscaVoosTeste.Application: This layer contains the application's use cases and business logic.
• BuscaVoosTeste.Infrastructure: This project deals with external concerns such as databases and APIs.
• BuscaVoosTeste.Api: This is the presentation layer, exposing the application's functionality through APIs.
• BuscaVoosTeste.McpServer: This project handles integrations with the MCP (Marketplace Connectivity Platform) server.

The Money Value Object plays a vital role in representing monetary values within the flight search domain. This includes handling fares, taxes, totals, and other price-related components. By creating a dedicated Value Object, we ensure consistency in currency representation, enforce immutability, and centralize validation rules.

To ensure adherence to the project's standards and best practices, it's crucial to consult the existing instructions within the repository. These instructions cover various aspects, including coding conventions, business rules, domain modeling, and application use cases. Specifically, the following files are essential references for this issue:

• .github/intructions/15-convencoes-de-codigo.md: This document outlines the coding conventions, including language, style, and naming conventions.
• .github/intructions/20-regras-negocio-busca-voos.md: This file details the business rules related to prices, currencies, and values within the flight search domain.
• .github/intructions/40-domain-model.md: This document provides insights into the modeling of entities, aggregates, and Value Objects within the domain.
• .github/intructions/50-application-usecases.md: This file helps understand how the domain layer will be consumed by the application layer and which scenarios involve monetary values.

In cases where there are discrepancies between this issue and the instructions, the instructions should always be considered the primary source of truth. Therefore, it's imperative to refer to these documents before making any implementation decisions.

Defining the Objective

The primary objective of this article is to guide you through the creation of the Money Value Object within the BuscaVoosTeste.Domain project. This Value Object must be designed to be immutable and consistent with the domain model and coding conventions established in the instructions. The Money Value Object is intended to represent monetary values, including the amount and currency, which are crucial for handling fares and other price-related components in flight searches.

Scope of Implementation

The scope of this article encompasses several key aspects of creating the Money Value Object. These include:

• Defining and Implementing the Money Value Object: The first step is to define and implement the Money Value Object within the BuscaVoosTeste.Domain project, adhering strictly to the rules and standards outlined in the project instructions.
• Ensuring Correct Namespace and Location: The Money Value Object must reside in the appropriate namespace and folder within the project structure. For example, it might be located in a directory such as Domain/ValueObjects, depending on the specifications in .github/intructions/40-domain-model.md.
• Adhering to Coding Conventions: The implementation must follow all language and naming conventions detailed in .github/intructions/15-convencoes-de-codigo.md. This ensures consistency and readability across the codebase.
• Representing Key Properties: The Money Value Object must represent at least two fundamental properties:
  • Amount: The numerical value representing the monetary amount.
  • Currency: The currency code, which should adhere to a standard such as ISO 4217, if specified in the instructions.
• Implementing Validation Rules and Invariants: It is crucial to implement validation rules and invariants to ensure the integrity of the monetary values. Examples of such rules include:
  • Handling Negative Values: Decide whether to allow negative values based on the business rules. If negative values are not permitted, the implementation should prevent their creation.
  • Currency Code Validation: Validate the currency code against a predefined standard or list of supported currencies. This ensures that only valid currency codes are used.
• Implementing Expected Value Object Behaviors: The Money Value Object should exhibit standard behaviors expected of Value Objects. These behaviors are typically defined in .github/intructions/40-domain-model.md and include:
  • Equality Based on Amount and Currency: Two Money Value Objects should be considered equal if they have the same amount and currency.
  • Creation Methods/Factories: Implement methods or factories for creating Money Value Objects, following the conventions established in the solution (e.g., Create, From, TryCreate).
  • Monetary Operations: If specified in 20-regras-negocio-busca-voos.md, implement helper methods for monetary operations such as adding or subtracting values. These operations should typically be restricted to values of the same currency.
• Documenting the Money Value Object: The Money Value Object should be thoroughly documented using comments and summaries written in Brazilian Portuguese, as specified in 15-convencoes-de-codigo.md. This documentation should explain the purpose, properties, and behavior of the Value Object.

Out of Scope

To maintain focus and prevent scope creep, certain aspects are explicitly excluded from this article. These include:

• API Layer Modifications: This article does not cover altering or creating any endpoints in the BuscaVoosTeste.Api layer. The focus is solely on the domain layer.
• MCP Integrations: No modifications or integrations with the MCP server in BuscaVoosTeste.McpServer are within the scope.
• Persistence Mappings: Implementing specific persistence mappings, such as Entity Framework Core converters, in the BuscaVoosTeste.Infrastructure layer is not included in this article.
• Application Use Cases: This article does not cover altering use cases in the BuscaVoosTeste.Application layer. The Money Value Object will be prepared for future use, but no use cases will be modified at this stage.
• Other Domain Elements: No entities or Value Objects other than the Money Value Object will be created or altered.
• Automated Tests: Creating automated tests is not part of this article. If testing is required, it will be addressed in a separate article.
• Architectural Changes: No modifications to the architecture, project structure, or references between projects are allowed beyond what is strictly necessary for the Money Value Object to compile and be usable within the domain.

References to Instructions

To successfully implement the Money Value Object, it is essential to read and follow several key instruction files. These files provide the necessary guidelines and standards for the project. The following files should be consulted:

• .github/intructions/00-visao-geral-e-objetivos.md
  • This file provides an overview of the BuscaVoosTeste.sln solution and the role of the flight search domain. It helps in understanding the broader context and objectives of the project.
• .github/intructions/10-arquitetura-clean.md
  • This document explains the principles of Clean Architecture and how they are applied in this project. It is crucial for ensuring that the Money Value Object adheres to the separation of responsibilities.
• .github/intructions/15-convencoes-de-codigo.md
  • This file details the coding conventions to be followed, including:
    • The standard language for classes, methods, properties, and comments.
    • Naming conventions for files, namespaces, and type suffixes/prefixes.
    • Guidelines on using record, class, struct, and immutability.
• .github/intructions/20-regras-negocio-busca-voos.md
  • This document outlines the business rules related to currencies and values, such as:
    • Supported currencies and their handling.
    • Rounding rules.
    • Decimal precision.
    • Minimum and maximum values.
    • Expected behavior for flight prices, taxes, and totals.
• .github/intructions/40-domain-model.md
  • This file describes the domain model and is essential for:
    • Verifying if the Money Value Object is already described in the model.
    • Ensuring that the name of the type (Money) and its properties align with the domain design.
    • Following the implementation pattern of other Value Objects in the solution.
• .github/intructions/50-application-usecases.md
  • This document helps in understanding the scenarios in which the Money Value Object will be used within the application. This ensures that the Value Object is suitable for its intended use, even though the use case implementation will not be altered in this article.

If there are specific sections within these files that detail