34 lines
2 KiB
Markdown
34 lines
2 KiB
Markdown
---
|
|
name: settlement-calculation
|
|
description: "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**: `aiAuditNotes` and `flaggedReason` columns must be populated and stored as valid bilingual JSON objects matching the format:
|
|
```json
|
|
{
|
|
"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.
|