feat(appointment): identify admin-booked patient by national code

Admin-side booking (POST /api/v1/my/appointment and
/api/v1/admin/appointment) resolved the patient User by mobile only, so
one person booked under two mobiles produced two User rows — and two
case-files, since PatientRecord is keyed on user_id. National code is the
real unique identity (User.national_code is already unique); a person may
have several mobiles.

Booking now requires + validates patient_national_code and resolves the
patient national-code-first (then mobile) via a shared PatientResolver, so
the case-file stays unique per national code even across mobiles. Reusing a
mobile already bound to a different national code returns 422
ERR_PROFILE_MOBILE_TAKEN. The admin create form and NewAppointmentDrawer
gain a national-code field and send it; both had a dead patient-picker URL
(/api/v1/patient) fixed to the real /api/v1/patients, whose payload already
carries user_national_code for autofill.

Docs (appointment.md, admin.md) and tests updated; new
AppointmentNationalCodeTest covers success, single-file reuse, missing,
invalid, and identity-conflict cases.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

src/Patient/Service/PatientResolver.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace App\Patient\Service;
+
+use App\Auth\Entity\User;
+use App\Auth\Repository\UserRepository;
+use App\Shared\Constant\ErrorCodes;
+use App\Shared\Exception\AppException;
+
+/**
+ * Resolves (or creates) the patient User for an admin-side booking.
+ *
+ * Identity key is the national code, which is unique per person. Mobile is only
+ * a contact detail — one national code may be booked under several mobiles — so
+ * lookup prefers the national code and never overwrites an existing mobile.
+ * Keeping resolution here (not duplicated in each controller) keeps the case-file
+ * (PatientRecord, keyed on user_id) unique per national code.
+ */
+class PatientResolver
+{
+    public function __construct(private readonly UserRepository $userRepo) {}
+
+    /**
+     * @param string $nationalCode already normalized to English digits and validated
+     */
+    public function resolveForBooking(string $nationalCode, string $mobile, string $name): User
+    {
+        $user = $this->userRepo->findByNationalCode($nationalCode);
+        if ($user !== null) {
+            $this->fillNameIfEmpty($user, $name);
+            return $user;
+        }
+
+        $user = $this->userRepo->findByMobile($mobile);
+        if ($user !== null) {
+            $existing = $user->getNationalCode();
+            if ($existing !== null && $existing !== $nationalCode) {
+                throw new AppException(ErrorCodes::ERR_PROFILE_MOBILE_TAKEN, 'این شماره موبایل با کد ملی دیگری ثبت شده است', 422, 'patient_mobile');
+            }
+            if ($existing === null) {
+                $user->setNationalCode($nationalCode);
+            }
+            $this->fillNameIfEmpty($user, $name);
+            return $user;
+        }
+
+        $user = new User($mobile);
+        $user->setRealName($name);
+        $user->setNationalCode($nationalCode);
+        $user->setRoles(['ROLE_USER']);
+        $this->userRepo->save($user, false);
+
+        return $user;
+    }
+
+    private function fillNameIfEmpty(User $user, string $name): void
+    {
+        if (($user->getRealName() ?? '') === '' && $name !== '') {
+            $user->setRealName($name);
+        }
+    }
+}