CashReceipts Module – Optimized RAG Knowledge Base

Chunk 1: Module Overview
Metadata: module=CashReceipts, type=paymentProcessing, location=CMH.HFA.Accounting.Orchestration/src/CashReceipts, domain=retailPayments, purpose=paymentApplication, components=7, scenarios=2
Purpose: Handles retail dealer payment events and applies those payments to outstanding invoice installments in Oracle AR.
Scope:

Stage 1: Cash receipt creation from retail payment events
Stage 2: Payment application to specific invoice installments
Components: MapCashReceipt, MapCashReceiptApplication, OracleCashReceipt, OracleCashReceiptApplication, RetailPaymentEventPayload, MapCashReceiptDto, ApplyInvoiceDto
Integration Points: Oracle Fusion AR (receipt/application posting), retail payment event system, policy invoice retrieval
Key Concepts: cash receipt creation, installment-level application, unapplied amount tracking, greedy allocation, retail dealer payments

Chunk 2: MapCashReceipt Lambda Function
Metadata: component=MapCashReceipt, type=Lambda, operation=receiptCreation, pattern=eventTransformation, deployment=serverless, references=MapCashReceiptDto, OracleCashReceipt
Purpose: Converts retail payment events into Oracle AR cash receipt records
Input: MapCashReceiptDto (OracleCustomer + RetailPaymentEventPayload)
Processing: Extracts amount, policy number, date, receipt number; formats receipt as "Retail Deal {ReceiptNumber}"; sets UnappliedAmount = full payment amount
Output: OracleCashReceipt object ready for Oracle integration
Lambda Config: Execution role, 256MB memory, 30s timeout
Use Case: Payment captured via POS or dealer portal; needs receipt before application

Chunk 3: MapCashReceiptApplication Lambda Function
Metadata: component=MapCashReceiptApplication, type=Lambda, operation=paymentApplication, pattern=greedyAllocation, deployment=serverless, references=ApplyInvoiceDto, OracleCashReceiptApplication
Purpose: Applies cash receipt to invoice installments sequentially
Input: ApplyInvoiceDto (OracleCashReceipt + array of OracleInstallment)
Processing: Iterates installments while UnappliedAmount > 0; applied amount = MIN(installment balance, unapplied amount); creates OracleCashReceiptApplication; reduces UnappliedAmount
Output: List<OracleCashReceiptApplication> linking receipt to installments
Allocation Pattern: Greedy sequential, supports partial payments, stops when receipt exhausted or all installments paid

Chunk 4: OracleCashReceipt Model
Metadata: model=OracleCashReceipt, type=document, purpose=receiptRecord, oracleModule=AR
Description: Represents cash receipt record in Oracle Fusion AR, tracking unapplied payments
Key Properties:

ReceiptId, ReceiptNumber (formatted), ReceiptDate
Amount, UnappliedAmount, Currency=USD
CustomerAccountNumber, BusinessUnit=HFA, BusinessGroup=HFA
ReceiptMethod="HFA I/C Retail"
AccountingDate, PolicyNumber, IntercompanyPaymentReference
Mutable State: UnappliedAmount decreases as payment applied
Purpose: Enables separate AR receipt creation before payment application

Chunk 5: OracleCashReceiptApplication Model
Metadata: model=OracleCashReceiptApplication, type=transaction, purpose=paymentApplication, granularity=installment
Description: Represents application of receipt to a specific installment
Key Properties:

ActionType="Apply", AmountApplied, ReceiptNumber/Id/Date, ReceiptMethod
CustomerTrxId (invoice), Installment sequence, ApplicationDate, AccountingDate
CustomerAccountNumber, optional Comments/Ids/Currency
Installment-Level: Enables precise payment tracking
Purpose: Links payments to invoice installments for aging and collections

Chunk 6: RetailPaymentEventPayload Model
Metadata: model=RetailPaymentEventPayload, type=eventPayload, source=retailSystem, requiredFields=6
Properties: AccountSourceReference, ReceiptNumber, PolicyNumber, ReceiptMethod, ReceiptDate, Amount, IntercompanyPaymentReference
Event Wrapper: RetailPaymentEventMessage extends EventMessage<RetailPaymentEventPayload>
Purpose: Standardized payment event structure from POS, portal, or payment processor

Chunk 7: MapCashReceiptDto
Metadata: model=MapCashReceiptDto, type=inputDTO, purpose=receiptCreation, components=2
Properties: Customer (OracleCustomer), RetailPaymentEventPayload
Deconstruction: Enables tuple unpacking in Lambda handler
Usage: Input to MapCashReceipt Lambda, passed from Step Function orchestration
Purpose: Combines customer lookup and event payload for single Lambda invocation

