# ThreeWayMatchEvent

## Description

ThreeWayMatchEvent is an append-only history table that records the matching relationship between a purchase bill line and a goods receipt line. Each row represents one matching event: which bill line was matched to which receipt line, for how much quantity, when, and by whom. The table is never updated or deleted — unmatch operations are recorded as new rows (e.g. with negative or zero matchedQuantity), preserving a full audit trail.

This table exists because the purchase-order-line reference on GoodsReceiptLine and PurchaseBillLine is nullable (receipts and bills can be created without a PO), and even when present, the indirect PO-line-based relationship between bills and receipts is insufficient for audit. ThreeWayMatchEvent provides the explicit, direct evidence of "which invoice line was matched to which receipt line" that ERP audit and reconciliation require.

## Domain Model Definitions

### Model type

AppendOnly

### Command Definitions

- [matchPurchaseBill](../commands/MatchPurchaseBill.md) - Creates ThreeWayMatchEvent records when matching bill lines to receipt lines

### Query Definitions

None

### Models

- ThreeWayMatchEvent

### Invariants

- Every event must reference exactly one PurchaseBillLine and one GoodsReceiptLine
- Matched quantity must be recorded (may be negative for unmatch events)
- Rows are immutable once created; corrections are expressed as new events
- matchedAt records the timestamp of the matching operation
- matchedBy optionally records the user or system that performed the match

### Relationships

- **References PurchaseBillLine**: `purchaseBillLineId` identifies which bill line participated in the match
- **References GoodsReceiptLine**: `goodsReceiptLineId` identifies which receipt line participated in the match
- **No direct PO reference**: The purchase order context is derivable from the referenced bill line or receipt line; storing it here would be redundant and risk update inconsistency
