feat(patients): phase B2 — attachments (ضمیمه)

Add patient file attachments: a new PatientAttachment entity (record-scoped,
CASCADE) + repository, and endpoints GET /patient/{uuid}/attachments,
POST /patient/{uuid}/attachment (raw-body upload) and DELETE
/patient/attachment/{uuid} (owner-scoped). Factor the shared raw-body upload
logic into FileUploadService. Wire the "ضمیمه" tab in PatientDetailPage
(upload + list + delete). PHPUnit covers list/delete/ownership; Vitest covers
the tab. API docs updated.

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

assets/admin/pages/PatientDetailPage.test.tsx

@@ -58,4 +58,12 @@ describe('PatientDetailPage (پرونده تب‌دار)', () => {
     fireEvent.click(screen.getByText('پیام‌ها'));
     expect(screen.getByText(/به‌زودی تکمیل می‌شود/)).toBeInTheDocument();
   });
+
+  it('renders the attachments tab with an upload button', async () => {
+    renderDetail();
+    await screen.findByText('ساغر صابری');
+    fireEvent.click(screen.getByText('ضمیمه'));
+    expect(await screen.findByRole('button', { name: /آپلود فایل جدید/ })).toBeInTheDocument();
+    expect(await screen.findByText('هنوز فایلی ضمیمه نشده است.')).toBeInTheDocument();
+  });
 });

assets/admin/pages/PatientDetailPage.tsx

@@ -1,14 +1,17 @@
-import { useState } from 'react';
-import { useQuery } from '@tanstack/react-query';
+import { useRef, useState } from 'react';
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import { useParams, Link } from 'react-router-dom';
 import {
   ChevronRightIcon, PencilIcon, ClipboardDocumentCheckIcon, DocumentTextIcon,
   CalendarDaysIcon, CreditCardIcon, BanknotesIcon, ChatBubbleLeftRightIcon,
   PhoneArrowUpRightIcon, PaperClipIcon, ClipboardDocumentListIcon,
+  ArrowUpTrayIcon, TrashIcon, DocumentIcon,
 } from '@heroicons/react/24/outline';
+import { toast } from 'sonner';
 import { api } from '../lib/api';
 import type { ApiResponse } from '../lib/api';
 import type { PatientRecord } from '../types';
+import { useAuthStore } from '../stores/authStore';
 import { formatDate } from '../lib/utils';
 
 type TabKey = 'services' | 'info' | 'appointments' | 'payments' | 'wallet' | 'messages' | 'callcenter' | 'attach' | 'records';
@@ -120,6 +123,8 @@ export default function PatientDetailPage() {
       ) : tab === 'appointments' ? (
         <TabList q={appointmentsQ} emptyLabel="نوبتی ثبت نشده است"
           row={(a) => ({ title: a.service_name || a.doctor_name || 'نوبت', meta: a.date ? formatDate(a.date) : (a.starts_at ? formatDate(a.starts_at) : ''), badge: a.status_label || a.status })} />
+      ) : tab === 'attach' ? (
+        <AttachmentsTab uuid={uuid!} />
       ) : (
         <Placeholder label={TABS.find((t) => t.key === tab)!.label} />
       )}
@@ -127,6 +132,88 @@ export default function PatientDetailPage() {
   );
 }
 
+interface Attachment { uuid: string; name: string; url: string; mime?: string | null; size?: number | null }
+
+const formatBytes = (n?: number | null) => {
+  if (!n) return '';
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${Math.round(n / 1024)} KB`;
+  return `${(n / 1024 / 1024).toFixed(1)} MB`;
+};
+
+/** ضمیمه — patient attachments: upload (raw body), list, delete. */
+function AttachmentsTab({ uuid }: { uuid: string }) {
+  const qc = useQueryClient();
+  const fileRef = useRef<HTMLInputElement>(null);
+  const [uploading, setUploading] = useState(false);
+
+  const { data, isLoading } = useQuery<ApiResponse<Attachment[]>>({
+    queryKey: ['patient-attachments', uuid],
+    queryFn: () => api.get(`/api/v1/patient/${uuid}/attachments`),
+  });
+  const items = data?.data ?? [];
+
+  const del = useMutation({
+    mutationFn: (attUuid: string) => api.delete(`/api/v1/patient/attachment/${attUuid}`),
+    onSuccess: () => { qc.invalidateQueries({ queryKey: ['patient-attachments', uuid] }); toast.success('ضمیمه حذف شد'); },
+    onError: (e: any) => toast.error(e.message),
+  });
+
+  const onFile = async (file: File) => {
+    setUploading(true);
+    try {
+      const token = useAuthStore.getState().token;
+      const res = await fetch(`/api/v1/patient/${uuid}/attachment?name=${encodeURIComponent(file.name)}`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/octet-stream',
+          'Content-Disposition': `attachment; filename="${file.name}"`,
+          ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        },
+        body: file,
+      });
+      if (!res.ok) throw new Error('خطا در آپلود فایل');
+      qc.invalidateQueries({ queryKey: ['patient-attachments', uuid] });
+      toast.success('فایل آپلود شد');
+    } catch (e: any) {
+      toast.error(e.message);
+    } finally {
+      setUploading(false);
+      if (fileRef.current) fileRef.current.value = '';
+    }
+  };
+
+  return (
+    <div>
+      <div style={{ marginBottom: 14 }}>
+        <input ref={fileRef} type="file" hidden onChange={(e) => e.target.files?.[0] && onFile(e.target.files[0])} />
+        <button className="btn primary" disabled={uploading} onClick={() => fileRef.current?.click()}>
+          <ArrowUpTrayIcon style={{ width: 16 }} /> {uploading ? 'در حال آپلود...' : 'آپلود فایل جدید'}
+        </button>
+      </div>
+
+      {isLoading ? (
+        <div style={{ padding: 16, color: 'var(--text-3)', fontSize: 13 }}>در حال بارگذاری...</div>
+      ) : items.length === 0 ? (
+        <div style={{ padding: '40px 0', textAlign: 'center', color: 'var(--text-3)', fontSize: 14 }}>هنوز فایلی ضمیمه نشده است.</div>
+      ) : (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+          {items.map((a) => (
+            <div key={a.uuid} style={{ background: 'var(--surface)', border: '1px solid var(--border)', borderRadius: 'var(--r-lg)', padding: '12px 16px', display: 'flex', alignItems: 'center', gap: 12 }}>
+              <DocumentIcon style={{ width: 22, color: 'var(--primary)', flexShrink: 0 }} />
+              <div style={{ flex: 1, minWidth: 0 }}>
+                <a href={a.url} target="_blank" rel="noreferrer" style={{ fontWeight: 600, fontSize: 14, color: 'var(--text)', textDecoration: 'none', wordBreak: 'break-all' }}>{a.name}</a>
+                {a.size ? <div style={{ fontSize: 12, color: 'var(--text-3)' }}>{formatBytes(a.size)}</div> : null}
+              </div>
+              <button className="btn sm ghost" aria-label="حذف" style={{ color: 'var(--danger)' }} onClick={() => del.mutate(a.uuid)}><TrashIcon style={{ width: 16 }} /></button>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
 function TabList({ q, emptyLabel, row }: {
   q: { data?: ApiResponse<any[]>; isLoading: boolean };
   emptyLabel: string;