feat: insurance & medical billing system (6 phases)

Multi-tenant insurance contracts, service coverage, versioned tariffs,
invoice calculation, and insurance claims with debt reporting.

- TenantInsurance: per-tenant insurance contracts (coverage/franchise/ceiling,
  versioning, soft-deactivate) + active guard
- ServiceItem.insuranceCovered + TenantServiceCoverage per-service overrides
- Tariff: versioned yearly tariffs with fallback to ServiceItem price
- Billing domain: Money/ShareBreakdown VOs, BillingCalculator (unit-tested),
  Invoice/InvoiceItem aggregate, InvoiceService.createFromSession
- Claim/ClaimItem with state machine (pending->submitted->approved/rejected->paid),
  ClaimService, insurance-debt report
- ClaimSubmitterInterface + ManualClaimSubmitter (future insurance API ready)
- Admin UI: insurance-pricing page, claims page, service tariff modal,
  service insurance toggle; routes + sidebar entries
- Architecture doc + billing/insurance/clinic-services API docs

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

assets/admin/pages/ClaimsPage.tsx

@@ -0,0 +1,187 @@
+import { useState } from 'react';
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { CheckIcon, XMarkIcon, PaperAirplaneIcon, BanknotesIcon } from '@heroicons/react/24/outline';
+import { toast } from 'sonner';
+import { api } from '../lib/api';
+import { formatRial, formatNumber } from '../lib/utils';
+import PageHeader from '../components/ui/PageHeader';
+import Modal from '../components/ui/Modal';
+
+interface ClaimItem {
+  invoice_item_id: number;
+  claimed_rials: number;
+  approved_rials: number | null;
+}
+
+interface Claim {
+  uuid: string;
+  insurance_id: number;
+  insurance_kind: string;
+  total_claimed_rials: number;
+  total_approved_rials: number | null;
+  total_paid_rials: number | null;
+  status: string;
+  reject_reason: string | null;
+  items: ClaimItem[];
+}
+
+interface DebtRow {
+  insurance_id: number;
+  claimed: number;
+  approved: number;
+  paid: number;
+  debt: number;
+}
+
+const STATUS_META: Record<string, { label: string; cls: string }> = {
+  pending: { label: 'در انتظار', cls: 'gray' },
+  submitted: { label: 'ارسال‌شده', cls: 'blue' },
+  approved: { label: 'تأییدشده', cls: 'amber' },
+  rejected: { label: 'ردشده', cls: 'red' },
+  paid: { label: 'پرداخت‌شده', cls: 'green' },
+};
+
+const KIND_LABEL: Record<string, string> = { base: 'پایه', supplementary: 'تکمیلی' };
+const STATUS_FILTERS = ['', 'pending', 'submitted', 'approved', 'rejected', 'paid'];
+
+export default function ClaimsPage() {
+  const qc = useQueryClient();
+  const [statusFilter, setStatusFilter] = useState('');
+  const [rejectTarget, setRejectTarget] = useState<Claim | null>(null);
+  const [rejectReason, setRejectReason] = useState('');
+
+  const claimsQuery = useQuery<{ data: { data: Claim[] } }>({
+    queryKey: ['claims', statusFilter],
+    queryFn: () => api.get(`/api/v1/billing/claims${statusFilter ? `?status=${statusFilter}` : ''}`),
+  });
+
+  const debtQuery = useQuery<{ data: { data: DebtRow[] } }>({
+    queryKey: ['insurance-debt'],
+    queryFn: () => api.get('/api/v1/billing/reports/insurance-debt'),
+  });
+
+  const claims = (claimsQuery.data as any)?.data?.data ?? [];
+  const debt = (debtQuery.data as any)?.data?.data ?? [];
+
+  const transitionMut = useMutation({
+    mutationFn: ({ uuid, action, body }: { uuid: string; action: string; body?: object }) =>
+      api.post(`/api/v1/billing/claims/${uuid}/${action}`, body ?? {}),
+    onSuccess: () => {
+      toast.success('وضعیت مطالبه به‌روزرسانی شد');
+      setRejectTarget(null);
+      setRejectReason('');
+      qc.invalidateQueries({ queryKey: ['claims'] });
+      qc.invalidateQueries({ queryKey: ['insurance-debt'] });
+    },
+    onError: (e: Error) => toast.error(e.message),
+  });
+
+  return (
+    <div className="fade-in">
+      <PageHeader title="مطالبات بیمه" description="پیگیری مطالبات و بدهی بیمه‌ها" />
+
+      <div className="card" style={{ padding: 18, marginBottom: 16 }}>
+        <div style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 12 }}>
+          <BanknotesIcon style={{ width: 18, color: 'var(--text-3)' }} />
+          <h2 style={{ fontSize: 14, fontWeight: 700, margin: 0 }}>بدهی بیمه‌ها</h2>
+        </div>
+        {debtQuery.isLoading ? (
+          <div className="muted" style={{ fontSize: 13 }}>در حال بارگذاری...</div>
+        ) : debt.length === 0 ? (
+          <div style={{ fontSize: 12.5, color: 'var(--text-3)' }}>بدهی‌ای ثبت نشده است.</div>
+        ) : (
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+            {debt.map((d: DebtRow) => (
+              <div key={d.insurance_id} style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', padding: '8px 12px', borderRadius: 8, border: '1px solid var(--border)', fontSize: 13 }}>
+                <span style={{ fontWeight: 600 }}>بیمه #{formatNumber(d.insurance_id)}</span>
+                <span style={{ color: 'var(--text-3)' }}>ادعا {formatRial(d.claimed)} · پرداخت {formatRial(d.paid)}</span>
+                <span style={{ fontWeight: 700, color: d.debt > 0 ? 'var(--danger)' : 'var(--success, #16a34a)' }}>بدهی {formatRial(d.debt)}</span>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+
+      <div className="card" style={{ padding: 18 }}>
+        <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 12 }}>
+          <h2 style={{ fontSize: 14, fontWeight: 700, margin: 0 }}>مطالبات</h2>
+          <select className="input" style={{ maxWidth: 160 }} value={statusFilter} onChange={(e) => setStatusFilter(e.target.value)}>
+            {STATUS_FILTERS.map((s) => (
+              <option key={s} value={s}>{s === '' ? 'همه وضعیت‌ها' : STATUS_META[s]?.label}</option>
+            ))}
+          </select>
+        </div>
+
+        {claimsQuery.isLoading ? (
+          <div className="muted" style={{ fontSize: 13 }}>در حال بارگذاری...</div>
+        ) : claims.length === 0 ? (
+          <div style={{ fontSize: 12.5, color: 'var(--text-3)', padding: '12px 0' }}>مطالبه‌ای یافت نشد.</div>
+        ) : (
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+            {claims.map((c: Claim) => {
+              const meta = STATUS_META[c.status] ?? { label: c.status, cls: 'gray' };
+              return (
+                <div key={c.uuid} style={{ padding: '12px 14px', borderRadius: 10, border: '1px solid var(--border)' }}>
+                  <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', gap: 10 }}>
+                    <div>
+                      <div style={{ fontWeight: 600, fontSize: 13.5 }}>
+                        بیمه #{formatNumber(c.insurance_id)}
+                        <span className="badge gray" style={{ fontSize: 10, marginInlineStart: 6 }}>{KIND_LABEL[c.insurance_kind] ?? c.insurance_kind}</span>
+                        <span className={`badge ${meta.cls}`} style={{ fontSize: 10, marginInlineStart: 4 }}><span className="bdot" />{meta.label}</span>
+                      </div>
+                      <div style={{ fontSize: 11.5, color: 'var(--text-3)', marginTop: 3 }}>
+                        ادعا {formatRial(c.total_claimed_rials)}
+                        {c.total_approved_rials != null && ` · تأیید ${formatRial(c.total_approved_rials)}`}
+                        {c.total_paid_rials != null && ` · پرداخت ${formatRial(c.total_paid_rials)}`}
+                        {c.reject_reason && ` · دلیل رد: ${c.reject_reason}`}
+                      </div>
+                    </div>
+                    <div style={{ display: 'flex', gap: 6, flexShrink: 0 }}>
+                      {c.status === 'pending' && (
+                        <button className="btn primary sm" disabled={transitionMut.isPending} onClick={() => transitionMut.mutate({ uuid: c.uuid, action: 'submit' })}>
+                          <PaperAirplaneIcon style={{ width: 13 }} /> ارسال
+                        </button>
+                      )}
+                      {c.status === 'submitted' && (
+                        <>
+                          <button className="btn primary sm" disabled={transitionMut.isPending} onClick={() => transitionMut.mutate({ uuid: c.uuid, action: 'approve' })}>
+                            <CheckIcon style={{ width: 13 }} /> تأیید
+                          </button>
+                          <button className="btn danger sm" onClick={() => { setRejectTarget(c); setRejectReason(''); }}>
+                            <XMarkIcon style={{ width: 13 }} /> رد
+                          </button>
+                        </>
+                      )}
+                      {c.status === 'approved' && (
+                        <button className="btn primary sm" disabled={transitionMut.isPending} onClick={() => transitionMut.mutate({ uuid: c.uuid, action: 'pay' })}>
+                          <BanknotesIcon style={{ width: 13 }} /> پرداخت
+                        </button>
+                      )}
+                    </div>
+                  </div>
+                </div>
+              );
+            })}
+          </div>
+        )}
+      </div>
+
+      <Modal open={!!rejectTarget} onClose={() => setRejectTarget(null)} title="رد مطالبه"
+        footer={
+          <>
+            <button className="btn ghost sm" onClick={() => setRejectTarget(null)}>انصراف</button>
+            <button className="btn danger sm" disabled={!rejectReason || transitionMut.isPending}
+              onClick={() => rejectTarget && transitionMut.mutate({ uuid: rejectTarget.uuid, action: 'reject', body: { reason: rejectReason } })}>
+              رد کردن
+            </button>
+          </>
+        }
+      >
+        <div className="field">
+          <label>دلیل رد</label>
+          <textarea className="input" rows={3} dir="rtl" value={rejectReason} onChange={(e) => setRejectReason(e.target.value)} placeholder="دلیل رد را بنویسید..." />
+        </div>
+      </Modal>
+    </div>
+  );
+}

assets/admin/pages/ClinicServicesPage.tsx

@@ -1,6 +1,6 @@
 import React, { useState } from 'react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { PlusIcon, PencilIcon, TrashIcon, WrenchScrewdriverIcon } from '@heroicons/react/24/outline';
+import { PlusIcon, PencilIcon, TrashIcon, WrenchScrewdriverIcon, BanknotesIcon } from '@heroicons/react/24/outline';
 import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
@@ -13,14 +13,17 @@ import Modal from '../components/ui/Modal';
 import PriceInput from '../components/ui/PriceInput';
 import ConfirmDialog from '../components/ui/ConfirmDialog';
 import PageHeader from '../components/ui/PageHeader';
+import ServiceTariffModal from '../components/ServiceTariffModal';
 import SearchableSelect from '../components/ui/SearchableSelect';
 import FeatureGate from '../components/ui/FeatureGate';
 
 const sectionSchema = z.object({ name: z.string().min(1, 'نام بخش الزامی است') });
 const itemSchema = z.object({
-  name:        z.string().min(1, 'نام سرویس الزامی است'),
-  price_rials: z.coerce.number().min(0, 'مبلغ نمی‌تواند منفی باشد'),
-  staff_uuid:  z.string().optional(),
+  name:                  z.string().min(1, 'نام سرویس الزامی است'),
+  price_rials:           z.coerce.number().min(0, 'مبلغ نمی‌تواند منفی باشد'),
+  staff_uuid:            z.string().optional(),
+  insurance_covered:     z.boolean().optional(),
+  insurance_price_rials: z.coerce.number().min(0).optional(),
 });
 type SectionForm = z.infer<typeof sectionSchema>;
 type ItemForm    = z.infer<typeof itemSchema>;
@@ -36,6 +39,7 @@ function ClinicServicesPageInner() {
   const [deleteSection, setDeleteSection] = useState<ServiceSection | null>(null);
   const [itemModal, setItemModal] = useState<'create' | ServiceItem | null>(null);
   const [deleteItem, setDeleteItem] = useState<ServiceItem | null>(null);
+  const [tariffItem, setTariffItem] = useState<ServiceItem | null>(null);
 
   const { data: sectionsData, isLoading: sectionsLoading } = useQuery<ApiResponse<ServiceSection[]>>({
     queryKey: ['service-sections'],
@@ -123,6 +127,8 @@ function ClinicServicesPageInner() {
       name: item.name,
       price_rials: item.price_rials,
       staff_uuid: item.staff?.uuid ?? '',
+      insurance_covered: item.insurance_covered ?? false,
+      insurance_price_rials: item.insurance_price_rials ?? 0,
     });
     setItemModal(item);
   };
@@ -234,7 +240,7 @@ function ClinicServicesPageInner() {
                 <button
                   className="btn primary sm"
                   style={{ display: 'flex', alignItems: 'center', gap: 4 }}
-                  onClick={() => { itemForm.reset({ price_rials: 0, staff_uuid: '' }); setItemModal('create'); }}
+                  onClick={() => { itemForm.reset({ price_rials: 0, staff_uuid: '', insurance_covered: false, insurance_price_rials: 0 }); setItemModal('create'); }}
                 >
                   <PlusIcon style={{ width: 14 }} /> سرویس جدید
                 </button>
@@ -249,7 +255,7 @@ function ClinicServicesPageInner() {
                   <button
                     className="btn primary sm"
                     style={{ marginTop: 12 }}
-                    onClick={() => { itemForm.reset({ price_rials: 0, staff_uuid: '' }); setItemModal('create'); }}
+                    onClick={() => { itemForm.reset({ price_rials: 0, staff_uuid: '', insurance_covered: false, insurance_price_rials: 0 }); setItemModal('create'); }}
                   >
                     افزودن سرویس
                   </button>
@@ -273,7 +279,14 @@ function ClinicServicesPageInner() {
                           background: idx % 2 === 1 ? 'oklch(0.985 0.005 256)' : 'transparent',
                         }}
                       >
-                        <td style={{ padding: '11px 16px', fontWeight: 500 }}>{item.name}</td>
+                        <td style={{ padding: '11px 16px', fontWeight: 500 }}>
+                          {item.name}
+                          {item.insurance_covered && (
+                            <span className="badge green" style={{ fontSize: 10, marginInlineStart: 6 }}>
+                              <span className="bdot" />بیمه
+                            </span>
+                          )}
+                        </td>
                         <td style={{ padding: '11px 16px', color: 'var(--primary)', fontWeight: 600 }}>
                           {formatRial(item.price_rials)}
                         </td>
@@ -299,6 +312,9 @@ function ClinicServicesPageInner() {
                             <button className="btn sm" onClick={() => openEditItem(item)} title="ویرایش">
                               <PencilIcon style={{ width: 13 }} />
                             </button>
+                            <button className="btn sm" onClick={() => setTariffItem(item)} title="تعرفه‌های سالانه">
+                              <BanknotesIcon style={{ width: 13 }} />
+                            </button>
                             <button className="btn sm" onClick={() => setDeleteItem(item)} title="حذف">
                               <TrashIcon style={{ width: 13 }} />
                             </button>
@@ -378,6 +394,25 @@ function ClinicServicesPageInner() {
                 isClearable
               />
             </div>
+            <label style={{ display: 'flex', alignItems: 'center', gap: 8, cursor: 'pointer', fontSize: 13.5 }}>
+              <input
+                type="checkbox"
+                checked={itemForm.watch('insurance_covered') ?? false}
+                onChange={(e) => itemForm.setValue('insurance_covered', e.target.checked)}
+              />
+              این خدمت شامل بیمه می‌شود
+            </label>
+            {itemForm.watch('insurance_covered') && (
+              <div className="field">
+                <label>قیمت با بیمه (ریال)</label>
+                <PriceInput
+                  value={itemForm.watch('insurance_price_rials') ?? 0}
+                  onChange={(v) => itemForm.setValue('insurance_price_rials', v)}
+                  placeholder="سهم بیمار با بیمه"
+                  min={0}
+                />
+              </div>
+            )}
           </div>
           <div style={{ display: 'flex', gap: 8, marginTop: 16 }}>
             <button type="submit" className="btn primary" disabled={createItem.isPending || editItem.isPending}>ذخیره</button>
@@ -386,6 +421,8 @@ function ClinicServicesPageInner() {
         </form>
       </Modal>
 
+      <ServiceTariffModal item={tariffItem} onClose={() => setTariffItem(null)} />
+
       {/* Confirm حذف بخش */}
       <ConfirmDialog
         open={!!deleteSection}

assets/admin/pages/InsurancePricingPage.tsx

@@ -0,0 +1,16 @@
+import PageHeader from '../components/ui/PageHeader';
+import InsurancePricingSection from '../components/InsurancePricingSection';
+import TenantInsuranceContracts from '../components/TenantInsuranceContracts';
+
+export default function InsurancePricingPage() {
+  return (
+    <div className="fade-in">
+      <PageHeader
+        title="بیمه و قیمت‌گذاری"
+        description="قراردادهای بیمه، درصد پوشش و مبلغ ویزیت"
+      />
+      <TenantInsuranceContracts />
+      <InsurancePricingSection />
+    </div>
+  );
+}