@accounter/server 0.0.8-alpha-20251102200443-d7162b8ce1dfc629b8b454df17dcec9ed005a052 → 0.0.8-alpha-20251102213150-c9d936f545d5351df0dc5326c2623266f1ad1f46

package/src/modules/charges-matcher/README.md

@@ -0,0 +1,279 @@
+# Charges Matcher Module
+
+This module implements a transaction-document matching system for the Accounter fullstack
+application. It provides both manual matching suggestions and automatic matching capabilities for
+unmatched charges.
+
+## Overview
+
+The charges-matcher module uses a confidence-based scoring algorithm to identify potential matches
+between:
+
+- Charges with only transactions (transaction charges)
+- Charges with only accounting documents (document charges)
+
+The system provides two main operations:
+
+1. **Single-Match Query**: Find potential matches for a specific unmatched charge
+2. **Auto-Match Mutation**: Automatically match all unmatched charges above a confidence threshold
+
+## Module Structure
+
+```
+charges-matcher/
+├── index.ts                          # Module exports and GraphQL module definition
+├── types.ts                          # TypeScript type definitions
+├── typeDefs/
+│   └── charges-matcher.graphql.ts    # GraphQL schema definitions
+├── resolvers/                        # GraphQL resolvers (to be implemented)
+├── providers/                        # Business logic providers (to be implemented)
+├── helpers/                          # Helper functions (to be implemented)
+└── __tests__/
+    ├── test-helpers.ts               # Test utilities and mock factories
+    └── test-infrastructure.spec.ts   # Infrastructure tests
+```
+
+## Type Definitions
+
+### Shared Types
+
+The module reuses types from existing modules:
+
+- `Transaction`: From `@modules/transactions/types.js` (`IGetTransactionsByIdsResult`)
+- `Document`: From `@modules/documents/types.js` (`IGetAllDocumentsResult`)
+- `Currency`: Re-exported from documents module
+- `DocumentType`: Re-exported from documents module
+
+### GraphQL Response Types
+
+- `ChargeMatch`: Single match with charge ID and confidence score
+- `ChargeMatchesResult`: Array of matches (up to 5)
+- `MergedCharge`: Record of a merged charge with confidence score
+- `AutoMatchChargesResult`: Summary of auto-match operation
+
+### Internal Types
+
+- `AggregatedTransaction`: Aggregated data from multiple transactions
+- `AggregatedDocument`: Aggregated data from multiple documents
+- `ConfidenceScores`: Individual confidence scores for each matching factor
+- `ConfidenceResult`: Complete confidence calculation result
+- `ChargeType`: Enum for charge classification (TRANSACTION_ONLY, DOCUMENT_ONLY, MATCHED)
+- `ChargeWithData`: Charge with its associated transactions and documents
+- `MatchCandidate`: Candidate charge with aggregated data
+
+## Database Schema
+
+The module works with these existing tables:
+
+### charges
+
+- `id`: UUID (primary key)
+- `owner_id`: UUID (references businesses)
+- Other fields not directly used in matching logic
+
+### transactions
+
+- `id`: UUID
+- `charge_id`: UUID (foreign key to charges)
+- `amount`: numeric (PostgreSQL numeric type)
+- `currency`: enum
+- `business_id`: UUID (nullable)
+- `event_date`: DATE
+- `debit_date`: DATE (nullable)
+- `debit_timestamp`: TIMESTAMP (nullable)
+- `is_fee`: boolean
+- `source_description`: text (nullable)
+
+### documents
+
+- `id`: UUID
+- `charge_id`: UUID (foreign key to charges)
+- `total_amount`: double precision (nullable)
+- `currency_code`: enum (nullable)
+- `creditor_id`: UUID (nullable)
+- `debtor_id`: UUID (nullable)
+- `date`: DATE (nullable)
+- `type`: enum (INVOICE, CREDIT_INVOICE, RECEIPT, etc.)
+- `serial_number`: text (nullable)
+
+## Testing Infrastructure
+
+### Mock Factories
+
+Test helpers provide factory functions for creating mock data:
+
+```typescript
+import {
+  createMockTransaction,
+  createMockDocument,
+  createMockAggregatedTransaction,
+  createMockAggregatedDocument,
+} from './__tests__/test-helpers.js';
+
+// Create a transaction with defaults
+const transaction = createMockTransaction();
+
+// Create with overrides
+const customTransaction = createMockTransaction({
+  amount: '250.00',
+  currency: 'USD',
+});
+```
+
+### Helper Functions
+
+```typescript
+import {
+  calculateExpectedConfidence,
+  roundConfidence,
+  isValidConfidenceScore,
+  daysDifference,
+  isWithinDays,
+} from './__tests__/test-helpers.js';
+
+// Calculate weighted confidence
+const scores = { amount: 0.9, currency: 1.0, business: 0.5, date: 0.8 };
+const confidence = calculateExpectedConfidence(scores); // 0.79
+
+// Round to 2 decimal places
+const rounded = roundConfidence(0.956789); // 0.96
+
+// Validate score range
+isValidConfidenceScore(0.95); // true
+isValidConfidenceScore(1.5); // false
+```
+
+## Key Concepts
+
+### Unmatched Charge
+
+A charge is considered unmatched if it has:
+
+- ≥1 transactions AND 0 accounting documents, OR
+- 0 transactions AND ≥1 accounting documents
+
+**Note**: PROFORMA, OTHER, and UNPROCESSED document types don't count toward matched/unmatched
+status.
+
+### Matched Charge
+
+A charge is considered matched if it has:
+
+- ≥1 transactions AND ≥1 accounting documents
+
+### Accounting Documents
+
+Documents with types: INVOICE, CREDIT_INVOICE, RECEIPT, INVOICE_RECEIPT
+
+### Confidence Score
+
+A value between 0.00 and 1.00 calculated using:
+
+```
+confidence = (amount × 0.4) + (currency × 0.2) + (business × 0.3) + (date × 0.1)
+```
+
+Where each component score is between 0.0 and 1.0.
+
+### Auto-Match Threshold
+
+Charges are automatically matched only when:
+
+- Exactly one match has confidence ≥ 0.95
+- Multiple matches ≥ 0.95 result in the charge being skipped
+
+## GraphQL API
+
+### Query: findChargeMatches
+
+Find potential matches for a single unmatched charge.
+
+```graphql
+query findChargeMatches($chargeId: UUID!) {
+  findChargeMatches(chargeId: $chargeId) {
+    matches {
+      chargeId
+      confidenceScore
+    }
+  }
+}
+```
+
+**Returns**: Up to 5 matches, ordered by confidence score (highest first)
+
+### Mutation: autoMatchCharges
+
+Automatically match all unmatched charges above the confidence threshold.
+
+```graphql
+mutation autoMatchCharges {
+  autoMatchCharges {
+    totalMatches
+    mergedCharges {
+      chargeId
+      confidenceScore
+    }
+    skippedCharges
+    errors
+  }
+}
+```
+
+**Returns**: Summary of matches made, skipped charges, and any errors
+
+## Implementation Roadmap
+
+### Step 1: Module Setup (✓ Complete)
+
+- [x] Create module structure
+- [x] Define TypeScript types
+- [x] Create GraphQL schema
+- [x] Set up test infrastructure
+
+### Step 2: Core Logic (To Do)
+
+- [ ] Implement charge classification
+- [ ] Implement multi-item aggregation
+- [ ] Implement confidence calculation helpers
+- [ ] Implement candidate filtering
+
+### Step 3: GraphQL Integration (To Do)
+
+- [ ] Implement findChargeMatches resolver
+- [ ] Implement autoMatchCharges resolver
+- [ ] Implement providers for data access
+- [ ] Add integration tests
+
+### Step 4: UI Integration (To Do)
+
+- [ ] Create ChargeMatchingModal component
+- [ ] Create AutoMatchButton component
+- [ ] Add to charge detail screens
+- [ ] Add to charges list view
+
+## Dependencies
+
+This module depends on:
+
+- `@modules/charges`: For charge data access and merge operations
+- `@modules/transactions`: For transaction data access
+- `@modules/documents`: For document data access
+- `@modules/common`: For error handling and common utilities
+- `@modules/financial-entities`: For business name resolution
+
+## Running Tests
+
+```bash
+# Run all tests
+yarn test
+
+# Run specific test file
+yarn test packages/server/src/modules/charges-matcher/__tests__/test-infrastructure.spec.ts
+
+# Run tests in watch mode
+yarn test --watch
+```
+
+## License
+
+See the main project LICENSE file.

