@ohos-ports/accounter-server 0.1.0-beta.0

package/src/demo-fixtures/validate-demo-data.ts

@@ -0,0 +1,153 @@
+/**
+ * Demo Data Validation Script
+ *
+ * Validates the integrity of seeded demo data with comprehensive ledger validation.
+ *
+ * Validation Checks:
+ * - Admin business entity exists
+ * - Charge count matches expected
+ * - Ledger records for each use-case:
+ *   - Per-record internal balance (FR1)
+ *   - Aggregate balance (FR2)
+ *   - Entity-level balance (FR3)
+ *   - No orphaned amounts (FR4)
+ *   - Positive amounts only (FR5)
+ *   - Foreign currency consistency (FR6)
+ *   - Valid dates (FR7)
+ *   - Record count matches (FR8)
+ *
+ * Exit codes:
+ * - 0: All validations passed
+ * - 1: Validation errors found or database connection failed
+ */
+import { config } from 'dotenv';
+import pg from 'pg';
+import { getAllUseCases } from './use-cases/index.js';
+import { validateLedgerRecords } from './validators/ledger-validators.js';
+import type { LedgerRecord, ValidationContext } from './validators/types.js';
+
+config({
+  path: [`.env`, `../../.env`],
+});
+
+const DEFAULT_CURRENCY = 'ILS';
+const BALANCE_TOLERANCE = 0.005;
+
+/**
+ * Main validation function - connects to DB and runs all checks
+ */
+async function validateDemoData() {
+  const client = new pg.Client({
+    user: process.env.POSTGRES_USER,
+    password: process.env.POSTGRES_PASSWORD,
+    host: process.env.POSTGRES_HOST,
+    port: parseInt(process.env.POSTGRES_PORT || '5432'),
+    database: process.env.POSTGRES_DB,
+    ssl: process.env.POSTGRES_SSL === '1',
+  });
+
+  const errors: string[] = [];
+
+  try {
+    await client.connect();
+
+    // 1. Admin business exists
+    const adminCheck = await client.query(
+      `SELECT id FROM accounter_schema.financial_entities WHERE type = 'business' AND name = 'Admin Business'`,
+    );
+    if (adminCheck.rows.length === 0) {
+      errors.push('Admin business entity missing');
+    }
+
+    // 2. Use-case charge count reconciliation
+    const useCases = getAllUseCases();
+    const expectedChargeCount = useCases.reduce((sum, uc) => sum + uc.fixtures.charges.length, 0);
+    const actualChargeCount = await client.query(`SELECT COUNT(*) FROM accounter_schema.charges`);
+    if (parseInt(actualChargeCount.rows[0].count) !== expectedChargeCount) {
+      errors.push(
+        `Charge count mismatch: expected ${expectedChargeCount}, got ${actualChargeCount.rows[0].count}`,
+      );
+    }
+
+    // 3. Comprehensive ledger validation for all use-cases with expectations (FR9)
+    const useCasesWithExpectations = useCases.filter(uc => uc.expectations);
+
+    console.log(
+      `\nValidating ledger records for ${useCasesWithExpectations.length} use-case(s)...`,
+    );
+
+    let ledgerRecordsExist = false;
+
+    for (const useCase of useCasesWithExpectations) {
+      // Get all charges for this use-case
+      const chargeIds = useCase.fixtures.charges.map(c => c.id);
+
+      // Fetch all ledger records for these charges
+      const ledgerRecords = await client.query<LedgerRecord>(
+        `SELECT * FROM accounter_schema.ledger_records WHERE charge_id = ANY($1) ORDER BY created_at`,
+        [chargeIds],
+      );
+
+      if (ledgerRecords.rows.length === 0) {
+        // Ledger generation is separate from seeding - this is expected
+        console.log(`  ⚠ ${useCase.id}: no ledger records (ledger generation not run)`);
+        continue;
+      }
+
+      ledgerRecordsExist = true;
+
+      // Create validation context
+      const context: ValidationContext = {
+        useCaseId: useCase.id,
+        defaultCurrency: DEFAULT_CURRENCY,
+        tolerance: BALANCE_TOLERANCE,
+      };
+
+      // Run comprehensive validation
+      const validationErrors = validateLedgerRecords(
+        ledgerRecords.rows,
+        useCase.expectations!.ledgerRecordCount,
+        context,
+      );
+
+      errors.push(...validationErrors);
+
+      // Log progress
+      if (validationErrors.length === 0) {
+        console.log(`  ✓ ${useCase.id} (${ledgerRecords.rows.length} records)`);
+      } else {
+        console.log(`  ✗ ${useCase.id} (${validationErrors.length} error(s))`);
+      }
+    }
+
+    if (!ledgerRecordsExist) {
+      console.log(
+        '  ℹ️  Ledger records not found. Run ledger generation to create and validate ledger entries.',
+      );
+    }
+
+    // 4. VAT row present (percentage stored as decimal 0.17 for 17%)
+    const vatCheck = await client.query(
+      `SELECT 1 FROM accounter_schema.vat_value WHERE percentage = 0.17`,
+    );
+    if (vatCheck.rows.length === 0) {
+      errors.push('VAT default (17%) missing');
+    }
+
+    // Report errors or success
+    if (errors.length > 0) {
+      console.error('❌ Validation failed:');
+      for (const err of errors) console.error(`  - ${err}`);
+      process.exit(1);
+    }
+
+    console.log('✅ Demo data validation passed');
+  } catch (error) {
+    console.error('❌ Validation error:', error);
+    process.exit(1);
+  } finally {
+    await client.end();
+  }
+}
+
+validateDemoData();

