From 02906bc9604c361d478670c04daaa613cf4f750e Mon Sep 17 00:00:00 2001 From: zwitschi Date: Mon, 10 Nov 2025 08:27:49 +0100 Subject: [PATCH] Add dashboard layout plan and scenario validation rules documentation --- specifications/dashboard_layout.md | 45 +++++++++++++++++++++++++++ specifications/scenario_validation.md | 44 ++++++++++++++++++++++++++ 2 files changed, 89 insertions(+) create mode 100644 specifications/dashboard_layout.md create mode 100644 specifications/scenario_validation.md diff --git a/specifications/dashboard_layout.md b/specifications/dashboard_layout.md new file mode 100644 index 0000000..0296cb5 --- /dev/null +++ b/specifications/dashboard_layout.md @@ -0,0 +1,45 @@ +# CalMiner Dashboard Layout Plan + +Last updated: 2025-11-09 + +This document describes the intended layout structure for the CalMiner homepage/dashboard template. + +## Page Goals + +- Provide a concise overview of key project and scenario metrics immediately after sign-in. +- Offer quick actions for creating or navigating to core workflows (projects, scenarios, data uploads). +- Surface recent activity in a scan-friendly, responsive layout that works on desktop and tablet. + +## Layout Structure + +1. **Hero Header** + + - Title block with optional welcome message and current environment badge. + - Primary CTA button group (e.g., "New Project", "Import Data"). + - Optional quick filter chips for project categories. + +2. **Summary Metrics Row** + + - Four metric cards showing: total projects, active scenarios, pending simulations, last import timestamp. + - Cards adapt to a two-column grid on screens < 960px. + +3. **Recent Activity Panels** + + - Left column (2/3 width) displays a table of recent projects with status, updated timestamp. + - Right column (1/3 width) hosts scenario alerts (validation conflicts, approaching deadlines) in a stacked list. + +4. **Secondary Widgets** + - Simulation pipeline status timeline (if data present) or placeholder guidance. + - Documentation and support links card. + +## Responsiveness + +- Desktop: two-column layout for activity panels and secondary widgets. +- Tablet: stacks columns vertically while keeping metric cards in two columns. +- Mobile: single-column flow; CTA buttons collapse into a vertical stack. + +## Implementation Notes + +- Reuse existing `.card`, `.page-header`, and `.container` classes from `static/css/main.css`. +- Introduce specialized dashboard classes (e.g., `.dashboard-metrics`, `.dashboard-grid`) scoped within a new `static/css/dashboard.css` file if needed. +- Provide placeholder content for areas where backend data integrations are pending (e.g., empty state messages). diff --git a/specifications/scenario_validation.md b/specifications/scenario_validation.md new file mode 100644 index 0000000..69e875b --- /dev/null +++ b/specifications/scenario_validation.md @@ -0,0 +1,44 @@ +# Scenario Validation Rules + +Last updated: 2025-11-09 + +This document captures the validation rules that must run before comparing two or more scenarios within the CalMiner application. The rules are enforced inside the scenario service layer and surfaced through the API and HTML workflows. + +## Comparison Preconditions + +All scenarios included in a comparison request **must** satisfy the following preconditions: + +| Rule | Description | Error Code | Client Message | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | ---------------------------------------------------------------------- | +| Same project | Every scenario must belong to the same project identifier. | `SCENARIO_PROJECT_MISMATCH` | "Selected scenarios do not belong to the same project." | +| Active status | Only scenarios in `draft` or `active` status may be compared. Archived scenarios are rejected. | `SCENARIO_STATUS_INVALID` | "Archived scenarios cannot be compared." | +| Shared currency | Scenarios must share the same `currency` value when provided. | `SCENARIO_CURRENCY_MISMATCH` | "Scenarios use different currencies and cannot be compared." | +| Timeline coherence | When both scenarios provide date ranges, they must overlap or touch (inclusive). Non-overlapping ranges raise a conflict. | `SCENARIO_TIMELINE_DISJOINT` | "Scenario timelines do not overlap; adjust the comparison window." | +| Primary resource alignment | Scenarios must declare the same `primary_resource` (if set). When one is unset, the non-null value is applied to both. If both are set but differ, the comparison fails. | `SCENARIO_RESOURCE_MISMATCH` | "Scenarios target different primary resources and cannot be compared." | + +## Error Response Contract + +When a validation rule fails, the service layer raises a `ScenarioValidationError` (to be implemented) containing: + +- a machine-readable `code` from the table above, +- a human-readable `message` designed for UI display, +- a list of related `scenario_ids` that triggered the rule (if available). + +The API adapts the error into an HTTP `422 Unprocessable Entity` payload: + +```jsonc +{ + "detail": { + "code": "SCENARIO_PROJECT_MISMATCH", + "message": "Selected scenarios do not belong to the same project.", + "scenario_ids": [12, 19] + } +} +``` + +HTML form flows display the `message` as a banner and set the HTTP status to `400`. + +## Future Considerations + +- Expand rules to cover incompatible simulation parameter configurations once parameter taxonomy stabilises. +- Provide localized error message variants when the internationalization framework is introduced.