@accounter/server 0.0.9-alpha-20251231123714-6cdd9de71b4672d74ece5d34c438d162987b2c93 → 0.0.9-alpha-20251231171312-67d2850c6eacafb65d42d987f3d49dca3c0f8bdd

package/src/demo-fixtures/__tests__/deterministic-uuid.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { makeUUID } from '../helpers/deterministic-uuid.js';
+import { UUID5_REGEX } from 'shared/constants.js';
 
 describe('deterministic-uuid', () => {
   describe('makeUUID', () => {
@@ -8,7 +9,7 @@ describe('deterministic-uuid', () => {
       const uuid2 = makeUUID('business', 'acme-consulting-llc');
 
       expect(uuid1).toBe(uuid2);
-      expect(uuid1).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+      expect(uuid1).toMatch(UUID5_REGEX);
     });
 
     it('generates different UUIDs for different names', () => {
@@ -41,7 +42,7 @@ describe('deterministic-uuid', () => {
 
       // UUID v5 format: xxxxxxxx-xxxx-5xxx-yxxx-xxxxxxxxxxxx
       // where y is one of [8, 9, a, b]
-      expect(uuid).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+      expect(uuid).toMatch(UUID5_REGEX);
     });
 
     it('handles kebab-case names correctly', () => {

package/src/demo-fixtures/__tests__/seed-and-validate.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Integration test: Seed demo data and validate
+ *
+ * This test runs the full seed + validate pipeline to ensure:
+ * 1. Seed script completes successfully (exit code 0)
+ * 2. Validation script passes all checks (exit code 0)
+ * 3. End-to-end data integrity from seed to validation
+ *
+ * Prerequisites:
+ * - Database connection available
+ * - ALLOW_DEMO_SEED=1 environment variable set
+ * - Migrations applied
+ *
+ * Note: This is a slow test (~10-30 seconds) and should be run separately
+ * or marked as integration test in CI/CD pipelines.
+ */
+describe('Seed and Validate Integration', () => {
+  // Increase timeout for this integration test (30 seconds)
+  it(
+    'seeds demo data and passes validation',
+    async () => {
+      // Check for stale migrations before running the test
+      if (process.env.SKIP_DEMO_SEED_STALE_MIGRATIONS === '1') {
+        throw new Error(
+          'Demo-seed test failed: migrations are stale. Run: yarn workspace @accounter/migrations migration:run',
+        );
+      }
+
+      const workspaceRoot = resolve(__dirname, '../../../../../');
+      const seedScriptPath = resolve(workspaceRoot, 'scripts/seed-demo-data.ts');
+      const validateScriptPath = resolve(
+        workspaceRoot,
+        'packages/server/src/demo-fixtures/validate-demo-data.ts',
+      );
+      const registerEsmPath = resolve(workspaceRoot, 'scripts/register-esm.js');
+
+      // Step 1: Run seed script
+      const seedExitCode = await new Promise<number>((resolve, reject) => {
+        const seedProcess = spawn(
+          'node',
+          ['--import', registerEsmPath, seedScriptPath],
+          {
+            cwd: workspaceRoot,
+            env: {
+              ...process.env,
+              ALLOW_DEMO_SEED: '1',
+            },
+            stdio: 'inherit', // Show output for debugging
+          },
+        );
+
+        seedProcess.on('close', code => {
+          resolve(code ?? 1);
+        });
+
+        seedProcess.on('error', err => {
+          reject(err);
+        });
+      });
+
+      expect(seedExitCode).toBe(0);
+
+      // Step 2: Run validation script
+      const validateExitCode = await new Promise<number>((resolve, reject) => {
+        const validateProcess = spawn(
+          'node',
+          ['--import', registerEsmPath, validateScriptPath],
+          {
+            cwd: workspaceRoot,
+            env: process.env,
+            stdio: 'inherit',
+          },
+        );
+
+        validateProcess.on('close', code => {
+          resolve(code ?? 1);
+        });
+
+        validateProcess.on('error', err => {
+          reject(err);
+        });
+      });
+
+      expect(validateExitCode).toBe(0);
+    },
+    30000,
+  ); // 30 second timeout
+});

package/src/demo-fixtures/__tests__/use-case-registry.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest';
+import { getAllUseCases } from '../use-cases/index.js';
+
+describe('Use-Case Registry', () => {
+  it('has no duplicate IDs across all categories', () => {
+    const allUseCases = getAllUseCases();
+    const ids = allUseCases.map(uc => uc.id);
+    const unique = new Set(ids);
+    expect(unique.size).toBe(ids.length);
+  });
+
+  it('all use-cases have required fields', () => {
+    const allUseCases = getAllUseCases();
+    allUseCases.forEach(uc => {
+      expect(uc.id).toBeTruthy();
+      expect(uc.name).toBeTruthy();
+      expect(uc.category).toBeTruthy();
+      expect(uc.fixtures).toBeDefined();
+      expect(Array.isArray(uc.fixtures.businesses)).toBe(true);
+      expect(Array.isArray(uc.fixtures.taxCategories)).toBe(true);
+      expect(Array.isArray(uc.fixtures.financialAccounts)).toBe(true);
+      expect(Array.isArray(uc.fixtures.charges)).toBe(true);
+      expect(Array.isArray(uc.fixtures.transactions)).toBe(true);
+      expect(Array.isArray(uc.fixtures.documents)).toBe(true);
+    });
+  });
+});

package/src/demo-fixtures/helpers/admin-context.ts

@@ -0,0 +1,59 @@
+import type { Client } from 'pg';
+import { makeUUID } from './deterministic-uuid.js';
+
+/**
+ * Create (or fetch) the Accounter Admin Business financial entity and return its id.
+ *
+ * Simplified logic:
+ * - Looks up existing row by id or by (type='business' AND name='Accounter Admin Business').
+ * - If not found, inserts a self-owned business entity with a deterministic id.
+ * - Returns the id of the Accounter Admin Business entity.
+ */
+export async function createAdminBusinessContext(client: Client): Promise<string> {
+  const deterministicId = makeUUID('business', 'admin-business');
+
+  // 1) Try find by deterministic id or by semantic key (type+name)
+  const findResult = await client.query<{ id: string }>(
+    `SELECT id
+       FROM accounter_schema.financial_entities
+      WHERE id = $1 OR (type = 'business' AND name = 'Accounter Admin Business')
+      LIMIT 1`,
+    [deterministicId],
+  );
+
+  if (findResult.rows.length > 0) {
+    return findResult.rows[0].id;
+  }
+
+  // 2) Handle circular FK: financial_entities.owner_id → businesses.id ← businesses.id → financial_entities.id
+  //    Resolution strategy:
+  //    a) Insert financial_entity with NULL owner_id (breaks circular dependency temporarily)
+  //    b) Insert business row (now has valid financial_entity reference)
+  //    c) Update financial_entity to set owner_id = self (closes the circle)
+  //
+  //    This 3-step process is necessary because PostgreSQL doesn't support DEFERRABLE
+  //    constraints on our foreign keys, and we need both tables to reference each other.
+  const adminId = deterministicId;
+  await client.query(
+    `INSERT INTO accounter_schema.financial_entities (id, type, name, owner_id)
+     VALUES ($1, 'business', 'Accounter Admin Business', NULL)`,
+    [adminId],
+  );
+
+  // 3) Insert business row (references financial_entity)
+  await client.query(
+    `INSERT INTO accounter_schema.businesses (id)
+     VALUES ($1)`,
+    [adminId],
+  );
+
+  // 4) Update financial_entity to set owner_id (self-reference)
+  await client.query(
+    `UPDATE accounter_schema.financial_entities
+     SET owner_id = $1
+     WHERE id = $1`,
+    [adminId],
+  );
+
+  return adminId;
+}

package/src/demo-fixtures/helpers/placeholder.ts

@@ -0,0 +1,50 @@
+/**
+ * Placeholder strings used in demo fixtures for runtime replacement.
+ */
+export const PLACEHOLDERS = {
+  ADMIN_BUSINESS_ID: '{{ADMIN_BUSINESS_ID}}',
+} as const;
+
+/**
+ * Resolve admin business ID placeholders in fixture objects.
+ *
+ * This function performs a deep replacement of all `{{ADMIN_BUSINESS_ID}}` placeholder
+ * strings within a fixture object by serializing to JSON, replacing all occurrences,
+ * and deserializing back to the original type.
+ *
+ * @param fixture - Fixture object containing placeholders (any type)
+ * @param adminBusinessId - The actual admin business UUID to replace placeholders with
+ * @returns New fixture object with all placeholders replaced
+ *
+ * @example
+ * ```typescript
+ * const fixture = {
+ *   id: 'charge-123',
+ *   ownerId: '{{ADMIN_BUSINESS_ID}}',
+ *   nested: {
+ *     businessId: '{{ADMIN_BUSINESS_ID}}'
+ *   }
+ * };
+ *
+ * const resolved = resolveAdminPlaceholders(fixture, 'actual-uuid-123');
+ * // {
+ * //   id: 'charge-123',
+ * //   ownerId: 'actual-uuid-123',
+ * //   nested: { businessId: 'actual-uuid-123' }
+ * // }
+ * ```
+ *
+ * @remarks
+ * **Performance Note:**
+ * Uses JSON serialization for deep replacement. For very large fixture objects,
+ * consider a more optimized approach if performance becomes an issue.
+ *
+ * **Type Safety:**
+ * Returns the same type as input, but type information is lost during JSON
+ * serialization (e.g., Date objects become strings). Use with plain object fixtures.
+ */
+export function resolveAdminPlaceholders<T>(fixture: T, adminBusinessId: string): T {
+  const json = JSON.stringify(fixture);
+  const resolved = json.replace(/\{\{ADMIN_BUSINESS_ID\}\}/g, adminBusinessId);
+  return JSON.parse(resolved) as T;
+}

package/src/demo-fixtures/helpers/seed-exchange-rates.ts

@@ -0,0 +1,29 @@
+import type { Client } from 'pg';
+
+/**
+ * Seed FIAT exchange rates for demo data.
+ *
+ * Inserts or updates exchange rates for common currencies to ILS.
+ * Uses ON CONFLICT to ensure idempotent seeding.
+ *
+ * **Schema Note**: The exchange_rates table stores rates as individual columns
+ * (usd, eur, gbp, etc.) for a given exchange_date, NOT as normalized rows.
+ * This denormalized structure optimizes read performance for multi-currency queries.
+ *
+ * Example row:
+ * | exchange_date | usd | eur | gbp |
+ * | 2024-11-26    | 3.5 | 4.0 | 4.5 |
+ *
+ * Rates seeded:
+ * - USD: 3.5 ILS
+ * - EUR: 4.0 ILS
+ * - GBP: 4.5 ILS
+ */
+export async function seedExchangeRates(client: Client): Promise<void> {
+  await client.query(
+    `INSERT INTO accounter_schema.exchange_rates (exchange_date, usd, eur, gbp)
+     VALUES (CURRENT_DATE, 3.5, 4.0, 4.5)
+     ON CONFLICT (exchange_date)
+     DO UPDATE SET usd = EXCLUDED.usd, eur = EXCLUDED.eur, gbp = EXCLUDED.gbp`,
+  );
+}

package/src/demo-fixtures/helpers/seed-vat.ts

@@ -0,0 +1,35 @@
+import type { Client } from 'pg';
+
+/**
+ * Seed VAT percentage history for demo data.
+ *
+ * Inserts historical VAT rates with effective dates. Israel's VAT has changed
+ * over time, so we maintain a history table to support accurate calculations
+ * for documents from different time periods.
+ *
+ * **Schema Note**: Percentage stored as decimal (0.17 = 17%), not integer.
+ * Column name is 'date', not 'effective_date' or 'effectiveDate'.
+ *
+ * Current rates:
+ * - 17% effective from 2015-01-01
+ * - 18% effective from 2025-01-01
+ *
+ * Uses ON CONFLICT to ensure idempotency across multiple seed runs.
+ *
+ * @param client - PostgreSQL client instance
+ */
+export async function seedVATDefault(client: Client): Promise<void> {
+  const vatRates = [
+    { percentage: 0.17, date: '2015-01-01' },
+    { percentage: 0.18, date: '2025-01-01' },
+  ];
+
+  for (const { percentage, date } of vatRates) {
+    await client.query(
+      `INSERT INTO accounter_schema.vat_value (percentage, date)
+       VALUES ($1, $2)
+       ON CONFLICT (date) DO NOTHING`,
+      [percentage, date],
+    );
+  }
+}

package/src/demo-fixtures/use-cases/equity/shareholder-dividend.ts

@@ -0,0 +1,88 @@
+import type { UseCaseSpec } from '../../../fixtures/fixture-spec.js';
+import { CountryCode, Currency } from '../../../shared/enums.js';
+import { makeUUID } from '../../helpers/deterministic-uuid.js';
+
+/**
+ * Shareholder Dividend (Q4 2024)
+ *
+ * Models a dividend payout in ILS with a single transaction
+ * and optional statement document. Designed as a simple
+ * equity scenario with minimal entities.
+ */
+export const shareholderDividend: UseCaseSpec = {
+  id: 'shareholder-dividend',
+  name: 'Shareholder Dividend (Q4 2024)',
+  description:
+    'Dividend payout from ILS bank account with withholding tax counterparty. Includes optional statement document.',
+  category: 'equity',
+  fixtures: {
+    businesses: [
+      {
+        id: makeUUID('business', 'dividends-withholding-tax'),
+        name: 'Dividends Withholding Tax',
+        country: CountryCode['Israel'],
+        canSettleWithReceipt: false,
+      },
+    ],
+    taxCategories: [
+      {
+        id: makeUUID('tax-category', 'dividend'),
+        name: 'Dividend',
+      },
+    ],
+    financialAccounts: [
+      {
+        id: makeUUID('financial-account', 'bank-ils-account'),
+        accountNumber: '11-222-3333',
+        type: 'BANK_ACCOUNT',
+        currency: Currency.Ils,
+        taxCategoryMappings: [
+          {
+            taxCategoryId: makeUUID('tax-category', 'dividend'),
+            currency: Currency.Ils,
+          },
+        ],
+      },
+    ],
+    charges: [
+      {
+        id: makeUUID('charge', 'dividend-distribution-2024-q4'),
+        ownerId: '{{ADMIN_BUSINESS_ID}}',
+        userDescription: 'Dividend distribution for Q4 2024',
+      },
+    ],
+    transactions: [
+      {
+        id: makeUUID('transaction', 'dividend-payout-2024-q4'),
+        chargeId: makeUUID('charge', 'dividend-distribution-2024-q4'),
+        businessId: makeUUID('business', 'dividends-withholding-tax'),
+        amount: '-10000.00',
+        currency: Currency.Ils,
+        eventDate: '2024-12-31',
+        debitDate: '2024-12-31',
+        accountNumber: '11-222-3333',
+      },
+    ],
+    documents: [
+      {
+        id: makeUUID('document', 'dividend-statement-2024-q4'),
+        chargeId: makeUUID('charge', 'dividend-distribution-2024-q4'),
+        creditorId: makeUUID('business', 'dividends-withholding-tax'),
+        debtorId: '{{ADMIN_BUSINESS_ID}}',
+        serialNumber: 'DIV-2024-Q4',
+        type: 'INVOICE',
+        date: '2024-12-31',
+        totalAmount: '10000.00',
+        currencyCode: Currency.Ils,
+      },
+    ],
+  },
+  metadata: {
+    author: 'demo-team',
+    createdAt: '2024-11-24',
+    updatedAt: '2024-11-24',
+  },
+  expectations: {
+    ledgerRecordCount: 2,
+  },
+};