Refactor test cases for improved readability and consistency

- Updated test functions in various test files to enhance code clarity by formatting long lines and improving indentation. - Adjusted assertions to use multi-line formatting for better readability. - Added new test cases for theme settings API to ensure proper functionality. - Ensured consistent use of line breaks and spacing across test files for uniformity.
2025-10-27 10:32:55 +01:00
parent e8a86b15e4
commit 97b1c0360b
78 changed files with 2327 additions and 650 deletions
--- a/docs/architecture/05_building_block_view.md
+++ b/docs/architecture/05_building_block_view.md
@@ -1,10 +1,11 @@
 ---
-title: "05 — Building Block View"
-description: "Explain the static structure: modules, components, services and their relationships."
+title: '05 — Building Block View'
+description: 'Explain the static structure: modules, components, services and their relationships.'
 status: draft
 ---

 <!-- markdownlint-disable-next-line MD025 -->
+
 # 05 — Building Block View

 ## Architecture overview
@@ -42,6 +43,144 @@ Refer to the detailed architecture chapters in `docs/architecture/`:
 - **Middleware** (`middleware/validation.py`): applies JSON validation before requests reach routers.
 - **Testing** (`tests/unit/`): pytest suite covering route and service behavior, including UI rendering checks and negative-path router validation tests to ensure consistent HTTP error semantics. Playwright end-to-end coverage is planned for core smoke flows (dashboard load, scenario inputs, reporting) and will attach in CI once scaffolding is completed.

+### Component Diagram
+
+# System Architecture — Mermaid Diagram
+
+```mermaid
+graph LR
+  %% Direction
+  %% LR = left-to-right for a wide architecture view
+
+  %% === Clients ===
+  U["User (Browser)"]
+
+  %% === Frontend ===
+  subgraph FE[Frontend]
+    TPL["Jinja2 Templates\n(templates/)\n• base layout + sidebar"]
+    PARTS["Reusable Partials\n(templates/partials/components.html)\n• inputs • empty states • table wrappers"]
+    STATIC["Static Assets\n(static/)\n• CSS: static/css/main.css (palette via CSS vars)\n• JS: static/js/*.js (page modules)"]
+    SETPAGE["Settings View\n(templates/settings.html)"]
+    SETJS["Settings Logic\n(static/js/settings.js)\n• validation • submit • live CSS updates"]
+  end
+
+  %% === Backend ===
+  subgraph BE[Backend FastAPI]
+    MAIN["FastAPI App\n(main.py)\n• routers • middleware • startup/shutdown"]
+
+    subgraph ROUTES[Routers]
+      R_SCN["scenarios"]
+      R_PAR["parameters"]
+      R_CST["costs"]
+      R_CONS["consumption"]
+      R_PROD["production"]
+      R_EQP["equipment"]
+      R_MNT["maintenance"]
+      R_SIM["simulations"]
+      R_REP["reporting"]
+      R_UI["ui.py (metadata for UI)"]
+      DEP["dependencies.get_db\n(shared SQLAlchemy session)"]
+    end
+
+    subgraph SRV[Services]
+      S_BLL["Business Logic Layer\n• orchestrates models + calc"]
+      S_REP["Reporting Calculations"]
+      S_SIM["Monte Carlo\n(simulation scaffolding)"]
+      S_SET["Settings Manager\n(services/settings.py)\n• defaults via CSS vars\n• persistence in DB\n• env overrides\n• surfaces to API & UI"]
+    end
+
+    subgraph MOD[Models]
+      M_SCN["Scenario"]
+      M_CAP["CapEx"]
+      M_OPEX["OpEx"]
+      M_CONS["Consumption"]
+      M_PROD["ProductionOutput"]
+      M_EQP["Equipment"]
+      M_MNT["Maintenance"]
+      M_SIMR["SimulationResult"]
+    end
+
+    subgraph DB[Database Layer]
+      CFG["config/database.py\n(SQLAlchemy engine & sessions)"]
+      PG[("PostgreSQL")]
+      APPSET["application_setting table"]
+    end
+  end
+
+  %% === Middleware & Utilities ===
+  subgraph MW[Middleware & Utilities]
+    VAL["JSON Validation Middleware\n(middleware/validation.py)"]
+  end
+
+  subgraph TEST[Testing]
+    UNIT["pytest unit tests\n(tests/unit/)\n• routes • services • UI rendering\n• negative-path validation"]
+    E2E["Playwright E2E (planned)\n• dashboard • scenario inputs • reporting\n• attach in CI"]
+  end
+
+  %% ===================== Edges / Flows =====================
+  %% User to Frontend/Backend
+  U -->|HTTP GET| MAIN
+  U --> TPL
+  TPL -->|server-rendered HTML| U
+  STATIC --> U
+  PARTS --> TPL
+  SETPAGE --> U
+  SETJS --> U
+
+  %% Frontend to Routers (AJAX/form submits)
+  SETJS -->|fetch/POST| R_UI
+  TPL -->|form submit / fetch| ROUTES
+
+  %% FastAPI app wiring and middleware
+  VAL --> MAIN
+  MAIN --> ROUTES
+
+  %% Routers to Services
+  ROUTES -->|calls| SRV
+  R_REP -->|calc| S_REP
+  R_SIM -->|run| S_SIM
+  R_UI -->|read/write settings meta| S_SET
+
+  %% Services to Models & DB
+  SRV --> MOD
+  MOD --> CFG
+  CFG --> PG
+
+  %% Settings manager persistence path
+  S_SET -->|persist/read| APPSET
+  APPSET --- PG
+
+  %% Shared DB session dependency
+  DEP -. provides .-> ROUTES
+  DEP -. session .-> SRV
+
+  %% Model entities mapping
+  S_BLL --> M_SCN & M_CAP & M_OPEX & M_CONS & M_PROD & M_EQP & M_MNT & M_SIMR
+
+  %% Testing coverage
+  UNIT --> ROUTES
+  UNIT --> SRV
+  UNIT --> TPL
+  UNIT --> VAL
+  E2E --> U
+  E2E --> MAIN
+
+  %% Legend
+  classDef store fill:#fff,stroke:#555,stroke-width:1px;
+  class PG store;
+```
+
+---
+
+**Notes**
+
+- Arrows represent primary data/command flow. Dashed arrows denote shared dependencies (injected SQLAlchemy session).
+- The settings pipeline shows how environment overrides and DB-backed defaults propagate to both API and UI.
+
+```
+
+```
+
 ## Module Map (code)

 - `scenario.py`: central scenario entity with relationships to cost, consumption, production, equipment, maintenance, and simulation results.
