feat: enhance payment status handling and summary in MyPaymentsPage

- Added support for 'partial' payment status in MyPaymentsPage and related components.
- Updated API responses to include 'paid_rials' and 'summary' for invoices.
- Introduced InvoicePaymentStatus service to derive payment status based on actual payments.
- Enhanced tests to cover new payment scenarios including partial payments and payment methods.
- Updated documentation to reflect changes in payment status and API responses.

assets/admin/pages/MyPaymentDetailPage.tsx

@@ -1,20 +1,20 @@
-import { Fragment, useState } from 'react';
+import { useState } from 'react';
 import { useNavigate, useParams } from 'react-router-dom';
 import { ChevronRightIcon, ChevronDownIcon, PlusIcon } from '@heroicons/react/24/outline';
 import { toast } from 'sonner';
 import PageHeader from '../components/ui/PageHeader';
 import Pagination from '../components/ui/Pagination';
+import StatCard from '../components/ui/StatCard';
+import StatusBadge from '../components/ui/StatusBadge';
+import DataTable, { type Column } from '../components/ui/DataTable';
 import { formatRial, formatDate, formatNumber } from '../lib/utils';
+import { paymentMethodLabel } from '../lib/paymentMethods';
 import {
   usePatientInvoices,
   MY_PAYMENTS_LIMIT,
   type PatientInvoiceRow,
-  type InvoiceRowStatus,
 } from '../hooks/useMyPayments';
 
-const STATUS_LABEL: Record<InvoiceRowStatus, string> = { paid: 'پرداخت شده', unsettled: 'تسویه نشده' };
-const STATUS_BADGE: Record<InvoiceRowStatus, string> = { paid: 'green', unsettled: 'amber' };
-
 const EMPTY: PatientInvoiceRow[] = [];
 
 /** HH:MM (Persian digits) from a unix timestamp. */
@@ -22,7 +22,73 @@ function formatTime(unix: number): string {
   return new Intl.DateTimeFormat('fa-IR', { hour: '2-digit', minute: '2-digit' }).format(new Date(unix * 1000));
 }
 
