From f20ac853104afda449725079ab8b6fc0bf15288a Mon Sep 17 00:00:00 2001 From: zwitschi Date: Mon, 10 Nov 2025 08:27:26 +0100 Subject: [PATCH] Add import/export file format guidelines to FR-008 --- requirements/FR-008.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/requirements/FR-008.md b/requirements/FR-008.md index 74e4392..dd5a153 100644 --- a/requirements/FR-008.md +++ b/requirements/FR-008.md @@ -59,3 +59,15 @@ The following table inventories the core project and scenario attributes that mu | 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.