Add AST cache files for AltchaService, API documentation, and AltchaService tests

- Created JSON representation of AltchaService class and its methods, including imports and relationships.
- Added documentation for the Captcha API, detailing endpoints and responses.
- Introduced test cases for AltchaService, covering various functionalities and edge cases.

src/Config/Controller/SiteConfigController.php

@@ -30,6 +30,8 @@ class SiteConfigController extends BaseController
         'max_cancel_hours_before',
         'appointment_reminder_hours',
         'log_retention_days',
+        // captcha
+        'altcha_enabled',
         // payment gateways
         'payment_test_mode',
         'payment_allowed_frontend_hosts',
@@ -47,6 +49,7 @@ class SiteConfigController extends BaseController
         private readonly SiteConfigRepository  $configRepo,
         private readonly \App\Config\Repository\TaxRateHistoryRepository $taxHistoryRepo,
         private readonly EntityManagerInterface $em,
+        private readonly \App\Shared\Captcha\AltchaService $altcha,
     ) {}
 
     #[Route('/api/v1/admin/settings', methods: ['GET'])]
@@ -55,6 +58,8 @@ class SiteConfigController extends BaseController
         $config = $this->configRepo->getAll();
         // کلید API پیامک فقط از env؛ فقط وضعیت تنظیم‌بودن برگردانده می‌شود نه مقدار.
         $config['sms_api_key_configured'] = ($_ENV['KAVENEGAR_API_KEY'] ?? '') !== '';
+        // مقدار مؤثر کپچا (override پنل اگر ست شده، وگرنه env) تا toggle درست نمایش دهد.
+        $config['altcha_enabled'] = $this->altcha->enabled() ? '1' : '0';
         return $this->success($config);
     }
 

src/Shared/Captcha/AltchaService.php

@@ -4,6 +4,7 @@ namespace App\Shared\Captcha;
 
 use AltchaOrg\Altcha\V1\Altcha;
 use AltchaOrg\Altcha\V1\ChallengeOptions;
+use App\Config\Repository\SiteConfigRepository;
 use Psr\Cache\CacheItemPoolInterface;
 
 /**
@@ -20,17 +21,26 @@ class AltchaService
 
     public function __construct(
         private readonly string $hmacKey,
-        private readonly bool $enabled,
+        private readonly bool $envEnabled,
         private readonly int $maxNumber,
         private readonly int $expireSeconds,
         private readonly CacheItemPoolInterface $altchaPool,
+        private readonly SiteConfigRepository $configRepo,
     ) {
         $this->altcha = new Altcha($this->hmacKey);
     }
 
+    /**
+     * فعال بودن کپچا: override پنل ادمین (site_config) مقدم است؛ اگر ست نشده باشد،
+     * به مقدار env (`ALTCHA_ENABLED`) برمی‌گردد. پس هم از env هم از پنل قابل کنترل است.
+     */
     public function enabled(): bool
     {
-        return $this->enabled;
+        $override = $this->configRepo->get('altcha_enabled');
+        if ($override !== null && $override !== '') {
+            return $override === '1' || strtolower($override) === 'true';
+        }
+        return $this->envEnabled;
     }
 
     /**