VSN-2042 : Defining necessary dtos, mappings ,external calls related to Circuits and adding corrected version of saving a new Circuit.

MR Description: Circuit Creation Feature – API, Validation, Mapping, and External Integration

Overview

This merge request introduces the complete backend support for creating and saving new circuits.
It covers API exposition, request DTO definition, service-layer integration, entity mapping, data validation, exception handling, and external contract retrieval.
The objective is to provide a clean, validated, and extensible circuit creation workflow aligned with the current domain model and architectural standards.

---

Detailed Changes

1. API Endpoint Definition

• Added a new REST endpoint dedicated to creating a new circuit.
• The endpoint clearly separates circuit creation from other circuit-related operations.
• Ensures consistency with existing REST path naming conventions.

---

2. Circuit Saving Request DTO

• Introduced a SaveCircuit request DTO specifically designed for circuit creation.
• The DTO contains only domain-relevant attributes required for saving a circuit.
• Incremental ID traces were removed to fully align with UUID-based identification and persistence strategy.

---

3. Service Layer Integration

• Added a new saving method signature to handle circuit creation.
• The method signature and its implementation were moved to the PreparedService to better reflect the business responsibility of circuit preparation.
• This refactor improves cohesion and avoids duplication across services.

---

4. Entity Mapping

• Implemented a new mapper function that converts SaveCircuit DTOs into Circuit entities.
• Ensures:
  • Clear separation between API contracts and persistence models.
  • Centralized transformation logic.
• This mapping prepares the entity for validation and persistence without leaking transport-layer concerns.

---

5. External Contract Retrieval

• Added an external call to retrieve contract data using a contract UUID.
• Refactored existing fetch logic to rely exclusively on identifiers instead of legacy access patterns.
• This ensures:
  • Accurate contract association during circuit creation.
  • Better alignment with distributed service communication standards.

---

6. Circuit Data Validation

• Introduced a dedicated validation step executed before persisting a circuit.
• Validation ensures:
  • Mandatory fields are present.
  • Business rules related to circuits are respected.
• Prevents invalid or inconsistent circuit data from being saved.

---

7. Exception Handling

• Added circuit-specific exception definitions.
• Introduced a mapping between:
  • Exception codes
  • Human-readable exception messages
• This allows consistent error handling and clear feedback for both API consumers and internal debugging.

---

8. Persistence Workflow Improvements

• Integrated external contract UUID resolution into the circuit saving workflow.
• Ensures that circuits are saved only after validating:
  • Circuit data integrity
  • Contract existence and correctness

---

9. Documentation

• Updated the changelog to reflect:
  • The introduction of the circuit creation feature.
  • Service, validation, and mapping changes.

---

Impact

• Enables full backend support for circuit creation.
• Improves data integrity through validation and strict DTO usage.
• Aligns circuit management with UUID-based domain modeling.
• Enhances maintainability by centralizing responsibilities in appropriate services.

---

Testing Notes

• Circuit creation tested with valid and invalid payloads.
• Validation errors correctly block persistence.
• External contract retrieval verified using contract UUIDs.
• No regression observed in existing circuit-related features.

---

Future Improvements

• Extend validation rules as business constraints evolve.
• Add audit logging for circuit creation events.
• Expose circuit update functionality using a similar validated workflow.

Closes VSN-2042