# نمایش تعلق دکتر به نماینده + صفحه‌ی نماینده با تعداد دکتر و نوبت

## زمینه

هر دکتر از طریق ستون `doctors.representation_id` (FK به `representations.id`) به یک نماینده وصل می‌شود؛ این ستون **از قبل وجود دارد** و هنگام ثبتِ دکتر توسط نماینده مقداردهی می‌شود (`RepresentationActionController::registerDoctor` → `setRepresentationId`). اما این تعلق **هیچ‌جا در پنل ادمین دیده نمی‌شود**: نه در لیست دکترها، نه در پروفایل دکتر، و صفحه‌ی نماینده‌ها تعداد دکتر و نوبت نماینده را نشان نمی‌دهد. هدف: مرئی‌کردن این رابطه در ادمین. **نیازی به migration نیست** — فقط expose و UI.

## مشکل / هدف

1. در لیست و پروفایل دکترِ ادمین، مشخص باشد دکتر به کدام نماینده تعلق دارد (نام + لینک به نماینده).
2. در صفحه‌ی نماینده‌ها (`RepresentationsPage`) هر نماینده ستون «تعداد پزشکان» و «تعداد نوبت» داشته باشد.
3. در جزئیات نماینده (`RepresentationDetailPage`) بشود پزشکان زیرمجموعه و نوبت‌های آن نماینده را دید.

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

| فایل | نقش |
|------|-----|
| `src/Doctor/Entity/Doctor.php` | `representationId` (ستون L76-77، getter L217)؛ `toDetailArray()` L530 — الان نماینده را برنمی‌گرداند |
| `src/Doctor/Controller/DoctorController.php` | `show()` L149-173 — `GET /api/v1/doctor/{uuid}`؛ پنل ادمینِ پروفایل دکتر از همین می‌خواند (`DoctorDetailPage.tsx:2363`) |
| `src/Admin/Controller/AdminApiController.php` | `doctorsList` (SELECT L350-359)؛ `representations` (L1016-1082) |
| `src/Representation/Repository/RepresentationRepository.php` | برای resolve نامِ نماینده از روی id |
| `assets/admin/pages/DoctorsPage.tsx` | لیست دکتر ادمین (fetch L144) |
| `assets/admin/pages/DoctorDetailPage.tsx` | پروفایل دکتر ادمین (fetch L2358-2364) |
| `assets/admin/pages/RepresentationsPage.tsx` | لیست نماینده‌ها (fetch L51-56) |
| `assets/admin/pages/RepresentationDetailPage.tsx` | جزئیات نماینده (fetch `/api/v1/representation/{uuid}` L42) |
| `docs/api/admin.md`, `docs/api/doctor.md` | مستندسازی |

## وضعیت فعلی

**الگوی aggregateِ آماده (برای adaptation)** — شمارش دکتر نماینده (`RepresentationActionController.php:606`):
```php
$total  = (int) $conn->fetchOne('SELECT COUNT(*) FROM doctors WHERE representation_id = ?', [$repId]);
```
نوبت‌های نماینده (`RepresentationActionController.php:673` تقریبی): `JOIN a.doctor d WHERE d.representationId = :repId`.

**لیست دکتر ادمین** الان نماینده را select نمی‌کند (`AdminApiController.php:350-359`):
```php
$rows = $conn->fetchAllAssociative(
    "SELECT d.id, d.uuid, d.name, ..., d.owner_status, d.source,
            u.mobile_number as user_mobile, u.email
     FROM doctors d JOIN users u ON u.id = d.user_id
     WHERE $whereStr ORDER BY $orderBy LIMIT $limit OFFSET $offset", $params);
```

**لیست نماینده‌ها** بدون تعداد دکتر/نوبت (`AdminApiController.php:1063-1078`):
```php
return [
    'id' => (int) $r['id'], ...,
    'commission_percent' => (float) $r['commissionPercent'],
    'wallet_balance'     => 0,
    'is_active'          => (bool) $r['active'],
    'created_at'         => date('c', (int) $r['createdAt']),
];
```

**پروفایل دکترِ ادمین** از `toDetailArray()` تغذیه می‌شود که `representation` ندارد.

## وظایف

### ۱. Backend — expose نماینده روی جزئیات دکتر (`show()`)

در `DoctorController::show()` بعد از ساخت آرایه‌ی دکتر، نماینده را از روی `representation_id` resolve کن و merge کن (مثل الگوی `clinics` که همان‌جا merge می‌شود). `null` اگر دکتر نماینده ندارد (مثل ایمپورت‌های IRIMC):
```php
$repId = $doctor->getRepresentationId();
$rep   = $repId ? $this->representationRepo->find($repId) : null;
$data  = array_merge($doctor->toDetailArray($schedule), [
    'clinics'        => $clinicData,
    'representation' => $rep ? ['id' => $rep->getId(), 'uuid' => $rep->getUuid(), 'full_name' => $rep->getFullName()] : null,
]);
```
`RepresentationRepository` را به constructor تزریق کن (اگر نیست). پاسخ همچنان double-nested است؛ شکل را نشکن.

### ۲. Backend — لیست دکتر ادمین: افزودن نماینده