package/src/demo-fixtures/validators/README.md

@@ -0,0 +1,190 @@
+# Ledger Validators - Overview and purpose
+
+This module provides a practical, production-like validation system for double-entry ledger data
+seeded as part of the demo fixtures. It verifies that generated ledger records are coherent,
+balanced, and conform to business and data integrity rules.
+
+The main entry point is `validateLedgerRecords(records, expectedRecordCount, context)` which runs
+all validations (FR1–FR10) and returns an array of human-readable error messages. An empty array
+means the ledger data passed validation.
+
+## Architecture - File structure and responsibilities
+
+```
+packages/server/src/demo-fixtures/
+├── validate-demo-data.ts                # Script that connects to DB and runs validation per use-case
+└── validators/
+    ├── ledger-validators.ts             # Core validators (FR1–FR10) + small utilities
+    └── types.ts                         # Shared types: LedgerRecord, ValidationContext, EntityBalance
+```
+
+- `validate-demo-data.ts`
+  - Queries demo DB for ledger records per use-case
+  - Builds a `ValidationContext`
+  - Calls `validateLedgerRecords(...)` and reports results
+- `validators/ledger-validators.ts`
+  - Contains all rule validators and a master function to run them all
+  - Utilities: `parseAmount`, `isBalanced`
+- `validators/types.ts`
+  - Shared TypeScript interfaces used across validators
+
+## Validation Rules
+
+All validators return `string[]` of error messages. No errors = rule passed.
+
+1. FR1: Per-Record Internal Balance
+   - Debit total equals credit total per record within tolerance.
+   - Formula: `(debit1 + debit2) == (credit1 + credit2)`.
+   - Error: `{use_case_id} - Record {i} ({record_id}): internal imbalance (debit={X}, credit={Y})`.
+
+2. FR2: Aggregate Balance Validation
+   - Total debits equal total credits across all records in the set.
+   - Error: `{use_case_id}: aggregate ledger not balanced (debit X, credit Y)`.
+
+3. FR3: Entity-Level Balance Validation
+   - Each entity’s net position across all records must balance to ~0.
+   - Error: `{use_case_id}: Entity {entity_id} unbalanced (net={amount})`.
+
+4. FR4: Orphaned Amount Detection
+   - Amount columns must have a corresponding entity; secondary pairs should be both null or both
+     set.
+   - Error: `{use_case_id} - Record {i} ({record_id}): orphaned amount in {column} ...`.
+
+5. FR5: Positive Amount Validation
+   - All amount fields must be `≥ 0`.
+   - Error: `{use_case_id} - Record {i} ({record_id}): negative amount in {column} ({value})`.
+
+6. FR6: Foreign Currency Validation
+   - Non-ILS currency requires foreign amounts; ILS must not have foreign amounts; basic FX sanity
+     check.
+   - Error examples:
+     - `foreign currency (...) but no foreign amounts`
+     - `local currency (...) but has foreign amounts`
+     - `suspicious exchange rate in {field} (rate=...)`
+
+7. FR7: Date Validation
+   - `invoice_date` and `value_date` required, valid, and within range (2020–2030).
+   - Error examples: `missing invoice_date`, `invalid value_date`,
+     `invoice_date out of range (...)`.
+
+8. FR8: Record Count Validation
+   - Validates record count against the expected count for the use-case.
+   - Error: `{use_case_id}: ledger record count mismatch (expected X, got Y)`.
+
+9. FR9: Multi-Use-Case Validation
+   - Run validations for all use-cases with expectations; aggregate all errors.
+
+10. FR10: Empty Ledger Detection
+    - Each record must have a non-zero total (debit + credit > 0).
+    - Error: `{use_case_id} - Record {i} ({record_id}): empty record (all amounts zero)`.
+
+## Usage Example
+
+```ts
+import { validateLedgerRecords } from './validators/ledger-validators.js'
+import type { LedgerRecord, ValidationContext } from './validators/types.js'
+
+const context: ValidationContext = {
+  useCaseId: 'example-use-case',
+  defaultCurrency: 'ILS',
+  tolerance: 0.005
+}
+
+const records: LedgerRecord[] = [
+  {
+    id: 'rec-1',
+    charge_id: 'charge-1',
+    owner_id: 'owner-1',
+
+    debit_entity1: 'entity-1',
+    debit_local_amount1: '100.00',
+    debit_foreign_amount1: null,
+
+    debit_entity2: null,
+    debit_local_amount2: null,
+    debit_foreign_amount2: null,
+
+    credit_entity1: 'entity-2',
+    credit_local_amount1: '100.00',
+    credit_foreign_amount1: null,
+
+    credit_entity2: null,
+    credit_local_amount2: null,
+    credit_foreign_amount2: null,
+
+    currency: 'ILS',
+    invoice_date: new Date('2024-01-01') as any,
+    value_date: new Date('2024-01-01') as any,
+    description: 'Demo',
+    reference1: null,
+    locked: false
+  }
+]
+
+const expectedRecordCount = 1
+const errors = validateLedgerRecords(records, expectedRecordCount, context)
+
+if (errors.length === 0) {
+  console.log('✅ Ledger valid')
+} else {
+  console.error('❌ Validation failed:', errors)
+}
+```
+
+## Adding New Validators
+
+- Create a validator function following the existing pattern:
+
+```ts
+/**
+ * Validates specific rule X
+ */
+export function validateRuleX(records: LedgerRecord[], context: ValidationContext): string[] {
+  const errors: string[] = []
+  // ... push error strings when violations are found
+  return errors
+}
+```
+
+- Add your validator to the master function order in `validateLedgerRecords(...)`.
+- Write unit tests in `validators/ledger-validators.test.ts` (positive + negative cases).
+- Update this README (Rules list, examples if helpful).
+
+## Testing
+
+Run just the validators tests:
+
+```bash
+yarn vitest run packages/server/src/demo-fixtures/validators
+```
+
+Run the whole test suite:
+
+```bash
+yarn test
+```
+
+Optionally run the demo validation script end-to-end (requires DB + seeded data):
+
+```bash
+# Setup and seed (example commands may vary by project scripts)
+yarn db:test:setup
+yarn seed:staging-demo
+
+# Run validation
+tsx packages/server/src/demo-fixtures/validate-demo-data.ts
+```
+
+## Error Message Format
+
+All errors follow a standardized, actionable format so you can quickly locate the problem:
+
+```
+{use_case_id} - Record {index} ({record_id}): {specific_issue} ({details})
+```
+
+- `use_case_id`: Which scenario/use-case produced the record(s)
+- `index`: Zero-based index within the current record set
+- `record_id`: The specific ledger record ID for pinpointing in DB/logs
+- `specific_issue`: Human-readable summary (e.g., "internal imbalance")
+- `details`: Helpful numeric context (e.g., debit/credit totals, rates, fields)

