zwitschi
07e68a553d
- 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.
60 lines
4.2 KiB
Markdown
60 lines
4.2 KiB
Markdown
# 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](../requirements/FR-013.md) 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
|
|
|
|
1. **Open the planner** via the sidebar or scenario action button. Query parameters (`project_id`, `scenario_id`) preload metadata for the selected context.
|
|
2. **Review defaults** in the form header: currency code, contingency, discount rate, and evaluation horizon pull from the scenario, project, or system defaults.
|
|
3. **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
|
|
4. **Adjust global parameters** in the sidebar panel for contingency percentage, discount rate, and evaluation horizon years.
|
|
5. **Run the calculation** with _Save & Calculate_. The POST request validates the payload, aggregates totals, applies contingency, and produces categorized and time-phased results.
|
|
6. **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.
|
|
|
|
## Related Resources
|
|
|
|
- [Capex Planner template](../../calminer/templates/scenarios/capex.html)
|
|
- [Capex snapshot models](../../calminer/models/capex_snapshot.py)
|
|
- [FR-013 Requirement](../requirements/FR-013.md)
|