refactor(core): enhance SDK structure and documentation

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

src/Data/NominalAccounts/Beneficiaries/UpdateBeneficiaryRequestData.php

@@ -1,14 +1,28 @@
 <?php
+/*
+// MODULE_CONTRACT: Defines the data structure for the request payload when updating an existing beneficiary.
+// RESPONSIBILITY: To hold and validate all necessary information for updating a beneficiary, including partial changes.
+// INPUTS: Raw data array for updated beneficiary details.
+// OUTPUTS: A structured, type-safe object for the `UpdateBeneficiaryRequest` payload.
+// LINKS: Requests/NominalAccounts/Beneficiaries/UpdateBeneficiaryRequest.php
+*/
 
 namespace Apoloz\AlfaBank\Data\NominalAccounts\Beneficiaries;
 
+// <SECTION name="module_imports" intent="Import necessary DTOs and Spatie Laravel Data components.">
+// <BELIEF_STATE "This DTO handles complex nested structures (`DigestSignatureData`, `AddressData`, `DocumentData`, `PersonalInformationData`), requiring `DataCollectionOf` for typed arrays.">
 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 a DTO for updating an existing beneficiary.">
+// <BELIEF_STATE "This DTO provides a robust contract for updating beneficiary details. By making most fields nullable, it supports partial updates (PATCH-like behavior) even if the API uses PUT.">
 class UpdateBeneficiaryRequestData extends Data
 {
+    // <SECTION name="constructor_properties" intent="Define all properties for the beneficiary update request, including nested DTOs and collections.">
+    // <BELIEF_STATE "Similar to `CreateBeneficiaryRequestData`, this constructor lists all updatable fields. Mandatory fields are `type` and `digestSignatures`. Most other fields are nullable to allow for partial updates, reflecting the flexibility often needed in update operations.">
     public function __construct(
         public string $type,
         #[DataCollectionOf(DigestSignatureData::class)]
@@ -24,4 +38,5 @@ class UpdateBeneficiaryRequestData extends Data
         public ?DataCollection $documents = null,
         public ?bool $isActive = null,
     ) {}
+    // </SECTION>
 }