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.
This commit is contained in:
@@ -118,6 +118,18 @@ A specific configuration of assumptions for a project.
|
||||
- `financial_inputs`: One-to-many with FinancialInput
|
||||
- `simulation_parameters`: One-to-many with SimulationParameter
|
||||
|
||||
#### Projects → Scenarios → Profitability Calculations
|
||||
|
||||
Calminer organises feasibility data in a nested hierarchy. A project defines the overarching mining context and exposes a one-to-many `scenarios` collection. Each scenario captures a self-contained assumption set and anchors derived artefacts such as financial inputs, simulation parameters, and profitability snapshots. Profitability calculations execute at the scenario scope; when triggered, the workflow in `services/calculations.py` persists a `ScenarioProfitability` record and can optionally roll results up to project level by creating a `ProjectProfitability` snapshot. Consumers typically surface the most recent metrics via the `latest_profitability` helpers on both ORM models.
|
||||
|
||||
| Layer | ORM models | Pydantic schema(s) | Key relationships |
|
||||
| -------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
||||
| Project | `models.project.Project` | `schemas.project.ProjectRead` | `Project.scenarios`, `Project.profitability_snapshots`, `Project.latest_profitability` |
|
||||
| Scenario | `models.scenario.Scenario` | `schemas.scenario.ScenarioRead` | `Scenario.project`, `Scenario.profitability_snapshots`, `Scenario.latest_profitability` |
|
||||
| Profitability calculations | `models.profitability_snapshot.ProjectProfitability`, `models.profitability_snapshot.ScenarioProfitability` | `schemas.calculations.ProfitabilityCalculationRequest`, `schemas.calculations.ProfitabilityCalculationResult` | Persisted via `services.calculations.calculate_profitability`; aggregates scenario metrics into project snapshots |
|
||||
|
||||
Detailed CRUD endpoint behaviour for projects and scenarios is documented in `calminer-docs/api/README.md`.
|
||||
|
||||
#### FinancialInput
|
||||
|
||||
Line-item financial assumption attached to a scenario.
|
||||
@@ -174,7 +186,7 @@ Project-level snapshot capturing aggregated initial capital expenditure metrics.
|
||||
|
||||
#### ScenarioCapexSnapshot
|
||||
|
||||
Scenario-level snapshot storing detailed initial capex results.
|
||||
Scenario-level snapshot storing detailed capex results.
|
||||
|
||||
**Table:** `scenario_capex_snapshots`
|
||||
|
||||
@@ -200,11 +212,11 @@ Scenario-level snapshot storing detailed initial capex results.
|
||||
- `scenario`: Many-to-one with Scenario
|
||||
- `created_by`: Many-to-one with User (nullable)
|
||||
|
||||
#### ProjectProcessingOpexSnapshot
|
||||
#### ProjectOpexSnapshot
|
||||
|
||||
Project-level snapshot persisting recurring processing opex metrics.
|
||||
Project-level snapshot persisting recurring opex metrics.
|
||||
|
||||
**Table:** `project_processing_opex_snapshots`
|
||||
**Table:** `project_opex_snapshots`
|
||||
|
||||
| Attribute | Type | Description |
|
||||
| ------------------------ | --------------------------------- | ------------------------------------------------------- |
|
||||
@@ -214,7 +226,7 @@ Project-level snapshot persisting recurring processing opex metrics.
|
||||
| calculation_source | String(64), nullable | Originating workflow identifier |
|
||||
| calculated_at | DateTime | Timestamp the calculation completed |
|
||||
| currency_code | String(3), nullable | Currency for totals |
|
||||
| overall_annual | Numeric(18,2), nullable | Total annual processing opex |
|
||||
| overall_annual | Numeric(18,2), nullable | Total annual opex |
|
||||
| escalated_total | Numeric(18,2), nullable | Escalated cost across the evaluation horizon |
|
||||
| annual_average | Numeric(18,2), nullable | Average annual cost over the horizon |
|
||||
| evaluation_horizon_years | Integer, nullable | Number of years included in the timeline |
|
||||
@@ -230,11 +242,11 @@ Project-level snapshot persisting recurring processing opex metrics.
|
||||
- `project`: Many-to-one with Project
|
||||
- `created_by`: Many-to-one with User (nullable)
|
||||
|
||||
#### ScenarioProcessingOpexSnapshot
|
||||
#### ScenarioOpexSnapshot
|
||||
|
||||
Scenario-level snapshot persisting recurring processing opex metrics.
|
||||
Scenario-level snapshot persisting recurring opex metrics.
|
||||
|
||||
**Table:** `scenario_processing_opex_snapshots`
|
||||
**Table:** `scenario_opex_snapshots`
|
||||
|
||||
| Attribute | Type | Description |
|
||||
| ------------------------ | --------------------------------- | ------------------------------------------------------- |
|
||||
@@ -244,7 +256,7 @@ Scenario-level snapshot persisting recurring processing opex metrics.
|
||||
| calculation_source | String(64), nullable | Originating workflow identifier |
|
||||
| calculated_at | DateTime | Timestamp the calculation completed |
|
||||
| currency_code | String(3), nullable | Currency for totals |
|
||||
| overall_annual | Numeric(18,2), nullable | Total annual processing opex |
|
||||
| overall_annual | Numeric(18,2), nullable | Total annual opex |
|
||||
| escalated_total | Numeric(18,2), nullable | Escalated cost across the evaluation horizon |
|
||||
| annual_average | Numeric(18,2), nullable | Average annual cost over the horizon |
|
||||
| evaluation_horizon_years | Integer, nullable | Number of years included in the timeline |
|
||||
|
||||
Reference in New Issue
Block a user