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/components/InsurancePricingSection.tsx

@@ -0,0 +1,169 @@
+import { useEffect, useState } from 'react';
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
+import { api } from '../lib/api';
+import { formatRial } from '../lib/utils';
+
+interface InsuranceRow {
+  insurance_id: number;
+  insurance_name: string;
+  type: string;
+  patient_share_rials: number | null;
+}
+
+interface PricingResponse {
+  free_visit_price_rials: number;
+  insurances: InsuranceRow[];
+}
+
+const TYPE_LABEL: Record<string, string> = {
+  basic: 'بیمه پایه',
+  supplementary: 'بیمه تکمیلی',
+};
+
+export default function InsurancePricingSection() {
+  const qc = useQueryClient();
+  const [freeVisit, setFreeVisit] = useState('');
+  const [shares, setShares] = useState<Record<number, string>>({});
+
+  const { data, isLoading } = useQuery<{ data: PricingResponse }>({
+    queryKey: ['insurance-pricing'],
+    queryFn: () => api.get('/api/v1/insurance-pricing'),
+  });
+
+  const pricing = (data as any)?.data as PricingResponse | undefined;
+
+  useEffect(() => {
+    if (!pricing) return;
+    setFreeVisit(String(pricing.free_visit_price_rials ?? 0));
+    const next: Record<number, string> = {};
+    pricing.insurances.forEach((i) => {
+      next[i.insurance_id] = i.patient_share_rials != null ? String(i.patient_share_rials) : '';
+    });
+    setShares(next);
+  }, [pricing]);
+
+  const saveMut = useMutation({
+    mutationFn: () =>
+      api.put('/api/v1/insurance-pricing', {
+        free_visit_price_rials: Number(freeVisit) || 0,
+        insurances: (pricing?.insurances ?? []).map((i) => ({
+          insurance_id: i.insurance_id,
+          patient_share_rials:
+            shares[i.insurance_id] === '' || shares[i.insurance_id] == null
+              ? null
+              : Number(shares[i.insurance_id]) || 0,
+        })),
+      }),
+    onSuccess: () => {
+      toast.success('قیمت‌گذاری بیمه ذخیره شد');
+      qc.invalidateQueries({ queryKey: ['insurance-pricing'] });
+    },
+    onError: (e: Error) => toast.error(e.message),
+  });
+
+  const basics = (pricing?.insurances ?? []).filter((i) => i.type === 'basic');
+  const supps = (pricing?.insurances ?? []).filter((i) => i.type === 'supplementary');
+
+  const renderRow = (i: InsuranceRow) => {
+    const share = shares[i.insurance_id] ?? '';
+    const preview =
+      share !== '' && freeVisit !== ''
+        ? `سهم بیمار: ${formatRial(Number(share) || 0)}`
+        : 'تعیین نشده';
+    return (
+      <div
+        key={i.insurance_id}
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 12,
+          padding: '10px 12px',
+          borderRadius: 10,
+          border: '1px solid var(--border)',
+          background: 'var(--surface)',
+        }}
+      >
+        <div style={{ flex: 1, minWidth: 0 }}>
+          <div style={{ fontWeight: 600, fontSize: 13.5 }}>{i.insurance_name}</div>
+          <div style={{ fontSize: 11.5, color: 'var(--text-3)', marginTop: 2 }}>{preview}</div>
+        </div>
+        <div style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+          <input
+            type="number"
+            min={0}
+            dir="ltr"
+            className="input"
+            style={{ width: 150 }}
+            placeholder="سهم بیمار (ریال)"
+            value={share}
+            onChange={(e) =>
+              setShares((p) => ({ ...p, [i.insurance_id]: e.target.value }))
+            }
+          />
+        </div>
+      </div>
+    );
+  };
+
+  return (
+    <div className="card" style={{ padding: 20 }}>
+      <div style={{ marginBottom: 14 }}>
+        <h2 style={{ fontSize: 14, fontWeight: 700, margin: 0 }}>قیمت‌گذاری ویزیت بر اساس بیمه</h2>
+        <p style={{ fontSize: 12, color: 'var(--text-3)', marginTop: 4, lineHeight: 1.7 }}>
+          مبلغ ویزیت آزاد و سهم بیمار به ازای هر بیمه را تعیین کنید. خالی‌گذاشتن یک بیمه یعنی پذیرفته نمی‌شود.
+        </p>
+      </div>
+
+      {isLoading ? (
+        <div className="muted" style={{ fontSize: 13 }}>در حال بارگذاری...</div>
+      ) : (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 18 }}>
+          <div className="field" style={{ flexDirection: 'column', alignItems: 'stretch', height: 'auto', gap: 6, padding: 0, border: 'none', background: 'none' }}>
+            <label style={{ fontSize: 12.5, fontWeight: 600 }}>مبلغ ویزیت آزاد (ریال)</label>
+            <input
+              type="number"
+              min={0}
+              dir="ltr"
+              className="input"
+              style={{ maxWidth: 220 }}
+              value={freeVisit}
+              onChange={(e) => setFreeVisit(e.target.value)}
+            />
+            <span style={{ fontSize: 11.5, color: 'var(--text-3)' }}>
+              {freeVisit !== '' ? formatRial(Number(freeVisit) || 0) : '—'}
+            </span>
+          </div>
+
+          {basics.length > 0 && (
+            <div>
+              <div style={{ fontSize: 12.5, fontWeight: 600, marginBottom: 8, color: 'var(--text-2)' }}>{TYPE_LABEL.basic}</div>
+              <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>{basics.map(renderRow)}</div>
+            </div>
+          )}
+
+          {supps.length > 0 && (
+            <div>
+              <div style={{ fontSize: 12.5, fontWeight: 600, marginBottom: 8, color: 'var(--text-2)' }}>{TYPE_LABEL.supplementary}</div>
+              <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>{supps.map(renderRow)}</div>
+            </div>
+          )}
+
+          {basics.length === 0 && supps.length === 0 && (
+            <div style={{ fontSize: 12.5, color: 'var(--text-3)' }}>بیمه فعالی در سیستم تعریف نشده است.</div>
+          )}
+
+          <div>
+            <button
+              className="btn primary sm"
+              disabled={saveMut.isPending}
+              onClick={() => saveMut.mutate()}
+            >
+              {saveMut.isPending ? 'در حال ذخیره...' : 'ذخیره قیمت‌گذاری'}
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

assets/admin/components/ServiceTariffModal.tsx

@@ -0,0 +1,94 @@
+import { useState } from 'react';
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
+import { api } from '../lib/api';
+import { formatRial, formatNumber } from '../lib/utils';
+import Modal from './ui/Modal';
+import type { ServiceItem } from '../types';
+
+interface TariffRow {
+  uuid: string;
+  year: number;
+  price_rials: number;
+  is_active: boolean;
+}
+
+interface TariffResponse {
+  current_year: number;
+  default_price_rials: number;
+  data: TariffRow[];
+}
+
+export default function ServiceTariffModal({ item, onClose }: { item: ServiceItem | null; onClose: () => void }) {
+  const qc = useQueryClient();
+  const [year, setYear] = useState('');
+  const [price, setPrice] = useState('');
+
+  const { data, isLoading } = useQuery<{ data: TariffResponse }>({
+    queryKey: ['service-tariffs', item?.uuid],
+    queryFn: () => api.get(`/api/v1/service-items/${item!.uuid}/tariffs`),
+    enabled: !!item,
+  });
+
+  const resp = (data as any)?.data as TariffResponse | undefined;
+  const tariffs = resp?.data ?? [];
+  const currentYear = resp?.current_year;
+
+  const saveMut = useMutation({
+    mutationFn: () =>
+      api.put(`/api/v1/service-items/${item!.uuid}/tariffs/${Number(year)}`, {
+        price_rials: Number(price) || 0,
+      }),
+    onSuccess: () => {
+      toast.success('تعرفه ذخیره شد');
+      setYear('');
+      setPrice('');
+      qc.invalidateQueries({ queryKey: ['service-tariffs', item?.uuid] });
+    },
+    onError: (e: Error) => toast.error(e.message),
+  });
+
+  return (
+    <Modal open={!!item} onClose={onClose} title={`تعرفه‌های سالانه — ${item?.name ?? ''}`}>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 14 }}>
+        {resp && (
+          <div style={{ fontSize: 12.5, color: 'var(--text-3)', lineHeight: 1.7 }}>
+            قیمت پیش‌فرض خدمت: <b>{formatRial(resp.default_price_rials)}</b>. اگر تعرفه‌ی سالی ثبت نشود، همین قیمت اعمال می‌شود.
+          </div>
+        )}
+
+        <div style={{ display: 'flex', flexWrap: 'wrap', gap: 10, alignItems: 'flex-end', padding: 12, borderRadius: 10, border: '1px solid var(--border)', background: 'var(--surface)' }}>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+            <label style={{ fontSize: 11.5, fontWeight: 600 }}>سال (شمسی)</label>
+            <input type="number" dir="ltr" className="input" style={{ width: 100 }} placeholder={currentYear ? String(currentYear) : '۱۴۰۴'} value={year} onChange={(e) => setYear(e.target.value)} />
+          </div>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+            <label style={{ fontSize: 11.5, fontWeight: 600 }}>تعرفه (ریال)</label>
+            <input type="number" min={0} dir="ltr" className="input" style={{ width: 150 }} value={price} onChange={(e) => setPrice(e.target.value)} />
+          </div>
+          <button className="btn primary sm" disabled={!year || saveMut.isPending} onClick={() => saveMut.mutate()}>
+            {saveMut.isPending ? '...' : 'ذخیره'}
+          </button>
+        </div>
+
+        {isLoading ? (
+          <div className="muted" style={{ fontSize: 13 }}>در حال بارگذاری...</div>
+        ) : tariffs.length === 0 ? (
+          <div style={{ fontSize: 12.5, color: 'var(--text-3)' }}>هنوز تعرفه‌ی سالانه‌ای ثبت نشده است.</div>
+        ) : (
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+            {tariffs.map((t) => (
+              <div key={t.uuid} style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', padding: '8px 12px', borderRadius: 8, border: '1px solid var(--border)' }}>
+                <span style={{ fontWeight: 600, fontSize: 13 }}>
+                  سال {formatNumber(t.year)}
+                  {t.year === currentYear && <span className="badge green" style={{ fontSize: 10, marginInlineStart: 6 }}><span className="bdot" />جاری</span>}
+                </span>
+                <span style={{ color: 'var(--primary)', fontWeight: 600, fontSize: 13 }}>{formatRial(t.price_rials)}</span>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+    </Modal>
+  );
+}

assets/admin/components/TenantInsuranceContracts.tsx

@@ -0,0 +1,164 @@
+import { useState } from 'react';
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { TrashIcon, PlusIcon } from '@heroicons/react/24/outline';
+import { toast } from 'sonner';
+import { api } from '../lib/api';
+import { formatRial } from '../lib/utils';
+
+interface Contract {
+  uuid: string;
+  insurance_id: number;
+  insurance_name: string | null;
+  insurance_kind: string | null;
+  version: number;
+  coverage_percent: number;
+  franchise_rials: number;
+  annual_ceiling_rials: number | null;
+}
+
+interface InsuranceOption {
+  insurance_id: number;
+  insurance_name: string;
+  type: string;
+}
+
+const KIND_LABEL: Record<string, string> = {
+  basic: 'پایه',
+  supplementary: 'تکمیلی',
+};
+
+export default function TenantInsuranceContracts() {
+  const qc = useQueryClient();
+  const [addOpen, setAddOpen] = useState(false);
+  const [insuranceId, setInsuranceId] = useState('');
+  const [coverage, setCoverage] = useState('');
+  const [franchise, setFranchise] = useState('');
+  const [ceiling, setCeiling] = useState('');
+
+  const contractsQuery = useQuery<{ data: Contract[] }>({
+    queryKey: ['tenant-insurances'],
+    queryFn: () => api.get('/api/v1/billing/tenant-insurances'),
+  });
+
+  const pricingQuery = useQuery<{ data: { insurances: InsuranceOption[] } }>({
+    queryKey: ['insurance-pricing'],
+    queryFn: () => api.get('/api/v1/insurance-pricing'),
+  });
+
+  const contracts = (contractsQuery.data as any)?.data?.data ?? [];
+  const allInsurances: InsuranceOption[] = (pricingQuery.data as any)?.data?.insurances ?? [];
+  const activeIds = new Set(contracts.map((c: Contract) => c.insurance_id));
+  const available = allInsurances.filter((i) => !activeIds.has(i.insurance_id));
+
+  const resetForm = () => {
+    setInsuranceId('');
+    setCoverage('');
+    setFranchise('');
+    setCeiling('');
+    setAddOpen(false);
+  };
+
+  const addMut = useMutation({
+    mutationFn: () =>
+      api.post('/api/v1/billing/tenant-insurances', {
+        insurance_id: Number(insuranceId),
+        coverage_percent: Number(coverage) || 0,
+        franchise_rials: Number(franchise) || 0,
+        annual_ceiling_rials: ceiling === '' ? null : Number(ceiling),
+      }),
+    onSuccess: () => {
+      toast.success('قرارداد بیمه فعال شد');
+      resetForm();
+      qc.invalidateQueries({ queryKey: ['tenant-insurances'] });
+    },
+    onError: (e: Error) => toast.error(e.message),
+  });
+
+  const delMut = useMutation({
+    mutationFn: (uuid: string) => api.delete(`/api/v1/billing/tenant-insurances/${uuid}`),
+    onSuccess: () => {
+      toast.success('قرارداد غیرفعال شد');
+      qc.invalidateQueries({ queryKey: ['tenant-insurances'] });
+    },
+    onError: (e: Error) => toast.error(e.message),
+  });
+
+  return (
+    <div className="card" style={{ padding: 20, marginBottom: 16 }}>
+      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', marginBottom: 14 }}>
+        <div>
+          <h2 style={{ fontSize: 14, fontWeight: 700, margin: 0 }}>قراردادهای بیمه</h2>
+          <p style={{ fontSize: 12, color: 'var(--text-3)', marginTop: 4, lineHeight: 1.7 }}>
+            بیمه‌هایی که با آن‌ها قرارداد دارید. درصد پوشش، فرانشیز و سقف تعهد هر بیمه را تعیین کنید.
+          </p>
+        </div>
+        {!addOpen && available.length > 0 && (
+          <button className="btn primary sm" onClick={() => setAddOpen(true)}>
+            <PlusIcon style={{ width: 14 }} /> افزودن بیمه
+          </button>
+        )}
+      </div>
+
+      {addOpen && (
+        <div style={{ display: 'flex', flexWrap: 'wrap', gap: 10, alignItems: 'flex-end', padding: 14, borderRadius: 10, border: '1px solid var(--border)', background: 'var(--surface)', marginBottom: 14 }}>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+            <label style={{ fontSize: 11.5, fontWeight: 600 }}>بیمه</label>
+            <select className="input" style={{ minWidth: 160 }} value={insuranceId} onChange={(e) => setInsuranceId(e.target.value)}>
+              <option value="">انتخاب...</option>
+              {available.map((i) => (
+                <option key={i.insurance_id} value={i.insurance_id}>{i.insurance_name} ({KIND_LABEL[i.type] ?? i.type})</option>
+              ))}
+            </select>
+          </div>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+            <label style={{ fontSize: 11.5, fontWeight: 600 }}>درصد پوشش</label>
+            <input type="number" min={0} max={100} dir="ltr" className="input" style={{ width: 100 }} value={coverage} onChange={(e) => setCoverage(e.target.value)} />
+          </div>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+            <label style={{ fontSize: 11.5, fontWeight: 600 }}>فرانشیز (ریال)</label>
+            <input type="number" min={0} dir="ltr" className="input" style={{ width: 130 }} value={franchise} onChange={(e) => setFranchise(e.target.value)} />
+          </div>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+            <label style={{ fontSize: 11.5, fontWeight: 600 }}>سقف تعهد (ریال)</label>
+            <input type="number" min={0} dir="ltr" className="input" style={{ width: 130 }} placeholder="بی‌نهایت" value={ceiling} onChange={(e) => setCeiling(e.target.value)} />
+          </div>
+          <div style={{ display: 'flex', gap: 6 }}>
+            <button className="btn primary sm" disabled={!insuranceId || addMut.isPending} onClick={() => addMut.mutate()}>
+              {addMut.isPending ? '...' : 'ذخیره'}
+            </button>
+            <button className="btn ghost sm" onClick={resetForm}>لغو</button>
+          </div>
+        </div>
+      )}
+
+      {contractsQuery.isLoading ? (
+        <div className="muted" style={{ fontSize: 13 }}>در حال بارگذاری...</div>
+      ) : contracts.length === 0 ? (
+        <div style={{ fontSize: 12.5, color: 'var(--text-3)', padding: '12px 0' }}>
+          هنوز با هیچ بیمه‌ای قرارداد فعال ندارید.
+        </div>
+      ) : (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+          {contracts.map((c: Contract) => (
+            <div key={c.uuid} style={{ display: 'flex', alignItems: 'center', gap: 12, padding: '10px 12px', borderRadius: 10, border: '1px solid var(--border)' }}>
+              <div style={{ flex: 1, minWidth: 0 }}>
+                <div style={{ fontWeight: 600, fontSize: 13.5 }}>
+                  {c.insurance_name ?? `#${c.insurance_id}`}
+                  {c.insurance_kind && <span className="badge gray" style={{ fontSize: 10, marginInlineStart: 6 }}>{KIND_LABEL[c.insurance_kind] ?? c.insurance_kind}</span>}
+                </div>
+                <div style={{ fontSize: 11.5, color: 'var(--text-3)', marginTop: 2 }}>
+                  پوشش {c.coverage_percent}٪
+                  {c.franchise_rials > 0 && ` · فرانشیز ${formatRial(c.franchise_rials)}`}
+                  {c.annual_ceiling_rials != null && ` · سقف ${formatRial(c.annual_ceiling_rials)}`}
+                </div>
+              </div>
+              <button className="mini-btn danger" title="غیرفعال‌سازی" disabled={delMut.isPending} onClick={() => delMut.mutate(c.uuid)}>
+                <TrashIcon style={{ width: 15 }} />
+              </button>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

assets/admin/components/layout/Sidebar.tsx

@@ -16,6 +16,7 @@ import {
     IdentificationIcon,
     KeyIcon,
     LockClosedIcon,
+    ShieldCheckIcon,
     StarIcon,
     TagIcon,
     UserCircleIcon,
@@ -192,6 +193,16 @@ function buildSections(
                         label: "پرونده بیماران",
                         feature: "patient_records",
                     },
+                    {
+                        to: "/admin/insurance-pricing",
+                        icon: ShieldCheckIcon,
+                        label: "قیمت‌گذاری بیمه",
+                    },
+                    {
+                        to: "/admin/claims",
+                        icon: DocumentTextIcon,
+                        label: "مطالبات بیمه",
+                    },
                     { to: "/admin/staff", icon: UserPlusIcon, label: "پرسنل" },
                     {
                         to: "/admin/my-secretaries",
@@ -261,6 +272,16 @@ function buildSections(
                         label: "پرونده بیماران",
                         feature: "patient_records",
                     },
+                    {
+                        to: "/admin/insurance-pricing",
+                        icon: ShieldCheckIcon,
+                        label: "قیمت‌گذاری بیمه",
+                    },
+                    {
+                        to: "/admin/claims",
+                        icon: DocumentTextIcon,
+                        label: "مطالبات بیمه",
+                    },
                     { to: "/admin/staff", icon: UserPlusIcon, label: "پرسنل" },
                     {
                         to: "/admin/my-secretaries",
@@ -320,6 +341,16 @@ function buildSections(
                         label: "پرونده بیماران",
                         feature: "patient_records",
                     },
+                    {
+                        to: "/admin/insurance-pricing",
+                        icon: ShieldCheckIcon,
+                        label: "قیمت‌گذاری بیمه",
+                    },
+                    {
+                        to: "/admin/claims",
+                        icon: DocumentTextIcon,
+                        label: "مطالبات بیمه",
+                    },
                 ],
             },
         ];