-/** پرداخت‌های ثبت‌شده — a single patient's recorded invoices (node 2). */
+function Avatar({ name }: { name: string | null }) {
+  return (
+    <div style={{
+      width: 44, height: 44, borderRadius: '50%', flexShrink: 0,
+      background: 'linear-gradient(145deg, var(--primary), var(--primary-700, var(--primary)))',
+      display: 'grid', placeItems: 'center', color: '#fff', fontSize: 17, fontWeight: 700,
+    }}>
+      {(name ?? '؟').charAt(0)}
+    </div>
+  );
+}
+
+function Section({ title, children }: { title: string; children: React.ReactNode }) {
+  return (
+    <div style={{ minWidth: 220, flex: '1 1 260px' }}>
+      <div style={{ fontSize: 12, fontWeight: 700, color: 'var(--text-3)', marginBottom: 8 }}>{title}</div>
+      {children}
+    </div>
+  );
+}
+
+/** آیتم‌های صورتحساب و پرداخت‌های ثبت‌شده‌ی آن، کنار هم در ردیف بازشونده. */
+function InvoiceBreakdown({ row }: { row: PatientInvoiceRow }) {
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 24 }}>
+      <Section title="آیتم‌های صورتحساب">
+        {row.items.length === 0 ? (
+          <span style={{ fontSize: 12.5, color: 'var(--text-3)' }}>آیتمی ثبت نشده است.</span>
+        ) : (
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+            {row.items.map((it) => (
+              <div key={it.uuid} style={{ display: 'flex', justifyContent: 'space-between', gap: 12, fontSize: 13 }}>
+                <span style={{ color: 'var(--text-2)' }}>
+                  {it.title}{it.quantity > 1 ? ` × ${formatNumber(it.quantity)}` : ''}
+                </span>
+                <span style={{ fontWeight: 600 }}>{formatRial(it.total_rials)}</span>
+              </div>
+            ))}
+          </div>
+        )}
+      </Section>
+
+      <Section title="روش‌های پرداخت">
+        {row.payments.length === 0 ? (
+          <span style={{ fontSize: 12.5, color: 'var(--text-3)' }}>پرداختی ثبت نشده است.</span>
+        ) : (
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+            {row.payments.map((p, i) => (
+              <div key={i} style={{ display: 'flex', justifyContent: 'space-between', gap: 12, fontSize: 13 }}>
+                <span style={{ display: 'inline-flex', alignItems: 'center', gap: 6, color: 'var(--text-2)' }}>
+                  <span className="badge gray"><span className="bdot" />{paymentMethodLabel(p.method)}</span>
+                  <span style={{ fontSize: 11.5, color: 'var(--text-3)' }} dir="ltr">{formatDate(p.paid_at)}</span>
+                </span>
+                <span style={{ fontWeight: 600 }}>{formatRial(p.amount_rials)}</span>
+              </div>
+            ))}
+          </div>
+        )}
+      </Section>
+    </div>
+  );
+}
+
+/**
+ * پرداخت‌های ثبت‌شده‌ی یک بیمار — سربرگ بیمار، کارت‌های آمار و جدول صورتحساب‌ها
+ * با ردیف بازشونده‌ی آیتم‌ها و روش‌های پرداخت.
+ */
 export default function MyPaymentDetailPage() {
   const { patientUuid } = useParams<{ patientUuid: string }>();
   const navigate = useNavigate();
@@ -33,15 +99,41 @@ export default function MyPaymentDetailPage() {
   const payload = data?.data;
   const patient = payload?.patient;
   const rows = payload?.data ?? EMPTY;
+  const summary = payload?.summary;
   const total = payload?.meta?.totalRecords ?? 0;
 
-  const th: React.CSSProperties = { textAlign: 'right', padding: '12px 16px', fontWeight: 600 };
-  const td: React.CSSProperties = { padding: '12px 16px' };
+  const columns: Column<PatientInvoiceRow>[] = [
+    { key: 'number', header: 'شماره صورتحساب', render: (r) => <span style={{ fontWeight: 600 }} dir="ltr">#{formatNumber(r.number)}</span> },
+    { key: 'issued_at', header: 'تاریخ', render: (r) => formatDate(r.issued_at) },
+    { key: 'time', header: 'ساعت', render: (r) => <span dir="ltr">{formatTime(r.issued_at)}</span> },
+    { key: 'service_title', header: 'نوع خدمت', render: (r) => <span style={{ color: 'var(--text-2)' }}>{r.service_title ?? '—'}</span> },
+    {
+      key: 'total_rials',
+      header: 'مبلغ کل',
+      render: (r) => (
+        <div>
+          <div style={{ fontWeight: 600 }}>{formatRial(r.total_rials)}</div>
+          {r.status === 'partial' && (
+            <div style={{ fontSize: 11.5, color: 'var(--text-3)', marginTop: 2 }}>
+              پرداخت‌شده: {formatRial(r.paid_rials)}
+            </div>
+          )}
+        </div>
+      ),
+    },
+    { key: 'status', header: 'وضعیت', render: (r) => <StatusBadge type="invoice" value={r.status} /> },
+  ];
 
   return (
     <>
       <PageHeader
         title="پرداخت‌های ثبت‌شده"
+        description="صورتحساب‌های ثبت‌شده‌ی این بیمار"
+        breadcrumbs={[
+          { label: 'داشبورد', to: '/admin' },
+          { label: 'لیست پرداخت‌ها', to: '/admin/my-payments' },
+          { label: patient?.name ?? 'بیمار' },
+        ]}
         action={
           <div style={{ display: 'flex', gap: 8 }}>
             <button className="btn sm" onClick={() => navigate('/admin/my-payments')}>
@@ -54,97 +146,46 @@ export default function MyPaymentDetailPage() {
         }
       />
 
-      {/* سربرگ بیمار */}
-      <div style={{
-        display: 'flex', gap: 24, flexWrap: 'wrap', alignItems: 'center',
-        marginBottom: 16, padding: '14px 16px',
-        background: 'var(--surface)', border: '1px solid var(--border)', borderRadius: 'var(--r)',
-      }}>
-        <span style={{ fontSize: 14 }}>
-          نام بیمار: <b style={{ fontWeight: 700 }}>{patient?.name ?? '—'}</b>
-        </span>
-        <span style={{ fontSize: 14, color: 'var(--text-2)' }} dir="ltr">
-          کدملی: {patient?.national_code ?? '—'}
-        </span>
+      <div className="card" style={{ display: 'flex', alignItems: 'center', gap: 14, padding: '14px 18px', marginBottom: 'var(--gap)' }}>
+        <Avatar name={patient?.name ?? null} />
+        <div style={{ minWidth: 0 }}>
+          <div style={{ fontWeight: 700, fontSize: 15 }}>{patient?.name ?? '—'}</div>
+          <div style={{ fontSize: 12.5, color: 'var(--text-3)', marginTop: 3 }} dir="ltr">
+            {patient?.national_code ?? '—'}
+          </div>
+        </div>
       </div>
 
-      {isLoading ? (
-        <div className="card" style={{ padding: 32, textAlign: 'center', color: 'var(--text-3)' }}>در حال بارگذاری…</div>
-      ) : rows.length === 0 ? (
-        <div className="card" style={{ padding: '60px 24px', textAlign: 'center', color: 'var(--text-3)' }}>
-          <div style={{ fontWeight: 600, fontSize: 15, marginBottom: 6, color: 'var(--text-2)' }}>صورتحسابی ثبت نشده است</div>
-          <div style={{ fontSize: 13 }}>برای این بیمار هنوز پرداخت ثبت‌شده‌ای وجود ندارد.</div>
-        </div>
-      ) : (
-        <>
-          <div className="card" style={{ overflowX: 'auto' }}>
-            <table style={{ width: '100%', borderCollapse: 'collapse', fontSize: 13.5 }}>
-              <thead>
-                <tr style={{ borderBottom: '1px solid var(--border)', color: 'var(--text-3)', fontSize: 12 }}>
-                  <th style={th}>شماره صورتحساب</th>
-                  <th style={th}>تاریخ</th>
-                  <th style={th}>ساعت</th>
-                  <th style={th}>نوع خدمت</th>
-                  <th style={th}>مبلغ کل (تومان)</th>
-                  <th style={th}>وضعیت</th>
-                  <th style={{ ...th, textAlign: 'left' }}>جزئیات</th>
-                </tr>
-              </thead>
-              <tbody>
-                {rows.map((row) => {
-                  const open = expanded === row.uuid;
-                  return (
-                    <Fragment key={row.uuid}>
-                      <tr style={{ borderBottom: open ? 'none' : '1px solid var(--border)' }}>
-                        <td style={{ ...td, fontWeight: 600 }} dir="ltr">#{formatNumber(row.number)}</td>
-                        <td style={td}>{formatDate(row.issued_at)}</td>
-                        <td style={td} dir="ltr">{formatTime(row.issued_at)}</td>
-                        <td style={{ ...td, color: 'var(--text-2)' }}>{row.service_title ?? '—'}</td>
-                        <td style={{ ...td, fontWeight: 600 }}>{formatRial(row.total_rials)}</td>
-                        <td style={td}>
-                          <span className={`badge ${STATUS_BADGE[row.status]}`}><span className="bdot" />{STATUS_LABEL[row.status]}</span>
-                        </td>
-                        <td style={{ ...td, textAlign: 'left' }}>
-                          <button
-                            className="btn sm ghost"
-                            style={{ display: 'inline-flex', alignItems: 'center', gap: 4, color: 'var(--primary)' }}
-                            onClick={() => setExpanded(open ? null : row.uuid)}
-                          >
-                            بیشتر <ChevronDownIcon style={{ width: 15, transform: open ? 'rotate(180deg)' : undefined, transition: 'transform .15s' }} />
-                          </button>
-                        </td>
-                      </tr>
-                      {open && (
-                        <tr style={{ borderBottom: '1px solid var(--border)', background: 'var(--surface-2)' }}>
-                          <td colSpan={7} style={{ padding: '10px 16px 14px' }}>
-                            {row.items.length === 0 ? (
-                              <span style={{ fontSize: 12.5, color: 'var(--text-3)' }}>آیتمی ثبت نشده است.</span>
-                            ) : (
-                              <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
-                                {row.items.map((it) => (
-                                  <div key={it.uuid} style={{ display: 'flex', justifyContent: 'space-between', gap: 12, fontSize: 13 }}>
-                                    <span style={{ color: 'var(--text-2)' }}>
-                                      {it.title}{it.quantity > 1 ? ` × ${formatNumber(it.quantity)}` : ''}
-                                    </span>
-                                    <span style={{ fontWeight: 600 }}>{formatRial(it.total_rials)}</span>
-                                  </div>
-                                ))}
-                              </div>
-                            )}
-                          </td>
-                        </tr>
-                      )}
-                    </Fragment>
-                  );
-                })}
-              </tbody>
-            </table>
-          </div>
-          <div style={{ marginTop: 16 }}>
-            <Pagination page={page} total={total} limit={MY_PAYMENTS_LIMIT} onPageChange={setPage} />
-          </div>
-        </>
-      )}
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))', gap: 'var(--gap)', marginBottom: 'var(--gap)' }}>
+        <StatCard tone="violet" label="مجموع صورتحساب‌ها" value={formatRial(summary?.total_rials ?? 0)} />
+        <StatCard tone="green" label="پرداخت‌شده" value={formatRial(summary?.paid_rials ?? 0)} />
+        <StatCard tone="pink" label="تسویه‌نشده" value={formatRial(summary?.unsettled_rials ?? 0)} />
+        <StatCard tone="amber" label="تعداد صورتحساب" value={formatNumber(summary?.invoices_count ?? 0)} />
+      </div>
+
+      <div className="card" style={{ padding: 18 }}>
+        <DataTable
+          columns={columns}
+          data={rows}
+          loading={isLoading}
+          emptyMessage="صورتحسابی ثبت نشده است."
+          actions={(row) => (
+            <button
+              className="btn ghost sm"
+              style={{ display: 'inline-flex', alignItems: 'center', gap: 4, color: 'var(--primary)' }}
+              onClick={() => setExpanded(expanded === row.uuid ? null : row.uuid)}
+            >
+              بیشتر
+              <ChevronDownIcon style={{ width: 15, transform: expanded === row.uuid ? 'rotate(180deg)' : undefined, transition: 'transform .15s' }} />
+            </button>
+          )}
+          renderExpanded={(row) => (expanded === row.uuid ? <InvoiceBreakdown row={row} /> : null)}
+        />
+
+        {total > MY_PAYMENTS_LIMIT && (
+          <Pagination page={page} total={total} limit={MY_PAYMENTS_LIMIT} onPageChange={setPage} />
+        )}
+      </div>
     </>
   );
 }