# Capability: Formula Refresh

## Purpose
The Formula Refresh capability allows the system to recalculate all formulas in an Excel workbook and update their cached values. This is essential when data has been written to the workbook externally and the calculated results need to be persisted within the file itself.

## Requirements

### Requirement: Refresh all formulas in workbook
The ExcelService SHALL provide a public method `RefreshFormulas` that evaluates and recalculates all formulas in an Excel workbook.

#### Scenario: Successful formula refresh
- **WHEN** a valid Excel file containing formulas is provided to `RefreshFormulas`
- **THEN** all formulas in the workbook are evaluated
- **AND** cached formula values are updated with recalculated results
- **AND** the workbook is saved back to the file
- **AND** the method returns `(success: true, result: <filePath>, error: null)`

#### Scenario: File not found
- **WHEN** `RefreshFormulas` is called with a file path that does not exist
- **THEN** the method returns `(success: false, result: null, error: FileNotFoundException)`

#### Scenario: Invalid or corrupted workbook
- **WHEN** `RefreshFormulas` is called with a file that is not a valid Excel workbook
- **THEN** the method returns `(success: false, result: null, error: <exception>)`
- **AND** the original file remains unmodified

#### Scenario: Empty file path
- **WHEN** `RefreshFormulas` is called with null or empty file path
- **THEN** the method returns `(success: false, result: null, error: ArgumentException)`

### Requirement: Formula evaluation completeness
The `RefreshFormulas` method SHALL evaluate all formula types across all sheets in the workbook.

#### Scenario: Multiple sheets with formulas
- **WHEN** a workbook contains multiple sheets with formulas
- **THEN** formulas in all sheets are evaluated
- **AND** cross-sheet references are properly resolved

#### Scenario: Different formula types
- **WHEN** a workbook contains various formula types (SUM, AVERAGE, IF, VLOOKUP, etc.)
- **THEN** all formula types are evaluated correctly
- **AND** formulas dependent on other formulas are evaluated in correct order

### Requirement: Resource management
The `RefreshFormulas` method SHALL properly dispose of all resources including file streams and workbook objects.

#### Scenario: Proper disposal after successful refresh
- **WHEN** formula refresh completes successfully
- **THEN** all file streams are closed and disposed
- **AND** the workbook object is disposed
- **AND** no file locks remain on the Excel file

#### Scenario: Proper disposal after error
- **WHEN** an exception occurs during formula refresh
- **THEN** all allocated resources are still disposed
- **AND** no file locks remain on the Excel file