Chunk 8: ApplyInvoiceDto
Metadata: model=ApplyInvoiceDto, type=inputDTO, purpose=paymentApplication, components=2
Properties: CashReceipt (OracleCashReceipt with ReceiptId), Installments (OracleInstallment[])
Deconstruction: Supports tuple unpacking in Lambda
Usage: Input to MapCashReceiptApplication Lambda
Purpose: Packages receipt and target installments for application processing

Chunk 9: Greedy Payment Allocation Algorithm
Metadata: algorithm=greedyAllocation, pattern=sequential, stopCondition=dual, precision=decimal
Description: Sequentially applies receipt to installments until fully applied or installments exhausted
Logic: MIN(installment balance, UnappliedAmount); create application record; decrement UnappliedAmount
Partial Payment Support: Allows installments to be partially paid; supports overpayment
Purpose: Matches Oracle AR standard allocation behavior

Chunk 10: Receipt Number Formatting
Metadata: operation=receiptNumberFormatting, pattern=prefix, source=retailSystem
Format: "Retail Deal {ReceiptNumber}"
Purpose: Distinguishes retail payments from other sources, enables Oracle AR filtering
Uniqueness: Assumes retail system provides unique numbers; no collision detection

Chunk 11: Customer Account Resolution
Metadata: operation=accountResolution, method=GetBillToCustomer, extension=OracleCustomerExtensions
Logic: Select first account with non-empty AccountNumber
Purpose: Provides customer account reference for receipts and applications
Usage: Called in MapCashReceipt Lambda

Chunk 12: Date Handling Patterns
Metadata: dates=multiple, sources=2, timezone=notSpecified
ReceiptDate: From RetailPaymentEventPayload, as-is
ApplicationDate & AccountingDate: Current system date
Purpose: Tracks payment vs posting dates correctly

Chunk 13: OrderInvoices Helper Method
Metadata: operation=OrderInvoices, sorting=documentNumber, filtering=openBalance, visibility=public
Description: Prepares invoices for payment application by filtering InvoiceBalanceAmount > 0 and ordering by DocumentNumber
Purpose: Ensures deterministic processing order

Chunk 14: Two-Stage Workflow Pattern
Metadata: workflow=twoStage, stage1=receiptCreation, stage2=paymentApplication, orchestration=stepFunction
Stage 1: MapCashReceipt → Oracle assigns ReceiptId
Stage 2: MapCashReceiptApplication applies receipt to installments using greedy algorithm
Purpose: Separate receipt creation and application for auditability and partial payments

Chunk 15: Installment Balance Tracking
Metadata: concept=installmentBalance, property=InstallmentBalanceDue, tracking=Oracle
Description: Each application reduces InstallmentBalanceDue; multiple receipts can apply until fully paid
Purpose: Supports aging, collection workflows, and accurate balance tracking

Chunk 16: Intercompany Reference Handling
Metadata: field=IntercompanyPaymentReference, type=integer, source=string, conversion=safe
Logic: int.TryParse(payload.IntercompanyPaymentReference, out var reference) ? reference : 0
Purpose: Tracks intercompany settlement reference safely

Chunk 17: Currency & Business Unit Defaults
Metadata: defaults=hardcoded, currency=USD, businessUnit=HFA, businessGroup=HFA
Currency: "USD"; BusinessUnit: HfaStatic.HfaBusinessUnit; BusinessGroup: HfaStatic.HFA
ReceiptMethod: "HFA I/C Retail"
Purpose: Applies consistent organizational context

Chunk 18: Use Case Scenarios
Metadata: useCases=retailPayments, channels=POS/portal, frequency=perTransaction

POS Payment: Customer pays at dealer; receipt created and applied
Portal Payment: Customer pays online; same workflow
Partial Payment: Applied to earliest installments
Overpayment: Remaining UnappliedAmount tracked
Multiple Installments: Single receipt can cover multiple installments

Chunk 19: Search Queries Supported
Metadata: type=queryPatterns, purpose=RAGRetrieval
Sample Queries:

"How are retail dealer payments processed?"
"What Lambda functions handle receipt creation and application?"
"How are payments applied to invoice installments?"
"What is the greedy allocation algorithm?"
"How are retail payment events transformed to Oracle cash receipts?"
"What properties does OracleCashReceipt contain?"
"How is the unapplied amount tracked?"
"What is the two-stage workflow?"
"How are installment balances updated?"
"How is receipt number formatted?"
"How is customer account resolved?"
"What dates are set on cash receipt applications?"
"How are partial payments handled?"
"What happens when payment exceeds installment balance?"
"How is intercompany reference converted?"
"What business unit and currency defaults apply?"