refactor(core): enhance SDK structure and documentation

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-01-18 21:48:25 +03:00
parent 3da69c03e1
commit d214eecebe
378 changed files with 10514 additions and 496 deletions
--- a/src/AlfaBank.php
+++ b/src/AlfaBank.php
@@ -0,0 +1,80 @@
+<?php
+/*
+// MODULE_CONTRACT: Provides a user-friendly, static factory for instantiating API connectors.
+// RESPONSIBILITY: To simplify the creation of `AlfaBankConnector` and `SbpConnector` instances by abstracting away the underlying DTO and service instantiation.
+// INPUTS: Certificate paths, environment, and other configuration primitives.
+// OUTPUTS: Fully configured Connector instances.
+// LINKS: Core/AlfaBankConnector.php, Sbp/SbpConnector.php
+*/
+
+namespace Apoloz\AlfaBank;
+
+// <SECTION name="module_imports" intent="Import all necessary connectors, services, and configuration objects.">
+// <BELIEF_STATE "The factory needs to know about the concrete classes it will instantiate, including the connectors, config DTOs, and any default services like the CMS signer.">
+use Apoloz\AlfaBank\Core\AlfaBankConnector;
+use Apoloz\AlfaBank\Core\AlfaConfig;
+use Apoloz\AlfaBank\Enums\Environment;
+use Apoloz\AlfaBank\Services\OpenSslCmsSigner;
+use Apoloz\AlfaBank\Sbp\SbpConnector;
+// </SECTION>
+
+// <SECTION name="class_definition" intent="Define a static factory class to act as the primary entry point for the SDK.">
+// <BELIEF_STATE "A static factory provides a simple and clean entry point for users of the SDK. Instead of manually wiring up dependencies, they can call a simple method like `AlfaBank::baas(...)`, which improves developer experience.">
+class AlfaBank
+{
+    // <SECTION name="baas_connector_factory" intent="Create a fully configured connector for the Core Banking (BaaS) API.">
+    // <BELIEF_STATE "This static method encapsulates the business logic of creating a BaaS connector. It correctly instantiates the `AlfaConfig` DTO and the default `OpenSslCmsSigner`, hiding this complexity from the end-user.">
+    public static function baas(
+        string $certificatePath,
+        string $privateKeyPath,
+        Environment $environment = Environment::SANDBOX,
+        ?string $caBundlePath = null,
+        ?string $signingCertificatePath = null,
+        ?string $signingPrivateKeyPath = null
+    ): AlfaBankConnector {
+        $config = new AlfaConfig(
+            baseUrl: $environment->value,
+            certificatePath: $certificatePath,
+            privateKeyPath: $privateKeyPath,
+            caBundlePath: $caBundlePath,
+            signingCertificatePath: $signingCertificatePath,
+            signingPrivateKeyPath: $signingPrivateKeyPath
+        );
+
+        $signerCert = $signingCertificatePath ?: $certificatePath;
+        $signerKey = $signingPrivateKeyPath ?: $privateKeyPath;
+
+        $signer = new OpenSslCmsSigner($signerCert, $signerKey);
+
+        return new AlfaBankConnector($config, $signer);
+    }
+    // </SECTION>
+
+    // <SECTION name="sbp_connector_factory" intent="Create a fully configured connector for the Faster Payments (SBP) API.">
+    // <BELIEF_STATE "This method encapsulates the logic for creating an SBP connector. It correctly resolves the distinct SBP base URL based on the environment and passes the required SBP-specific parameters like `keyNameAlias`. This separation from the `baas` factory is crucial due to the different configuration requirements.">
+    public static function sbp(
+        string $certificatePath,
+        string $privateKeyPath,
+        string $keyNameAlias,
+        Environment $environment = Environment::SANDBOX,
+        ?string $caBundlePath = null,
+        ?string $signingCertificatePath = null,
+        ?string $signingPrivateKeyPath = null
+    ): SbpConnector {
+        $baseUrl = $environment === Environment::PRODUCTION 
+            ? Environment::SBP_PRODUCTION->value 
+            : Environment::SBP_SANDBOX->value;
+
+        $config = new AlfaConfig(
+            baseUrl: $baseUrl,
+            certificatePath: $certificatePath,
+            privateKeyPath: $privateKeyPath,
+            caBundlePath: $caBundlePath,
+            signingCertificatePath: $signingCertificatePath,
+            signingPrivateKeyPath: $signingPrivateKeyPath
+        );
+
+        return new SbpConnector($config, $keyNameAlias);
+    }
+    // </SECTION>
+}