Files

zwitschi 07e68a553d Enhance documentation for data model and import/export processes

- Updated data model documentation to clarify relationships between projects, scenarios, and profitability calculations.
- Introduced a new guide for data import/export templates, detailing CSV and Excel workflows for profitability, capex, and opex data.
- Created a comprehensive field inventory for data import/export, outlining input fields, derived outputs, and snapshot columns.
- Renamed "Initial Capex Planner" to "Capex Planner" and "Processing Opex Planner" to "Opex Planner" for consistency across user guides.
- Adjusted access paths and related resources in user guides to reflect the new naming conventions.
- Improved clarity and consistency in descriptions and instructions throughout the user documentation.

2025-11-13 14:10:47 +01:00

4.2 KiB

Raw Blame History

Capex Planner

The Capex Planner helps project teams capture upfront capital requirements, categorize spend, and produce a shareable breakdown that feeds downstream profitability analysis. The feature implements the acceptance criteria described in FR-013 and persists calculation snapshots for both projects and scenarios when context is provided.

Access Paths

Workspace sidebar: Navigate to Workspace → Capex Planner.
Scenario detail page: Use the Capex Planner button in the scenario header to open the planner pre-loaded with the selected project and scenario.

Prerequisites

Authenticated CalMiner account with at least viewer permissions on the target project/scenario.
Baseline pricing settings seeded through the database initializer (the GET route resolves pricing metadata for defaults).

Planner Workflow

Open the planner via the sidebar or scenario action button. Query parameters (project_id, scenario_id) preload metadata for the selected context.
Review defaults in the form header: currency code, contingency, discount rate, and evaluation horizon pull from the scenario, project, or system defaults.
Capture capex components by adding rows to the components table. Each row records:
- Category (equipment, infrastructure, land, miscellaneous, etc.)
- Component name and optional internal identifier
- Amount and currency (defaults to scenario or project currency)
- Planned spend year and notes
Adjust global parameters in the sidebar panel for contingency percentage, discount rate, and evaluation horizon years.
Run the calculation with Save & Calculate. The POST request validates the payload, aggregates totals, applies contingency, and produces categorized and time-phased results.
Review results in the Capex Summary cards, category table, and timeline table. Optional chart containers are rendered for future visualization enhancements.

Persistence Behaviour

When a project_id or scenario_id is supplied, the POST handler stores a snapshot via ProjectCapexSnapshot and/or ScenarioCapexSnapshot before rendering results.
Snapshots include aggregate totals, contingency metrics, component counts, and the normalized payload, enabling auditing and downstream financial modelling.
JSON clients can set options[persist]=0 to skip persistence in future iterations (HTML form defaults to persist enabled).

API Reference

Route	Method	Description
`/calculations/capex` (`calculations.capex_form`)	GET	Renders the planner template with defaults for the provided project/scenario context.
`/calculations/capex` (`calculations.capex_submit`)	POST	Accepts form or JSON payload matching `CapexCalculationRequest`, returns HTML or JSON results, and persists snapshots when context is present.

Key schemas and services:

schemas.calculations.CapexCalculationRequest, CapexComponentInput, CapexParameters
services.calculations.calculate_initial_capex
_persist_capex_snapshots helper in routes/calculations.py

Refer to tests/integration/test_capex_calculations.py for example payloads and persistence assertions.

Troubleshooting

Validation errors: Field-level messages appear above the components table for row-specific issues and in the global error alert for general problems.
Currency mismatch: The service enforces a single currency across all components; ensure component rows use the same ISO-4217 code or adjust the default currency.
Timeline gaps: Rows without a spend_year are excluded from the timeline but still contribute to totals.

4.2 KiB Raw Blame History