refactor(core): enhance SDK structure and documentation

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

src/Sbp/Data/DigitalRuble/CashLink/ChangeAccForCashUniQrRequestData.php

@@ -1,21 +1,36 @@
 <?php
+/*
+// MODULE_CONTRACT: Defines the data structure for a CashLink Universal QR Code account change request payload.
+// RESPONSIBILITY: To hold and type-safely represent the parameters needed to update the linked account for a Digital Ruble CashLink QR Code.
+// INPUTS: Terminal number (TermNo), and various optional account, merchant, and redirection parameters.
+// OUTPUTS: A structured, type-safe object for the `ChangeAccForCashUniQrRequest` payload.
+// LINKS: Sbp/Requests/DigitalRuble/CashLink/ChangeAccForCashUniQrRequest.php
+*/
 
 namespace Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink;
 
+// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
+// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
 use Spatie\LaravelData\Data;
+// </SECTION>
 
+// <SECTION name="class_definition" intent="Define a DTO for CashLink Universal QR Code account change request.">
+// <BELIEF_STATE "This DTO ensures the account change payload is strictly typed and complete, supporting clear communication for Digital Ruble CashLink QR Code modifications.">
 class ChangeAccForCashUniQrRequestData extends Data
 {
+    // <SECTION name="constructor_properties" intent="Define the properties for the CashLink Uni QR Code account change request.">
+    // <BELIEF_STATE "The constructor includes the mandatory `TermNo`. Optional fields cover `messageID`, `qrcId`, account details (`account`, `accountDR`), new terminal/merchant IDs (`NewTermNo`, `NewMerchantId`), redirection (`redirectUrl`, `paymentPageUrl`), and `fraudScore` for risk assessment.">
     public function __construct(
         public string $TermNo,
         public ?string $messageID = null,
         public ?string $qrcId = null,
-        public ?string $account = null,
-        public ?string $accountDR = null,
+        public ?string $account = null, // Current or target conventional account
+        public ?string $accountDR = null, // Current or target Digital Ruble account
         public ?string $NewTermNo = null,
         public ?string $NewMerchantId = null,
         public ?string $redirectUrl = null,
         public ?string $paymentPageUrl = null,
         public ?string $fraudScore = null,
     ) {}
+    // </SECTION>
 }

src/Sbp/Data/DigitalRuble/CashLink/ChangeAccForCashUniQrResponseData.php

@@ -1,11 +1,25 @@
 <?php
+/*
+// MODULE_CONTRACT: Defines the data structure for the response of a CashLink Universal QR Code account change request.
+// RESPONSIBILITY: To hold and type-safely represent the outcome of updating the linked account for a Digital Ruble CashLink QR.
+// INPUTS: Raw JSON object from the API response.
+// OUTPUTS: A structured object containing account change confirmation details.
+// LINKS: Sbp/Requests/DigitalRuble/CashLink/ChangeAccForCashUniQrRequest.php
+*/
 
 namespace Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink;
 
+// <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 DTO benefits.">
 use Spatie\LaravelData\Data;
+// </SECTION>
 
+// <SECTION name="class_definition" intent="Define a DTO for SBP CashLink Uni QR Code account change response.">
+// <BELIEF_STATE "This DTO provides a clear, type-safe contract for the confirmation details of an account change operation, crucial for verifying the updated QR Code configuration.">
 class ChangeAccForCashUniQrResponseData extends Data
 {
+    // <SECTION name="constructor_properties" intent="Define the properties of the CashLink Uni QR Code account change response.">
+    // <BELIEF_STATE "The constructor includes mandatory `ErrorCode` and `message` for overall status. Optional fields provide details about the updated QR Code, such as `messageID`, `qrcId`, `TermNo`, account details (`account`, `accountDR`), redirection (`redirectUrl`, `paymentPageUrl`), `fraudScore`, and new terminal/merchant IDs (`NewTermNo`, `NewMerchantId`).">
     public function __construct(
         public int $ErrorCode,
         public string $message,
@@ -13,7 +27,7 @@ class ChangeAccForCashUniQrResponseData extends Data
         public ?string $qrcId = null,
         public ?string $TermNo = null,
         public ?string $account = null,
-        public ?string $accountDR = null,
+        public ?string $accountDR = null, // Digital Ruble account
         public ?string $redirectUrl = null,
         public ?string $paymentPageUrl = null,
         public ?string $fraudScore = null,
@@ -22,4 +36,5 @@ class ChangeAccForCashUniQrResponseData extends Data
         public ?string $status = null,
         public ?string $merchantId = null,
     ) {}
+    // </SECTION>
 }

