2 KiB
2 KiB
| name | description |
|---|---|
| settlement-calculation | Executes automated commission calculations, processes retroactive delta/clawback adjustments, and translates notes. Use this when calculating settlements, running delta checks, or writing AI audit notes. |
Settlement Calculation
Defines the mathematical and procedural rules for running automated commission calculations and processing retroactive adjustments.
Core Rationale
Sales data can change retroactively (e.g., late cancellations, modified booking values). The settlement engine must dynamically detect changes in historical periods and reconcile them without modifying finalized records.
Execution Rules
1. Retroactive Delta & Clawback Calculations
- Delta Check: For the target collaborator and period, compare the previously calculated and finalized commissions against the current actual PMS sales records.
- Adjustment Generation:
- If the PMS value has decreased (e.g. refund/cancellation), calculate the difference and record a negative adjustment (clawback) in the current period.
- If the PMS value has increased, record a positive adjustment.
- Never modify past finalized settlement records; adjustments must be registered as new records in the active period.
2. Bilingual AI Audit Notes & i18n
- Requirement:
aiAuditNotesandflaggedReasoncolumns must be populated and stored as valid bilingual JSON objects matching the format:{ "en": "English explanation of the calculation/flag.", "es": "Explicación en español del cálculo/alerta." } - Translation Chain: Utilize the n8n translation LLM chain to translate dynamically generated audit notes.
- Verification: Ensure that the database schemas and fields can store this JSON structure correctly.
3. Idempotency Key Validation
- Before saving a settlement record, validate the idempotency key (header token/hash) to prevent duplicate transactions. If the transaction has already been processed, skip or throw a controlled exception.