feat(profile): enforce uniqueness of national_code across user profiles and update related error handling

2026-06-24 11:52:13 +03:30
parent 3eb82ffa7d
commit 650e36bce2
9 changed files with 247 additions and 7 deletions
@@ -0,0 +1,149 @@
+# یکتا بودن کد ملی در پروفایل بیمار (هر کد ملی فقط یک پروفایل)
+
+## پروژه
+
+`clinicpro` (Backend — منبع واحد داده و constraint).
+
+> این تغییر cross-repo اثر دارد: سایت عمومی `nobat724_front` و پنل ادمین React (داخل همین پروژه) فقط باید خطای `409`/`422` جدید را نمایش دهند. قرارداد پاسخ خطا در «نکات مهم» آمده تا کلاینت‌ها مصرف کنند. تغییر منطق فقط backend است.
+
+## زمینه
+
+هر کاربر (`User`) دقیقاً یک پروفایل (`UserProfile`, جدول `profiles`, رابطه `OneToOne` با کلید یکتای `idx_profiles_user`) دارد. کد ملی هم روی `User` و هم روی `UserProfile` ذخیره می‌شود ولی **در هیچ‌کدام یکتا نیست** — فقط یک ایندکس غیر-یکتا روی `profiles.national_code` هست:
+
+```php
+// src/UserProfile/Entity/UserProfile.php:12
+#[ORM\Index(columns: ['national_code'], name: 'idx_profiles_national_code')]
+// src/UserProfile/Entity/UserProfile.php:36
+#[ORM\Column(name: 'national_code', type: 'string', length: 10, nullable: true)]
+private ?string $nationalCode = null;
+
+// src/Auth/Entity/User.php:35
+#[ORM\Column(name: 'national_code', type: 'string', length: 10, nullable: true)]
+private ?string $nationalCode = null;
+```
+
+پرامپت قبلی `fix-server-side-mobile-nationalcode-validation.md` فقط **فرمت** کد ملی (رقم کنترلی ایرانی) را سمت سرور اضافه کرد، نه **یکتایی** را. در نتیجه دو پروفایل مختلف می‌توانند یک کد ملی داشته باشند — چه از مسیر پروفایل عمومی، چه نوبت‌دهی توسط منشی.
+
+## مشکل / هدف
+
+کد ملی باید در سطح بیمار یکتا باشد: نباید دو پروفایل جدا با یک کد ملی وجود داشته باشد. وقتی کاربر/منشی/هر مسیرِ نوبت‌دهی کد ملی‌ای ثبت می‌کند که قبلاً به پروفایل **کاربر دیگری** تعلق دارد، باید با خطای `409` رد شود (نه ذخیره).
+
+دامنه‌ی یکتایی: **`UserProfile.national_code`** (منبع نهاییِ هویت بیمار، رابطه‌ی ۱:۱ با کاربر). `User.nationalCode` در حد همگام‌سازی است و قید یکتایی روی پروفایل کافی است.
+
+## فایل‌های مرتبط
+
+| فایل | نقش |
+|------|-----|
+| `src/UserProfile/Entity/UserProfile.php` | افزودن قید یکتای partial روی `national_code` |
+| `src/UserProfile/Repository/UserProfileRepository.php` | متد `findOneByNationalCode()` جدید |
+| `src/UserProfile/Controller/UserProfileController.php` | `hydrate()` / `update()` — چک یکتایی قبل از set |
+| `src/Shared/Constant/ErrorCodes.php` | کد خطای جدید برای کد ملی تکراری |
+| `migrations/VersionXXXX.php` (جدید) | unique index روی `profiles.national_code` |
+| `docs/api/user-profile.md` | مستندسازی پاسخ `409` |
+
+## وضعیت فعلی (کد واقعی)
+
+`UserProfileController::hydrate` — بدون چک یکتایی ذخیره می‌شود:
+
+```php
+// src/UserProfile/Controller/UserProfileController.php:211
+if (array_key_exists('national_code', $data))  $profile->setNationalCode($data['national_code']);
+```
+
+`update()` فقط فرمت را چک می‌کند (از پرامپت قبلی)، یکتایی نه:
+
+```php
+// src/UserProfile/Controller/UserProfileController.php:134
+if (array_key_exists('national_code', $data) && $data['national_code'] !== null && $data['national_code'] !== '') {
+    $code = InputValidator::toEnglishDigits((string) $data['national_code']);
+    if (!InputValidator::isValidIranNationalCode($code)) {
+        return $this->error(ErrorCodes::ERR_VALIDATION_001, 'کد ملی نامعتبر است', 422, 'national_code');
+    }
+    $data['national_code'] = $code;
+}
+```
+
+## وظایف
+
+### ۱. قید یکتای دیتابیس (partial — فقط مقادیر non-null)
+
+در `UserProfile.php` ایندکس فعلی را به unique تبدیل کن. چون `national_code` nullable است و چند پروفایلِ بدون کد ملی باید مجاز بمانند، در MariaDB رفتار پیش‌فرضِ unique index این است که چندین `NULL` مجاز است (دقیقاً همان partial-unique موردنظر) — پس کافی است index را unique کنیم:
+
+```php
+// به‌جای خط 12
+#[ORM\UniqueConstraint(name: 'uniq_profiles_national_code', columns: ['national_code'])]
+```
+
+سپس migration بساز:
+
+```bash
+ddev exec php bin/console doctrine:migrations:diff --no-interaction
+```
+
+**هشدار داده‌ی موجود:** قبل از migrate، تکراری‌های فعلی را پیدا کن وگرنه migration روی `ALTER TABLE` می‌شکند:
+
+```sql
+SELECT national_code, COUNT(*) c FROM profiles
+WHERE national_code IS NOT NULL AND national_code <> ''
+GROUP BY national_code HAVING c > 1;
+```
+
+اگر تکراری بود، در توضیحات خروجی به کاربر گزارش بده (پاک‌سازی دستی لازم است؛ خودسرانه merge/حذف نکن).
+
+### ۲. متد repository
+
+در `UserProfileRepository.php`:
+
+```php
+public function findOneByNationalCode(string $nationalCode): ?UserProfile
+{
+    return $this->findOneBy(['nationalCode' => $nationalCode]);
+}
+```
+
+### ۳. چک یکتایی در سطح اپلیکیشن (قبل از flush)
+
+قید DB لایه‌ی آخر است؛ برای پیام تمیز و جلوگیری از `UniqueConstraintViolationException`، در `UserProfileController::update()` بعد از validation فرمت و قبل از `hydrate`، یکتایی را چک کن. اگر کد ملی به پروفایلی با `uuid` **متفاوت** تعلق دارد → `409`:
+
+```php
+// داخل update()، بعد از بلوک normalize/validate فرمت (خط ~140)
+if (isset($data['national_code']) && $data['national_code'] !== '') {
+    $existing = $this->repository->findOneByNationalCode($data['national_code']);
+    if ($existing !== null && $existing->getUuid() !== $profile->getUuid()) {
+        return $this->error(
+            ErrorCodes::ERR_PROFILE_NATIONAL_CODE_TAKEN,
+            'این کد ملی قبلاً برای کاربر دیگری ثبت شده است',
+            409,
+            'national_code'
+        );
+    }
+}
+```
+
+### ۴. کد خطا
+
+در `src/Shared/Constant/ErrorCodes.php` کنار سایر `ERR_VALIDATION_*` اضافه کن:
+
+```php
+public const ERR_PROFILE_NATIONAL_CODE_TAKEN = 'ERR_PROFILE_001';
+```
+
+و پیام فارسی متناظرش را در همان نگاشتِ پیام‌ها (همان‌جا که بقیه کدها پیام دارند) قرار بده: «این کد ملی قبلاً برای کاربر دیگری ثبت شده است».
+
+### ۵. مسیرهای نوبت‌دهی منشی / سایر
+
+هر نقطه‌ای که از مسیرِ غیر-پروفایل کد ملی روی پروفایل یا کاربر می‌نشاند، باید همین چک `findOneByNationalCode` را قبل از set اجرا کند. بررسی کن این نقاط را و در صورت وجود set کد ملی روی `UserProfile`/`User`، چک را اضافه کن:
+
+- `src/Patient/Controller/PatientController.php` (`createPatient` — خطوط ~133–160، set روی `User`)
+- `src/Staff/Controller/StaffController.php` (خطوط 64, 91 — `ClinicStaff.nationalCode`؛ این **پرسنل** است نه بیمار، فقط در صورتی که staff به پروفایل بیمار map می‌شود چک لازم است — اگر نه، دست نزن)
+
+برای مسیر منشی/پنل که از `UserProfileController::update` می‌گذرد، وظیفه‌ی ۳ کافی است و نیازی به تکرار نیست.
+
+## نکات مهم
+
+- **partial-unique با NULL:** عمداً `NULL` را آزاد می‌گذاریم تا پروفایل‌های ناقصِ بدون کد ملی (که سیستم به‌صورت lazy می‌سازد — `resolveProfile`، خط 193) نشکنند. هرگز رشته‌ی خالی `''` ذخیره نکن؛ همیشه `null`. اگر جایی `''` می‌نشیند، به `null` نرمالایز کن وگرنه دو پروفایلِ `''` قید را می‌شکنند.
+- **دامنه‌ی یکتایی = global** (نه per-clinic). یک کد ملی در کل سیستم = یک بیمار.
+- چک اپلیکیشنی **race-condition** دارد (دو request همزمان)؛ قید DB لایه‌ی نهایی است. اگر خواستی، `UniqueConstraintViolationException` را در یک try/catch دور `save()` بگیر و همان `409` را برگردان تا حالت رقابتی هم پیام تمیز بدهد.
+- همه‌ی پاسخ‌ها از `BaseController`؛ خطا با `$this->error($code, $msg, 409, 'national_code')`.
+- بعد از تغییر `UserProfileController`، طبق قانون استاندارد پروژه `docs/api/user-profile.md` را در همین session به‌روز کن (افزودن پاسخ `409`).
+- **مصرف‌کنندگان (cross-repo):** سایت عمومی و پنل ادمین باید کد `ERR_PROFILE_001` / status `409` را روی فیلد `national_code` نمایش دهند. این در همین پرامپت پیاده نمی‌شود؛ فقط قرارداد را در doc ثبت کن تا کلاینت‌ها وصل شوند.