feat(doctor): complete IRIMC import feature — claim flow, least-privilege importer, unique import key

- Extract import logic from AdminApiController into DoctorImportService (thin DoctorImportController keeps the same route/contract) - Surrogate users get marker role ROLE_UNCLAIMED_DOCTOR (+ backfill command app:doctors:backfill-surrogate-role) enabling safe deletion after claim - DB-level UNIQUE (source, medical_system_code) + concurrent-import retry - Doctor profile claim flow (climed.md): shahkar + PersonInfo identity checks via existing ApiIrService, Persian name normalization (PersianText), pessimistic-lock race protection, DoctorClaimRequest audit table (national code hashed, mobile masked), doctor_claim rate limiter, public claim-info endpoint, welcome SMS - Admin support tools: manual transfer endpoint + paginated doctor-claims audit list + owner_status filter/fields in admin doctors list - Least privilege: system owner now gets ROLE_IMPORTER (ROLE_ADMIN stripped), import endpoint accepts ADMIN|IMPORTER, isStaff includes IMPORTER - Headless crawler login: X-Service-Token header bypasses captcha only (rate limit + password checks intact; empty env = no bypass) - docs: doctor-claim.md (new), doctor-import.md, admin.md, doctor.md - tests: DoctorImportTest (6), DoctorClaimTest (11), PersianTextTest (5) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-11 11:39:15 +03:30
parent 83c872bb78
commit af125572c9
29 changed files with 1944 additions and 303 deletions
@@ -0,0 +1,131 @@
+<?php
+
+namespace App\Doctor\Service;
+
+use App\Auth\Entity\User;
+use App\Doctor\Entity\Doctor;
+use App\Location\Entity\City;
+use App\Location\Entity\Province;
+use App\Specialty\Entity\Specialty;
+use Doctrine\DBAL\Exception\UniqueConstraintViolationException;
+use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\Persistence\ManagerRegistry;
+
+/**
+ * ایمپورت پزشک از سازمان نظام پزشکی (IRIMC) — منطق دامنه، جدا از کنترلر.
+ *
+ * برخلاف ساخت عادی پزشک، موبایل لازم نیست: برای هر پزشک یک «کاربر جانشین»
+ * غیرفعال با شناسهٔ مصنوعی ساخته می‌شود و پروفایل در وضعیت unclaimed ذخیره
+ * می‌گردد تا بعداً به پزشک واقعی منتقل شود. idempotent بر پایهٔ
+ * (source, medical_system_code): اجرای مجدد، رکورد موجود را به‌روزرسانی می‌کند
+ * و پروفایل claimed هرگز بازنویسی نمی‌شود (مالک واقعی اولویت دارد).
+ */
+class DoctorImportService
+{
+    /** نقش marker کاربر جانشین — permission نمی‌دهد؛ مبنای شناسایی و حذف امن پس از claim است. */
+    public const ROLE_UNCLAIMED_DOCTOR = 'ROLE_UNCLAIMED_DOCTOR';
+
+    public function __construct(
+        private readonly EntityManagerInterface $em,
+        private readonly ManagerRegistry $registry,
+    ) {}
+
+    /** @param array $data بدنهٔ validated (name و medical_system_code غیرخالی). */
+    public function import(array $data, User $importedBy): DoctorImportResult
+    {
+        try {
+            return $this->doImport($data, $importedBy);
+        } catch (UniqueConstraintViolationException) {
+            // برندهٔ هم‌زمانی رکورد را همین الان ساخته (قید uniq_doctors_source_code).
+            // EM پس از این خطا بسته است — reset و اجرای مجدد که این‌بار مسیر update را می‌رود.
+            $this->registry->resetManager();
+            return $this->doImport($data, $importedBy);
+        }
+    }
+
+    private function doImport(array $data, User $importedBy): DoctorImportResult
+    {
+        return $this->em->wrapInTransaction(function () use ($data, $importedBy): DoctorImportResult {
+            $name   = trim((string) $data['name']);
+            $code   = trim((string) ($data['medical_system_code'] ?? $data['medicalSystemCode']));
+            $source = trim((string) ($data['source'] ?? 'irimc')) ?: 'irimc';
+
+            $doctorRepo = $this->em->getRepository(Doctor::class);
+            $userRepo   = $this->em->getRepository(User::class);
+
+            // idempotency: همان پزشکِ منبع → به‌روزرسانی، نه ساخت تکراری
+            $doctor  = $doctorRepo->findOneBy(['source' => $source, 'medicalSystemCode' => $code]);
+            $created = false;
+
+            // پروفایل تصاحب‌شده را با ایمپورت مجدد بازنویسی نکن (مالک واقعی اولویت دارد)
+            if ($doctor !== null && $doctor->getOwnerStatus() === 'claimed') {
+                return new DoctorImportResult($doctor, false, 'claimed');
+            }
+
+            if ($doctor === null) {
+                // کاربر جانشینِ یکتا و غیرفعال؛ شناسهٔ مصنوعی قطعی از روی کد نظام پزشکی
+                $synthetic = 'imp_' . substr(md5($source . ':' . $code), 0, 14); // ≤ ۱۸ کاراکتر، ASCII، یکتا
+                $user = $userRepo->findOneBy(['mobileNumber' => $synthetic]);
+                if ($user === null) {
+                    $user = new User($synthetic);
+                    $user->setRealName($name);
+                    $user->setStatus(0); // جانشین: هرگز لاگین نمی‌کند
+                    $user->addRole(self::ROLE_UNCLAIMED_DOCTOR);
+                    $this->em->persist($user);
+                }
+                $doctor = new Doctor($user, $name);
+                $doctor->setSource($source);
+                $doctor->setOwnerStatus('unclaimed');
+                $doctor->setActiveDoctorAppointment(false); // تا مالک واقعی برنامهٔ کاری بسازد
+                $created = true;
+            }
+
+            // backfill: جانشین‌های ایمپورت‌شده پیش از افزودن نقش marker، در ایمپورت مجدد نقش می‌گیرند
+            $surrogate = $doctor->getUser();
+            if (!$created
+                && str_starts_with($surrogate->getMobileNumber(), 'imp_')
+                && !$surrogate->hasRole(self::ROLE_UNCLAIMED_DOCTOR)) {
+                $surrogate->addRole(self::ROLE_UNCLAIMED_DOCTOR);
+            }
+
+            // فیلدهای مشترک
+            $doctor->setName($name);
+            $doctor->setMedicalSystemCode($code);
+            $doctor->setManagedBy($importedBy->getId());
+            if (array_key_exists('source_ref', $data) || array_key_exists('profile_url', $data)) {
+                $doctor->setSourceRef($data['source_ref'] ?? $data['profile_url'] ?? null);
+            }
+            if (!empty($data['gender'])) $doctor->setGender($data['gender']);
+            if (!empty($data['degree'])) $doctor->setDegree($data['degree']);
+            if (array_key_exists('info', $data)) $doctor->setInfo($data['info']);
+
+            // روابط بر پایهٔ شناسه‌های مرجع (تخصص/استان/شهر)
+            $this->syncRefCollection($doctor->getSpecialties(), $data['specialties'] ?? null, Specialty::class);
+            $this->syncRefCollection($doctor->getProvinces(),   $data['states'] ?? null,      Province::class);
+            $this->syncRefCollection($doctor->getCities(),      $data['cities'] ?? null,       City::class);
+
+            $this->em->persist($doctor);
+            $this->em->flush();
+
+            return new DoctorImportResult($doctor, $created);
+        });
+    }
+
+    /**
+     * یک مجموعهٔ ManyToMany پزشک را با آرایه‌ای از شناسه‌های مرجع همگام می‌کند.
+     * اگر $ids null باشد دست نمی‌خورد؛ اگر آرایه باشد، پاک و از نو پر می‌شود.
+     */
+    private function syncRefCollection(\Doctrine\Common\Collections\Collection $col, ?array $ids, string $class): void
+    {
+        if ($ids === null) {
+            return;
+        }
+        $col->clear();
+        foreach ($ids as $id) {
+            $ref = $this->em->getRepository($class)->find((int) $id);
+            if ($ref !== null && !$col->contains($ref)) {
+                $col->add($ref);
+            }
+        }
+    }
+}