clinicpro/.claude/prompt/maintenance-mode.md

# Maintenance Mode مرکزی (Web + API + پنل‌ها)

## پروژه

`clinicpro` (backend Symfony + پنل ادمین React)

کنترل مرکزی کاملاً در backend انجام می‌شود؛ چون `nobat724_front` و `clinic-pro-tauri` هر دو کلاینت همان `/api/v1/...` هستند، وقتی API با `503` پاسخ دهد آن‌ها هم عملاً وارد حالت تعمیرات می‌شوند. **نیازی به تغییر جداگانه در آن ریپوها نیست** (اختیاری: نمایش زیباتر پیام در فرانت — خارج از این پرامپت).

## زمینه

پروژه از قبل یک key-value store برای تنظیمات سایت دارد:

- Entity: `src/Config/Entity/SiteConfig.php` (`config_key` PK، `config_value` text، `updated_at` int)
- Repository: `src/Config/Repository/SiteConfigRepository.php` — `DEFAULTS` const، `get()`، `getAll()`، `set()`
- Controller: `src/Config/Controller/SiteConfigController.php` — `GET/PATCH /api/v1/admin/settings` با `#[IsGranted('ROLE_ADMIN')]` و whitelist `ALLOWED_KEYS`
- صفحه ادمین: `assets/admin/pages/SettingsPage.tsx` (route `settings` در `assets/admin/App.tsx:201`)

پس **نباید Entity جدید ساخت** — فقط کلید جدید به همین جدول اضافه می‌شود؛ **migration لازم نیست**.

همچنین چهار EventSubscriber در `src/Shared/EventSubscriber/` وجود دارد که الگوی موجود پروژه است:

| کلاس | رویداد | priority |
|---|---|---|
| `ExceptionSubscriber` | `kernel.exception` | 10 |
| `NumericFieldNormalizerSubscriber` | `kernel.request` | 8 |
| `AdminCspSubscriber` | `kernel.response` | 0 |
| `SecurityHeadersSubscriber` | `kernel.response` | 0 |

## هدف

یک Maintenance Mode حرفه‌ای که:

- با یک سوییچ از پنل ادمین کل سیستم (Web + API + همه کلاینت‌ها) وارد حالت تعمیرات شود
- کاربر عادی فقط صفحه/پاسخ maintenance ببیند
- فقط `ROLE_ADMIN` بتواند وارد شود و از پنل ادمین استفاده کند
- پیام و عنوان صفحه maintenance از پنل ادمین قابل ویرایش باشد
- کنترل **مرکزی** باشد (یک `kernel.request` subscriber) نه پراکنده در کنترلرها

## فایل‌های مرتبط

| فایل | نقش |
|------|-----|
| `src/Config/Repository/SiteConfigRepository.php` | افزودن کلیدهای جدید به `DEFAULTS` + کش |
| `src/Config/Controller/SiteConfigController.php` | افزودن کلیدها به `ALLOWED_KEYS` |
| `src/Config/Service/MaintenanceService.php` | **جدید** — منبع واحد تصمیم maintenance |
| `src/Shared/EventSubscriber/MaintenanceSubscriber.php` | **جدید** — کنترل مرکزی روی `kernel.request` |
| `src/Shared/Controller/HealthController.php` | باید در whitelist بماند |
| `src/Admin/Controller/AdminController.php` | catch-all `/admin/{reactRouting}` — SPA shell |
| `templates/maintenance.html.twig` | **جدید** — صفحه HTML حالت تعمیرات |
| `assets/admin/pages/SettingsPage.tsx` | افزودن بخش «حالت تعمیرات» |
| `docs/api/admin.md` | مستندسازی کلیدهای جدید + رفتار 503 |

## وضعیت فعلی

`src/Config/Repository/SiteConfigRepository.php:11`

```php
class SiteConfigRepository extends ServiceEntityRepository
{
    public const DEFAULTS = [
        'site_name' => '...',
        // ... ~28 کلید
    ];

    public function get(string $key): ?string { /* DB، fallback به DEFAULTS */ }
    public function getAll(): array { /* findAll() + پر کردن با DEFAULTS */ }
    public function set(string $key, ?string $value): void { /* بدون flush */ }
}
```