--- a/docs/architecture/05_frontend/05_03_theming.md
+++ b/docs/architecture/05_frontend/05_03_theming.md
@@ -0,0 +1,88 @@
+# Theming
+
+## Overview
+
+CalMiner uses a centralized theming system based on CSS custom properties (variables) to ensure consistent styling across the application. The theme is stored in the database and can be customized through environment variables or the UI settings page.
+
+## Default Theme Settings
+
+The default theme provides a light, professional color palette suitable for business applications. The colors are defined as CSS custom properties and stored in the `application_setting` table with category "theme".
+
+### Color Palette
+
+| CSS Variable                | Default Value            | Description              |
+| --------------------------- | ------------------------ | ------------------------ |
+| `--color-background`        | `#f4f5f7`                | Main background color    |
+| `--color-surface`           | `#ffffff`                | Surface/card background  |
+| `--color-text-primary`      | `#2a1f33`                | Primary text color       |
+| `--color-text-secondary`    | `#624769`                | Secondary text color     |
+| `--color-text-muted`        | `#64748b`                | Muted text color         |
+| `--color-text-subtle`       | `#94a3b8`                | Subtle text color        |
+| `--color-text-invert`       | `#ffffff`                | Text on dark backgrounds |
+| `--color-text-dark`         | `#0f172a`                | Dark text for contrast   |
+| `--color-text-strong`       | `#111827`                | Strong/bold text         |
+| `--color-primary`           | `#5f320d`                | Primary brand color      |
+| `--color-primary-strong`    | `#7e4c13`                | Stronger primary         |
+| `--color-primary-stronger`  | `#837c15`                | Strongest primary        |
+| `--color-accent`            | `#bff838`                | Accent/highlight color   |
+| `--color-border`            | `#e2e8f0`                | Default border color     |
+| `--color-border-strong`     | `#cbd5e1`                | Strong border color      |
+| `--color-highlight`         | `#eef2ff`                | Highlight background     |
+| `--color-panel-shadow`      | `rgba(15, 23, 42, 0.08)` | Subtle shadow            |
+| `--color-panel-shadow-deep` | `rgba(15, 23, 42, 0.12)` | Deeper shadow            |
+| `--color-surface-alt`       | `#f8fafc`                | Alternative surface      |
+| `--color-success`           | `#047857`                | Success state color      |
+| `--color-error`             | `#b91c1c`                | Error state color        |
+
+## Customization
+
+### Environment Variables
+
+Theme colors can be overridden using environment variables with the prefix `CALMINER_THEME_`. For example:
+
+```bash
+export CALMINER_THEME_COLOR_BACKGROUND="#000000"
+export CALMINER_THEME_COLOR_ACCENT="#ff0000"
+```
+
+The variable names are derived by:
+
+1. Removing the `--` prefix
+2. Converting to uppercase
+3. Replacing `-` with `_`
+4. Adding `CALMINER_THEME_` prefix
+
+### Database Storage
+
+Settings are stored in the `application_setting` table with:
+
+- `category`: "theme"
+- `value_type`: "color"
+- `is_editable`: true
+
+### UI Settings
+
+Users can modify theme colors through the settings page at `/ui/settings`.
+
+## Implementation
+
+The theming system is implemented in:
+
+- `services/settings.py`: Color management and defaults
+- `routes/settings.py`: API endpoints for theme settings
+- `static/css/main.css`: CSS variable definitions
+- `templates/settings.html`: UI for theme customization
+
+## Seeding
+
+Default theme settings are seeded during database setup using the seed script:
+
+```bash
+python scripts/seed_data.py --theme
+```
+
+Or as part of defaults:
+
+```bash
+python scripts/seed_data.py --defaults
+```
--- a/docs/architecture/08_concepts/08_01_security.md
+++ b/docs/architecture/08_concepts/08_01_security.md
@@ -0,0 +1,36 @@
+# User Roles and Permissions Model
+
+This document outlines the proposed user roles and permissions model for the CalMiner application.
+
+## User Roles
+
+- **Admin:** Full access to all features, including user management, application settings, and all data.
+- **Analyst:** Can create, view, edit, and delete scenarios, run simulations, and view reports. Cannot modify application settings or manage users.
+- **Viewer:** Can view scenarios, simulations, and reports. Cannot create, edit, or delete anything.
+
+## Permissions (examples)
+
+- `users:manage`: Admin only.
+- `settings:manage`: Admin only.
+- `scenarios:create`: Admin, Analyst.
+- `scenarios:view`: Admin, Analyst, Viewer.
+- `scenarios:edit`: Admin, Analyst.
+- `scenarios:delete`: Admin, Analyst.
+- `simulations:run`: Admin, Analyst.
+- `simulations:view`: Admin, Analyst, Viewer.
+- `reports:view`: Admin, Analyst, Viewer.
+
+## Authentication System
+
+The authentication system uses JWT (JSON Web Tokens) for securing API endpoints. Users can register with a username, email, and password. Passwords are hashed using bcrypt. Upon successful login, an access token is issued, which must be included in subsequent requests for protected resources.
+
+## Key Components
+
+- **Password Hashing:** `passlib.context.CryptContext` with `bcrypt` scheme.
+- **Token Creation & Verification:** `jose.jwt` for encoding and decoding JWTs.
+- **Authentication Flow:**
+  1. User registers via `/users/register`.
+  2. User logs in via `/users/login` to obtain an access token.
+  3. The access token is sent in the `Authorization` header (Bearer token) for protected routes.
+  4. The `get_current_user` dependency verifies the token and retrieves the authenticated user.
+- **Password Reset:** A placeholder `forgot_password` endpoint is available, and a `reset_password` endpoint allows users to set a new password with a valid token (token generation and email sending are not yet implemented).
--- a/docs/architecture/13_ui_and_style.md
+++ b/docs/architecture/13_ui_and_style.md
@@ -28,6 +28,32 @@ Import macros via:
 - **Tables**: `.table-container` wrappers need overflow handling for narrow viewports; consider `overflow-x: auto` with padding adjustments.
 - **Feedback/Empty states**: Messages use default font weight and spacing; a utility class for margin/padding would ensure consistent separation from forms or tables.