src/Sbp/Data/DigitalRuble/CashLink/CreateCashUniQrRequestData.php

@@ -1,11 +1,25 @@
 <?php
+/*
+// MODULE_CONTRACT: Defines the data structure for an SBP Digital Ruble CashLink Universal QR Code creation request payload.
+// RESPONSIBILITY: To hold and type-safely represent the parameters needed to generate a new Digital Ruble CashLink QR.
+// INPUTS: Terminal number (TermNo) and various optional display, payment, and notification parameters.
+// OUTPUTS: A structured, type-safe object for the `CreateCashUniQrRequest` payload.
+// LINKS: Sbp/Requests/DigitalRuble/CashLink/CreateCashUniQrRequest.php
+*/
 
 namespace Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink;
 
+// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
+// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
 use Spatie\LaravelData\Data;
+// </SECTION>
 
+// <SECTION name="class_definition" intent="Define a DTO for SBP Digital Ruble CashLink Universal QR Code creation request.">
+// <BELIEF_STATE "This DTO ensures the CashLink Uni QR creation payload is strictly typed and complete, supporting clear communication for Digital Ruble transactions with the SBP API.">
 class CreateCashUniQrRequestData extends Data
 {
+    // <SECTION name="constructor_properties" intent="Define the properties for the Digital Ruble CashLink Uni QR Code creation request.">
+    // <BELIEF_STATE "The constructor includes the mandatory `TermNo`. Optional fields cover display (`mediaType`, `width`, `height`), redirection (`redirectUrl`, `paymentPageUrl`), tracking (`messageID`, `notificationUrl`), and explicit `qrcId` if pre-defined.">
     public function __construct(
         public string $TermNo,
         public ?string $messageID = null,
@@ -17,4 +31,5 @@ class CreateCashUniQrRequestData extends Data
         public ?string $qrcId = null,
         public ?string $notificationUrl = null,
     ) {}
+    // </SECTION>
 }

src/Sbp/Data/DigitalRuble/CashLink/CreateCashUniQrResponseData.php

@@ -1,20 +1,35 @@
 <?php
+/*
+// MODULE_CONTRACT: Defines the data structure for the response of a CashLink Universal QR Code creation request.
+// RESPONSIBILITY: To hold and type-safely represent the outcome of generating a Digital Ruble CashLink QR Code.
+// INPUTS: Raw JSON object from the API response.
+// OUTPUTS: A structured object containing QR Code creation details.
+// LINKS: Sbp/Requests/DigitalRuble/CashLink/CreateCashUniQrRequest.php
+*/
 
 namespace Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink;
 
+// <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 DTO benefits.">
 use Spatie\LaravelData\Data;
+// </SECTION>
 
+// <SECTION name="class_definition" intent="Define a DTO for SBP CashLink Universal QR Code creation response.">
+// <BELIEF_STATE "This DTO provides a clear, type-safe contract for the confirmation details of a CashLink Uni QR Code creation, crucial for displaying the QR Code to the user.">
 class CreateCashUniQrResponseData extends Data
 {
+    // <SECTION name="constructor_properties" intent="Define the properties of the CashLink Uni QR Code creation response.">
+    // <BELIEF_STATE "The constructor includes mandatory `ErrorCode` and `message` for overall status. Optional fields provide details about the created QR Code, such as `TermNo`, `payload` (the QR data itself), `image` (URL to the QR image), `mediaType`, `qrcId`, `messageID`, and `status`.">
     public function __construct(
         public int $ErrorCode,
         public string $message,
         public ?string $TermNo = null,
-        public ?string $payload = null,
-        public ?string $image = null,
+        public ?string $payload = null, // The raw QR string data
+        public ?string $image = null, // URL to the QR image
         public ?string $mediaType = null,
         public ?string $qrcId = null,
         public ?string $messageID = null,
         public ?string $status = null,
     ) {}
+    // </SECTION>
 }

