feat(package): session packages backed by a credit ledger

"Six laser sessions" is the common case in an aesthetics clinic: the patient pays once and books the sessions later. Credit is a ledger, not a counter. No table has a remaining/used_count column and a schema test enforces that — the balance is always SUM(delta) over append-only rows, so every number a patient sees has a full history behind it. Corrections are new rows, never edits. - purchase / consume / refund / adjustment / expiry, each with a reason, an author and the appointment it belongs to - consume happens in confirm(), never in quote(): if the preview consumed, a page refresh would cost the patient a session - cancelling adds a refund row; the consume row stays - FIFO across a patient's packages — the oldest is closest to expiring - an empty package is not an error, it just does not apply and the patient pays - adjust/expire need a doctor or clinic role, and adjust always needs a reason - app:package:expire writes the closing row so "where did my 3 sessions go?" always has an answer Consume takes a pessimistic lock on the one package row. That is the opposite of task 07's slot buckets, and docs/api/package.md carries the table explaining why, so nobody unifies them later. Idempotency checks for an existing consume row before inserting rather than catching the unique violation: in Doctrine that exception closes the EntityManager and burns the rest of the request. The unique key stays as the last line of defence. Admin: PackagesPage, a packages tab on the patient record, and a ledger page whose running-balance column shows where the final number came from. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-31 11:11:03 +03:30
parent d6294242b7
commit ca9648732d
35 changed files with 3205 additions and 78 deletions
@@ -0,0 +1,78 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { screen, waitFor } from '@testing-library/react';
+import { renderWithProviders } from '../test/utils';
+
+vi.mock('../lib/api', () => ({
+  api: { get: vi.fn(), post: vi.fn(), patch: vi.fn(), put: vi.fn(), delete: vi.fn() },
+  ApiError: class extends Error {},
+}));
+
+vi.mock('sonner', () => ({ toast: { success: vi.fn(), error: vi.fn() } }));
+
+import { Routes, Route } from 'react-router-dom';
+import { api } from '../lib/api';
+import PatientPackageLedgerPage from './PatientPackageLedgerPage';
+
+const get = api.get as ReturnType<typeof vi.fn>;
+
+const ledger = {
+  package: {
+    uuid: 'pp1',
+    package_uuid: 'p1',
+    package_name: '۶ جلسه لیزر',
+    patient_uuid: 'pat1',
+    session_count: 6,
+    price_paid_rials: 25_000_000,
+    purchased_at: 1_700_000_000,
+    valid_to: null,
+    expired: false,
+    balance: 5,
+  },
+  rows: [
+    {
+      uuid: 'l1', kind: 'purchase', delta: 6, appointment_uuid: null, service_uuid: null,
+      service_name: null, reason: 'خرید پکیج', created_by: 'u1', created_at: 1_700_000_000,
+      running_balance: 6,
+    },
+    {
+      uuid: 'l2', kind: 'consume', delta: -1, appointment_uuid: 'a1', service_uuid: 's1',
+      service_name: 'لیزر', reason: null, created_by: null, created_at: 1_700_100_000,
+      running_balance: 5,
+    },
+  ],
+};
+
+function renderPage() {
+  return renderWithProviders(
+    <Routes>
+      <Route path="/admin/patient-package/:patientPackageUuid/ledger" element={<PatientPackageLedgerPage />} />
+    </Routes>,
+    { route: '/admin/patient-package/pp1/ledger' },
+  );
+}
+
+describe('PatientPackageLedgerPage', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    get.mockResolvedValue({ success: true, data: ledger });
+  });
+
+  /** ماندهٔ هر ردیف باید دیده شود — همان چیزی که یک شمارنده نمی‌تواند نشان دهد. */
+  it('shows every ledger row with its running balance', async () => {
+    renderPage();
+
+    await waitFor(() => expect(screen.getByText('خرید')).toBeInTheDocument());
+    expect(screen.getByText('مصرف در نوبت')).toBeInTheDocument();
+    expect(screen.getByText('+6')).toBeInTheDocument();
+    expect(screen.getByText('-1')).toBeInTheDocument();
+  });
+
+  it('summarises the balance against the purchased session count', async () => {
+    renderPage();
+
+    await waitFor(() => expect(screen.getByText(/از 6 جلسه/)).toBeInTheDocument());
+
+    // عدد مانده در همان جمله می‌آید؛ «۵ از ۶» یعنی یک جلسه مصرف شده.
+    expect(screen.getByText(/از 6 جلسه/).parentElement).toHaveTextContent('5');
+  });
+});