package/src/modules/charges-matcher/__generated__/types.ts

@@ -0,0 +1,71 @@
+import * as Types from "../../../__generated__/types.js";
+import * as gm from "graphql-modules";
+export namespace ChargesMatcherModule {
+  interface DefinedFields {
+    Query: 'findChargeMatches';
+    Mutation: 'autoMatchCharges';
+    ChargeMatchesResult: 'matches';
+    ChargeMatch: 'chargeId' | 'confidenceScore';
+    AutoMatchChargesResult: 'totalMatches' | 'mergedCharges' | 'skippedCharges' | 'errors';
+    MergedCharge: 'chargeId' | 'confidenceScore';
+  };
+  
+  export type Query = Pick<Types.Query, DefinedFields['Query']>;
+  export type ChargeMatchesResult = Pick<Types.ChargeMatchesResult, DefinedFields['ChargeMatchesResult']>;
+  export type UUID = Types.Uuid;
+  export type Mutation = Pick<Types.Mutation, DefinedFields['Mutation']>;
+  export type AutoMatchChargesResult = Pick<Types.AutoMatchChargesResult, DefinedFields['AutoMatchChargesResult']>;
+  export type ChargeMatch = Pick<Types.ChargeMatch, DefinedFields['ChargeMatch']>;
+  export type MergedCharge = Pick<Types.MergedCharge, DefinedFields['MergedCharge']>;
+  
+  export type QueryResolvers = Pick<Types.QueryResolvers, DefinedFields['Query']>;
+  export type MutationResolvers = Pick<Types.MutationResolvers, DefinedFields['Mutation']>;
+  export type ChargeMatchesResultResolvers = Pick<Types.ChargeMatchesResultResolvers, DefinedFields['ChargeMatchesResult']>;
+  export type ChargeMatchResolvers = Pick<Types.ChargeMatchResolvers, DefinedFields['ChargeMatch']>;
+  export type AutoMatchChargesResultResolvers = Pick<Types.AutoMatchChargesResultResolvers, DefinedFields['AutoMatchChargesResult']>;
+  export type MergedChargeResolvers = Pick<Types.MergedChargeResolvers, DefinedFields['MergedCharge']>;
+  
+  export interface Resolvers {
+    Query?: QueryResolvers;
+    Mutation?: MutationResolvers;
+    ChargeMatchesResult?: ChargeMatchesResultResolvers;
+    ChargeMatch?: ChargeMatchResolvers;
+    AutoMatchChargesResult?: AutoMatchChargesResultResolvers;
+    MergedCharge?: MergedChargeResolvers;
+  };
+  
+  export interface MiddlewareMap {
+    '*'?: {
+      '*'?: gm.Middleware[];
+    };
+    Query?: {
+      '*'?: gm.Middleware[];
+      findChargeMatches?: gm.Middleware[];
+    };
+    Mutation?: {
+      '*'?: gm.Middleware[];
+      autoMatchCharges?: gm.Middleware[];
+    };
+    ChargeMatchesResult?: {
+      '*'?: gm.Middleware[];
+      matches?: gm.Middleware[];
+    };
+    ChargeMatch?: {
+      '*'?: gm.Middleware[];
+      chargeId?: gm.Middleware[];
+      confidenceScore?: gm.Middleware[];
+    };
+    AutoMatchChargesResult?: {
+      '*'?: gm.Middleware[];
+      totalMatches?: gm.Middleware[];
+      mergedCharges?: gm.Middleware[];
+      skippedCharges?: gm.Middleware[];
+      errors?: gm.Middleware[];
+    };
+    MergedCharge?: {
+      '*'?: gm.Middleware[];
+      chargeId?: gm.Middleware[];
+      confidenceScore?: gm.Middleware[];
+    };
+  };
+}

