allucanget/calminer-docs
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add import/export file format guidelines to FR-008

Browse Source
This commit is contained in:
zwitschi
2025-11-10 08:27:26 +01:00
parent e573f7dc7b
commit f20ac85310
1 changed files with 12 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
requirements/FR-008.md
View File

@@ -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). | | 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. 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.