`src/Config/Controller/SiteConfigController.php:18`

```php
private const ALLOWED_KEYS = [ /* whitelist 28 کلید */ ];
// PATCH کلیدهای خارج از whitelist را بی‌صدا نادیده می‌گیرد
```

`src/Shared/EventSubscriber/NumericFieldNormalizerSubscriber.php:34` — الگوی subscriber روی `kernel.request`:

```php
public static function getSubscribedEvents(): array
{
    return [KernelEvents::REQUEST => ['onKernelRequest', 8]];
}
```

`config/packages/security.yaml` — **بدون `role_hierarchy`**؛ نقش‌ها تخت‌اند. `/admin/*` در هیچ firewall pattern نیست (HTML عمومی؛ auth سمت کلاینت + روی `/api/v1`).

`config/packages/cache.yaml` — app pool روی `cache.adapter.redis` (`REDIS_URL`). هیچ‌جا `SiteConfig` کش نمی‌شود.

---

## وظایف

### ۱. افزودن کلیدهای تنظیمات

در `SiteConfigRepository::DEFAULTS` این کلیدها اضافه شوند:

```php
'maintenance_enabled'      => '0',
'maintenance_title'        => 'در حال به‌روزرسانی سیستم',
'maintenance_message'      => 'سامانه موقتاً برای انجام عملیات فنی در دسترس نیست. لطفاً چند دقیقه دیگر مجدداً تلاش کنید.',
'maintenance_retry_after'  => '600',   // ثانیه — هدر Retry-After
'maintenance_allowed_ips'  => '',      // CSV، اختیاری — دور زدن maintenance برای IP خاص
```

همین پنج کلید به `SiteConfigController::ALLOWED_KEYS` اضافه شوند تا از `PATCH /api/v1/admin/settings` قابل تغییر باشند.

**نکته:** `maintenance_enabled` باید boolean-ish پارس شود (`'1'`, `'true'`, `'on'` → true). مقدار ورودی از PATCH ممکن است `true` boolean یا `"1"` باشد.

### ۲. کش کردن خواندن تنظیمات (الزامی، نه اختیاری)

`MaintenanceSubscriber` روی **هر** درخواست اجرا می‌شود؛ زدن به DB در هر request قابل قبول نیست.

در `MaintenanceService` مقدار را از `CacheInterface` (app pool، همان الگوی `TokenService.php:15`) با TTL کوتاه (مثلاً ۳۰ ثانیه) بخوان:

```php
final class MaintenanceService
{
    private const CACHE_KEY = 'maintenance_state';
    private const TTL = 30;

    public function __construct(
        private SiteConfigRepository $configRepo,
        private CacheInterface $cache,
    ) {}

    /** @return array{enabled:bool,title:string,message:string,retryAfter:int,allowedIps:string[]} */
    public function getState(): array
    {
        return $this->cache->get(self::CACHE_KEY, function (ItemInterface $item): array {
            $item->expiresAfter(self::TTL);
            // خواندن ۵ کلید از configRepo و نرمال‌سازی نوع
        });
    }

    public function invalidate(): void
    {
        $this->cache->delete(self::CACHE_KEY);
    }
}
```

در `SiteConfigController` بعد از هر `PATCH` موفق روی هر کلید `maintenance_*`، متد `invalidate()` صدا زده شود تا تغییر فوراً اعمال شود (نه بعد از ۳۰ ثانیه).

**Edge case:** اگر Redis در دسترس نبود، `getState()` نباید کل سایت را down کند — استثنا را بگیر و مستقیم از DB بخوان؛ اگر DB هم خطا داد `enabled => false` برگردان (fail-open). Maintenance mode نباید خودش عامل قطعی شود.

### ۳. Subscriber مرکزی

فایل جدید `src/Shared/EventSubscriber/MaintenanceSubscriber.php`، دقیقاً با الگوی سایر subscriberها در همان پوشه.