package/src/modules/charges-matcher/__tests__/amount-confidence.test.ts

@@ -0,0 +1,260 @@
+import { describe, it, expect } from 'vitest';
+import { calculateAmountConfidence } from '../helpers/amount-confidence.helper.js';
+
+describe('calculateAmountConfidence', () => {
+  describe('exact matches', () => {
+    it('should return 1.0 for exact match with positive amounts', () => {
+      expect(calculateAmountConfidence(100, 100)).toBe(1.0);
+      expect(calculateAmountConfidence(50.5, 50.5)).toBe(1.0);
+      expect(calculateAmountConfidence(0.01, 0.01)).toBe(1.0);
+    });
+
+    it('should return 1.0 for exact match with negative amounts', () => {
+      expect(calculateAmountConfidence(-100, -100)).toBe(1.0);
+      expect(calculateAmountConfidence(-50.5, -50.5)).toBe(1.0);
+    });
+
+    it('should return 1.0 for zero amounts', () => {
+      expect(calculateAmountConfidence(0, 0)).toBe(1.0);
+    });
+
+    it('should return 1.0 for matching absolute values with different signs', () => {
+      // Since we compare absolute values, sign differences shouldn't matter for exact amounts
+      expect(calculateAmountConfidence(100, 100)).toBe(1.0);
+      expect(calculateAmountConfidence(-100, -100)).toBe(1.0);
+    });
+  });
+
+  describe('amounts within 1 unit', () => {
+    it('should return 0.9 for amounts within 0.5 units', () => {
+      expect(calculateAmountConfidence(100, 100.5)).toBe(0.9);
+      expect(calculateAmountConfidence(100.5, 100)).toBe(0.9);
+      expect(calculateAmountConfidence(50, 50.3)).toBe(0.9);
+    });
+
+    it('should return 0.9 for amounts at exactly 1 unit difference', () => {
+      expect(calculateAmountConfidence(100, 101)).toBe(0.9);
+      expect(calculateAmountConfidence(101, 100)).toBe(0.9);
+      expect(calculateAmountConfidence(50, 51)).toBe(0.9);
+    });
+
+    it('should return 0.9 for amounts just under 1 unit difference', () => {
+      expect(calculateAmountConfidence(100, 100.99)).toBe(0.9);
+      expect(calculateAmountConfidence(100.99, 100)).toBe(0.9);
+    });
+
+    it('should return 0.9 for negative amounts within 1 unit', () => {
+      expect(calculateAmountConfidence(-100, -100.5)).toBe(0.9);
+      expect(calculateAmountConfidence(-100, -101)).toBe(0.9);
+    });
+  });
+
+  describe('amounts with differences between 1 unit and 20%', () => {
+    it('should return value between 0.0 and 0.7 for 1.5 units difference', () => {
+      const confidence = calculateAmountConfidence(100, 101.5);
+      expect(confidence).toBeGreaterThan(0.0);
+      expect(confidence).toBeLessThan(0.7);
+    });
+
+    it('should return value between 0.0 and 0.7 for 2 units difference', () => {
+      const confidence = calculateAmountConfidence(100, 102);
+      expect(confidence).toBeGreaterThan(0.0);
+      expect(confidence).toBeLessThan(0.7);
+    });
+
+    it('should return value between 0.0 and 0.7 for 5 units difference (on 100)', () => {
+      const confidence = calculateAmountConfidence(100, 105);
+      expect(confidence).toBeGreaterThan(0.0);
+      expect(confidence).toBeLessThan(0.7);
+      // 5% difference should be roughly in the middle
+      expect(confidence).toBeGreaterThan(0.3);
+    });
+
+    it('should return value between 0.0 and 0.7 for 10 units difference (on 100)', () => {
+      const confidence = calculateAmountConfidence(100, 110);
+      expect(confidence).toBeGreaterThan(0.0);
+      expect(confidence).toBeLessThan(0.7);
+      // 10% difference should be lower
+      expect(confidence).toBeLessThan(0.4);
+    });
+
+    it('should demonstrate linear degradation', () => {
+      // For amounts where 1 unit = 1%, we can test linear degradation more precisely
+      // Starting from just over 1% to just under 20%
+      
+      // At around 1% (just over 1 unit on 100): should be close to 0.7
+      const conf1 = calculateAmountConfidence(100, 101.5); // 1.5%
+      
+      // At around 10% (middle of range): should be around 0.35
+      const conf10 = calculateAmountConfidence(100, 110); // 10%
+      
+      // At around 19% (near end): should be close to 0.0
+      const conf19 = calculateAmountConfidence(100, 119); // 19%
+      
+      // Verify degradation order
+      expect(conf1).toBeGreaterThan(conf10);
+      expect(conf10).toBeGreaterThan(conf19);
+    });
+  });
+
+  describe('amounts at exactly 20% difference', () => {
+    it('should return 0.0 for exactly 20% difference', () => {
+      expect(calculateAmountConfidence(100, 120)).toBe(0.0);
+      expect(calculateAmountConfidence(120, 100)).toBe(0.0);
+      expect(calculateAmountConfidence(50, 60)).toBe(0.0);
+    });
+
+    it('should return 0.0 for just under 20% difference (19.99%)', () => {
+      // Just under 20% should still be very close to 0
+      const confidence = calculateAmountConfidence(100, 119.9);
+      expect(confidence).toBeLessThanOrEqual(0.01);
+    });
+  });
+
+  describe('amounts beyond 20% difference', () => {
+    it('should return 0.0 for 25% difference', () => {
+      expect(calculateAmountConfidence(100, 125)).toBe(0.0);
+    });
+
+    it('should return 0.0 for 50% difference', () => {
+      expect(calculateAmountConfidence(100, 150)).toBe(0.0);
+    });
+
+    it('should return 0.0 for 100% difference', () => {
+      expect(calculateAmountConfidence(100, 200)).toBe(0.0);
+    });
+
+    it('should return 0.0 for very large differences', () => {
+      expect(calculateAmountConfidence(100, 1000)).toBe(0.0);
+      expect(calculateAmountConfidence(10, 500)).toBe(0.0);
+    });
+  });
+
+  describe('edge cases with negative amounts', () => {
+    it('should handle negative transaction amount', () => {
+      expect(calculateAmountConfidence(-100, -100)).toBe(1.0);
+      expect(calculateAmountConfidence(-100, -101)).toBe(0.9);
+      expect(calculateAmountConfidence(-100, -105)).toBeGreaterThan(0.0);
+      expect(calculateAmountConfidence(-100, -120)).toBe(0.0);
+    });
+
+    it('should handle negative document amount', () => {
+      expect(calculateAmountConfidence(-100, -100)).toBe(1.0);
+      expect(calculateAmountConfidence(-101, -100)).toBe(0.9);
+    });
+
+    it('should handle both amounts negative', () => {
+      expect(calculateAmountConfidence(-50, -50.5)).toBe(0.9);
+      expect(calculateAmountConfidence(-100, -110)).toBeGreaterThan(0.0);
+    });
+  });
+
+  describe('edge cases with very small amounts', () => {
+    it('should handle very small amounts correctly', () => {
+      expect(calculateAmountConfidence(0.1, 0.1)).toBe(1.0);
+      expect(calculateAmountConfidence(0.01, 0.01)).toBe(1.0);
+    });
+
+    it('should return 0.9 for small amounts within 1 unit', () => {
+      // Even though 1 unit is huge compared to 0.1, it should still return 0.9
+      expect(calculateAmountConfidence(0.1, 1.0)).toBe(0.9);
+      expect(calculateAmountConfidence(0.5, 1.5)).toBe(0.9);
+    });
+
+    it('should handle small amounts with percentage differences correctly', () => {
+      // 0.1 to 0.12 has a difference of 0.02, which is within 1 unit, so returns 0.9
+      expect(calculateAmountConfidence(0.1, 0.12)).toBe(0.9);
+      // 0.1 to 0.11 has a difference of 0.01, which is within 1 unit, so returns 0.9
+      expect(calculateAmountConfidence(0.1, 0.11)).toBe(0.9);
+      // 0.1 to 1.2 has >1 unit difference (1.1) and is also >20%, so returns 0.0
+      expect(calculateAmountConfidence(0.1, 1.2)).toBe(0.0);
+    });
+  });
+
+  describe('edge cases with zero', () => {
+    it('should handle zero in transaction amount', () => {
+      expect(calculateAmountConfidence(0, 0)).toBe(1.0);
+    });
+
+    it('should handle zero vs non-zero amounts', () => {
+      // 0 to 1 is within 1 unit
+      expect(calculateAmountConfidence(0, 1)).toBe(0.9);
+      expect(calculateAmountConfidence(1, 0)).toBe(0.9);
+      
+      // 0 to >1 means one amount is 0, which makes percentage calculation undefined
+      // The spec requires us to handle this gracefully - since we can't calculate percentage
+      // and the difference is >1, we return 0.0
+      expect(calculateAmountConfidence(0, 2)).toBe(0.0);
+    });
+  });
+
+  describe('formula verification for linear degradation', () => {
+    it('should verify the linear formula in the middle range', () => {
+      // Using base amount of 100 for easier percentage calculation
+      // 1 unit = 1% on 100
+      // Range is from 1% to 20%
+      // Confidence degrades linearly from 0.7 to 0.0
+      
+      // At 1% (101): should be close to 0.7 (but we're just over 1 unit)
+      const conf1 = calculateAmountConfidence(100, 101.01);
+      expect(conf1).toBeCloseTo(0.7, 1);
+      
+      // At 10.5% (halfway between 1% and 20%): should be around 0.35
+      const conf10_5 = calculateAmountConfidence(100, 110.5);
+      expect(conf10_5).toBeCloseTo(0.35, 1);
+      
+      // At 19.9% (just before 20%): should be close to 0.0
+      const conf19_9 = calculateAmountConfidence(100, 119.9);
+      expect(conf19_9).toBeCloseTo(0.0, 1);
+    });
+
+    it('should verify degradation is proportional across the range', () => {
+      // Calculate several points and verify linear relationship
+      const base = 100;
+      
+      // Points at different percentages in the degradation range
+      const conf_2pct = calculateAmountConfidence(base, 102);   // ~2%
+      const conf_5pct = calculateAmountConfidence(base, 105);   // 5%
+      const conf_10pct = calculateAmountConfidence(base, 110);  // 10%
+      const conf_15pct = calculateAmountConfidence(base, 115);  // 15%
+      
+      // Each should be progressively smaller
+      expect(conf_2pct).toBeGreaterThan(conf_5pct);
+      expect(conf_5pct).toBeGreaterThan(conf_10pct);
+      expect(conf_10pct).toBeGreaterThan(conf_15pct);
+    });
+  });
+
+  describe('return value precision', () => {
+    it('should return values rounded to 2 decimal places', () => {
+      const confidence = calculateAmountConfidence(100, 105);
+      // Check that the value has at most 2 decimal places
+      const decimalPlaces = (confidence.toString().split('.')[1] || '').length;
+      expect(decimalPlaces).toBeLessThanOrEqual(2);
+    });
+
+    it('should handle rounding correctly for edge values', () => {
+      // Test various amounts that might produce values needing rounding
+      const amounts = [
+        [100, 102.5],
+        [100, 107.3],
+        [100, 113.7],
+        [50, 53.3],
+      ];
+      
+      amounts.forEach(([amt1, amt2]) => {
+        const confidence = calculateAmountConfidence(amt1, amt2);
+        const decimalPlaces = (confidence.toString().split('.')[1] || '').length;
+        expect(decimalPlaces).toBeLessThanOrEqual(2);
+      });
+    });
+  });
+
+  describe('symmetry', () => {
+    it('should return same confidence regardless of parameter order', () => {
+      expect(calculateAmountConfidence(100, 105)).toBe(calculateAmountConfidence(105, 100));
+      expect(calculateAmountConfidence(50, 60)).toBe(calculateAmountConfidence(60, 50));
+      expect(calculateAmountConfidence(100, 101)).toBe(calculateAmountConfidence(101, 100));
+    });
+  });
+});