src/Sbp/Data/DigitalRuble/CashLink/GetCashUniQrStatusRequestData.php

@@ -1,11 +1,25 @@
 <?php
+/*
+// MODULE_CONTRACT: Defines the data structure for a CashLink Universal QR Code status request payload.
+// RESPONSIBILITY: To hold and type-safely represent the parameters needed to query the status of a Digital Ruble CashLink QR Code.
+// INPUTS: Terminal number (TermNo), Uni QR ID, parameters ID, and optional message ID/payrrn.
+// OUTPUTS: A structured, type-safe object for the `GetCashUniQrStatusRequest` payload.
+// LINKS: Sbp/Requests/DigitalRuble/CashLink/GetCashUniQrStatusRequest.php
+*/
 
 namespace Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink;
 
+// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
+// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
 use Spatie\LaravelData\Data;
+// </SECTION>
 
+// <SECTION name="class_definition" intent="Define a DTO for CashLink Universal QR Code status request.">
+// <BELIEF_STATE "This DTO ensures the status request payload is strictly typed and complete, supporting clear communication with the SBP API.">
 class GetCashUniQrStatusRequestData extends Data
 {
+    // <SECTION name="constructor_properties" intent="Define the properties for the CashLink Uni QR Code status request.">
+    // <BELIEF_STATE "The constructor includes the mandatory `TermNo`, `uniQrId`, and `paramsId` to identify the target QR Code and its associated parameters. Optional fields `messageID` and `payrrn` provide additional query flexibility.">
     public function __construct(
         public string $TermNo,
         public string $uniQrId,
@@ -13,4 +27,5 @@ class GetCashUniQrStatusRequestData extends Data
         public ?string $messageID = null,
         public ?string $payrrn = null,
     ) {}
+    // </SECTION>
 }

src/Sbp/Data/DigitalRuble/CashLink/GetCashUniQrStatusResponseData.php

@@ -1,11 +1,25 @@
 <?php
+/*
+// MODULE_CONTRACT: Defines the data structure for the response of a CashLink Universal QR Code status request.
+// RESPONSIBILITY: To hold and type-safely represent detailed status information about a Digital Ruble CashLink QR Code.
+// INPUTS: Raw JSON object from the API response.
+// OUTPUTS: A structured object containing CashLink Uni QR status details.
+// LINKS: Sbp/Requests/DigitalRuble/CashLink/GetCashUniQrStatusRequest.php
+*/
 
 namespace Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink;
 
+// <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 DTO benefits.">
 use Spatie\LaravelData\Data;
+// </SECTION>
 
+// <SECTION name="class_definition" intent="Define a DTO for SBP CashLink Universal QR Code status response.">
+// <BELIEF_STATE "This DTO provides a clear, type-safe contract for tracking the status of Digital Ruble CashLink QR Codes, crucial for managing payment flows.">
 class GetCashUniQrStatusResponseData extends Data
 {
+    // <SECTION name="constructor_properties" intent="Define the properties of the CashLink Uni QR Code status response.">
+    // <BELIEF_STATE "The constructor includes mandatory `ErrorCode` and `message` for overall status. Optional fields provide detailed information about the QR Code and its associated transaction, such as `TermNo`, `messageID`, `uniQrId`, `paramsId`, `trxStatus`, `payrrn`, `timestamp`, `cashRegisterQrcStatus`, `trxId`, `trxDT`, `amount`, `currency`, `Url`, `CreditDatePos`, `payerId`, `kzo`, `merchantId`, and `paymentServiceId`.">
     public function __construct(
         public int $ErrorCode,
         public string $message,
@@ -28,4 +42,5 @@ class GetCashUniQrStatusResponseData extends Data
         public ?string $merchantId = null,
         public ?string $paymentServiceId = null,
     ) {}
+    // </SECTION>
 }