در `AdminApiController::doctorsList` کوئری را `LEFT JOIN representations` کن و دو ستون اضافه کن:
```php
"SELECT d.id, ..., d.owner_status, d.source,
        d.representation_id, rep.full_name AS representation_name,
        u.mobile_number as user_mobile, u.email
 FROM doctors d JOIN users u ON u.id = d.user_id
 LEFT JOIN representations rep ON rep.id = d.representation_id
 WHERE $whereStr ORDER BY $orderBy LIMIT $limit OFFSET $offset"
```
و در `array_map` خروجی:
```php
'representation_id'   => $d['representation_id'] !== null ? (int) $d['representation_id'] : null,
'representation_name' => $d['representation_name'] ?? null,
```

### ۳. Backend — لیست نماینده‌ها: تعداد دکتر + نوبت

در `AdminApiController::representations` بعد از گرفتن `$rows` و `$repIds`، دو شمارش گروهی با یک کوئری هرکدام بگیر (نه N+1):
```php
$docCounts = [];   // representation_id => count
$apptCounts = [];  // representation_id => count
if ($repIds !== []) {
    foreach ($this->em->getConnection()->fetchAllAssociative(
        'SELECT representation_id, COUNT(*) c FROM doctors
         WHERE representation_id IN (?) GROUP BY representation_id',
        [$repIds], [\Doctrine\DBAL\ArrayParameterType::INTEGER]) as $row) {
        $docCounts[(int) $row['representation_id']] = (int) $row['c'];
    }
    foreach ($this->em->getConnection()->fetchAllAssociative(
        'SELECT d.representation_id, COUNT(*) c FROM appointments a
         JOIN doctors d ON d.id = a.doctor_id
         WHERE d.representation_id IN (?) GROUP BY d.representation_id',
        [$repIds], [\Doctrine\DBAL\ArrayParameterType::INTEGER]) as $row) {
        $apptCounts[(int) $row['representation_id']] = (int) $row['c'];
    }
}
```
و در آیتم خروجی:
```php
'doctor_count'      => $docCounts[(int) $r['id']] ?? 0,
'appointment_count' => $apptCounts[(int) $r['id']] ?? 0,
```

### ۴. Backend — endpoint پزشکان یک نماینده (برای صفحه‌ی جزئیات)

یک endpoint ادمین اضافه کن: `GET /api/v1/admin/representations/{uuid}/doctors` (paginated) که پزشکان `representation_id = rep.id` را برمی‌گرداند (همان الگوی `d.representation_id = :repId`). `$this->paginated(...)`. برای نوبت‌ها می‌توانی از `appointment_count` تجمیعی وظیفه‌ی ۳ در خود صفحه استفاده کنی، یا در صورت نیاز endpoint مشابه `.../appointments` بساز.

### ۵. Frontend — ستون «نماینده» در لیست و کارت در پروفایل دکتر

- `DoctorsPage.tsx`: به `AdminDoctor` تایپ `representation_id`/`representation_name` اضافه کن و یک ستون «نماینده» در `<DataTable>` نشان بده؛ اگر null → «بدون نماینده». (فقط حالت ادمین؛ نقش representation خودش زیرمجموعه است.)
- `DoctorDetailPage.tsx`: یک بخش/کارت «نماینده» با نام و لینک به `/representations/${representation.uuid}` از `data.representation` بساز؛ اگر null → «این پزشک به نماینده‌ای متصل نیست».

### ۶. Frontend — ستون‌های نماینده + بخش پزشکان/نوبت‌ها

- `RepresentationsPage.tsx`: دو ستون «تعداد پزشکان» (`doctor_count`) و «تعداد نوبت» (`appointment_count`) در جدول.
- `RepresentationDetailPage.tsx`: یک بخش «پزشکان این نماینده» با `useQuery` روی `/api/v1/admin/representations/${uuid}/doctors` (paginated: items از `data?.data`) و نمایش `appointment_count`/`doctor_count`.

### ۷. مستندسازی

- `docs/api/admin.md`: فیلدهای جدید `doctor_count`/`appointment_count` در پاسخ `representations`؛ فیلدهای `representation_id`/`representation_name` در `doctors`؛ endpoint جدید `GET /api/v1/admin/representations/{uuid}/doctors`.
- `docs/api/doctor.md`: فیلد `representation` در پاسخ single (`show`).

## نکات مهم

- **بدون migration**: `representation_id` از قبل روی `doctors` هست (Doctor.php:76). فقط expose.
- **ایمپورت‌های IRIMC** `representation_id = NULL` دارند (فقط `managed_by` ست می‌شود، `DoctorImportService.php:106`) — در UI «بدون نماینده» نشان بده؛ **auto-assign نکن** (خارج از دامنه‌ی این تسک).
- **پاسخ‌ها**: paginated → items از `data?.data`، total از `data?.meta?.totalRecords`؛ single (`show`) → double-nested `data?.data?.data`. همه‌ی endpointها از `BaseController` (`success`/`paginated`).
- شمارش‌ها گروهی (`GROUP BY ... IN (?)`) باشند تا N+1 نشود؛ همان الگوی `cityNames` موجود در `representations` (AdminApiController.php:1048).
- `show()` عمومی است و توسط `nobat724_front` هم مصرف می‌شود؛ افزودن `representation` مشکلی ایجاد نمی‌کند (سایت آن را نادیده می‌گیرد) ولی شکل پاسخ را تغییر نده.
- تاریخ‌ها Unix timestamp؛ نمایش با `formatDate()` شمسی.
- تست: `ddev exec php -l ...`، `ddev exec php bin/console cache:clear`، `ddev exec yarn dev`، `ddev exec php bin/console debug:router | grep representations`.