calminer-docs/requirements/FR-008.md

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.
• Export endpoints must respect role-based access rules (analyst, project_manager, admin) and return streaming responses with proper content-disposition headers.
• UI tooling must support triggered downloads via modal forms with format and metadata controls.

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.