fix: return patient national code from profile in patients list

National code is stored on the profiles table, not users, so the patients
search returned null user_national_code for patients that actually have one
— which blocked selecting an existing patient on the appointment create
form. Backfill user_national_code from the profile (batch query) in the
list endpoint. On the create page, show a picked patient's stored national
code read-only and only prompt for input when the record genuinely lacks
one. Add backend tests and update docs/api/patient.md.

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

src/Patient/Controller/PatientController.php

@@ -542,12 +542,18 @@ class PatientController extends BaseController
         $records = $this->recordRepo->findByEntity($entityType, $entityId, $page, $limit, $search, $filters);
         $total   = $this->recordRepo->countByEntity($entityType, $entityId, $search, $filters);
 
-        return $this->paginated(
-            array_map(fn(PatientRecord $r) => $r->toArray(), $records),
-            $total,
-            $page,
-            $limit
-        );
+        // کد ملی روی profiles ذخیره می‌شود نه users؛ اگر روی user خالی بود از پروفایل پر کن.
+        $userIds = array_map(fn(PatientRecord $r) => $r->getUser()->getId(), $records);
+        $profileCodes = $this->profileRepo->nationalCodesByUserIds($userIds);
+        $rows = array_map(function (PatientRecord $r) use ($profileCodes) {
+            $row = $r->toArray();
+            if (empty($row['user_national_code'])) {
+                $row['user_national_code'] = $profileCodes[$r->getUser()->getId()] ?? null;
+            }
+            return $row;
+        }, $records);
+
+        return $this->paginated($rows, $total, $page, $limit);
     }
 
     #[Route('/api/v1/patient', methods: ['POST'])]

src/UserProfile/Repository/UserProfileRepository.php

@@ -29,6 +29,31 @@ class UserProfileRepository extends ServiceEntityRepository
         return $this->findOneBy(['nationalCode' => $nationalCode]);
     }
 
+    /**
+     * نگاشتِ userId → کد ملیِ ذخیره‌شده روی پروفایل، فقط برای پروفایل‌هایی که کد ملی دارند.
+     * برای پر کردنِ گروهیِ کد ملی در لیست بیماران (کد ملی روی profiles است نه users).
+     *
+     * @param int[] $userIds
+     * @return array<int,string>
+     */
+    public function nationalCodesByUserIds(array $userIds): array
+    {
+        if ($userIds === []) {
+            return [];
+        }
+        $rows = $this->createQueryBuilder('p')
+            ->select('IDENTITY(p.user) AS uid', 'p.nationalCode AS nc')
+            ->where('p.user IN (:ids)')->setParameter('ids', $userIds)
+            ->andWhere('p.nationalCode IS NOT NULL')
+            ->getQuery()->getArrayResult();
+
+        $map = [];
+        foreach ($rows as $r) {
+            $map[(int) $r['uid']] = (string) $r['nc'];
+        }
+        return $map;
+    }
+
     public function save(UserProfile $profile, bool $flush = true): void
     {
         $this->getEntityManager()->persist($profile);