refactor(core): enhance SDK structure and documentation

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

src/Data/NominalAccounts/Payouts/TaxRefundRequestData.php

@@ -1,14 +1,28 @@
 <?php
+/*
+// MODULE_CONTRACT: Defines the data structure for a tax refund request payload.
+// RESPONSIBILITY: To provide a strongly-typed structure for initiating a tax refund for a beneficiary, including financial details, purpose, handling of remaining funds, and cryptographic signatures.
+// INPUTS: Beneficiary ID, refund amount, purpose, a flag to keep funds on the nominal account, and a collection of `DigestSignatureData`.
+// OUTPUTS: An instantiated DTO representing the tax refund request payload.
+// LINKS: Requests/NominalAccounts/Payouts/CreateTaxRefundRequest.php, Data/NominalAccounts/Payouts/DigestSignatureData.php
+*/
 
 namespace Apoloz\AlfaBank\Data\NominalAccounts\Payouts;
 
+// <SECTION name="module_imports" intent="Import necessary classes for cryptographic signatures, data collection, and Laravel Data.">
+// <BELIEF_STATE "These imports are essential for constructing a secure and structured tax refund request. `DigestSignatureData` ensures the integrity and authenticity of the request, `DataCollectionOf` and `DataCollection` facilitate handling multiple signatures, and `Data` provides the foundational capabilities for data object mapping and validation.">
 use Apoloz\AlfaBank\Data\NominalAccounts\Payouts\DigestSignatureData;
 use Spatie\LaravelData\Attributes\DataCollectionOf;
 use Spatie\LaravelData\Data;
 use Spatie\LaravelData\DataCollection;
+// </SECTION>
 
+// <SECTION name="class_definition" intent="Define the tax refund request data structure.">
+// <BELIEF_STATE "The `TaxRefundRequestData` DTO encapsulates all the necessary information to process a tax refund. It includes critical financial and beneficiary identifiers, along with a mechanism to handle remaining funds and mandatory cryptographic signatures to ensure request security and non-repudiation.">
 class TaxRefundRequestData extends Data
 {
+    // <SECTION name="constructor_properties" intent="Define the properties of the tax refund request DTO.">
+    // <BELIEF_STATE "Properties are defined directly in the constructor, leveraging PHP 8's property promotion for conciseness. Mandatory fields like `beneficiaryId`, `amount`, `purpose`, and `digestSignatures` ensure a complete request. `keepOnNominalAccount` provides control over fund disposition, and `requisiteId` allows for specific payout instructions.">
     public function __construct(
         public string $beneficiaryId,
         public string $amount,
@@ -18,4 +32,6 @@ class TaxRefundRequestData extends Data
         public DataCollection $digestSignatures,
         public ?string $requisiteId = null,
     ) {}
+    // </SECTION>
 }
+// </SECTION>