FSA Warranty & Financial Settlement Engine: Feature Request

Dec 4, 2025 by Admin 60 views

FSA Availability Warranty & Financial Settlement Engine: A Detailed Feature Request

Hey guys! Today, we're diving deep into a feature request that could seriously revolutionize how we manage and validate financial settlements related to availability warranties. This isn't just about tweaking a few things; it's about building a robust, transparent, and automated system. Let's break it down!

1. Executive Summary & Business Value: Why This Matters

Currently, our "FSA Management" module is basically just a data viewer. The goal? To transform it into a fully compliant Commercial Settlement Engine that digitizes Schedule 3 (Availability Warranty) of the O&M Agreement. This is a game-changer because the Annual Performance Review often involves millions in potential penalties or bonuses. Right now, asset managers are stuck using complex, and often error-prone, Excel sheets to validate contractor claims. Think about the hours wasted, the potential for mistakes, and the sheer headache of it all! This proposed module will:

Automate Trust: Forget manual spreadsheet formulas! We're talking about replacing them with code-codified logic straight from the contract. This means fewer disputes and more confidence in the accuracy of the calculations.
Streamline Validation: Say goodbye to endless email chains! Instead of "email ping-pong," we'll have a structured "Compare & Sign-off" workflow. This will make the validation process faster, more efficient, and way less frustrating.
Ensure Auditability: Every single number in the final invoice will be traceable back to its source. No more black boxes! We're talking about complete transparency, from SCADA raw data to negotiated adjustments. This is crucial for defending calculations during audits and meetings.

This upgrade is not just about making things easier; it's about creating a reliable, auditable, and efficient financial settlement process. Think of the time and money we'll save, not to mention the reduced stress on our asset managers.

2. User Stories: Seeing Things from the Asset Manager's Perspective

To really understand the value of this feature, let's put ourselves in the shoes of an asset manager. What are their pain points? What would make their lives easier? Here are a few user stories that highlight the key benefits:

As an Asset Manager, I want to input the official IPC and IPPIEM inflation indices once a year so that the Energy Rate (ER) is automatically updated without me hacking a formula. No more wrestling with spreadsheets or worrying about manual errors. Just simple, automated updates.
As an Asset Manager, I want to run "What-If" Scenarios: "If I accept their Grid Loss claim for October, how does that change the final Balance Payable?" This is about having the power to explore different scenarios and make informed decisions. Imagine being able to quickly see the financial impact of accepting or rejecting a claim. That's a game-changer!
As an Asset Manager, I need a "Trace-to-Source" tooltip on every calculated field (e.g., $BAA$ ), showing exactly which raw numbers ( $MAA$ , $AAP$ ) fed into it, so I can defend the calculation during meetings. This is all about transparency and accountability. Being able to quickly trace a number back to its source builds trust and makes it easier to defend calculations.

These user stories paint a clear picture of how this feature request can empower asset managers and streamline the financial settlement process. It's about giving them the tools they need to do their jobs effectively and confidently.

3. Functional Architecture: Building the Foundation

To bring this vision to life, we need a solid functional architecture. This involves refactoring the FsaView to support a dedicated sub-module navigation under FSA Management. Think of it as organizing our toolbox for maximum efficiency. Here's the proposed structure:

Availability Matrix (The Data Lake): This is where all the operational data lives – the single source of truth.
Validation Desk (The Work Bench): A workspace to resolve disputes and validate data before any money is calculated.
Financial Settlement (The Cash Register): The engine that automates the complex formulas and calculates the final balance.

Module A: Availability Matrix (Data Ingestion): The Single Source of Truth

The Availability Matrix is crucial because it serves as the single source of truth for all operational data. It's organized in a hierarchy: Assessment Period (5-Year) > Production Period (Year) > Month. Here are some key enhancements:

New Data Column - Peak Availability ( $AAP$ ): Schedule 3, Clause 5 introduces a bonus for availability during "Heures de Pointe" (e.g., 17h-22h / 18h-23h). We need to add an input field/column for AAP alongside $EP$ , $EL$ , and $ELX$ . This will allow us to accurately calculate the peak bonus.
Smart Aggregation: A critical rule: never average percentages! Parent rows (Year/Period) must sum the Energy MWh ( $EP, EL, ELX$ ) from their children first, then calculate the Availability % using the formula: $Availability = rac{\sum(EP + ELX)}{\sum(EP + ELX + EL)}$ This ensures accurate aggregation and prevents misleading averages.
WAA Target Automation: To prevent user error, we need to hardcode the targets from Schedule 3: Y1-Y5: 97.5%, Y6-Y10: 97.0%, Y11-Y15: 96.5%. This ensures consistency and accuracy in the calculations.

Module B: Validation Desk (The Variance Engine): Resolving Disputes

The Validation Desk is designed to be a workspace where we can resolve disputes before any money changes hands. It's all about ensuring that everyone is on the same page before we start calculating the financials. Key features include:

Variance Highlighting: Compare Owner Calculated vs. Contractor Reported data. Highlight cells in Orange if variance > 0.1% and Red if > 0.5%. This makes it easy to spot discrepancies and focus on the areas that need attention.
Contractor Adjustment Workflow: Since we import Contractor data as monthly aggregates (CSV), we cannot use the granular IncidentAdjustmentModal. The solution? Enable an "Override Mode" on the Contractor Adjusted column. Any change to $EP$ , $EL$ , $ELX$ , or $AAP$ should trigger a Required Comment Modal (e.g., "Adjustment: Conceded 50% of Grid Loss claim per meeting minutes 12/04"). This ensures that all adjustments are documented and auditable.

Module C: Financial Settlement (The Calculator): Automating the Formulas

