BillingChange Module - Optimized RAG Knowledge Base

Chunk 1: Module Overview
Metadata: module=BillingChange, type=overview, location=CMH.HFA.Accounting.Orchestration/src/BillingChange, domain=billingModifications, purpose=midTermBillingAdjustments, components=5, scenarios=2
Purpose: Handles mid-term policy billing modifications requiring coordinated credit memo and invoice generation workflows.
Scope:

Billing plan changes (payment schedule modifications)
Billing type changes (internal/external lender transitions)
Components: BillingPlanChangeLambda, BillingTypeChangeLambda, BillingChangeService, BillingChangeModel, BillingTypeChangeDto
Integration Points: Oracle Fusion AR (invoice/credit memo posting), Oracle OIC (memo line lookups)
Key Concepts: credit memo reversal, invoice regeneration, double-entry accounting, payment term changes, billing type transitions

Chunk 2: BillingPlanChangeLambda – GetCreditMemo Operation
Metadata: component=BillingPlanChangeLambda, type=Lambda, operation=GetCreditMemo, scenario=planChange, output=CreditMemo, references=BillingChangeService, BillingPlanChangeDto
Purpose: Creates credit memo reversing original billing plan charges for mid-term plan change.
Input: BillingPlanChangeDto (OracleCustomer, OracleInvoice, NewBillingPlan)
Processing: Delegates to BillingChangeService.MapCreditMemo with BillingChangeEvent.PlanChange
Output: CreditMemo object with negated amounts, mapped transaction type, organizational defaults (BU=HFA, LegalEntity=HFA ID)
Validation: Ensures original invoice exists and has AR clearing lines; throws InvalidOperationException if not

Chunk 3: BillingPlanChangeLambda – GetInvoice Operation
Metadata: component=BillingPlanChangeLambda, type=Lambda, operation=GetInvoice, scenario=planChange, output=OracleInvoice, references=BillingChangeService, BillingPlanChangeDto
Purpose: Creates new invoice with updated payment terms
Input: BillingPlanChangeDto
Processing: Delegates to BillingChangeService.MapInvoicePlanChange, preserves original premium amount, maps transaction type based on original Internal/External classification
Output: OracleInvoice with new payment terms, accounting date set to today, AR clearing line applied
Use Case: Customer switches from monthly to annual or vice versa mid-term

Chunk 4: BillingTypeChangeLambda – GetCreditMemo Operation
Metadata: component=BillingTypeChangeLambda, type=Lambda, operation=GetCreditMemo, scenario=typeChange, output=CreditMemo, references=BillingChangeService, BillingTypeChangeDto
Purpose: Creates credit memo reversing original billing type charges
Input: BillingTypeChangeDto (OracleCustomer, OracleInvoice, UnpaidServiceFee)
Processing: Delegates to BillingChangeService.MapCreditMemo with BillingChangeEvent.TypeChange
Amount: InvoiceBalanceAmount minus absolute UnpaidServiceFee
Output: CreditMemo with negated amounts, classification preserved (no flip), organizational defaults applied

Chunk 5: BillingTypeChangeLambda – GetInvoice Operation
Metadata: component=BillingTypeChangeLambda, type=Lambda, operation=GetInvoice, scenario=typeChange, output=OracleInvoice, references=BillingChangeService, BillingTypeChangeDto
Purpose: Creates invoice for billing type transition with balance adjustment for unpaid fees
Processing:

ShallowCopy of original invoice, clears TransactionID
TransactionType mapped via MapInvoiceBillingTypeTransactionType (Internal ↔ External flip)
PaymentTerms reset to "1 Pay Plan"
InvoiceBalanceAmount reduced by unpaid service fee
AccountingDate set to today
Validation: Throws exception if due date parsing fails

Chunk 6: BillingTypeChangeLambda – IsBillingTypeChanged Operation
Metadata: component=BillingTypeChangeLambda, type=Lambda, operation=IsBillingTypeChanged, scenario=typeChange, output=bool, references=BillingTypeChangeDto, BillingChangeStatic
Purpose: Determines if billing type change is required
Logic:

Parses original type using GetTransactionType
Evaluates NewBillingType vs OtherInterest.InternalLender
Returns true if classification (Internal/External) differs
Validation: Supports only "OtherInterest" or "Client"; throws ArgumentOutOfRangeException for unsupported values

Chunk 7: BillingChangeService – MapCreditMemo Method
Metadata: component=BillingChangeService, type=serviceMethod, operation=MapCreditMemo, references=BuildTransactionLines, BillingChangeModel
Purpose: Generates reversal credit memo for plan or type change
Processing:

Extracts AR clearing lines via IMemoLookup
Negates UnitPrice for reversal
Maps TransactionType (plan/type)
Sets organizational defaults (BU, LegalEntity, Currency=USD)
TransactionDate and AccountingDate set to today
Output: CreditMemo object ready for AR posting

