feat: implement Phase 2 backend tasks including staff management, subscription tiers, secretary completion, clinic services, SMS panel, patient records, and smart dashboard
This commit is contained in:
hamed
@@ -0,0 +1,580 @@
|
||||
# پیادهسازی فاز ۲ — Backend تسکبهتسک
|
||||
|
||||
## زمینه
|
||||
|
||||
تسکهای فاز ۲ در `docs/phase2_taskes/` طراحی شدهاند (task-10 تا task-16).
|
||||
این پرامپت فقط **Backend** را پیادهسازی میکند — Entity، Migration، Repository، Service، Controller — و
|
||||
بعد از هر تسک، فایل داک مربوطه در `docs/api/` ایجاد یا بهروز میکند.
|
||||
|
||||
## ترتیب اجباری تسکها (وابستگی)
|
||||
|
||||
```
|
||||
task-10 (Staff) ← پیشنیاز task-13 و task-15
|
||||
↓
|
||||
task-11 (Subscription) ← پیشنیاز gate check در task-12، 13، 15
|
||||
↓
|
||||
task-12 (Secretary) ← فقط SecretaryController تغییر میکند
|
||||
↓
|
||||
task-13 (Services) ← نیاز به Staff و Subscription
|
||||
↓
|
||||
task-14 (SMS Panel) ← مستقل، بعد از task-11 (نه الزامی)
|
||||
↓
|
||||
task-15 (Patient) ← نیاز به Staff + Subscription + Services
|
||||
↓
|
||||
task-16 (Dashboard) ← آخر — فقط query های موجود تغییر میکنند
|
||||
```
|
||||
|
||||
## قوانین عمومی پروژه
|
||||
|
||||
### Backend (Symfony 7)
|
||||
- همه controllerها از `App\Shared\Controller\BaseController` ارث میبرند
|
||||
- پاسخها **فقط** با این متدها:
|
||||
- `$this->success($data, $httpStatus)` — single resource
|
||||
- `$this->paginated($items, $total, $page, $limit)` — لیست با صفحهبندی
|
||||
- `$this->error($code, $message, $httpStatus)` — خطا
|
||||
- `$this->validationError($violations)` — خطای validation (422)
|
||||
- تاریخها **همیشه** Unix timestamp (`int`) — نه DateTime، نه DateTimeImmutable
|
||||
- بعد از هر تغییر Entity: `doctrine:migrations:diff` و `doctrine:migrations:migrate`
|
||||
- Error code های جدید باید در `src/Shared/Constant/ErrorCodes.php` اضافه شوند
|
||||
|
||||
### ساختار Entity (الگو)
|
||||
```php
|
||||
#[ORM\Entity(repositoryClass: XxxRepository::class)]
|
||||
#[ORM\Table(name: 'table_name')]
|
||||
class XxxEntity
|
||||
{
|
||||
#[ORM\Id, ORM\GeneratedValue, ORM\Column(type: 'integer')]
|
||||
private ?int $id = null;
|
||||
|
||||
#[ORM\Column(type: 'string', length: 36, unique: true)]
|
||||
private string $uuid;
|
||||
|
||||
// polymorphic:
|
||||
#[ORM\Column(type: 'string', length: 10)]
|
||||
private string $entityType; // 'doctor' | 'clinic'
|
||||
|
||||
#[ORM\Column(type: 'integer')]
|
||||
private int $entityId;
|
||||
|
||||
#[ORM\Column(type: 'integer')]
|
||||
private int $createdAt;
|
||||
|
||||
#[ORM\Column(type: 'integer')]
|
||||
private int $updatedAt;
|
||||
|
||||
public function __construct()
|
||||
{
|
||||
$this->uuid = (string) \Symfony\Component\Uid\Uuid::v4();
|
||||
$this->createdAt = time();
|
||||
$this->updatedAt = time();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### توجه مهم — BaseController::success() double-nested
|
||||
```php
|
||||
// اشتباه — double-nested data:
|
||||
return $this->success(['data' => $item->toArray()]);
|
||||
// نتیجه: { data: { data: {...} } } — frontend باید data?.data?.data بزند
|
||||
|
||||
// درست:
|
||||
return $this->success($item->toArray());
|
||||
// نتیجه: { data: {...} }
|
||||
|
||||
// برای لیست paginated: array مستقیم (نه ['data' => ...])
|
||||
return $this->paginated($items, $total, $page, $limit);
|
||||
```
|
||||
|
||||
### SecretaryController — وضعیت واقعی فعلی
|
||||
```php
|
||||
// src/Secretary/Controller/SecretaryController.php (line 19)
|
||||
private const MAX_SECRETARIES = 1;
|
||||
// TODO موجود: link to subscription plan
|
||||
|
||||
// متد create() در line 32 — دارد MAX_SECRETARIES را check میکند
|
||||
// اما هنوز SubscriptionService inject نشده
|
||||
// ERR_SECRETARY_001 موجود در ErrorCodes.php
|
||||
```
|
||||
|
||||
### Payment entity — وضعیت واقعی
|
||||
```php
|
||||
// src/Payment/Entity/Payment.php
|
||||
public const TYPE_APPOINTMENT = 'appointment';
|
||||
public const TYPE_SUBSCRIPTION = 'subscription';
|
||||
// TYPE_SMS_WALLET هنوز وجود ندارد — باید اضافه شود
|
||||
```
|
||||
|
||||
### SmsService — signature واقعی
|
||||
```php
|
||||
// src/Sms/Service/SmsService.php
|
||||
public function dispatchAsync(string $mobile, string $message, string $provider = 'kavenegar', ...): void
|
||||
public function sendNow(SendSmsMessage $msg): bool
|
||||
// entityType/entityId پارامتر ندارد — wallet deduct باید در caller انجام شود
|
||||
```
|
||||
|
||||
### AppointmentController::updateStatus — وضعیت واقعی
|
||||
```php
|
||||
// src/Appointment/Controller/AppointmentController.php
|
||||
// بعد از $appointment->setStatus($newStatus) و flush:
|
||||
// باید PatientService::autoCreateOnAppointmentConfirm() اضافه شود
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## تسکها
|
||||
|
||||
---
|
||||
|
||||
### TASK-10: مدیریت پرسنل (Staff)
|
||||
|
||||
**مرجع:** `docs/phase2_taskes/task-10-staff/`
|
||||
|
||||
#### فایلهای جدید:
|
||||
```
|
||||
src/Staff/Entity/ClinicStaff.php
|
||||
src/Staff/Repository/ClinicStaffRepository.php
|
||||
src/Staff/Service/StaffService.php
|
||||
src/Staff/Controller/StaffController.php
|
||||
migrations/Version_YYYYMMDD_staff.php
|
||||
```
|
||||
|
||||
#### Entity ClinicStaff:
|
||||
فیلدها: `id`, `uuid`, `entityType` (VARCHAR 10), `entityId` (INT), `fullName` (VARCHAR 200, required),
|
||||
`phone` (nullable), `jobTitle` (nullable), `address` (TEXT nullable), `nationalCode` (CHAR 10 nullable),
|
||||
`active` (bool=true), `createdAt` (int), `updatedAt` (int).
|
||||
|
||||
Index: `(entity_type, entity_id, active)`
|
||||
|
||||
#### Controller endpoints:
|
||||
```
|
||||
GET /api/v1/staff → لیست (entity از JWT)
|
||||
POST /api/v1/staff → ایجاد
|
||||
PATCH /api/v1/staff/{uuid} → ویرایش
|
||||
PATCH /api/v1/staff/{uuid}/toggle → toggle active
|
||||
```
|
||||
|
||||
#### نکات:
|
||||
- entity_type و entity_id از JWT token claim (`db_key` و `db_uuid` → resolve به id)
|
||||
- toggle: فقط `active = !active` — هیچ حذفی نیست
|
||||
- ownership check: staff.entity_type/entityId == JWT claim
|
||||
- **بعد از پیادهسازی:** فایل `docs/api/staff.md` بساز
|
||||
|
||||
---
|
||||
|
||||
### TASK-11: پنل اشتراکی (Subscription Tiers)
|
||||
|
||||
**مرجع:** `docs/phase2_taskes/task-11-subscription/`
|
||||
|
||||
#### فایلهای جدید:
|
||||
```
|
||||
src/Subscription/Entity/SubscriptionPlan.php
|
||||
src/Subscription/Entity/SubscriptionPeriod.php
|
||||
src/Subscription/Entity/ClinicSubscription.php
|
||||
src/Subscription/Repository/SubscriptionPlanRepository.php
|
||||
src/Subscription/Repository/SubscriptionPeriodRepository.php
|
||||
src/Subscription/Repository/ClinicSubscriptionRepository.php
|
||||
src/Subscription/Service/SubscriptionService.php
|
||||
src/Subscription/Controller/SubscriptionController.php
|
||||
migrations/Version_YYYYMMDD_subscription.php
|
||||
```
|
||||
|
||||
#### SubscriptionPlan: `id`, `uuid`, `name` (VARCHAR 30: free/basic/professional), `level` (TINYINT),
|
||||
`maxSecretaries` (TINYINT), `features` (JSON: `{"patient_records":bool,"services":bool,"sms_panel":bool}`),
|
||||
`active` (bool), `createdAt`, `updatedAt`.
|
||||
|
||||
#### SubscriptionPeriod: `id`, `uuid`, `plan` (FK→SubscriptionPlan), `label` (VARCHAR 50),
|
||||
`durationMonths` (TINYINT), `priceRials` (INT, 0 برای تریال), `isTrial` (bool=false),
|
||||
`active` (bool=true), `sortOrder` (TINYINT=0), `createdAt`, `updatedAt`.
|
||||
|
||||
#### ClinicSubscription: `id`, `uuid`, `entityType`, `entityId`, `plan` (FK),
|
||||
`period` (FK), `payment` (FK nullable → Payment), `isTrial` (bool), `startsAt` (int),
|
||||
`expiresAt` (int nullable — NULL = بینهایت)، `createdAt`.
|
||||
|
||||
Index روی `(entity_type, entity_id, expires_at)`.
|
||||
|
||||
#### SubscriptionService — متدهای الزامی:
|
||||
```php
|
||||
public function getActiveSubscription(string $entityType, int $entityId): ?ClinicSubscription
|
||||
// query: WHERE entity_type=? AND entity_id=? AND (expires_at IS NULL OR expires_at > :now) ORDER BY id DESC LIMIT 1
|
||||
|
||||
public function hasFeature(string $entityType, int $entityId, string $feature): bool
|
||||
// false اگر اشتراک نداشت یا plan->features[$feature] = false
|
||||
|
||||
public function getSecretaryLimit(string $entityType, int $entityId): int
|
||||
// اشتراک فعال → plan->maxSecretaries — اگر اشتراک نداشت: 1 (Free default)
|
||||
|
||||
public function hasUsedTrial(string $entityType, int $entityId): bool
|
||||
|
||||
public function activateTrial(string $entityType, int $entityId): ClinicSubscription
|
||||
// بررسی hasUsedTrial → throw اگر قبلاً استفاده شده
|
||||
// بررسی SiteConfig['trial_enabled'] != '0'
|
||||
// plan Basic پیدا کن → period is_trial=true پیدا کن
|
||||
// ClinicSubscription با payment=null بساز
|
||||
|
||||
public function calculateExpiresAt(?int $currentExpiresAt, int $durationMonths): int
|
||||
// base = max($currentExpiresAt ?? 0, time())
|
||||
// return base + durationMonths * 30 * 86400
|
||||
```
|
||||
|
||||
#### SubscriptionController endpoints:
|
||||
```
|
||||
GET /api/v1/subscription/plans → public — لیست با nested periods
|
||||
GET /api/v1/subscription/my → JWT — اشتراک فعال + used_trial + days_remaining
|
||||
POST /api/v1/subscription/trial → JWT — activateTrial()
|
||||
GET /api/v1/admin/subscription/plans → ROLE_ADMIN
|
||||
POST /api/v1/admin/subscription/plan → ROLE_ADMIN
|
||||
PATCH /api/v1/admin/subscription/plan/{uuid} → ROLE_ADMIN
|
||||
POST /api/v1/admin/subscription/period → ROLE_ADMIN
|
||||
PATCH /api/v1/admin/subscription/period/{uuid} → ROLE_ADMIN
|
||||
DELETE /api/v1/admin/subscription/period/{uuid} → ROLE_ADMIN (active=false)
|
||||
GET /api/v1/admin/subscription/report → ROLE_ADMIN
|
||||
```
|
||||
|
||||
#### تغییر PaymentController:
|
||||
بعد از تأیید موفق callback نوع `TYPE_SUBSCRIPTION`:
|
||||
```php
|
||||
// payment->type === Payment::TYPE_SUBSCRIPTION:
|
||||
// 1. از meta یا period_uuid پرداخت، SubscriptionPeriod پیدا کن
|
||||
// 2. subscriptionService->calculateExpiresAt(currentSub?->expiresAt, period->durationMonths)
|
||||
// 3. ClinicSubscription جدید بساز و persist کن
|
||||
```
|
||||
|
||||
#### Seed data در migration:
|
||||
سه plan (free, basic, professional) + دورههای نمونه برای basic.
|
||||
|
||||
#### Error codes جدید در ErrorCodes.php:
|
||||
```php
|
||||
const ERR_SUBSCRIPTION_REQUIRED = 'ERR_SUBSCRIPTION_REQUIRED'; // 'این قابلیت نیاز به پنل Basic یا بالاتر دارد'
|
||||
const ERR_TRIAL_ALREADY_USED = 'ERR_TRIAL_ALREADY_USED'; // 'قبلاً از تریال استفاده کردهاید'
|
||||
const ERR_TRIAL_DISABLED = 'ERR_TRIAL_DISABLED'; // 'تریال در حال حاضر غیرفعال است'
|
||||
```
|
||||
|
||||
**بعد از پیادهسازی:** فایل `docs/api/subscription.md` بساز.
|
||||
|
||||
---
|
||||
|
||||
### TASK-12: تکمیل منشی — محدودیت پنل
|
||||
|
||||
**مرجع:** `docs/phase2_taskes/task-12-secretary-completion/`
|
||||
|
||||
#### فایلهای تغییرکننده (هیچ فایل جدیدی نیست):
|
||||
- `src/Secretary/Controller/SecretaryController.php`
|
||||
- `src/Secretary/Repository/DoctorSecretaryRepository.php`
|
||||
|
||||
#### تغییر SecretaryController::create():
|
||||
```php
|
||||
// وضعیت فعلی (line 19): private const MAX_SECRETARIES = 1;
|
||||
// باید حذف شود و جایش با SubscriptionService جایگزین شود
|
||||
|
||||
// inject SubscriptionService در constructor
|
||||
|
||||
// در create() — جایگزین check فعلی:
|
||||
// $limit = $this->subscriptionService->getSecretaryLimit($entityType, $entityId);
|
||||
// $activeCount = $this->secretaryRepo->countActiveByDoctor($doctor); // متد موجود
|
||||
// if ($activeCount >= $limit) → error ERR_SECRETARY_001
|
||||
```
|
||||
|
||||
#### نکته مهم — متد موجود:
|
||||
`countActiveByDoctor(Doctor $doctor)` در `DoctorSecretaryRepository` **از قبل وجود دارد** — نیازی به ایجاد نیست.
|
||||
|
||||
#### Error code موجود:
|
||||
`ERR_SECRETARY_001` در ErrorCodes.php موجود است — نیازی به اضافه کردن نیست.
|
||||
|
||||
**بعد از پیادهسازی:** بخش «محدودیت پنل» را به `docs/api/secretary.md` اضافه کن.
|
||||
|
||||
---
|
||||
|
||||
### TASK-13: سرویسهای کلینیک (Clinic Services)
|
||||
|
||||
**مرجع:** `docs/phase2_taskes/task-13-clinic-services/`
|
||||
|
||||
#### فایلهای جدید:
|
||||
```
|
||||
src/ClinicService/Entity/ServiceSection.php
|
||||
src/ClinicService/Entity/ServiceItem.php
|
||||
src/ClinicService/Repository/ServiceSectionRepository.php
|
||||
src/ClinicService/Repository/ServiceItemRepository.php
|
||||
src/ClinicService/Controller/ClinicServiceController.php
|
||||
migrations/Version_YYYYMMDD_clinic_service.php
|
||||
```
|
||||
|
||||
#### ServiceSection: `id`, `uuid`, `entityType`, `entityId`, `name` (VARCHAR 200), `active` (bool=true), `createdAt`, `updatedAt`.
|
||||
Index: `(entity_type, entity_id)`.
|
||||
|
||||
#### ServiceItem: `id`, `uuid`, `section` (FK→ServiceSection ON DELETE CASCADE),
|
||||
`staff` (FK→ClinicStaff nullable ON DELETE SET NULL), `name` (VARCHAR 200), `priceRials` (INT=0),
|
||||
`active` (bool=true), `createdAt`, `updatedAt`.
|
||||
|
||||
#### Controller endpoints:
|
||||
```
|
||||
GET /api/v1/service-sections → Basic+ gate
|
||||
POST /api/v1/service-section → Basic+ gate
|
||||
PATCH /api/v1/service-section/{uuid} → Basic+ gate
|
||||
DELETE /api/v1/service-section/{uuid} → Basic+ gate
|
||||
GET /api/v1/service-items/{sectionUuid}
|
||||
POST /api/v1/service-item → Basic+ gate
|
||||
PATCH /api/v1/service-item/{uuid}
|
||||
DELETE /api/v1/service-item/{uuid}
|
||||
```
|
||||
|
||||
#### gate check helper:
|
||||
```php
|
||||
private function assertServicesGate(): void
|
||||
{
|
||||
[$type, $id] = $this->resolveEntityFromJwt();
|
||||
if (!$this->subscriptionService->hasFeature($type, $id, 'services')) {
|
||||
throw new \App\Shared\Exception\AppException(ErrorCodes::ERR_SUBSCRIPTION_REQUIRED, null, 403);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### حذف ServiceItem با استفاده در پرونده:
|
||||
```php
|
||||
// session_services.service_item_id FK ON DELETE RESTRICT
|
||||
// اگر در session_services باشد → DBAL ForeignKeyConstraintViolationException
|
||||
try {
|
||||
$this->em->remove($item); $this->em->flush();
|
||||
} catch (\Doctrine\DBAL\Exception\ForeignKeyConstraintViolationException) {
|
||||
return $this->error(ErrorCodes::ERR_SERVICE_ITEM_IN_USE, 'این سرویس در پرونده بیمار ثبت شده است', 409);
|
||||
}
|
||||
```
|
||||
|
||||
#### Error codes جدید:
|
||||
```php
|
||||
const ERR_SERVICE_ITEM_IN_USE = 'ERR_SERVICE_ITEM_IN_USE'; // 'این سرویس در پرونده بیمار ثبت شده است'
|
||||
```
|
||||
|
||||
**بعد از پیادهسازی:** فایل `docs/api/clinic-services.md` بساز.
|
||||
|
||||
---
|
||||
|
||||
### TASK-14: پنل پیامکی (SMS Panel)
|
||||
|
||||
**مرجع:** `docs/phase2_taskes/task-14-sms-panel/`
|
||||
|
||||
#### فایلهای جدید:
|
||||
```
|
||||
src/Sms/Entity/SmsWallet.php
|
||||
src/Sms/Entity/SmsWalletTransaction.php
|
||||
src/Sms/Entity/SmsSettings.php
|
||||
src/Sms/Repository/SmsWalletRepository.php
|
||||
src/Sms/Repository/SmsWalletTransactionRepository.php
|
||||
src/Sms/Repository/SmsSettingsRepository.php
|
||||
src/Sms/Service/SmsWalletService.php
|
||||
src/Sms/Controller/SmsWalletController.php
|
||||
migrations/Version_YYYYMMDD_sms_panel.php
|
||||
```
|
||||
|
||||
#### فایلهای تغییرکننده:
|
||||
- `src/Payment/Entity/Payment.php` — اضافه کردن `const TYPE_SMS_WALLET = 'sms_wallet'`
|
||||
- `src/Payment/Controller/PaymentController.php` — callback برای type=sms_wallet
|
||||
|
||||
#### SmsWallet: `id`, `entityType`, `entityId`, `balanceRials` (INT=0), `createdAt`, `updatedAt`.
|
||||
UNIQUE INDEX روی `(entity_type, entity_id)`.
|
||||
|
||||
#### SmsWalletTransaction: `id`, `uuid`, `wallet` (FK→SmsWallet ON DELETE CASCADE),
|
||||
`type` (VARCHAR 10: credit/debit), `amountRials` (INT), `description` (nullable),
|
||||
`payment` (FK→Payment nullable ON DELETE SET NULL), `createdAt`.
|
||||
|
||||
#### SmsSettings: `id`, `entityType`, `entityId`, `reminderEnabled` (bool=false),
|
||||
`reminderHoursBefore` (TINYINT=2), `postVisitEnabled` (bool=false), `postVisitText` (TEXT nullable),
|
||||
`updatedAt`. UNIQUE INDEX روی `(entity_type, entity_id)`.
|
||||
|
||||
#### SmsWalletService:
|
||||
```php
|
||||
public function getOrCreate(string $entityType, int $entityId): SmsWallet
|
||||
public function charge(SmsWallet $wallet, int $amountRials, Payment $payment): void // ثبت credit tx
|
||||
public function deduct(SmsWallet $wallet, int $amountRials, string $description): bool // ثبت debit tx
|
||||
public function getBalance(string $entityType, int $entityId): int
|
||||
```
|
||||
|
||||
#### SmsWalletController endpoints:
|
||||
```
|
||||
GET /api/v1/sms/wallet/balance → موجودی + sms_price_rials از SiteConfig + estimated_sms_count
|
||||
POST /api/v1/sms/wallet/charge → { gateway, amount_rials } → Payment TYPE_SMS_WALLET → redirect
|
||||
GET /api/v1/sms/wallet/logs → paginated SmsWalletTransactions
|
||||
GET /api/v1/sms/settings → SmsSettings (یا مقادیر پیشفرض)
|
||||
PATCH /api/v1/sms/settings → UPSERT SmsSettings
|
||||
GET /api/v1/admin/sms/wallet-report → ROLE_ADMIN
|
||||
```
|
||||
|
||||
#### تغییر PaymentController callback برای sms_wallet:
|
||||
```php
|
||||
if ($payment->getType() === Payment::TYPE_SMS_WALLET) {
|
||||
$wallet = $this->smsWalletService->getOrCreate($entityType, $entityId);
|
||||
$this->smsWalletService->charge($wallet, $payment->getAmountRials(), $payment);
|
||||
}
|
||||
```
|
||||
|
||||
#### SiteConfig key:
|
||||
`sms_price_rials` — باید در `GET /api/v1/sms/wallet/balance` خوانده شود.
|
||||
|
||||
**بعد از پیادهسازی:** بخش «SMS Wallet» و «SMS Settings» را به `docs/api/sms.md` اضافه کن.
|
||||
|
||||
---
|
||||
|
||||
### TASK-15: پرونده بیمار (Patient Records)
|
||||
|
||||
**مرجع:** `docs/phase2_taskes/task-15-patient-records/`
|
||||
|
||||
#### فایلهای جدید:
|
||||
```
|
||||
src/Patient/Entity/PatientRecord.php
|
||||
src/Patient/Entity/PatientSession.php
|
||||
src/Patient/Entity/SessionService.php
|
||||
src/Patient/Repository/PatientRecordRepository.php
|
||||
src/Patient/Repository/PatientSessionRepository.php
|
||||
src/Patient/Service/PatientService.php
|
||||
src/Patient/Controller/PatientController.php
|
||||
migrations/Version_YYYYMMDD_patient.php
|
||||
```
|
||||
|
||||
#### فایل تغییرکننده:
|
||||
- `src/Appointment/Controller/AppointmentController.php::updateStatus()` — بعد از persist
|
||||
|
||||
#### PatientRecord: `id`, `uuid`, `entityType`, `entityId`, `user` (FK→User ON DELETE RESTRICT),
|
||||
`createdByType` (VARCHAR 15: doctor/secretary/system), `createdById` (INT), `createdAt`.
|
||||
UNIQUE: `(entity_type, entity_id, user_id)`.
|
||||
|
||||
#### PatientSession: `id`, `uuid`, `record` (FK→PatientRecord CASCADE), `appointment` (FK nullable SET NULL),
|
||||
`insuranceBaseId` (INT nullable FK→categories), `insuranceSupplementaryId` (INT nullable FK→categories),
|
||||
`visitPriceRials` (INT=0), `baseInsuranceDiscountPercent` (DECIMAL 5,2=0),
|
||||
`supplementaryDiscountPercent` (DECIMAL 5,2=0), `servicesTotalRials` (INT=0),
|
||||
`finalPriceRials` (INT=0), `paymentMethod` (VARCHAR 15=pending), `notes` (TEXT nullable),
|
||||
`createdAt`, `updatedAt`.
|
||||
|
||||
#### SessionService (entity): `id`, `uuid`, `session` (FK→PatientSession CASCADE),
|
||||
`serviceItem` (FK→ServiceItem ON DELETE RESTRICT), `staff` (FK→ClinicStaff nullable SET NULL),
|
||||
`priceRials` (INT — کپی در زمان ثبت)، `createdAt`.
|
||||
|
||||
#### PatientService:
|
||||
```php
|
||||
public function calculateFinalPrice(
|
||||
int $visitPrice, float $baseDiscount, float $suppDiscount, array $serviceItems
|
||||
): array {
|
||||
$afterBase = $visitPrice * (1 - $baseDiscount / 100);
|
||||
$afterSupp = $afterBase * (1 - $suppDiscount / 100);
|
||||
$servicesTotal = array_sum(array_column($serviceItems, 'price_rials'));
|
||||
return [
|
||||
'services_total_rials' => $servicesTotal,
|
||||
'final_price_rials' => (int) round($afterSupp) + $servicesTotal,
|
||||
];
|
||||
}
|
||||
|
||||
public function autoCreateOnAppointmentConfirm(Appointment $appointment): void
|
||||
{
|
||||
// entityType/entityId از appointment doctor یا clinic
|
||||
// if !hasFeature('patient_records') → return (نه خطا)
|
||||
// findOrCreate PatientRecord با UNIQUE constraint
|
||||
// ایجاد PatientSession با appointment_id, visit_price=0, payment_method='pending'
|
||||
}
|
||||
```
|
||||
|
||||
#### PatientController endpoints:
|
||||
```
|
||||
GET /api/v1/patients → paginated + ?search= — Basic+ gate
|
||||
POST /api/v1/patient → Basic+ gate — { user_uuid }
|
||||
GET /api/v1/patient/{uuid} → Basic+ gate
|
||||
GET /api/v1/patient/{uuid}/sessions → paginated
|
||||
POST /api/v1/patient/{uuid}/session → { appointment_uuid?, insurance_base_uuid?, visit_price_rials, base_insurance_discount_percent, supplementary_discount_percent, payment_method, notes?, services: [{service_item_uuid, staff_uuid?}] }
|
||||
PATCH /api/v1/session/{uuid} → ویرایش notes و payment_method
|
||||
```
|
||||
|
||||
#### تغییر AppointmentController::updateStatus():
|
||||
```php
|
||||
// بعد از $this->em->flush()، اگر $newStatus === Appointment::STATUS_CONFIRMED:
|
||||
$this->patientService->autoCreateOnAppointmentConfirm($appointment);
|
||||
```
|
||||
|
||||
#### Error codes جدید:
|
||||
```php
|
||||
const ERR_PATIENT_NOT_FOUND = 'ERR_PATIENT_NOT_FOUND'; // 'پرونده بیمار یافت نشد'
|
||||
const ERR_SESSION_NOT_FOUND = 'ERR_SESSION_NOT_FOUND'; // 'مراجعه یافت نشد'
|
||||
```
|
||||
|
||||
**بعد از پیادهسازی:** فایل `docs/api/patient.md` بساز.
|
||||
|
||||
---
|
||||
|
||||
### TASK-16: داشبورد هوشمند (Smart Dashboard)
|
||||
|
||||
**مرجع:** `docs/phase2_taskes/task-16-smart-dashboard/`
|
||||
|
||||
#### فایلهای تغییرکننده (هیچ فایل جدیدی نیست):
|
||||
- `src/Dashboard/Controller/DashboardController.php`
|
||||
- `src/Admin/Controller/AdminApiController.php`
|
||||
|
||||
#### تغییر DashboardController — اضافه کردن `from`/`to`:
|
||||
```php
|
||||
// متدهای clinic() و doctor():
|
||||
$from = (int) $request->query->get('from', strtotime('-30 days'));
|
||||
$to = (int) $request->query->get('to', time());
|
||||
|
||||
// فیلدهای جدید در response:
|
||||
'sms_wallet_balance' => $this->smsWalletService->getBalance($entityType, $entityId),
|
||||
'unique_patients_count' => $this->patientRecordRepo->countUnique($entityType, $entityId, $from, $to),
|
||||
'revenue_period_rials' => $this->patientSessionRepo->sumRevenue($entityType, $entityId, $from, $to),
|
||||
```
|
||||
|
||||
#### تغییر AdminApiController::dashboardCharts():
|
||||
```php
|
||||
$from = (int) $request->query->get('from', strtotime('-30 days'));
|
||||
$to = (int) $request->query->get('to', time());
|
||||
|
||||
// appointments_by_day: DQL با FLOOR(a.createdAt / 86400) * 86400 AS date, COUNT
|
||||
// revenue_by_day: از patient_sessions در بازه
|
||||
// subscription_sales_by_plan: از clinic_subscriptions در بازه (is_trial=0)
|
||||
```
|
||||
|
||||
#### PatientRecordRepository متد جدید:
|
||||
```php
|
||||
public function countUnique(string $entityType, int $entityId, int $from, int $to): int
|
||||
// COUNT(DISTINCT ps_session.user) با JOIN patient_sessions روی بازه
|
||||
```
|
||||
|
||||
#### PatientSessionRepository متد جدید:
|
||||
```php
|
||||
public function sumRevenue(string $entityType, int $entityId, int $from, int $to): int
|
||||
// SUM(final_price_rials) با JOIN patient_records
|
||||
```
|
||||
|
||||
**بعد از پیادهسازی:** بخش «فیلتر زمانی» و «فیلدهای جدید» را به `docs/api/dashboard.md` اضافه کن.
|
||||
|
||||
---
|
||||
|
||||
## نکات مهم برای همه تسکها
|
||||
|
||||
### resolveEntityFromJwt — helper مشترک
|
||||
هر controller باید entity_type و entity_id کاربر جاری را از JWT بخواند:
|
||||
```php
|
||||
// از $this->getUser() (که User entity است) → db_key و db_uuid
|
||||
// db_key = 'doctor' یا 'clinic'
|
||||
// db_uuid → resolve به id از repository مربوطه
|
||||
// این منطق باید در BaseController یا یک trait مشترک باشد
|
||||
// بررسی کن آیا getUser()->getDbKey() / getDbUuid() موجود است
|
||||
```
|
||||
|
||||
### migration بعد از هر تسک:
|
||||
```bash
|
||||
ddev exec php bin/console doctrine:migrations:diff --no-interaction
|
||||
ddev exec php bin/console doctrine:migrations:migrate --no-interaction
|
||||
ddev exec php bin/console cache:clear
|
||||
```
|
||||
|
||||
### بررسی route بعد از هر تسک:
|
||||
```bash
|
||||
ddev exec php bin/console debug:router | grep "api/v1/staff\|subscription\|service-section\|sms/wallet\|patient"
|
||||
```
|
||||
|
||||
### ترتیب مستندسازی (docs/api/):
|
||||
| تسک | فایل |
|
||||
|-----|------|
|
||||
| task-10 | `docs/api/staff.md` ← **ایجاد جدید** |
|
||||
| task-11 | `docs/api/subscription.md` ← **ایجاد جدید** |
|
||||
| task-12 | `docs/api/secretary.md` ← **اضافه کردن بخش** |
|
||||
| task-13 | `docs/api/clinic-services.md` ← **ایجاد جدید** |
|
||||
| task-14 | `docs/api/sms.md` ← **اضافه کردن بخش** |
|
||||
| task-15 | `docs/api/patient.md` ← **ایجاد جدید** |
|
||||
| task-16 | `docs/api/dashboard.md` ← **اضافه کردن بخش** |
|
||||
|
||||
هر فایل doc باید داشته باشد: method/path، permission، request body، response JSON، error codes.
|
||||
Reference in New Issue
Block a user