The Financial Settlement module is where the magic happens. It's designed to automate the complex formulas of Schedule 3, Clause 5. Let's break it down into its key components:

1. Variable Configuration (The "Inputs" Card)

This is where we configure the key variables that drive the calculations:

Indices: Input fields for IPC_n and IPPIEM_n (published by HCP.ma). These indices are crucial for calculating the Energy Rate.
Energy Rate (ER) Engine: Base: 620 MAD. Formula: $ER = 620 \times (0.4 + 0.4 \frac{IPC_n}{IPC_0} + 0.2 \frac{IPPIEM_n}{IPPIEM_0})$ . This engine automatically updates the Energy Rate based on the latest inflation indices.
PEE (Project Electrical Efficiency): Default to 98% (Editable). This allows for flexibility in case the efficiency changes over time.
PWE (Project Wake Efficiency): Default to 92% (Editable). Similar to PEE, this allows for adjustments to wake efficiency.

2. The "Peak Bonus" Calculator ( $PointeBonus$ )

This calculator determines the bonus availability percentage derived from Peak Hours:

Logic: Calculate the bonus availability percentage derived from Peak Hours.
Formula: $PointeBonus = 0.1 \times (AAP - MAA)$
Condition: If $AAP < MAA$ , force $PointeBonus = 0$ .
Output: $BAA$ (Bonus Average Availability) = $MAA + PointeBonus$ .

3. The Incentive (Bonus) Calculator

This calculator determines the bonus amount based on the availability performance:

Trigger: Active only if $MAA > (WAA + 0.25\%)$ .
Algorithm: Implement the Tiered Tranche logic specific to the Assessment Period. Example (Years 1-5): Tranche A (Low): $0.4 \times \max(\min(BAA, 98\%) - WAA, 0)$ , Tranche B (Mid): $0.5 \times \max(\min(BAA, 98.5\%) - 98\%, 0)$ , Tranche C (High): $0.6 \times \max(BAA - 98.5\%, 0)$ . Total Incentive: $(A + B + C) \times TEP \times PEE \times ER$ .

4. The Compensation (Penalty) Calculator

This calculator determines the penalty amount if the availability performance falls below the warranted level:

Trigger: Active only if $MAA < WAA$ .
Formula: $(WAA - MAA) \times (\frac{TEP}{MAA}) \times PEE \times ER$ .
Manual Adjustment (Clause 5.1): Add a field "Compensation Deduction" to manually subtract amounts for specific exclusions (e.g., Employer Instructions not captured in SCADA).

5. The "Bottom Line" Display

This is where we see the final balance payable:

Formula: $Balance = Compensation - Incentive - AccruedPayments$ .
Visuals: Positive Balance: Display "Employer Invoices Contractor" card in Green. Negative Balance: Display "Contractor Invoices Employer" card in Orange.

4. Technical Specification: Under the Hood

To make this all work, we need to define the data model and component logic. Here's a glimpse under the hood:

Data Model: `availabilityTypes.ts`

// New: Financial Parameters
export interface FinancialParams {
 year: number;
 ipc_n: number;
 ippiem_n: number;
 // Constants (loaded from config but overridable)
 ipc_0: number;
 ippiem_0: number;
 er_base: number; // 620
 pee: number; // 0.98
}

// Update: FsaDataPoint
export interface FsaDataPoint {
 ep: number;
 elx: number;
 el: number;
 epot: number;
 availability: number;
 // NEW: Peak Hours Availability
 aap: number; 
}

// New: Settlement Record
export interface SettlementRecord {
 periodId: string;
 maa: number; // Measured Average Availability
 aap: number; // Peak Availability
 baa: number; // Bonus Average Availability
 waa: number; // Warranted Availability
 
 // Financials
 energyRate: number;
 incentive: number;
 compensation: number;
 balancePayable: number;
 status: "Draft" | "Finalized";
}

Component Logic: `FinancialSettlementView.tsx`

State Management: Must subscribe to the FsaContext to get the live "Active Source" data for the selected year.
Reactivity: If a user goes back to "Validation Desk" and adjusts a Contractor value for January, the "Financial Settlement" total for the Year must instantly reflect that change.

5. Acceptance Criteria: How We Know We've Succeeded

Finally, let's define the acceptance criteria. How will we know that this feature request has been successfully implemented?

[ ] Hierarchy: The "Availability Matrix" correctly renders the 3-level tree (Period > Year > Month).
[ ] Peak Hours Input: Users can input/import AAP values for every month.
[ ] Indices Calculation: The Energy Rate ( $ER$ ) updates dynamically when users input IPC and IPPIEM.
[ ] WAA Logic: The system enforces the correct WAA target (97.5% vs 97.0% vs 96.5%) based on the year selected.
[ ] Bonus Logic: $PointeBonus$ is calculated correctly ( $0.1 \times (AAP-MAA)$ ) and clamped to 0 if negative.
[ ] Incentive Tiers: The system correctly splits the Incentive calculation into the 0.4/0.5/0.6 weighted tranches.
[ ] Traceability: Hovering over the "Balance Payable" shows a popover breakdown: "Compensation (0) - Incentive (1.2M) - Accrued (0)". This provides transparency and makes it easy to understand the final balance.
[ ] Scenario Mode: Toggling the "Source" in the Settlement view (e.g., from "Owner Adjusted" to "Contractor Adjusted") instantly updates the Balance Payable, allowing for real-time negotiation modeling. This is a critical feature for exploring different scenarios and making informed decisions.

So, there you have it! A comprehensive feature request for an FSA Availability Warranty & Financial Settlement Engine. This isn't just about automating a few calculations; it's about transforming the way we manage and validate financial settlements, saving time, reducing errors, and building trust. Let's make it happen!