```php
public static function getSubscribedEvents(): array
{
    // priority بالا تا قبل از firewall/router کار کند اما بعد از تشخیص مسیر
    return [KernelEvents::REQUEST => ['onKernelRequest', 6]];
}
```

منطق:

```
if (!$event->isMainRequest()) return;
if (!$state['enabled']) return;

$path = $request->getPathInfo();

// 1) whitelist مسیرهایی که هرگز نباید بلاک شوند
if (isWhitelisted($path)) return;

// 2) IP allowlist
if (in_array($request->getClientIp(), $state['allowedIps'], true)) return;

// 3) اگر کاربر لاگین‌شده ROLE_ADMIN دارد → عبور
if ($this->security->isGranted('ROLE_ADMIN')) return;

// 4) بلاک
$event->setResponse($this->buildResponse($request, $state));
$event->stopPropagation();
```

**whitelist مسیرها (بحرانی — بدون این، ادمین قفل بیرون می‌ماند):**

- `/api/v1/auth/*` (کل مسیرهای ورود/OTP/refresh token) — وگرنه ادمین نمی‌تواند لاگین کند
- `/api/v1/admin/settings` (GET و PATCH) — وگرنه راه خاموش کردن maintenance بسته می‌شود
- مسیر health check از `src/Shared/Controller/HealthController.php`
- `/admin` و `/admin/*` (SPA shell) — خودِ HTML باید بارگذاری شود؛ محافظت واقعی روی `/api/v1` است
- asset‌های Encore (`/build/*`) و `/favicon.ico`
- در محیط `dev`: `/_wdt/*`، `/_profiler/*`

whitelist را به‌صورت آرایه‌ی const از prefixها در همان کلاس تعریف کن، نه پراکنده در if.

**نکته ترتیب اجرا:** `Security::isGranted()` نیاز به توکن firewall دارد. Firewall listener روی `kernel.request` با priority `8` اجرا می‌شود. اگر priority انتخابی باعث شود توکن هنوز ست نشده باشد، `isGranted` همیشه false برمی‌گرداند و ادمین هم بلاک می‌شود. **این را عملاً تست کن**: با کاربر ادمین لاگین‌شده و maintenance روشن، یک endpoint معمولی `/api/v1/...` را صدا بزن و مطمئن شو `200` می‌گیری نه `503`. اگر بلاک شد، priority را پایین‌تر از firewall ببر (عدد کوچک‌تر) تا بعد از authentication اجرا شود.

### ۴. تفکیک پاسخ API از پاسخ Web

`buildResponse()` باید بر اساس نوع درخواست تصمیم بگیرد:

**درخواست API** — اگر `str_starts_with($path, '/api/')` یا هدر `Accept` شامل `application/json` بود:

```php
return new JsonResponse([
    'success' => false,
    'data' => null,
    'errors' => [[
        'code' => 'MAINTENANCE_MODE',
        'message' => $state['message'],
    ]],
], 503, ['Retry-After' => (string) $state['retryAfter']]);
```

فرمت دقیقاً باید با envelope خطای `BaseController::error()` (`src/Shared/Controller/BaseController.php:32`) یکی باشد تا `nobat724_front/services/response.js` و `clinic-pro-tauri/src/service/response.js` بدون تغییر بتوانند آن را parse کنند.

**درخواست Web** — رندر `templates/maintenance.html.twig` با status `503` و همان هدر `Retry-After`.

قالب باید:
- RTL، فارسی، فونت Vazir (هماهنگ با بقیه templateها)
- بدون وابستگی به build اسِت‌ها (CSS اینلاین) — چون ممکن است در حین deploy اجرا شود
- `title` و `message` را از state بگیرد
- `noindex` در متا (`<meta name="robots" content="noindex">`) تا صفحه تعمیرات ایندکس نشود

### ۵. تعامل با `ExceptionSubscriber`

