refactor(core): enhance SDK structure and documentation

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

tests/Feature/ErrorHandlingTest.php

@@ -0,0 +1,40 @@
+<?php
+
+use Apoloz\AlfaBank\Core\AlfaBankConnector;
+use Apoloz\AlfaBank\Core\AlfaConfig;
+use Apoloz\AlfaBank\Exceptions\AlfaBankException;
+use Apoloz\AlfaBank\Requests\Auth\GetTokenRequest;
+use Saloon\Http\Faking\MockResponse;
+
+test('it throws AlfaBankException on BaaS error', function () {
+    $mockClient = new \Saloon\Http\Faking\MockClient([
+        GetTokenRequest::class => MockResponse::make([
+            'error' => 'invalid_client',
+            'error_description' => 'Bad client secret'
+        ], 401, ['Content-Type' => 'application/json']),
+    ]);
+
+    $config = createTestConfig();
+    $connector = new AlfaBankConnector($config);
+    $connector->withMockClient($mockClient);
+
+    $connector->login('id', 'secret');
+})->throws(AlfaBankException::class, 'Alfa Bank API Error: [invalid_client] Bad client secret');
+
+test('it throws AlfaBankException on SBP error', function () {
+    $mockClient = new \Saloon\Http\Faking\MockClient([
+        '*' => MockResponse::make([
+            'ErrorCode' => 'RQ05014',
+            'message' => 'Invalid amount'
+        ], 200, ['Content-Type' => 'application/json']), // SBP often returns 200 even on errors
+    ]);
+
+    $config = createTestConfig();
+    $connector = new \Apoloz\AlfaBank\Sbp\SbpConnector($config, 'alias');
+    $connector->withMockClient($mockClient);
+
+    $connector->send(new class extends \Saloon\Http\Request {
+        protected \Saloon\Enums\Method $method = \Saloon\Enums\Method::GET;
+        public function resolveEndpoint(): string { return '/'; }
+    });
+})->throws(AlfaBankException::class, 'Alfa Bank API Error: [RQ05014] Invalid amount');