# 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)