package/src/demo-fixtures/validators/ledger-validators.test.ts

@@ -0,0 +1,298 @@
+import { describe, expect, it } from 'vitest';
+import {
+  isBalanced,
+  parseAmount,
+  validateDates,
+  validateEntityBalance,
+  validateForeignCurrency,
+  validateLedgerRecords,
+  validateNoOrphanedAmounts,
+  validatePositiveAmounts,
+  validateRecordInternalBalance,
+} from './ledger-validators.js';
+import type { LedgerRecord, ValidationContext } from './types';
+
+const mockContext: ValidationContext = {
+  useCaseId: 'test-case',
+  defaultCurrency: 'ILS',
+  tolerance: 0.005,
+};
+
+function createMockRecord(overrides: Partial<LedgerRecord> = {}): LedgerRecord {
+  return {
+    id: 'rec-1',
+    charge_id: 'charge-1',
+    owner_id: 'owner-1',
+    debit_entity1: null,
+    debit_local_amount1: null,
+    debit_foreign_amount1: null,
+    debit_entity2: null,
+    debit_local_amount2: null,
+    debit_foreign_amount2: null,
+    credit_entity1: null,
+    credit_local_amount1: null,
+    credit_foreign_amount1: null,
+    credit_entity2: null,
+    credit_local_amount2: null,
+    credit_foreign_amount2: null,
+    currency: 'ILS',
+    invoice_date: new Date('2024-01-01'),
+    value_date: new Date('2024-01-01'),
+    description: null,
+    reference1: null,
+    locked: false,
+    ...overrides,
+  };
+}
+
+describe('parseAmount', () => {
+  it('should parse valid number strings', () => {
+    expect(parseAmount('100.50')).toBe(100.5);
+    expect(parseAmount('0')).toBe(0);
+  });
+
+  it('should handle null and undefined', () => {
+    expect(parseAmount(null)).toBe(0);
+    expect(parseAmount(undefined)).toBe(0);
+  });
+
+  it('should handle invalid strings', () => {
+    expect(parseAmount('invalid')).toBe(0);
+    expect(parseAmount('')).toBe(0);
+  });
+});
+
+describe('isBalanced', () => {
+  it('should return true for equal values', () => {
+    expect(isBalanced(100, 100)).toBe(true);
+  });
+
+  it('should return true for values within tolerance', () => {
+    expect(isBalanced(100, 100.005, 0.005)).toBe(true);
+  });
+
+  it('should return false for values outside tolerance', () => {
+    expect(isBalanced(100, 102, 0.005)).toBe(false);
+  });
+});
+
+describe('validateRecordInternalBalance', () => {
+  it('should pass for balanced record', () => {
+    const record = createMockRecord({
+      debit_entity1: 'entity-1',
+      debit_local_amount1: '100.00',
+      credit_entity1: 'entity-2',
+      credit_local_amount1: '100.00',
+    });
+
+    const errors = validateRecordInternalBalance([record], mockContext);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should fail for unbalanced record', () => {
+    const record = createMockRecord({
+      debit_local_amount1: '100.00',
+      credit_local_amount1: '99.00',
+    });
+
+    const errors = validateRecordInternalBalance([record], mockContext);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toContain('internal imbalance');
+    expect(errors[0]).toContain('debit=100.00');
+    expect(errors[0]).toContain('credit=99.00');
+  });
+
+  it('should detect empty records', () => {
+    const record = createMockRecord({
+      // All amounts null/zero
+    });
+
+    const errors = validateRecordInternalBalance([record], mockContext);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]).toContain('empty record');
+  });
+});
+
+describe('validateEntityBalance', () => {
+  it('should pass when all entities balance to zero', () => {
+    const records = [
+      createMockRecord({
+        debit_entity1: 'entity-1',
+        debit_local_amount1: '100.00',
+        credit_entity1: 'entity-2',
+        credit_local_amount1: '100.00',
+      }),
+      createMockRecord({
+        id: 'rec-2',
+        debit_entity1: 'entity-2',
+        debit_local_amount1: '100.00',
+        credit_entity1: 'entity-1',
+        credit_local_amount1: '100.00',
+      }),
+    ];
+
+    const errors = validateEntityBalance(records, mockContext);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should fail when entity has unbalanced position', () => {
+    const record = createMockRecord({
+      debit_entity1: 'entity-1',
+      debit_local_amount1: '100.00',
+      credit_entity1: 'entity-2',
+      credit_local_amount1: '100.00',
+    });
+
+    const errors = validateEntityBalance([record], mockContext);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]).toContain('unbalanced');
+    expect(errors[0]).toContain('entity-1');
+  });
+});
+
+describe('validateNoOrphanedAmounts', () => {
+  it('should fail when amount exists without entity', () => {
+    const record = createMockRecord({
+      debit_entity1: null,
+      debit_local_amount1: '100.00',
+    });
+
+    const errors = validateNoOrphanedAmounts([record], mockContext);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]).toContain('orphaned amount');
+  });
+
+  it('should pass when amounts have entities', () => {
+    const record = createMockRecord({
+      debit_entity1: 'entity-1',
+      debit_local_amount1: '100.00',
+      credit_entity1: 'entity-2',
+      credit_local_amount1: '100.00',
+    });
+
+    const errors = validateNoOrphanedAmounts([record], mockContext);
+    expect(errors).toHaveLength(0);
+  });
+});
+
+describe('validatePositiveAmounts', () => {
+  it('should fail for negative amounts', () => {
+    const record = createMockRecord({
+      debit_local_amount1: '-100.00',
+    });
+
+    const errors = validatePositiveAmounts([record], mockContext);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]).toContain('negative amount');
+  });
+
+  it('should pass for positive amounts', () => {
+    const record = createMockRecord({
+      debit_local_amount1: '100.00',
+      credit_local_amount1: '100.00',
+    });
+
+    const errors = validatePositiveAmounts([record], mockContext);
+    expect(errors).toHaveLength(0);
+  });
+});
+
+describe('validateForeignCurrency', () => {
+  it('should require foreign amounts for non-ILS currency', () => {
+    const record = createMockRecord({
+      currency: 'USD',
+      debit_local_amount1: '350.00',
+      debit_foreign_amount1: null,
+    });
+
+    const errors = validateForeignCurrency([record], mockContext);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]).toContain('no foreign amounts');
+  });
+
+  it('should reject foreign amounts for ILS currency', () => {
+    const record = createMockRecord({
+      currency: 'ILS',
+      debit_local_amount1: '100.00',
+      debit_foreign_amount1: '100.00',
+    });
+
+    const errors = validateForeignCurrency([record], mockContext);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]).toContain('has foreign amounts');
+  });
+
+  it('should detect suspicious exchange rates', () => {
+    const record = createMockRecord({
+      currency: 'USD',
+      debit_local_amount1: '1000.00',
+      debit_foreign_amount1: '10.00', // Rate = 100
+    });
+
+    const errors = validateForeignCurrency([record], mockContext);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]).toContain('suspicious exchange rate');
+  });
+});
+
+describe('validateDates', () => {
+  it('should fail for missing dates', () => {
+    const record = createMockRecord({
+      invoice_date: null as unknown as Date,
+    });
+
+    const errors = validateDates([record], mockContext);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]).toContain('missing invoice_date');
+  });
+
+  it('should fail for dates out of range', () => {
+    const record = createMockRecord({
+      invoice_date: new Date('1999-01-01'),
+    });
+
+    const errors = validateDates([record], mockContext);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]).toContain('out of range');
+  });
+});
+
+describe('validateLedgerRecords', () => {
+  it('should pass when all validations succeed', () => {
+    // Create two records that balance entities:
+    // Record 1: entity-1 debits 100, entity-2 credits 100
+    // Record 2: entity-1 credits 100, entity-2 debits 100
+    // This ensures each entity has equal debits and credits
+    const record1 = createMockRecord({
+      debit_entity1: 'entity-1',
+      debit_local_amount1: '100.00',
+      credit_entity1: 'entity-2',
+      credit_local_amount1: '100.00',
+    });
+
+    const record2 = createMockRecord({
+      debit_entity1: 'entity-2',
+      debit_local_amount1: '100.00',
+      credit_entity1: 'entity-1',
+      credit_local_amount1: '100.00',
+    });
+
+    const errors = validateLedgerRecords([record1, record2], 2, mockContext);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should collect errors from multiple validators', () => {
+    const record = createMockRecord({
+      debit_local_amount1: '100.00',
+      credit_local_amount1: '99.00', // Imbalance
+      debit_entity1: null, // Orphaned amount
+      invoice_date: null as unknown as Date, // Missing date
+    });
+
+    const errors = validateLedgerRecords([record], 1, mockContext);
+    expect(errors.length).toBeGreaterThan(1); // Multiple errors
+    expect(errors.some(e => e.includes('imbalance'))).toBe(true);
+    expect(errors.some(e => e.includes('orphaned'))).toBe(true);
+    expect(errors.some(e => e.includes('missing invoice_date'))).toBe(true);
+  });
+});