# Functional Requirement FR-008: Export Analysis Results

## Description

The system shall provide functionality for users to export analysis results in various formats (e.g., CSV, Excel, PDF) to facilitate sharing and further analysis. Users should be able to select specific data sets and customize the export options based on their needs.

## Priority

Medium

## Rationale

Exporting analysis results in multiple formats is essential for users who need to share findings with stakeholders, integrate data into other tools, or perform additional analysis outside the CalMiner platform. This functionality enhances the usability and flexibility of the system.

## Acceptance Criteria

- Users can select specific data sets for export.
- The system supports exporting data in multiple formats (e.g., CSV, Excel, PDF).
- Users can customize export options (e.g., file name, data range, included fields).
- The export process is efficient and does not impact system performance.
- Users receive a notification upon successful export, along with a link to download the file.
- The system maintains data integrity and security during the export process.

## Dependencies

- Integration with data storage systems to retrieve and process data for export.
- User interface components for export configuration and progress tracking.
- Integration with other functional requirements, such as reporting and data visualization features.

## Additional Requirements

- The system should provide a user-friendly interface for configuring export options.
- The export functionality should be accessible from relevant areas of the application (e.g., project dashboards, analysis results pages).
- The system should log export activities for auditing and monitoring purposes.
- Import and export flows must share a consistent schema contract so that data exported from the platform can be re-imported without loss.

## Import/Export Field Mapping

The following table inventories the core project and scenario attributes that must participate in bulk import/export workflows. It also documents whether a field is required during import, how validation should behave, and any special handling notes for generated values.

| Dataset  | Field              | Data Type         | Required on Import | Validation & Normalization                                                 | Export Behaviour                             |
| -------- | ------------------ | ----------------- | ------------------ | -------------------------------------------------------------------------- | -------------------------------------------- |
| Project  | `name`             | string (≤255)     | Yes                | Must be unique (case-insensitive); trim whitespace.                        | Always include; acts as stable identifier.   |
| Project  | `location`         | string (≤255)     | No                 | Accept blank values; normalize to title case where practical.              | Include when present; blank otherwise.       |
| Project  | `operation_type`   | enum              | Yes                | Must map to `MiningOperationType`; allow human-friendly labels on import.  | Export canonical enum value.                 |
| Project  | `description`      | text              | No                 | Permit multiline text; strip dangerous markup.                             | Export full text.                            |
| Project  | `created_at`       | datetime (UTC)    | No                 | Ignored on import; system assigns timestamp.                               | Export for audit purposes (read-only).       |
| Project  | `updated_at`       | datetime (UTC)    | No                 | Ignored on import; system manages.                                         | Export for audit purposes (read-only).       |
| Scenario | `project_name`     | string (≤255)     | Yes                | Must resolve to an existing project `name`; case-insensitive lookup.       | Export to maintain relationship context.     |
| Scenario | `name`             | string (≤255)     | Yes                | Unique per project; trim whitespace.                                       | Always include.                              |
| Scenario | `status`           | enum              | Yes                | Map to `ScenarioStatus`; accept friendly labels (`Draft`, `Active`, etc.). | Export canonical enum value.                 |
| Scenario | `start_date`       | date (ISO 8601)   | No                 | Validate ordering with `end_date` when provided.                           | Export ISO 8601 string or blank.             |
| Scenario | `end_date`         | date (ISO 8601)   | No                 | Must be ≥ `start_date` when both present.                                  | Export ISO 8601 string or blank.             |
| Scenario | `discount_rate`    | decimal (5,2)     | No                 | Accept percentage string or decimal; normalize to decimal (0-100).         | Export numeric percentage with two decimals. |
| Scenario | `currency`         | string (ISO 4217) | No                 | Uppercase 3-letter ISO code; validate against supported list.              | Export uppercase code.                       |
| Scenario | `primary_resource` | enum              | No                 | Map to `ResourceType`; accept human-friendly names on import.              | Export canonical enum value.                 |
| Scenario | `description`      | text              | No                 | Allow multiline text; strip dangerous markup.                              | Export full text.                            |
| Scenario | `created_at`       | datetime (UTC)    | No                 | Ignored on import; system assigns timestamp.                               | Export for audit purposes (read-only).       |
| Scenario | `updated_at`       | datetime (UTC)    | No                 | Ignored on import; system manages.                                         | Export for audit purposes (read-only).       |

Additional domain entities (financial inputs, simulation parameters, etc.) will be inventoried in subsequent iterations once their import/export scope is defined. This initial mapping focuses on the mandatory Project and Scenario records required to satisfy FR-008 and related reporting flows.

## Import/Export File Format Guidelines

- **Supported formats:** CSV (`.csv`) and Excel (`.xlsx`).
- **Encoding:** All text-based files must use UTF-8 encoding without byte-order marks to ensure consistent parsing across environments.
- **Header row:** The first row must contain column headers matching the field names defined in the mapping table (case-insensitive). Additional columns are ignored during import but preserved during export when possible.
- **CSV specifics:** Values are comma-delimited, double-quoted when containing commas or line breaks, and line endings follow `\n`. Empty strings are treated as null when the field is optional.
- **Excel specifics:** Importers read from the first worksheet. Each sheet must use the same header row convention. Cells containing formulas are evaluated before ingestion (using stored values, not formulas).
- **Date/time:** Dates and timestamps must be supplied in ISO 8601 format (`YYYY-MM-DD` for dates, `YYYY-MM-DDTHH:MM:SSZ` for timestamps). Exporters always output UTC timestamps.
- **Numeric fields:** Decimal values use `.` as the separator. Discount rates accept either raw decimals (`7.5`) or percentages (`7.5%`).
- **Enumerations:** Enum columns accept canonical values or the friendly labels documented in the alias table. Exporters always emit canonical enum codes.
- **Validation feedback:** Import workflows return structured error payloads indicating row number, column, and validation failure to guide remediation.