refactor(core): enhance SDK structure and documentation

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

src/Data/NominalAccounts/Deals/Steps/StepActionRequestData.php

@@ -1,20 +1,35 @@
 <?php
+/*
+// MODULE_CONTRACT: Defines the data structure for the request payload to perform an action on a deal step.
+// RESPONSIBILITY: To hold and validate all necessary information for actions such as completing or canceling a step within a deal.
+// INPUTS: Deal ID, action type, signatures, and optional step ID and description.
+// OUTPUTS: A structured, type-safe object for the `ManageStepRequest` payload.
+// LINKS: Requests/NominalAccounts/Deals/Steps/ManageStepRequest.php
+*/
 
 namespace Apoloz\AlfaBank\Data\NominalAccounts\Deals\Steps;
 
+// <SECTION name="module_imports" intent="Import necessary DTOs and Spatie Laravel Data components.">
+// <BELIEF_STATE "This DTO requires `DigestSignatureData` as a collection for security, utilizing `DataCollectionOf` for type safety.">
 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 performing an action on a deal step.">
+// <BELIEF_STATE "This DTO provides a robust contract for managing the lifecycle of deal steps. It ensures that critical operational and security data is strictly typed and correctly structured for actions like completion or cancellation.">
 class StepActionRequestData extends Data
 {
+    // <SECTION name="constructor_properties" intent="Define all properties for the step action request.">
+    // <BELIEF_STATE "The constructor includes mandatory fields like `dealId`, `action` (e.g., 'COMPLETE', 'CANCEL'), and `digestSignatures`. Optional fields like `stepId` (if targeting a specific step within the deal) and `description` provide flexibility and context for the action.">
     public function __construct(
         public string $dealId,
-        public string $action,
+        public string $action, // e.g., COMPLETE, CANCEL
         #[DataCollectionOf(DigestSignatureData::class)]
         public DataCollection $digestSignatures,
         public ?string $stepId = null,
         public ?string $description = null,
     ) {}
+    // </SECTION>
 }