refactor(core): enhance SDK structure and documentation

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

src/Data/Auth/UserInfo/ClientConsentCollectionData.php

@@ -1,17 +1,32 @@
 <?php
+/*
+// MODULE_CONTRACT: Defines the data structure for a paginated collection of client consent records.
+// RESPONSIBILITY: To provide a structured, type-safe container for lists of client consents returned by the API, including pagination metadata.
+// INPUTS: Raw JSON array from the API response.
+// OUTPUTS: An object containing pagination details and a collection of `ClientConsentData`.
+// LINKS: Requests/Auth/UserInfo/GetClientConsentsRequest.php
+*/
 
 namespace Apoloz\AlfaBank\Data\Auth\UserInfo;
 
+// <SECTION name="module_imports" intent="Import necessary DTOs and Spatie Laravel Data components.">
+// <BELIEF_STATE "This collection DTO relies on `PaginationData` for metadata and `ClientConsentData` for the individual items. `DataCollection` and `DataCollectionOf` are Spatie Data features for handling typed arrays of DTOs.">
 use Apoloz\AlfaBank\Data\PaginationData;
 use Spatie\LaravelData\Attributes\DataCollectionOf;
 use Spatie\LaravelData\Data;
 use Spatie\LaravelData\DataCollection;
+// </SECTION>
 
+// <SECTION name="class_definition" intent="Define a DTO for a collection of client consents.">
+// <BELIEF_STATE "A dedicated DTO for a collection ensures that the structure of paginated lists is consistent and type-safe, providing a reliable contract for consumers to manage client consents.">
 class ClientConsentCollectionData extends Data
 {
+    // <SECTION name="constructor_properties" intent="Define the properties of the client consent collection.">
+    // <BELIEF_STATE "The collection structure includes pagination metadata (`pagination`) and the actual list of consent items (`items`). The `#[DataCollectionOf(ClientConsentData::class)]` attribute is crucial for ensuring that each item in the `items` array is automatically cast to a `ClientConsentData` DTO.">
     public function __construct(
         public PaginationData $pagination,
         #[DataCollectionOf(ClientConsentData::class)]
         public DataCollection $items
     ) {}
+    // </SECTION>
 }

src/Data/Auth/UserInfo/ClientConsentData.php

@@ -1,14 +1,28 @@
 <?php
+/*
+// MODULE_CONTRACT: Defines the data structure for a single client consent record.
+// RESPONSIBILITY: To hold and type-safely represent the details of a user's consent given to a client application.
+// INPUTS: Raw JSON object from the API response.
+// OUTPUTS: A structured object containing client consent information.
+// LINKS: ClientConsentCollectionData.php
+*/
 
 namespace Apoloz\AlfaBank\Data\Auth\UserInfo;
 
-use Apoloz\AlfaBank\Data\PaginationData;
-use Spatie\LaravelData\Attributes\DataCollectionOf;
+// <SECTION name="module_imports" intent="Import necessary DTOs and Spatie Laravel Data components.">
+// <BELIEF_STATE "This DTO represents a single consent entry. The `PaginationData` import here is likely due to prior usage or template, but not directly used within this single DTO.">
+use Apoloz\AlfaBank\Data\PaginationData; // This import is likely extraneous for a single DTO, but kept for context consistency.
+use Spatie\LaravelData\Attributes\DataCollectionOf; // This is also likely extraneous for a single DTO.
 use Spatie\LaravelData\Data;
-use Spatie\LaravelData\DataCollection;
+use Spatie\LaravelData\DataCollection; // This is also likely extraneous for a single DTO.
+// </SECTION>
 
+// <SECTION name="class_definition" intent="Define a DTO for a single client consent.">
+// <BELIEF_STATE "This DTO provides a clear, type-safe contract for an individual consent record, which is crucial for managing access permissions within an OAuth/OIDC system.">
 class ClientConsentData extends Data
 {
+    // <SECTION name="constructor_properties" intent="Define the properties of a client consent record.">
+    // <BELIEF_STATE "The constructor includes key information such as `createDateTime`, `sub` (subject ID), `clientId`, `isActive` status, and `expireDate`. The `organizationIdHash` provides additional context. These fields define the scope and validity of the consent.">
     public function __construct(
         public string $createDateTime,
         public string $sub,
@@ -17,4 +31,5 @@ class ClientConsentData extends Data
         public string $expireDate,
         public ?string $organizationIdHash = null,
     ) {}
+    // </SECTION>
 }

src/Data/Auth/UserInfo/UserInfoData.php

@@ -1,15 +1,29 @@
 <?php
+/*
+// MODULE_CONTRACT: Defines the data structure for OpenID Connect UserInfo claims.
+// RESPONSIBILITY: To hold and type-safely represent details about the authenticated end-user.
+// INPUTS: Raw JSON object (typically from a JWT payload) from the UserInfo endpoint.
+// OUTPUTS: A structured object containing user claims.
+// LINKS: Requests/Auth/UserInfo/GetUserInfoRequest.php
+*/
 
 namespace Apoloz\AlfaBank\Data\Auth\UserInfo;
 
+// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
+// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from JSON and provides other DTO benefits.">
 use Spatie\LaravelData\Data;
+// </SECTION>
 
+// <SECTION name="class_definition" intent="Define a DTO for OpenID Connect UserInfo claims.">
+// <BELIEF_STATE "This DTO provides a clear, type-safe contract for handling user claims returned by the OIDC UserInfo endpoint, ensuring consistent access to user attributes.">
 class UserInfoData extends Data
 {
+    // <SECTION name="constructor_properties" intent="Define the standard and extended properties (claims) for user information.">
+    // <BELIEF_STATE "The constructor includes `sub` (subject identifier) as mandatory. Many other fields are optional and represent common OIDC claims like `name`, `email`, `birthdate`, `phone_number`, and `inn`. These claims provide rich detail about the end-user.">
     public function __construct(
         public string $sub,
-        public ?string $iss = null,
-        public ?string $aud = null,
+        public ?string $iss = null, // Issuer
+        public ?string $aud = null, // Audience
         public ?string $name = null,
         public ?string $given_name = null,
         public ?string $family_name = null,
@@ -18,7 +32,8 @@ class UserInfoData extends Data
         public ?string $gender = null,
         public ?string $birthdate = null,
         public ?string $phone_number = null,
-        public ?string $inn = null,
+        public ?string $inn = null, // Individual Taxpayer Number (Russia)
         // Add more claims as needed based on the response
     ) {}
+    // </SECTION>
 }