+## CSS Variable Naming Conventions
+
+The project adheres to a clear and descriptive naming convention for CSS variables, primarily defined in `static/css/main.css`.
+
+## Naming Structure
+
+Variables are prefixed based on their category:
+
+- `--color-`: For all color-related variables (e.g., `--color-primary`, `--color-background`, `--color-text-primary`).
+- `--space-`: For spacing and layout-related variables (e.g., `--space-sm`, `--space-md`, `--space-lg`).
+- `--font-size-`: For font size variables (e.g., `--font-size-base`, `--font-size-lg`).
+- Other specific prefixes for components or properties (e.g., `--panel-radius`, `--table-radius`).
+
+## Descriptive Names
+
+Color names are chosen to be semantically meaningful rather than literal color values, allowing for easier theme changes. For example:
+
+- `--color-primary`: Represents the main brand color.
+- `--color-accent`: Represents an accent color used for highlights.
+- `--color-text-primary`: The main text color.
+- `--color-text-muted`: A lighter text color for less emphasis.
+- `--color-surface`: The background color for UI elements like cards or panels.
+- `--color-background`: The overall page background color.
+
+This approach ensures that the CSS variables are intuitive, maintainable, and easily adaptable for future theme customizations.
+
 ## Per-page data & actions

 Short reference of per-page APIs and primary actions used by templates and scripts.
@@ -76,6 +102,21 @@ Short reference of per-page APIs and primary actions used by templates and scrip
  - Data: `POST /api/reporting/summary` (accepts arrays of `{ "result": float }` objects)
  - Actions: Trigger summary refreshes and export/download actions.

+## Navigation Structure
+
+The application uses a sidebar navigation menu organized into the following top-level categories:
+
+- **Dashboard**: Main overview page.
+- **Overview**: Sub-menu for core scenario inputs.
+  - Parameters: Process parameters configuration.
+  - Costs: Capital and operating costs.
+  - Consumption: Resource consumption tracking.
+  - Production: Production output settings.
+  - Equipment: Equipment inventory (with Maintenance sub-item).
+- **Simulations**: Monte Carlo simulation runs.
+- **Analytics**: Reporting and analytics.
+- **Settings**: Administrative settings (with Themes and Currency Management sub-items).
+
 ## UI Template Audit (2025-10-20)

 - Existing HTML templates: `ScenarioForm.html`, `ParameterInput.html`, and `Dashboard.html` (reporting summary view).