hamed/clinicpro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive project documentation for ClinicPro in CLAUDE.md and README.md

Browse Source 
- Introduced CLAUDE.md for internal guidance on project structure, commands, and architecture.
- Created README.md with detailed project overview, technology stack, directory structure, setup instructions, API endpoints, authentication flow, and external services.
This commit is contained in:
hamed
2026-06-10 11:12:15 +03:30
parent c7ae591e49
commit e9075e8c92
18 changed files with 3533 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/Payment/Controller/PaymentController.php
+287
View File
@@ -12,6 +12,7 @@ use App\Payment\Repository\PaymentRepository;
use App\Payment\Service\CircuitBreakerService;
use App\Shared\Constant\ErrorCodes;
use App\Shared\Controller\BaseController;
use OpenApi\Attributes as OA;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;
@@ -19,6 +20,7 @@ use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Security\Http\Attribute\CurrentUser;
use Symfony\Component\Security\Http\Attribute\IsGranted;
#[OA\Tag(name: 'Payments')]
class PaymentController extends BaseController
{
// Shaparak payment network callback IP ranges
@@ -39,6 +41,99 @@ class PaymentController extends BaseController
// ── Appointment Payment ───────────────────────────────────────────────────
#[OA\Post(
path: '/api/v1/payment/appointment',
summary: 'Initiate an appointment payment',
security: [['bearerAuth' => []]],
requestBody: new OA\RequestBody(
required: true,
content: new OA\JsonContent(
required: ['appointment_uuid', 'gateway'],
properties: [
new OA\Property(property: 'appointment_uuid', type: 'string', format: 'uuid'),
new OA\Property(property: 'gateway', type: 'string', enum: ['mellat', 'sep']),
new OA\Property(property: 'frontend_address', type: 'string', format: 'uri', nullable: true),
]
)
),
responses: [
new OA\Response(
response: 200,
description: 'Payment initiated',
content: new OA\JsonContent(
properties: [
new OA\Property(property: 'success', type: 'boolean', example: true),
new OA\Property(
property: 'data',
properties: [
new OA\Property(property: 'payment_uuid', type: 'string', format: 'uuid'),
new OA\Property(property: 'redirect_url', type: 'string', format: 'uri'),
new OA\Property(property: 'order_id', type: 'string'),
],
type: 'object'
),
]
)
),
new OA\Response(
response: 401,
description: 'Unauthorized',
content: new OA\JsonContent(
properties: [
new OA\Property(property: 'success', type: 'boolean', example: false),
new OA\Property(
property: 'errors',
type: 'array',
items: new OA\Items(
properties: [
new OA\Property(property: 'code', type: 'string'),
new OA\Property(property: 'message', type: 'string'),
]
)
),
]
)
),
new OA\Response(
response: 422,
description: 'Validation error',
content: new OA\JsonContent(
properties: [
new OA\Property(property: 'success', type: 'boolean', example: false),
new OA\Property(
property: 'errors',
type: 'array',
items: new OA\Items(
properties: [
new OA\Property(property: 'code', type: 'string'),
new OA\Property(property: 'message', type: 'string'),
]
)
),
]
)
),
new OA\Response(
response: 503,
description: 'Gateway unavailable',
content: new OA\JsonContent(
properties: [
new OA\Property(property: 'success', type: 'boolean', example: false),
new OA\Property(
property: 'errors',
type: 'array',
items: new OA\Items(
properties: [
new OA\Property(property: 'code', type: 'string'),
new OA\Property(property: 'message', type: 'string'),
]
)
),
]
)
),
]
)]
#[IsGranted('IS_AUTHENTICATED_FULLY')]
#[Route('/api/v1/payment/appointment', methods: ['POST'])]
public function initiateAppointment(Request $request, #[CurrentUser] User $user): JsonResponse
@@ -100,6 +195,33 @@ class PaymentController extends BaseController
// ── Payment Callback (public — no JWT) ───────────────────────────────────
#[OA\Post(
path: '/api/v1/payment/callback/{gateway}',
summary: 'Payment gateway callback (public, IP-restricted)',
parameters: [
new OA\Parameter(
name: 'gateway',
in: 'path',
required: true,
schema: new OA\Schema(type: 'string', enum: ['mellat', 'sep'])
),
],
responses: [
new OA\Response(
response: 200,
description: 'Callback processed — either a redirect or JSON result',
content: new OA\JsonContent(
properties: [
new OA\Property(property: 'success', type: 'boolean'),
new OA\Property(property: 'payment', type: 'object'),
]
)
),
new OA\Response(response: 302, description: 'Redirect to frontend with payment result'),
new OA\Response(response: 403, description: 'Forbidden — IP not in allowed Shaparak ranges'),
new OA\Response(response: 404, description: 'Payment not found'),
]
)]
#[Route('/api/v1/payment/callback/{gateway}', methods: ['POST', 'GET'])]
public function callback(string $gateway, Request $request): \Symfony\Component\HttpFoundation\Response
{
@@ -139,6 +261,99 @@ class PaymentController extends BaseController
// ── Subscription Payment ──────────────────────────────────────────────────
#[OA\Post(
path: '/api/v1/subscription-payment',
summary: 'Initiate a subscription payment',
security: [['bearerAuth' => []]],
requestBody: new OA\RequestBody(
required: true,
content: new OA\JsonContent(
required: ['gateway', 'amount_rials'],
properties: [
new OA\Property(property: 'gateway', type: 'string', enum: ['mellat', 'sep']),
new OA\Property(property: 'frontend_address', type: 'string', format: 'uri', nullable: true),
new OA\Property(property: 'amount_rials', type: 'integer', minimum: 1),
]
)
),
responses: [
new OA\Response(
response: 200,
description: 'Subscription payment initiated',
content: new OA\JsonContent(
properties: [
new OA\Property(property: 'success', type: 'boolean', example: true),
new OA\Property(
property: 'data',
properties: [
new OA\Property(property: 'payment_uuid', type: 'string', format: 'uuid'),
new OA\Property(property: 'redirect_url', type: 'string', format: 'uri'),
new OA\Property(property: 'order_id', type: 'string'),
],
type: 'object'
),
]
)
),
new OA\Response(
response: 401,
description: 'Unauthorized',
content: new OA\JsonContent(
properties: [
new OA\Property(property: 'success', type: 'boolean', example: false),
new OA\Property(
property: 'errors',
type: 'array',
items: new OA\Items(
properties: [
new OA\Property(property: 'code', type: 'string'),
new OA\Property(property: 'message', type: 'string'),
]
)
),
]
)
),
new OA\Response(
response: 422,
description: 'Validation error',
content: new OA\JsonContent(
properties: [
new OA\Property(property: 'success', type: 'boolean', example: false),
new OA\Property(
property: 'errors',
type: 'array',
items: new OA\Items(
properties: [
new OA\Property(property: 'code', type: 'string'),
new OA\Property(property: 'message', type: 'string'),
]
)
),
]
)
),
new OA\Response(
response: 503,
description: 'Gateway unavailable',
content: new OA\JsonContent(
properties: [
new OA\Property(property: 'success', type: 'boolean', example: false),
new OA\Property(
property: 'errors',
type: 'array',
items: new OA\Items(
properties: [
new OA\Property(property: 'code', type: 'string'),
new OA\Property(property: 'message', type: 'string'),
]
)
),
]
)
),
]
)]
#[IsGranted('IS_AUTHENTICATED_FULLY')]
#[Route('/api/v1/subscription-payment', methods: ['POST'])]
public function initiateSubscription(Request $request, #[CurrentUser] User $user): JsonResponse
@@ -187,6 +402,33 @@ class PaymentController extends BaseController
]);
}
#[OA\Post(
path: '/api/v1/subscription-payment/callback/{gateway}',
summary: 'Subscription payment gateway callback (public, IP-restricted)',
parameters: [
new OA\Parameter(
name: 'gateway',
in: 'path',
required: true,
schema: new OA\Schema(type: 'string', enum: ['mellat', 'sep'])
),
],
responses: [
new OA\Response(
response: 200,
description: 'Callback processed — either a redirect or JSON result',
content: new OA\JsonContent(
properties: [
new OA\Property(property: 'success', type: 'boolean'),
new OA\Property(property: 'payment', type: 'object'),
]
)
),
new OA\Response(response: 302, description: 'Redirect to frontend with payment result'),
new OA\Response(response: 403, description: 'Forbidden — IP not in allowed Shaparak ranges'),
new OA\Response(response: 404, description: 'Payment not found'),
]
)]
#[Route('/api/v1/subscription-payment/callback/{gateway}', methods: ['POST', 'GET'])]
public function subscriptionCallback(string $gateway, Request $request): \Symfony\Component\HttpFoundation\Response
{
@@ -195,6 +437,51 @@ class PaymentController extends BaseController
// ── Status ────────────────────────────────────────────────────────────────
#[OA\Get(
path: '/api/v1/payment/{uuid}',
summary: 'Get payment status by UUID',
security: [['bearerAuth' => []]],
parameters: [
new OA\Parameter(
name: 'uuid',
in: 'path',
required: true,
schema: new OA\Schema(type: 'string', format: 'uuid')
),
],
responses: [
new OA\Response(
response: 200,
description: 'Payment details',
content: new OA\JsonContent(
properties: [
new OA\Property(property: 'success', type: 'boolean', example: true),
new OA\Property(
property: 'data',
properties: [
new OA\Property(
property: 'data',
properties: [
new OA\Property(property: 'uuid', type: 'string', format: 'uuid'),
new OA\Property(property: 'status', type: 'string'),
new OA\Property(property: 'amount_rials', type: 'integer'),
new OA\Property(property: 'gateway', type: 'string'),
new OA\Property(property: 'reference_id', type: 'string', nullable: true),
new OA\Property(property: 'created_at', type: 'string', format: 'date-time'),
],
type: 'object'
),
],
type: 'object'
),
]
)
),
new OA\Response(response: 401, description: 'Unauthorized'),
new OA\Response(response: 403, description: 'Forbidden'),
new OA\Response(response: 404, description: 'Payment not found'),
]
)]
#[IsGranted('IS_AUTHENTICATED_FULLY')]
#[Route('/api/v1/payment/{uuid}', methods: ['GET'])]
public function getStatus(string $uuid, #[CurrentUser] User $user): JsonResponse