src/Sbp/Data/DigitalRuble/CreateUniQrRequestData.php

@@ -1,11 +1,25 @@
 <?php
+/*
+// MODULE_CONTRACT: Defines the data structure for an SBP Digital Ruble Universal QR Code creation request payload.
+// RESPONSIBILITY: To hold and type-safely represent the parameters needed to generate a new Digital Ruble Uni QR.
+// INPUTS: Terminal number (TermNo), QR type, and various optional display, payment, and notification parameters.
+// OUTPUTS: A structured, type-safe object for the `CreateUniQrRequest` payload.
+// LINKS: Sbp/Requests/DigitalRuble/CreateUniQrRequest.php
+*/
 
 namespace Apoloz\AlfaBank\Sbp\Data\DigitalRuble;
 
+// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
+// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
 use Spatie\LaravelData\Data;
+// </SECTION>
 
+// <SECTION name="class_definition" intent="Define a DTO for SBP Digital Ruble Universal QR Code creation request.">
+// <BELIEF_STATE "This DTO ensures the Uni QR creation payload is strictly typed and complete, supporting clear communication for Digital Ruble transactions with the SBP API.">
 class CreateUniQrRequestData extends Data
 {
+    // <SECTION name="constructor_properties" intent="Define the properties for the Digital Ruble Uni QR Code creation request.">
+    // <BELIEF_STATE "The constructor includes the mandatory `TermNo` and `uniQrType`. Optional fields cover display (`mediaType`, `width`, `height`), payment details (`amount`, `paymentPurpose`), redirection (`redirectUrl`, `paymentPageUrl`), validity (`qrTtl`), tracking (`messageID`, `notificationUrl`), and optional sender information (`SenderFIO`, `SenderID`, `SenderBankBIC`).">
     public function __construct(
         public string $TermNo,
         public string $uniQrType = '02', // 01=Multi, 02=Single
@@ -23,4 +37,5 @@ class CreateUniQrRequestData extends Data
         public ?string $SenderID = null,
         public ?string $SenderBankBIC = null,
     ) {}
+    // </SECTION>
 }

src/Sbp/Data/DigitalRuble/Notifications/PaymentDrNotificationData.php

@@ -1,11 +1,25 @@
 <?php
+/*
+// MODULE_CONTRACT: Defines the data structure for a Digital Ruble payment notification payload.
+// RESPONSIBILITY: To hold and type-safely represent the details of an incoming Digital Ruble payment event.
+// INPUTS: Raw array from a Digital Ruble payment webhook.
+// OUTPUTS: A structured object containing payment notification details.
+// LINKS: Sbp/Requests/DigitalRuble/Notifications/ParsePaymentDrNotification.php
+*/
 
 namespace Apoloz\AlfaBank\Sbp\Data\DigitalRuble\Notifications;
 
+// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
+// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
 use Spatie\LaravelData\Data;
+// </SECTION>
 
+// <SECTION name="class_definition" intent="Define a DTO for Digital Ruble payment notification.">
+// <BELIEF_STATE "This DTO provides a clear, type-safe contract for Digital Ruble payment notifications, crucial for reliably processing incoming payment events.">
 class PaymentDrNotificationData extends Data
 {
+    // <SECTION name="constructor_properties" intent="Define the properties of a Digital Ruble payment notification.">
+    // <BELIEF_STATE "The constructor includes mandatory fields such as `command`, `payrrn`, `BatchId`, `TermNo`, `CreditDatePos`, and `merchantName`. Optional fields provide additional context like `uniQrId`, `operationId`, `status`, `amount`, `timestamp`, and `purpose`, essential for a comprehensive payment record.">
     public function __construct(
         public string $command,
         public string $payrrn,
@@ -20,4 +34,5 @@ class PaymentDrNotificationData extends Data
         public ?string $timestamp = null,
         public ?string $purpose = null,
     ) {}
+    // </SECTION>
 }