# افزودن endpoint لیست پرداخت‌های کاربر لاگین‌شده (`GET /api/v1/my/payments`)

## پروژه

`clinicpro` (Backend). **این پرامپت اول اجرا شود.**

> **Cross-repo:** سایت عمومی (`nobat724_front`) این endpoint را در تب «تراکنش‌ها»ی داشبورد مصرف می‌کند. پرامپت همتای frontend:
> `nobat724_front/.claude/prompt/fix-dashboard-uuid-and-lists.md`

## زمینه

داشبورد کاربر در سایت عمومی تب «تراکنش‌ها» دارد که `request.getMyPayments(userId)` را صدا می‌زند → `GET /api/v1/payment/my-payments/{userId}`. اما **چنین route‌ای در backend وجود ندارد** (تأییدشده با `debug:router`): تنها endpointهای پرداخت، `GET /api/v1/payment/{uuid}` (تک پرداخت) و `GET /api/v1/admin/payments` (ادمین) هستند. در نتیجه تب تراکنش‌ها همیشه **404** می‌گیرد.

`Payment` به `user` (پرداخت‌کننده) لینک دارد و `toArray()` دارد، ولی `PaymentRepository` متد `findByUser` ندارد.

## مشکل / هدف

یک endpoint عمومی-برای-کاربر بساز: `GET /api/v1/my/payments` که **پرداخت‌های خودِ کاربر لاگین‌شده** را (از روی توکن، نه از روی userId در URL) به‌صورت لیست برمی‌گرداند. الگو دقیقاً مثل `MyAppointmentsController` و قرارداد پاسخ مثل بقیه‌ی listهای کاربر.

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

| فایل | نقش |
|------|-----|
| `src/Payment/Controller/PaymentController.php` | افزودن متد `myPayments()` (یا کنترلر `MyPaymentsController` جدید) |
| `src/Payment/Repository/PaymentRepository.php` | افزودن `findByUser(User $user, ?string $status, int $page, int $limit)` |
| `src/Payment/Entity/Payment.php` | `getUser()`, `toArray()` موجود |
| `src/Appointment/Controller/MyAppointmentsController.php` | مرجع الگو (CurrentUser, paginated) |
| `docs/api/payment.md` | مستندسازی endpoint جدید |

## وضعیت فعلی (کد واقعی)

### `PaymentRepository` — بدون findByUser

```php
public function findByUuid(string $uuid): ?Payment { ... }
public function findByOrderId(string $orderId): ?Payment { ... }
public function save(Payment $entity, bool $flush = true): void { ... }
```

### `Payment` — لینک user + toArray

```php
#[ORM\JoinColumn(name: 'user_id', ...)] private User $user;
public function getUser(): User { return $this->user; }
public function getOrderId(): string { ... }
public function getAmountRials(): int { ... }
public function getStatus(): string { ... }
public function toArray(): array { ... }   // شکل پرداخت
```

### route ناموجود که فرانت صدا می‌زند

```
GET /api/v1/payment/my-payments/{userId}   → 404 (وجود ندارد)
```

## وظایف

### ۱. `findByUser` در `PaymentRepository`

```php
/** @return Payment[] */
public function findByUser(User $user, ?string $status = null, int $page = 1, int $limit = 20): array
{
    $qb = $this->createQueryBuilder('p')
        ->where('p.user = :user')->setParameter('user', $user)
        ->orderBy('p.createdAt', 'DESC')
        ->setFirstResult(($page - 1) * $limit)
        ->setMaxResults($limit);
    if ($status !== null) {
        $qb->andWhere('p.status = :status')->setParameter('status', $status);
    }
    return $qb->getQuery()->getResult();
}

public function countByUser(User $user, ?string $status = null): int
{
    $qb = $this->createQueryBuilder('p')->select('COUNT(p.id)')
        ->where('p.user = :user')->setParameter('user', $user);
    if ($status !== null) {
        $qb->andWhere('p.status = :status')->setParameter('status', $status);
    }
    return (int) $qb->getQuery()->getSingleScalarResult();
}
```

> از `User` به‌جای `user_id` در DQL استفاده کن (`App\Auth\Entity\User` را import کن). status اختیاری (`pending`/`paid`/`failed`/...).

### ۲. endpoint `GET /api/v1/my/payments`

در `PaymentController` (یا کنترلر جدید `MyPaymentsController` هم‌سبک با `MyAppointmentsController`):

```php
#[Route('/api/v1/my/payments', methods: ['GET'])]
#[IsGranted('IS_AUTHENTICATED_FULLY')]
public function myPayments(Request $request, #[CurrentUser] User $user): JsonResponse
{
    $page   = max(1, (int) $request->query->get('page', 1));
    $limit  = min(100, max(1, (int) $request->query->get('limit', 20)));
    $status = $request->query->get('status');

    $items = array_map(
        fn(Payment $p) => $p->toArray(),
        $this->paymentRepo->findByUser($user, $status, $page, $limit)
    );
    $total = $this->paymentRepo->countByUser($user, $status);

    return $this->paginated($items, $total, $page, $limit);
}
```

> از `paginated()` استفاده کن (نه success تودرتو) تا فرانت items را از `data` و total را از `meta.totalRecords` بخواند — هم‌خوان با بقیه‌ی listها. **کاربر فقط پرداخت‌های خودش را می‌بیند** (از `#[CurrentUser]`؛ هیچ userId از URL گرفته نمی‌شود).

### ۳. مطمئن شو route عمومی/auth درست است

- `/api/v1/my/payments` زیر فایروال `^/api` با `IS_AUTHENTICATED_FULLY` می‌افتد (نیاز به whitelist عمومی ندارد چون کاربر لاگین است). نیازی به تغییر `security.yaml` نیست. تأیید کن با `debug:router`.

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

در `docs/api/payment.md`: endpoint `GET /api/v1/my/payments` با permission، query params (`page`, `limit`, `status`)، و نمونه‌ی پاسخ paginated واقعی (items + meta).

## نکات مهم

- **هیچ migration لازم نیست** (فقط query + route).
- **امنیت:** هرگز `userId` از URL نگیر؛ فقط `#[CurrentUser]`. کاربر نباید پرداخت دیگران را ببیند.
- پاسخ‌ها از `BaseController`؛ این endpoint باید `paginated()` بدهد (نه `success(['data'=>...])`) — فرانت `data` (آرایه) و `meta.totalRecords` می‌خواند.
- `toArray()` پرداخت شکل واقعی را می‌دهد؛ اگر فیلدی برای نمایش لازم است (مبلغ، وضعیت، تاریخ، نوع، order_id، appointment_uuid) و در `toArray` نیست، اضافه کن.
- تست:
  - `ddev exec php -l` روی فایل‌های تغییر یافته
  - `ddev exec php bin/console cache:clear`
  - `ddev exec php bin/console debug:router | grep "my/payments"`
  - با توکن یک کاربر (مثلاً `09210651788` که یک پرداخت آزمایشی دارد): `GET /api/v1/my/payments` → ۲۰۰ با لیست پرداخت‌های همان کاربر؛ بدون توکن → ۴۰۱.
  - `docs/api/payment.md` به‌روز شود.