Add import/export field mapping for Project and Scenario attributes in FR-008

admin/installation.md

@@ -46,7 +46,26 @@ Before you begin, ensure that you have the following prerequisites installed on
 
    The first time you run the application, the database will be initialized automatically. Ensure that the database container is running and accessible.
 
-5. **Stopping the Application**
+5. **Seed Default Accounts and Roles**
+
+   After the schema is in place, run the initial data seeding utility so the default roles and administrator account exist:
+
+   ```bash
+   # activate your virtualenv first
+   python -m scripts.00_initial_data
+   ```
+
+   The script reads the standard database environment variables (see below) and supports the following overrides:
+
+   - `CALMINER_SEED_ADMIN_EMAIL` (default `admin@calminer.local`)
+   - `CALMINER_SEED_ADMIN_USERNAME` (default `admin`)
+   - `CALMINER_SEED_ADMIN_PASSWORD` (default `ChangeMe123!` — change in production)
+   - `CALMINER_SEED_ADMIN_ROLES` (comma list, always includes `admin`)
+   - `CALMINER_SEED_FORCE` (`true` to rotate the admin password on every run)
+
+   You can rerun the script safely; it updates existing roles and user details without creating duplicates.
+
+6. **Stopping the Application**
 
    To stop the application, run the following command in the terminal:
 

architecture/08_concepts/03_security.md

@@ -12,6 +12,20 @@ Role-based access controls (RBAC) are implemented to restrict data access based
 
 Also see [Authentication and Authorization](../08_concepts.md#authentication-and-authorization) and the [Data Model](../08_concepts/02_data_model.md#user-roles) sections.
 
+- Default administrative credentials are provided at deployment time through environment variables (`CALMINER_SEED_ADMIN_EMAIL`, `CALMINER_SEED_ADMIN_USERNAME`, `CALMINER_SEED_ADMIN_PASSWORD`, `CALMINER_SEED_ADMIN_ROLES`). These values are consumed by a shared bootstrap helper on application startup, ensuring mandatory roles and the administrator account exist before any user interaction.
+- Operators can request a managed credential reset by setting `CALMINER_SEED_FORCE=true`. On the next startup the helper rotates the admin password and reapplies role assignments, so downstream environments must update stored secrets immediately after the reset.
+- The bootstrap helper is idempotent; when no changes are required, startup completes without mutating the database, preserving audit trails while still verifying the presence of required roles.
+
+### Route Guard Dependencies
+
+- `require_project_resource` and `require_scenario_resource` build on service-level authorization helpers to enforce role checks while resolving requested entities.
+- `require_project_scenario_resource` ensures the scenario referenced by a request belongs to the provided project identifier before continuing processing.
+- These dependencies surface 401/403/404 responses consistently across API and UI handlers and can be composed with additional ownership checks when project member metadata is introduced.
+
+## Session Management
+
+Authentication relies on a pair of signing tokens issued as `calminer_access_token` and `calminer_refresh_token` HttpOnly cookies. An `AuthSessionMiddleware` component validates incoming access tokens, refreshes them when still covered by a valid refresh token, and attaches the resolved user context to `request.state.auth_session`. Logout clears both cookies and redirects users back to the login form. This approach keeps credentials out of JavaScript, supports transparent rotation of short-lived access tokens, and ensures templates can adapt their navigation to the current session state.
+
 ## Audit Logging
 
 Comprehensive logging of user activities and system events is maintained for monitoring and auditing purposes. Also see [Error Handling and Logging](../08_concepts.md#error-handling-and-logging) section for more details.

requirements/FR-008.md

@@ -32,3 +32,30 @@ Exporting analysis results in multiple formats is essential for users who need t
 - 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.