Chunk 8: BillingChangeService – MapInvoicePlanChange Method
Metadata: component=BillingChangeService, type=serviceMethod, operation=MapInvoicePlanChange, scenario=planChange, references=BuildTransactionLines
Purpose: Creates new invoice reflecting updated billing plan
Processing:

Preserves premium amount and original invoice metadata
Updates PaymentTerms to NewBillingPlan
Maps TransactionType via MapInvoiceBillingPlanTransactionType
Includes AR clearing line only
Output: OracleInvoice ready for posting

Chunk 9: BillingChangeService – MapInvoiceTypeChange Method
Metadata: component=BillingChangeService, type=serviceMethod, operation=MapInvoiceTypeChange, scenario=typeChange, references=BuildTransactionLines
Purpose: Creates invoice for billing type transition with balance adjustment
Processing:

Shallow copy of original invoice
Flip transaction type Internal ↔ External
Reduce InvoiceBalanceAmount by unpaid service fee
Reset PaymentTerms to "1 Pay Plan"
Set AccountingDate and TransactionDate to today
Validation: Ensures due date is valid

Chunk 10: BuildTransactionLines Method
Metadata: component=BillingChangeService, type=helperMethod, purpose=transactionLineConstruction
Purpose: Builds transaction lines for invoices and credit memos
Logic:

Filters memo lines by action type (PlanChange/TypeChange) and AR clearing type
Generates sequential LineNumbers
Calculates UnitPrice using GetDistributionAmountByAssurantStatus
Output: List<TransactionLine> ready for document assignment

Chunk 11: Transaction Type Parsing and Mapping
Metadata: component=BillingChangeService, type=helperMethod, references=BillingChangeStatic
Purpose: Determine Internal/External classification and map to codes
Methods:

GetTransactionType: Parses string aliases (Internal: "internal","intern","int"; External: "external","extern","ext")
MapInvoiceBillingPlanTransactionType: preserves classification
MapInvoiceBillingTypeTransactionType: flips classification
MapCreditMemoBillingPlan/TypeTransactionType: preserves classification
Purpose: Ensures proper GL posting based on original or transitioned type

Chunk 12: BillingChangeModel Enumerations and Static Data
Metadata: module=BillingChange, type=model, references=BillingChangeService, DTOs
Purpose: Define billing change events, transaction types, and alias dictionaries
Details:

BillingChangeEvent: PlanChange, TypeChange
TransactionType: Internal, External
BillingChangeStatic: arrays of aliases, mapping dictionaries

Chunk 13: DTOs – BillingTypeChangeDto & IsBillingTypeChangedDto
Metadata: type=DTOs, references=BillingTypeChangeLambda
Purpose: Encapsulate input parameters for Lambda functions
Fields:

BillingTypeChangeDto: OracleCustomer, OracleInvoice, UnpaidServiceFee
IsBillingTypeChangedDto: OriginalTransactionType, NewBillingType, OtherInterest

Chunk 14: Business Rules – Unpaid Service Fee
Metadata: concept=unpaidServiceFee, scope=typeChange
Purpose: Adjust invoice balances for unpaid service fees
Applies To: Type change only
Logic: MapInvoiceTypeChange reduces InvoiceBalanceAmount, MapCreditMemo subtracts absolute UnpaidServiceFee

Chunk 15: Double-Entry Accounting Pattern
Metadata: pattern=doubleEntry, documents=2, sequence=creditThenInvoice
Purpose: Maintain accounting integrity and audit trail
Flow: Credit memo first (negates original charges) → Invoice second (applies new charges)
Orchestration: Typically coordinated by Step Function calling GetCreditMemo → Oracle Integration → GetInvoice → Oracle Integration

Chunk 16: Use Case – Plan Change Scenario
Metadata: useCase=planChange, trigger=customerRequest
Scenario: Customer switches from monthly → annual payment plan
Processing: Credit memo reverses original charges → Invoice generated with new payment terms → AR posting via Oracle

Chunk 17: Use Case – Type Change Scenario (Internal ↔ External)
Metadata: useCase=typeChange, trigger=customerRequest
Scenarios:

Internal → External: Credit memo with Internal codes, invoice flips to External, adjusts for unpaid fees
External → Internal: Credit memo with External codes, invoice flips to Internal, adjusts for unpaid fees
Change Detection: IsBillingTypeChanged prevents unnecessary processing if classification unchanged

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

"How are billing plan changes processed?"
"Which Lambda functions handle billing type changes?"
"How are credit memos and invoices generated?"
"What transaction codes apply for plan or type changes?"
"How are unpaid service fees applied?"
"How does internal vs external classification affect billing changes?"
"How are AR clearing lines selected?"
"What is the double-entry pattern for billing modifications?"