feat(payment): unify payment flow with new pure redirect entry and update related endpoints
This commit is contained in:
hamed
@@ -0,0 +1,159 @@
|
||||
# یکسانسازی کامل پرداخت به یک Flow واحد + entry ریدایرکت خالص (Backend + Admin)
|
||||
|
||||
## پروژه
|
||||
|
||||
`clinicpro` (Backend + Admin SPA). **cross-repo** — پرامپت همتا: `nobat724_front/.claude/prompt/payment-single-flow-frontend.md` (سایت عمومی entry پرداخت را مصرف میکند؛ Backend اول اجرا شود).
|
||||
|
||||
## زمینه
|
||||
|
||||
بعد از بازطراحیهای قبلی، بخش زیادی از «flow واحد» موجود است و **نباید دوباره ساخته شود**:
|
||||
|
||||
- `PaymentManager` (`src/Payment/Service/PaymentManager.php`): تنها جایی که با درگاه صحبت میکند و verify (transaction+قفل+idempotent+post-action+log) را انجام میدهد.
|
||||
- `GatewayFactory`: Factory/Strategy انتخاب درگاه.
|
||||
- `GET /api/v1/payment/pay/{orderId}` (عمومی): ارتباط با بانک + انتقال 302/فرم POST.
|
||||
- `callback/{gateway}` → `PaymentManager::processCallback` → 302 به `frontend_address` (دامنهٔ مبدأ با `status`).
|
||||
- appointment و subscription: POST فقط `Payment` میسازد و `pay_url` میدهد؛ سپس همان pay-endpoint.
|
||||
|
||||
اما دو انحراف از «تنها یک روش پرداخت» باقی مانده که این پرامپت آنها را رفع میکند:
|
||||
|
||||
1. **`SmsWalletController::charge` یک Flow پرداخت جداگانه است** — خودش درگاه را resolve میکند (`mellat/sep/mock` با `match`)، خودش `new Payment` + `$gateway->initiate(...)` را صدا میزند و `redirect_url` بانک را برمیگرداند. این نقض «یک flow واحد» است و باید حذف و به flow واحد منتقل شود.
|
||||
2. **entry پرداخت هنوز نیازمند یک XHR است** (POST برای ساخت `Payment` سپس ریدایرکت به `pay_url`). طبق نیاز جدید باید یک entry ریدایرکتِ خالص هم وجود داشته باشد: مرورگر مستقیماً به `GET /api/v1/payment/order/{appointmentUuid}` برود و Backend همهٔ کار (اعتبارسنجی + ساخت Payment + ارتباط با بانک + ریدایرکت به شاپرک) را انجام دهد.
|
||||
|
||||
## مشکل / هدف
|
||||
|
||||
- تنها **یک** مسیر ساخت/شروع پرداخت در کل backend وجود داشته باشد: ساخت `Payment` (هر `type`) → `PaymentManager::startGatewayHandoff` → بانک → `callback` → `PaymentManager::processCallback` → ریدایرکت به دامنهٔ مبدأ.
|
||||
- هیچ کنترلری غیر از `PaymentManager` نباید `->initiate(` یا resolve مستقیم درگاه داشته باشد.
|
||||
- افزودن entry ریدایرکتِ خالص `GET /api/v1/payment/order/{appointmentUuid}` (بدون XHR) برای مسیر نوبت.
|
||||
|
||||
## فایلهای مرتبط
|
||||
|
||||
| فایل | نقش |
|
||||
|------|-----|
|
||||
| `src/Sms/Controller/SmsWalletController.php` | **حذف flow جدا**: متد `charge` باید فقط Payment بسازد و `pay_url` بدهد |
|
||||
| `src/Payment/Controller/PaymentController.php` | افزودن `GET /payment/order/{appointmentUuid}`؛ نگهداشتن pay/callback |
|
||||
| `src/Payment/Service/PaymentManager.php` | موجود — منبع واحد ارتباط با درگاه (بدون تغییر بزرگ) |
|
||||
| `src/Payment/Gateway/GatewayFactory.php` | موجود — resolve/activeGateways |
|
||||
| `src/Payment/Repository/PaymentRepository.php` | موجود `findPendingByAppointment` برای جلوگیری از pending تکراری |
|
||||
| `config/packages/security.yaml` | `^/api/v1/payment/order/` عمومی شود |
|
||||
| `assets/admin/pages/SmsWalletPage.tsx`, `SubscriptionPage.tsx` | مصرف `pay_url` (قبلاً بهروز شده؛ فقط تأیید) |
|
||||
| `docs/api/payment.md`, `docs/api/sms.md` | بهروزرسانی |
|
||||
|
||||
## وضعیت فعلی (flow جدا در SmsWallet — باید حذف شود)
|
||||
|
||||
```php
|
||||
// src/Sms/Controller/SmsWalletController.php (charge)
|
||||
if ($this->configRepo->get('payment_test_mode') === '1') {
|
||||
$gateway = $this->mock;
|
||||
} else {
|
||||
$gateway = match ($gatewayName) { 'mellat' => $this->mellat, 'sep' => $this->sep, default => null };
|
||||
}
|
||||
if ($gateway === null) { return $this->error(...); }
|
||||
$payment = new Payment($user, $amountRials, $gatewayName, Payment::TYPE_SMS_WALLET, $frontendAddress);
|
||||
$payment->setMetadata(['entity_type' => $entityType, 'entity_id' => $entityId]);
|
||||
$this->paymentRepo->save($payment);
|
||||
$callbackUrl = $this->appBaseUrl . '/api/v1/payment/callback/' . $gatewayName . '?order_id=' . $payment->getOrderId();
|
||||
$result = $gateway->initiate($amountRials, $payment->getOrderId(), $callbackUrl); // ❌ ارتباط مستقیم با درگاه
|
||||
// ... setGatewayToken ... return ['redirect_url' => $result->redirectUrl]; // ❌ redirect_url بانک
|
||||
```
|
||||
|
||||
## وظایف
|
||||
|
||||
### ۱. حذف Flow جداگانهٔ SmsWallet و انتقال به flow واحد
|
||||
|
||||
`SmsWalletController::charge` را طوری بازنویسی کن که **هیچ ارتباطی با درگاه نداشته باشد**؛ فقط `Payment` بسازد و `pay_url` بدهد (دقیقاً مثل appointment/subscription):
|
||||
|
||||
```php
|
||||
$payment = new Payment($user, $amountRials, $gatewayName, Payment::TYPE_SMS_WALLET, $frontendAddress);
|
||||
$payment->setMetadata(['entity_type' => $entityType, 'entity_id' => $entityId]);
|
||||
$this->paymentRepo->save($payment);
|
||||
|
||||
return $this->success([
|
||||
'payment_uuid' => $payment->getUuid(),
|
||||
'pay_url' => $this->appBaseUrl . '/api/v1/payment/pay/' . $payment->getOrderId(),
|
||||
'order_id' => $payment->getOrderId(),
|
||||
]);
|
||||
```
|
||||
|
||||
- فقط اعتبارسنجی درگاه با `GatewayFactory::resolve($gatewayName) === null` (بدون init). `GatewayFactory` را به کنترلر تزریق کن.
|
||||
- Dependencyهای درگاه از `SmsWalletController` حذف شوند: `MellatGateway`, `SepGateway`, `MockGateway` و منطق `match`/`configRepo` مربوط به درگاه. (init توسط `PaymentManager` در `pay` endpoint انجام میشود؛ post-action `TYPE_SMS_WALLET` از قبل در `PaymentManager::handleSmsWalletCharge` هست.)
|
||||
- Callback این نوع از قبل به `/api/v1/payment/callback/{gateway}` → `PaymentManager` میرود (چون `pay` endpoint با `PaymentManager::callbackUrl` بر اساس type میسازد؛ برای غیر-subscription پیشوند `/payment/callback/` است). تأیید کن.
|
||||
|
||||
### ۲. entry ریدایرکتِ خالص `GET /api/v1/payment/order/{appointmentUuid}`
|
||||
|
||||
در `PaymentController` یک route جدید (عمومی، بدون JWT) اضافه کن که کل مراحل ۴ تا ۶ نیاز را انجام دهد و **نیازی به XHR نداشته باشد**:
|
||||
|
||||
```php
|
||||
#[Route('/api/v1/payment/order/{appointmentUuid}', methods: ['GET'])]
|
||||
public function startOrderPayment(string $appointmentUuid, Request $request): Response
|
||||
{
|
||||
$gatewayName = trim((string) $request->query->get('gateway', ''));
|
||||
$return = trim((string) $request->query->get('return', ''));
|
||||
|
||||
$appointment = $this->appointmentRepo->findByUuid($appointmentUuid);
|
||||
if ($appointment === null) {
|
||||
return $this->redirectToReturn($return, 'notfound');
|
||||
}
|
||||
// اعتبارسنجی سفارش: قابلپرداخت بودن (pending/confirmed) و منقضی نبودن
|
||||
if (!in_array($appointment->getStatus(), [Appointment::STATUS_PENDING, Appointment::STATUS_CONFIRMED], true)) {
|
||||
return $this->redirectToReturn($return, 'invalid');
|
||||
}
|
||||
if (!empty($return) && !$this->isAllowedFrontend($return)) {
|
||||
return $this->redirectToReturn('', 'invalid'); // آدرس بازگشت مجاز نیست
|
||||
}
|
||||
if ($this->gateways->resolve($gatewayName) === null) {
|
||||
return $this->redirectToReturn($return, 'gateway');
|
||||
}
|
||||
|
||||
// جلوگیری از pending تکراری: اگر پرداخت pending برای این نوبت هست، همان را ادامه بده.
|
||||
$payment = $this->paymentRepo->findPendingByAppointment($appointment)
|
||||
?? $this->createAppointmentPayment($appointment, $gatewayName, $return);
|
||||
|
||||
// ارتباط با بانک + انتقال به شاپرک (همان مسیر واحد).
|
||||
$result = $this->paymentManager->startGatewayHandoff($payment);
|
||||
if ($result === false) {
|
||||
return $this->redirectToFrontend($payment, false);
|
||||
}
|
||||
return $result->redirectMethod === 'POST'
|
||||
? $this->autoSubmitForm(strtok($result->redirectUrl, '?'), $result->redirectParams)
|
||||
: new RedirectResponse($result->redirectUrl);
|
||||
}
|
||||
```
|
||||
|
||||
نکتهها:
|
||||
- `createAppointmentPayment()` همان منطق ساخت `Payment` در `initiateAppointment` را کپسوله کند (fee از `appointment_fee_rials`، `frontend_address = $return`).
|
||||
- اگر یک pending موجود بود ولی درگاه/گیتوی متفاوت انتخاب شده، تصمیم بگیر: یا درگاهِ pending را بهروزرسانی کن یا همان را ادامه بده (سادهترین: همان pending را ادامه بده).
|
||||
- `redirectToReturn(string $return, string $status)`: اگر `$return` مجاز بود `302` به `"$return?status=$status"`، وگرنه یک JSON خطای کوتاه.
|
||||
- **مالکیت/امنیت (مهم):** این endpoint عمومی است و بهصورت full-page redirect از دامنهٔ دیگری فراخوانی میشود؛ JWT در دسترس نیست. بنابراین `appointmentUuid` نقش capability را دارد (غیرقابلحدس/UUID). پرداخت فقط به نفع صاحب نوبت است، پس شروع پرداخت توسط دارندهٔ لینک ریسک مالی ندارد. اگر مالکیت سختگیرانه لازم است، یک پارامتر امضاشدهٔ `sig` (HMAC از uuid + secret) اضافه کن و در این endpoint verify کن؛ در غیر اینصورت همین کافی است. تصمیم را در docs ذکر کن.
|
||||
|
||||
### ۳. عمومیکردن route جدید در security
|
||||
|
||||
در `config/packages/security.yaml`:
|
||||
- الگوی firewall `payment_callback` را گسترش بده تا `^/api/v1/payment/(callback|pay|order)/` را پوشش دهد.
|
||||
- یک `access_control` برای `^/api/v1/payment/order/` با `PUBLIC_ACCESS`.
|
||||
|
||||
### ۴. تضمین «تنها یک flow»
|
||||
|
||||
- بعد از تغییرات، مطمئن شو تنها فایلی که `->initiate(` یا resolve مستقیم درگاه دارد `PaymentManager` است:
|
||||
```bash
|
||||
grep -rn "->initiate(\|new Payment(" src --include=*.php
|
||||
```
|
||||
انتظار: `new Payment(` فقط در نقاط ساختِ Payment (کنترلرها/SmsWallet برای ساخت، بدون init)؛ `->initiate(` فقط در `PaymentManager` و کلاسهای Gateway.
|
||||
- `payment_url`/`redirect_url` بانکی نباید از هیچ endpointی به کلاینت برگردد؛ فقط `pay_url` (یا ریدایرکت مستقیم در `order`).
|
||||
|
||||
### ۵. مستندسازی
|
||||
|
||||
- `docs/api/payment.md`: افزودن `GET /api/v1/payment/order/{appointmentUuid}` (پارامترهای `gateway`, `return`, رفتار، امنیت، نمودار بهروزشده).
|
||||
- `docs/api/sms.md`: بهروزرسانی `POST /api/v1/sms/wallet/charge` — حالا `pay_url` برمیگرداند و init در pay-endpoint واحد است.
|
||||
|
||||
## نکات مهم
|
||||
|
||||
- **جریان بیرونی نباید بشکند:** `pay`/`callback`/`frontend_address?status=` ثابت بمانند. `order` یک entry جدید است، نه جایگزین pay.
|
||||
- **همهٔ typeها یک مسیر:** appointment (هم XHR→pay_url و هم entry جدید order)، subscription و sms_wallet (XHR→pay_url) همگی به `pay`+`callback`+`PaymentManager` میرسند. تفاوت فقط در ساختِ اولیهٔ Payment است.
|
||||
- **علت باقیماندن یک XHR برای subscription/sms:** اینها order uuidِ ازپیشموجود ندارند و از پنل ادمین (JWT در localStorage) شروع میشوند؛ ساخت Payment نیازمند auth است. entry ریدایرکتِ خالص فقط برای نوبت (که uuid عمومی دارد) ممکن است. این موضوع در docs شفاف شود.
|
||||
- controllerها از `BaseController`؛ تاریخها Unix timestamp.
|
||||
- بعد از تغییر: `ddev exec php -l`, `ddev exec php bin/console cache:clear`, `ddev exec php vendor/bin/phpstan analyse src/Payment src/Sms`, و تست دستی `order` در `payment_test_mode=1`:
|
||||
```bash
|
||||
curl -sk -o /dev/null -w "%{http_code} %{redirect_url}\n" \
|
||||
"https://clinic-pro.ddev.site/api/v1/payment/order/<APPT_UUID>?gateway=mellat&return=http://yazd-nobat.localhost:3000/payment/result"
|
||||
```
|
||||
- بعد از تغییر API → `docs/api/payment.md` و `docs/api/sms.md` در همین session.
|
||||
Reference in New Issue
Block a user