refactor(core): enhance SDK structure and documentation

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

src/Data/NominalAccounts/BeneficiaryData.php

@@ -1,18 +1,32 @@
 <?php
+/*
+// MODULE_CONTRACT: Defines the core data structure for a single beneficiary.
+// RESPONSIBILITY: To hold and type-safely represent all attributes of a beneficiary, as returned by the API.
+// INPUTS: Raw JSON object from the API response.
+// OUTPUTS: A structured object containing beneficiary details.
+// LINKS: BeneficiaryCollectionData.php
+*/
 
 namespace Apoloz\AlfaBank\Data\NominalAccounts;
 
-use Apoloz\AlfaBank\Data\PaginationData;
-use Spatie\LaravelData\Data;
+// <SECTION name="module_imports" intent="Import necessary DTOs and Spatie Laravel Data components.">
+// <BELIEF_STATE "This DTO may contain nested DTOs (e.g., for personal information, addresses, documents) or simple arrays, requiring appropriate Spatie Data attributes if they were themselves DTOs. It also references `PaginationData` due to a namespace mismatch in the original, but this file is primarily about the single beneficiary.">
+use Apoloz\AlfaBank\Data\PaginationData; // This import might be misleading for a single DTO, but kept for context consistency.
 use Spatie\LaravelData\Attributes\DataCollectionOf;
+use Spatie\LaravelData\Data;
 use Spatie\LaravelData\DataCollection;
+// </SECTION>
 
+// <SECTION name="class_definition" intent="Define a DTO for a single beneficiary's details.">
+// <BELIEF_STATE "This DTO provides a comprehensive, type-safe representation of a beneficiary, which is essential for consistent data handling across the SDK.">
 class BeneficiaryData extends Data
 {
+    // <SECTION name="constructor_properties" intent="Define all properties that describe a beneficiary.">
+    // <BELIEF_STATE "The constructor includes a wide range of properties covering identification, personal information, contact details, and status. While some are typed as `array` here, in a more refined design, these would likely be nested DTOs (e.g., `PersonalInformationData`, `AddressData`). The `isBeneficiary` and `isVpr` flags represent specific statuses or roles.">
     public function __construct(
         public string $beneficiaryId,
         public string $type,
-        public ?array $personalInformation = null,
+        public ?array $personalInformation = null, // Could be PersonalInformationData DTO
         public ?string $inn = null,
         public ?string $firstName = null,
         public ?string $lastName = null,
@@ -21,11 +35,12 @@ class BeneficiaryData extends Data
         public ?string $countryOfTaxResidence = null,
         public ?string $phoneNumber = null,
         public ?string $email = null,
-        public ?array $addresses = null,
-        public ?array $documents = null,
+        public ?array $addresses = null, // Could be DataCollectionOf(AddressData::class)
+        public ?array $documents = null, // Could be DataCollectionOf(DocumentData::class)
         public ?bool $isActive = null,
-        public ?array $balances = null,
+        public ?array $balances = null, // Could be DataCollectionOf(WalletBalanceData::class)
         public ?bool $isBeneficiary = null,
         public ?bool $isVpr = null,
     ) {}
+    // </SECTION>
 }