`ExceptionSubscriber` روی `kernel.exception` با priority `10` است. چون maintenance پاسخ را روی `kernel.request` ست می‌کند و exception پرتاب نمی‌کند، تداخلی نباید باشد — اما بررسی کن که `setResponse()` + `stopPropagation()` باعث رد شدن از `SecurityHeadersSubscriber` (روی `kernel.response`) نشود. `stopPropagation` فقط روی همان event اثر دارد، پس `kernel.response` همچنان اجرا می‌شود — تأیید کن هدرهای امنیتی روی پاسخ 503 هم ست می‌شوند.

### ۶. UI پنل ادمین

در `assets/admin/pages/SettingsPage.tsx` یک بخش (Card/Section هم‌شکل با بخش‌های موجود همان فایل) با عنوان «حالت تعمیرات» اضافه کن:

- سوییچ/چک‌باکس `maintenance_enabled`
- `TextField` برای `maintenance_title`
- `TextField` چندخطی برای `maintenance_message`
- عدد برای `maintenance_retry_after` (ثانیه)
- ورودی متنی `maintenance_allowed_ips` (CSV) با helper text

الزامات UI:

- **حتماً از کامپوننت‌ها و تم موجود همان صفحه استفاده کن؛ طراحی جدید نساز.** اگر `select` لازم شد، `SearchableSelect` استفاده شود نه `<select>` بومی.
- وقتی سوییچ روشن می‌شود، قبل از ذخیره یک تأیید (confirm dialog) نشان بده — این عمل کل سایت را برای کاربران عادی از دسترس خارج می‌کند.
- وقتی maintenance فعال است، یک بنر هشدار ثابت و واضح در بالای صفحه (یا `Topbar`) نمایش داده شود تا ادمین فراموش نکند سایت down است.
- خواندن/نوشتن دقیقاً از همان `GET/PATCH /api/v1/admin/settings` موجود؛ endpoint جدید نساز.
- دسترسی صفحه فقط نقش `admin` (همان الگوی `RoleRoute` در `App.tsx`).

### ۷. دستور کنسول (اختیاری اما توصیه‌شده)

یک command مثل `app:maintenance` با آرگومان `on|off|status` بساز تا اگر پنل ادمین به هر دلیل در دسترس نبود، از طریق `ddev exec php bin/console app:maintenance off` بتوان خارج شد. باید بعد از تغییر، کش را `invalidate()` کند.

## نکات مهم

- **Entity جدید نساز و migration ننویس** — `SiteConfig` کافی است.
- Fail-open الزامی است: هر خطای Redis/DB داخل `MaintenanceService` نباید سایت را بلاک کند.
- بدون کش، subscriber به‌ازای هر request یک کوئری می‌زند — این را حتماً پیاده کن.
- `role_hierarchy` وجود ندارد؛ `ROLE_ADMIN` باید مستقیم در `roles` کاربر باشد. فرض نکن نقش‌های دیگر آن را ارث می‌برند.
- کاربران با نقش `ROLE_DOCTOR` / `ROLE_CLINIC` / `ROLE_SECRETARY` **باید** بلاک شوند — فقط ادمین عبور می‌کند.
- پاسخ 503 برای API باید دقیقاً envelope خطای پروژه را داشته باشد؛ اگر شکل متفاوتی برگردانی، کلاینت‌های `nobat724_front` و `clinic-pro-tauri` هنگام parse خطا می‌دهند.
- بعد از اتمام، `docs/api/admin.md` را به‌روز کن: کلیدهای جدید تنظیمات + توضیح رفتار `503 MAINTENANCE_MODE` و هدر `Retry-After` روی همه endpointها.
- تست دستی الزامی (با اکانت `09390039833 / 09390039833`):
  1. maintenance روشن → کاربر ناشناس روی `/api/v1/doctor` باید `503` بگیرد
  2. کاربر ادمین لاگین‌شده روی همان endpoint باید `200` بگیرد
  3. `POST /api/v1/auth/...` (لاگین) باید در حالت maintenance کار کند
  4. `PATCH /api/v1/admin/settings` با `maintenance_enabled=0` باید سایت را فوراً برگرداند (نه بعد از ۳۰ ثانیه)
  5. باز کردن `/` در مرورگر → صفحه HTML تعمیرات با status 503