Add UI and styling documentation; remove idempotency and logging audits
Some checks failed
CI / test (pull_request) Failing after 1m8s
Some checks failed
CI / test (pull_request) Failing after 1m8s
- Introduced a new document outlining UI structure, reusable template components, CSS variable conventions, and per-page data/actions for the CalMiner application. - Removed outdated idempotency audit and logging audit documents as they are no longer relevant. - Updated quickstart guide to streamline developer setup instructions and link to relevant documentation. - Created a roadmap document detailing scenario enhancements and data management strategies. - Deleted the seed data plan document to consolidate information into the setup process. - Refactored setup_database.py for improved logging and error handling during database setup and migration processes.
This commit is contained in:
@@ -1,110 +0,0 @@
|
||||
# Implementation Plan 2025-10-20
|
||||
|
||||
This file contains the implementation plan (MVP features, steps, and estimates).
|
||||
|
||||
## Project Setup
|
||||
|
||||
1. Connect to PostgreSQL database with schema `calminer`.
|
||||
1. Create and activate a virtual environment and install dependencies via `requirements.txt`.
|
||||
1. Define database environment variables in `.env` (e.g., `DATABASE_DRIVER`, `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_USER`, `DATABASE_PASSWORD`, `DATABASE_NAME`, optional `DATABASE_SCHEMA`).
|
||||
1. Configure FastAPI entrypoint in `main.py` to include routers.
|
||||
|
||||
## Feature: Scenario Management
|
||||
|
||||
### Scenario Management — Steps
|
||||
|
||||
1. Create `models/scenario.py` for scenario CRUD.
|
||||
1. Implement API endpoints in `routes/scenarios.py` (GET, POST, PUT, DELETE).
|
||||
1. Write unit tests in `tests/unit/test_scenario.py`.
|
||||
1. Build UI component `components/ScenarioForm.html`.
|
||||
|
||||
## Feature: Process Parameters
|
||||
|
||||
### Parameters — Steps
|
||||
|
||||
1. Create `models/parameters.py` for process parameters.
|
||||
1. Implement Pydantic schemas in `routes/parameters.py`.
|
||||
1. Add validation middleware in `middleware/validation.py`.
|
||||
1. Write unit tests in `tests/unit/test_parameter.py`.
|
||||
1. Build UI component `components/ParameterInput.html`.
|
||||
|
||||
## Feature: Stochastic Variables
|
||||
|
||||
### Stochastic Variables — Steps
|
||||
|
||||
1. Create `models/distribution.py` for variable distributions.
|
||||
1. Implement API routes in `routes/distributions.py`.
|
||||
1. Write Pydantic schemas and validations.
|
||||
1. Write unit tests in `tests/unit/test_distribution.py`.
|
||||
1. Build UI component `components/DistributionEditor.html`.
|
||||
|
||||
## Feature: Cost Tracking
|
||||
|
||||
### Cost Tracking — Steps
|
||||
|
||||
1. Create `models/capex.py` and `models/opex.py`.
|
||||
1. Implement API routes in `routes/costs.py`.
|
||||
1. Write Pydantic schemas for CAPEX/OPEX.
|
||||
1. Write unit tests in `tests/unit/test_costs.py`.
|
||||
1. Build UI component `components/CostForm.html`.
|
||||
|
||||
## Feature: Consumption Tracking
|
||||
|
||||
### Consumption Tracking — Steps
|
||||
|
||||
1. Create models for consumption: `chemical_consumption.py`, `fuel_consumption.py`, `water_consumption.py`, `scrap_consumption.py`.
|
||||
1. Implement API routes in `routes/consumption.py`.
|
||||
1. Write Pydantic schemas for consumption data.
|
||||
1. Write unit tests in `tests/unit/test_consumption.py`.
|
||||
1. Build UI component `components/ConsumptionDashboard.html`.
|
||||
|
||||
## Feature: Production Output
|
||||
|
||||
### Production Output — Steps
|
||||
|
||||
1. Create `models/production_output.py`.
|
||||
1. Implement API routes in `routes/production.py`.
|
||||
1. Write Pydantic schemas for production output.
|
||||
1. Write unit tests in `tests/unit/test_production.py`.
|
||||
1. Build UI component `components/ProductionChart.html`.
|
||||
|
||||
## Feature: Equipment Management
|
||||
|
||||
### Equipment Management — Steps
|
||||
|
||||
1. Create `models/equipment.py` for equipment data.
|
||||
1. Implement API routes in `routes/equipment.py`.
|
||||
1. Write Pydantic schemas for equipment.
|
||||
1. Write unit tests in `tests/unit/test_equipment.py`.
|
||||
1. Build UI component `components/EquipmentList.html`.
|
||||
|
||||
## Feature: Maintenance Logging
|
||||
|
||||
### Maintenance Logging — Steps
|
||||
|
||||
1. Create `models/maintenance.py` for maintenance events.
|
||||
1. Implement API routes in `routes/maintenance.py`.
|
||||
1. Write Pydantic schemas for maintenance logs.
|
||||
1. Write unit tests in `tests/unit/test_maintenance.py`.
|
||||
1. Build UI component `components/MaintenanceLog.html`.
|
||||
|
||||
## Feature: Monte Carlo Simulation Engine
|
||||
|
||||
### Monte Carlo Engine — Steps
|
||||
|
||||
1. Implement Monte Carlo logic in `services/simulation.py`.
|
||||
1. Persist results in `models/simulation_result.py`.
|
||||
1. Expose endpoint in `routes/simulations.py`.
|
||||
1. Write integration tests in `tests/unit/test_simulation.py`.
|
||||
1. Build UI component `components/SimulationRunner.html`.
|
||||
|
||||
## Feature: Reporting / Dashboard
|
||||
|
||||
### Reporting / Dashboard — Steps
|
||||
|
||||
1. Implement report calculations in `services/reporting.py`.
|
||||
1. Add detailed and summary endpoints in `routes/reporting.py`.
|
||||
1. Write unit tests in `tests/unit/test_reporting.py`.
|
||||
1. Enhance UI in `components/Dashboard.html` with charts.
|
||||
|
||||
See [UI and Style](../13_ui_and_style.md) for the UI template audit, layout guidance, and next steps.
|
||||
@@ -21,10 +21,7 @@ CalMiner uses a combination of unit, integration, and end-to-end tests to ensure
|
||||
### CI/CD
|
||||
|
||||
- Use Gitea Actions for CI/CD; workflows live under `.gitea/workflows/`.
|
||||
- `test.yml` runs on every push, provisions a temporary Postgres 16 service, waits for readiness, executes the setup script in dry-run and live modes, then fans out into parallel matrix jobs for unit (`pytest tests/unit`) and end-to-end (`pytest tests/e2e`) suites. Playwright browsers install only for the E2E job.
|
||||
- `build-and-push.yml` runs only after the **Run Tests** workflow finishes successfully (triggered via `workflow_run` on `main`). Once tests pass, it builds the Docker image with `docker/build-push-action@v2`, reuses cache-backed layers, and pushes to the Gitea registry.
|
||||
- `deploy.yml` runs only after the build workflow reports success on `main`. It connects to the target host (via `appleboy/ssh-action`), pulls the Docker image tagged with the build commit SHA, and restarts the container with that exact image reference.
|
||||
- Mandatory secrets: `REGISTRY_USERNAME`, `REGISTRY_PASSWORD`, `REGISTRY_URL`, `SSH_HOST`, `SSH_USERNAME`, `SSH_PRIVATE_KEY`.
|
||||
- `ci.yml` runs on push and pull requests to `main` and `develop` branches. It provisions a temporary PostgreSQL 15 service, sets up Python 3.11, installs dependencies from `requirements.txt` and `requirements-test.txt`, runs pytest with coverage on all tests, and builds the Docker image.
|
||||
- Run tests on pull requests to shared branches; enforce coverage target ≥80% (pytest-cov).
|
||||
|
||||
### Running Tests
|
||||
@@ -74,7 +71,7 @@ To run the Playwright tests:
|
||||
|
||||
```bash
|
||||
pytest tests/e2e/
|
||||
````
|
||||
```
|
||||
|
||||
To run headed mode:
|
||||
|
||||
@@ -166,11 +163,11 @@ When adding new workflows, mirror this structure to ensure secrets, caching, and
|
||||
- Usage sketch (in `test.yml`):
|
||||
|
||||
```yaml
|
||||
- name: Prepare Python environment
|
||||
uses: ./.gitea/actions/setup-python-env
|
||||
with:
|
||||
install-playwright: ${{ matrix.target == 'e2e' }}
|
||||
db-dry-run: true
|
||||
- name: Prepare Python environment
|
||||
uses: ./.gitea/actions/setup-python-env
|
||||
with:
|
||||
install-playwright: ${{ matrix.target == 'e2e' }}
|
||||
db-dry-run: true
|
||||
```
|
||||
|
||||
- Benefits: centralizes proxy logic and dependency installs, reduces duplication across matrix jobs, and keeps future lint/type-check jobs lightweight by disabling database setup.
|
||||
|
||||
82
docs/architecture/07_deployment/07_02_database.md
Normal file
82
docs/architecture/07_deployment/07_02_database.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# Database Deployment
|
||||
|
||||
## Migrations & Baseline
|
||||
|
||||
A consolidated baseline migration (`scripts/migrations/000_base.sql`) captures all schema changes required for a fresh installation. The script is idempotent: it creates the `currency` and `measurement_unit` reference tables, provisions the `application_setting` store for configurable UI/system options, ensures consumption and production records expose unit metadata, and enforces the foreign keys used by CAPEX and OPEX.
|
||||
|
||||
Configure granular database settings in your PowerShell session before running migrations:
|
||||
|
||||
```powershell
|
||||
$env:DATABASE_DRIVER = 'postgresql'
|
||||
$env:DATABASE_HOST = 'localhost'
|
||||
$env:DATABASE_PORT = '5432'
|
||||
$env:DATABASE_USER = 'calminer'
|
||||
$env:DATABASE_PASSWORD = 's3cret'
|
||||
$env:DATABASE_NAME = 'calminer'
|
||||
$env:DATABASE_SCHEMA = 'public'
|
||||
python scripts/setup_database.py --run-migrations --seed-data --dry-run
|
||||
python scripts/setup_database.py --run-migrations --seed-data
|
||||
```
|
||||
|
||||
The dry-run invocation reports which steps would execute without making changes. The live run applies the baseline (if not already recorded in `schema_migrations`) and seeds the reference data relied upon by the UI and API.
|
||||
|
||||
> ℹ️ When `--seed-data` is supplied without `--run-migrations`, the bootstrap script automatically applies any pending SQL migrations first so the `application_setting` table (and future settings-backed features) are present before seeding.
|
||||
>
|
||||
> ℹ️ The application still accepts `DATABASE_URL` as a fallback if the granular variables are not set.
|
||||
|
||||
## Database bootstrap workflow
|
||||
|
||||
Provision or refresh a database instance with `scripts/setup_database.py`. Populate the required environment variables (an example lives at `config/setup_test.env.example`) and run:
|
||||
|
||||
```powershell
|
||||
# Load test credentials (PowerShell)
|
||||
Get-Content .\config\setup_test.env.example |
|
||||
ForEach-Object {
|
||||
if ($_ -and -not $_.StartsWith('#')) {
|
||||
$name, $value = $_ -split '=', 2
|
||||
Set-Item -Path Env:$name -Value $value
|
||||
}
|
||||
}
|
||||
|
||||
# Dry-run to inspect the planned actions
|
||||
python scripts/setup_database.py --ensure-database --ensure-role --ensure-schema --initialize-schema --run-migrations --seed-data --dry-run -v
|
||||
|
||||
# Execute the full workflow
|
||||
python scripts/setup_database.py --ensure-database --ensure-role --ensure-schema --initialize-schema --run-migrations --seed-data -v
|
||||
```
|
||||
|
||||
Typical log output confirms:
|
||||
|
||||
- Admin and application connections succeed for the supplied credentials.
|
||||
- Database and role creation are idempotent (`already present` when rerun).
|
||||
- SQLAlchemy metadata either reports missing tables or `All tables already exist`.
|
||||
- Migrations list pending files and finish with `Applied N migrations` (a new database reports `Applied 1 migrations` for `000_base.sql`).
|
||||
|
||||
After a successful run the target database contains all application tables plus `schema_migrations`, and that table records each applied migration file. New installations only record `000_base.sql`; upgraded environments retain historical entries alongside the baseline.
|
||||
|
||||
### Seeding reference data
|
||||
|
||||
`scripts/seed_data.py` provides targeted control over the baseline datasets when the full setup script is not required:
|
||||
|
||||
```powershell
|
||||
python scripts/seed_data.py --currencies --units --dry-run
|
||||
python scripts/seed_data.py --currencies --units
|
||||
```
|
||||
|
||||
The seeder upserts the canonical currency catalog (`USD`, `EUR`, `CLP`, `RMB`, `GBP`, `CAD`, `AUD`) using ASCII-safe symbols (`USD$`, `EUR`, etc.) and the measurement units referenced by the UI (`tonnes`, `kilograms`, `pounds`, `liters`, `cubic_meters`, `kilowatt_hours`). The setup script invokes the same seeder when `--seed-data` is provided and verifies the expected rows afterward, warning if any are missing or inactive.
|
||||
|
||||
### Rollback guidance
|
||||
|
||||
`scripts/setup_database.py` now tracks compensating actions when it creates the database or application role. If a later step fails, the script replays those rollback actions (dropping the newly created database or role and revoking grants) before exiting. Dry runs never register rollback steps and remain read-only.
|
||||
|
||||
If the script reports that some rollback steps could not complete—for example because a connection cannot be established—rerun the script with `--dry-run` to confirm the desired end state and then apply the outstanding cleanup manually:
|
||||
|
||||
```powershell
|
||||
python scripts/setup_database.py --ensure-database --ensure-role --dry-run -v
|
||||
|
||||
# Manual cleanup examples when automation cannot connect
|
||||
psql -d postgres -c "DROP DATABASE IF EXISTS calminer"
|
||||
psql -d postgres -c "DROP ROLE IF EXISTS calminer"
|
||||
```
|
||||
|
||||
After a failure and rollback, rerun the full setup once the environment issues are resolved.
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: "CalMiner Architecture Documentation"
|
||||
description: "arc42-based architecture documentation for the CalMiner project"
|
||||
title: 'CalMiner Architecture Documentation'
|
||||
description: 'arc42-based architecture documentation for the CalMiner project'
|
||||
---
|
||||
|
||||
# Architecture documentation (arc42 mapping)
|
||||
@@ -11,16 +11,32 @@ This folder mirrors the arc42 chapter structure (adapted to Markdown).
|
||||
|
||||
- [01 Introduction and Goals](01_introduction_and_goals.md)
|
||||
- [02 Architecture Constraints](02_architecture_constraints.md)
|
||||
- [02_01 Technical Constraints](02_constraints/02_01_technical_constraints.md)
|
||||
- [02_02 Organizational Constraints](02_constraints/02_02_organizational_constraints.md)
|
||||
- [02_03 Regulatory Constraints](02_constraints/02_03_regulatory_constraints.md)
|
||||
- [02_04 Environmental Constraints](02_constraints/02_04_environmental_constraints.md)
|
||||
- [02_05 Performance Constraints](02_constraints/02_05_performance_constraints.md)
|
||||
- [03 Context and Scope](03_context_and_scope.md)
|
||||
- [03_01 Architecture Scope](03_scope/03_01_architecture_scope.md)
|
||||
- [04 Solution Strategy](04_solution_strategy.md)
|
||||
- [04_01 Client-Server Architecture](04_strategy/04_01_client_server_architecture.md)
|
||||
- [04_02 Technology Choices](04_strategy/04_02_technology_choices.md)
|
||||
- [04_03 Trade-offs](04_strategy/04_03_trade_offs.md)
|
||||
- [04_04 Future Considerations](04_strategy/04_04_future_considerations.md)
|
||||
- [05 Building Block View](05_building_block_view.md)
|
||||
- [05_01 Architecture Overview](05_blocks/05_01_architecture_overview.md)
|
||||
- [05_02 Backend Components](05_blocks/05_02_backend_components.md)
|
||||
- [05_03 Frontend Components](05_blocks/05_03_frontend_components.md)
|
||||
- [05_03 Theming](05_blocks/05_03_theming.md)
|
||||
- [05_04 Middleware & Utilities](05_blocks/05_04_middleware_utilities.md)
|
||||
- [06 Runtime View](06_runtime_view.md)
|
||||
- [07 Deployment View](07_deployment_view.md)
|
||||
- [Testing & CI](07_deployment/07_01_testing_ci.md.md)
|
||||
- [07_01 Testing & CI](07_deployment/07_01_testing_ci.md.md)
|
||||
- [07_02 Database](07_deployment/07_02_database.md)
|
||||
- [08 Concepts](08_concepts.md)
|
||||
- [08_01 Security](08_concepts/08_01_security.md)
|
||||
- [08_02 Data Models](08_concepts/08_02_data_models.md)
|
||||
- [09 Architecture Decisions](09_architecture_decisions.md)
|
||||
- [10 Quality Requirements](10_quality_requirements.md)
|
||||
- [11 Technical Risks](11_technical_risks.md)
|
||||
- [12 Glossary](12_glossary.md)
|
||||
- [13 UI and Style](13_ui_and_style.md)
|
||||
- [15 Development Setup](15_development_setup.md)
|
||||
|
||||
@@ -1,50 +1,77 @@
|
||||
# 15 Development Setup Guide
|
||||
# Development Environment Setup
|
||||
|
||||
This document outlines the local development environment and steps to get the project running.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python (version 3.10+)
|
||||
- Python (version 3.11+)
|
||||
- PostgreSQL (version 13+)
|
||||
- Git
|
||||
- Docker and Docker Compose (optional, for containerized development)
|
||||
|
||||
## Clone and Project Setup
|
||||
|
||||
````powershell
|
||||
```powershell
|
||||
# Clone the repository
|
||||
git clone https://git.allucanget.biz/allucanget/calminer.git
|
||||
cd calminer
|
||||
```python
|
||||
```
|
||||
|
||||
## Virtual Environment
|
||||
## Development with Docker Compose (Recommended)
|
||||
|
||||
For a quick setup without installing PostgreSQL locally, use Docker Compose:
|
||||
|
||||
```powershell
|
||||
# Start services
|
||||
docker-compose up
|
||||
|
||||
# The app will be available at http://localhost:8000
|
||||
# Database is automatically set up
|
||||
```
|
||||
|
||||
To run in background:
|
||||
|
||||
```powershell
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
To stop:
|
||||
|
||||
```powershell
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
## Manual Development Setup
|
||||
|
||||
### Virtual Environment
|
||||
|
||||
```powershell
|
||||
# Create and activate a virtual environment
|
||||
python -m venv .venv
|
||||
.\.venv\Scripts\Activate.ps1
|
||||
```python
|
||||
```
|
||||
|
||||
## Install Dependencies
|
||||
### Install Dependencies
|
||||
|
||||
```powershell
|
||||
pip install -r requirements.txt
|
||||
```python
|
||||
```
|
||||
|
||||
## Database Setup
|
||||
### Database Setup
|
||||
|
||||
1. Create database user:
|
||||
|
||||
```sql
|
||||
CREATE USER calminer_user WITH PASSWORD 'your_password';
|
||||
````
|
||||
```
|
||||
|
||||
1. Create database:
|
||||
|
||||
````sql
|
||||
```sql
|
||||
CREATE DATABASE calminer;
|
||||
```python
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
### Environment Variables
|
||||
|
||||
1. Copy `.env.example` to `.env` at project root.
|
||||
1. Edit `.env` to set database connection details:
|
||||
@@ -57,21 +84,21 @@ DATABASE_USER=calminer_user
|
||||
DATABASE_PASSWORD=your_password
|
||||
DATABASE_NAME=calminer
|
||||
DATABASE_SCHEMA=public
|
||||
````
|
||||
```
|
||||
|
||||
1. The application uses `python-dotenv` to load these variables. A legacy `DATABASE_URL` value is still accepted if the granular keys are omitted.
|
||||
|
||||
## Running the Application
|
||||
### Running the Application
|
||||
|
||||
````powershell
|
||||
```powershell
|
||||
# Start the FastAPI server
|
||||
uvicorn main:app --reload
|
||||
```python
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
```powershell
|
||||
pytest
|
||||
````
|
||||
```
|
||||
|
||||
E2E tests use Playwright and a session-scoped `live_server` fixture that starts the app at `http://localhost:8001` for browser-driven tests.
|
||||
@@ -1,6 +1,6 @@
|
||||
# 13 — UI, templates and styling
|
||||
# UI, templates and styling
|
||||
|
||||
This chapter collects UI integration notes, reusable template components, styling audit points and per-page UI data/actions.
|
||||
This document outlines the UI structure, template components, CSS variable conventions, and per-page data/actions for the CalMiner application.
|
||||
|
||||
## Reusable Template Components
|
||||
|
||||
@@ -1,31 +0,0 @@
|
||||
# Setup Script Idempotency Audit (2025-10-25)
|
||||
|
||||
This note captures the current evaluation of idempotent behaviour for `scripts/setup_database.py` and outlines follow-up actions.
|
||||
|
||||
## Admin Tasks
|
||||
|
||||
- **ensure_database**: guarded by `SELECT 1 FROM pg_database`; re-runs safely. Failure mode: network issues or lack of privileges surface as psycopg2 errors without additional context.
|
||||
- **ensure_role**: checks `pg_roles`, creates role if missing, reapplies grants each time. Subsequent runs execute grants again but PostgreSQL tolerates repeated grants.
|
||||
- **ensure_schema**: uses `information_schema` guard and respects `--dry-run`; idempotent when schema is `public` or already present.
|
||||
|
||||
## Application Tasks
|
||||
|
||||
- **initialize_schema**: relies on SQLAlchemy `create_all(checkfirst=True)`; repeatable. Dry-run output remains descriptive.
|
||||
- **run_migrations**: new baseline workflow applies `000_base.sql` once and records legacy scripts as applied. Subsequent runs detect the baseline in `schema_migrations` and skip reapplication.
|
||||
|
||||
## Seeding
|
||||
|
||||
- `seed_baseline_data` seeds currencies and measurement units with upsert logic. Verification now raises on missing data, preventing silent failures.
|
||||
- Running `--seed-data` repeatedly performs `ON CONFLICT` updates, making the operation safe.
|
||||
|
||||
## Outstanding Risks
|
||||
|
||||
1. Baseline migration relies on legacy files being present when first executed; if removed beforehand, old entries are never marked. (Low risk given repository state.)
|
||||
2. `ensure_database` and `ensure_role` do not wrap SQL execution errors with additional context beyond psycopg2 messages.
|
||||
3. Baseline verification assumes migrations and seeding run in the same process; manual runs of `scripts/seed_data.py` without the baseline could still fail.
|
||||
|
||||
## Recommended Actions
|
||||
|
||||
- Add regression tests ensuring repeated executions of key CLI paths (`--run-migrations`, `--seed-data`) result in no-op behaviour after the first run.
|
||||
- Extend logging/error handling for admin operations to provide clearer messages on repeated failures.
|
||||
- Consider a preflight check when migrations directory lacks legacy files but baseline is pending, warning about potential drift.
|
||||
@@ -1,29 +0,0 @@
|
||||
# Setup Script Logging Audit (2025-10-25)
|
||||
|
||||
The following observations capture current logging behaviour in `scripts/setup_database.py` and highlight areas requiring improved error handling and messaging.
|
||||
|
||||
## Connection Validation
|
||||
|
||||
- `validate_admin_connection` and `validate_application_connection` log entry/exit messages and raise `RuntimeError` with context if connection fails. This coverage is sufficient.
|
||||
- `ensure_database` logs creation states but does not surface connection or SQL exceptions beyond the initial connection acquisition. When the inner `cursor.execute` calls fail, the exceptions bubble without contextual logging.
|
||||
|
||||
## Migration Runner
|
||||
|
||||
- Lists pending migrations and logs each application attempt.
|
||||
- When the baseline is pending, the script logs whether it is a dry-run or live application and records legacy file marking. However, if `_apply_migration_file` raises an exception, the caller re-raises after logging the failure; there is no wrapping message guiding users toward manual cleanup.
|
||||
- Legacy migration marking happens silently (just info logs). Failures during the insert into `schema_migrations` would currently propagate without added guidance.
|
||||
|
||||
## Seeding Workflow
|
||||
|
||||
- `seed_baseline_data` announces each seeding phase and skips verification in dry-run mode with a log breadcrumb.
|
||||
- `_verify_seeded_data` warns about missing currencies/units and inactive defaults but does **not** raise errors, meaning CI can pass while the database is incomplete. There is no explicit log when verification succeeds.
|
||||
- `_seed_units` logs when the `measurement_unit` table is missing, which is helpful, but the warning is the only feedback; no exception is raised.
|
||||
|
||||
## Suggested Enhancements
|
||||
|
||||
1. Wrap baseline application and legacy marking in `try/except` blocks that log actionable remediation steps before re-raising.
|
||||
2. Promote seed verification failures (missing or inactive records) to exceptions so automated workflows fail fast; add success logs for clarity.
|
||||
3. Add contextual logging around currency/measurement-unit insert failures, particularly around `execute_values` calls, to aid debugging malformed data.
|
||||
4. Introduce structured logging (log codes or phases) for major steps (`CONNECT`, `MIGRATE`, `SEED`, `VERIFY`) to make scanning log files easier.
|
||||
|
||||
These findings inform the remaining TODO subtasks for enhanced error handling.
|
||||
@@ -1,348 +1,87 @@
|
||||
# Quickstart & Expanded Project Documentation
|
||||
# Developer Quickstart
|
||||
|
||||
This document contains the expanded development, usage, testing, and migration guidance moved out of the top-level README for brevity.
|
||||
- [Developer Quickstart](#developer-quickstart)
|
||||
- [Development](#development)
|
||||
- [User Interface](#user-interface)
|
||||
- [Testing](#testing)
|
||||
- [Staging](#staging)
|
||||
- [Deployment](#deployment)
|
||||
- [Using Docker Compose](#using-docker-compose)
|
||||
- [Manual Docker Deployment](#manual-docker-deployment)
|
||||
- [Database Deployment \& Migrations](#database-deployment--migrations)
|
||||
- [Usage Overview](#usage-overview)
|
||||
- [Theme configuration](#theme-configuration)
|
||||
- [Where to look next](#where-to-look-next)
|
||||
|
||||
This document provides a quickstart guide for developers to set up and run the CalMiner application locally.
|
||||
|
||||
## Development
|
||||
|
||||
### Prerequisites
|
||||
See [Development Setup](docs/developer/development_setup.md).
|
||||
|
||||
- Python 3.10+
|
||||
- Node.js 20+ (for Playwright-driven E2E tests)
|
||||
- Docker (optional, required for containerized workflows)
|
||||
- Git
|
||||
### User Interface
|
||||
|
||||
To get started locally:
|
||||
There is a dedicated [UI and Style](docs/developer/ui_and_style.md) guide for frontend contributors.
|
||||
|
||||
```powershell
|
||||
# Clone the repository
|
||||
git clone https://git.allucanget.biz/allucanget/calminer.git
|
||||
cd calminer
|
||||
### Testing
|
||||
|
||||
# Create and activate a virtual environment
|
||||
python -m venv .venv
|
||||
.\.venv\Scripts\Activate.ps1
|
||||
Testing is described in the [Testing CI](docs/architecture/07_deployment/07_01_testing_ci.md) document.
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
## Staging
|
||||
|
||||
# Start the development server
|
||||
uvicorn main:app --reload
|
||||
Staging environment setup is covered in [Staging Environment Setup](docs/developer/staging_environment_setup.md).
|
||||
|
||||
## Deployment
|
||||
|
||||
The application can be deployed using Docker containers.
|
||||
|
||||
### Using Docker Compose
|
||||
|
||||
For production deployment, use the provided `docker-compose.yml`:
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## Docker-based setup
|
||||
This starts the FastAPI app and PostgreSQL database.
|
||||
|
||||
To build and run the application using Docker instead of a local Python environment:
|
||||
### Manual Docker Deployment
|
||||
|
||||
```powershell
|
||||
# Build the application image (multi-stage build keeps runtime small)
|
||||
docker build -t calminer:latest .
|
||||
Build and run the container manually:
|
||||
|
||||
# Start the container on port 8000
|
||||
docker run --rm -p 8000:8000 calminer:latest
|
||||
|
||||
# Supply environment variables (e.g., Postgres connection)
|
||||
docker run --rm -p 8000:8000 ^
|
||||
-e DATABASE_DRIVER="postgresql" ^
|
||||
-e DATABASE_HOST="db.host" ^
|
||||
-e DATABASE_PORT="5432" ^
|
||||
-e DATABASE_USER="calminer" ^
|
||||
-e DATABASE_PASSWORD="s3cret" ^
|
||||
-e DATABASE_NAME="calminer" ^
|
||||
-e DATABASE_SCHEMA="public" ^
|
||||
calminer:latest
|
||||
```bash
|
||||
docker build -t calminer .
|
||||
docker run -d -p 8000:8000 \
|
||||
-e DATABASE_HOST=your-postgres-host \
|
||||
-e DATABASE_USER=calminer \
|
||||
-e DATABASE_PASSWORD=your-password \
|
||||
-e DATABASE_NAME=calminer_db \
|
||||
calminer
|
||||
```
|
||||
|
||||
If you maintain a Postgres or Redis dependency locally, consider authoring a `docker compose` stack that pairs them with the app container. The Docker image expects the database to be reachable and migrations executed before serving traffic.
|
||||
Ensure the database is set up and migrated before running.
|
||||
|
||||
### Compose-driven development stack
|
||||
### Database Deployment & Migrations
|
||||
|
||||
The repository ships with `docker-compose.dev.yml`, wiring the API and database into a single development stack. It defaults to the Debian-based `postgres:16` image so UTF-8 locales are available without additional tooling and mounts persistent data in the `pg_data_dev` volume.
|
||||
|
||||
Typical workflow (run from the repository root):
|
||||
|
||||
```powershell
|
||||
# Build images and ensure dependencies are cached
|
||||
docker compose -f docker-compose.dev.yml build
|
||||
|
||||
# Start FastAPI and Postgres in the background
|
||||
docker compose -f docker-compose.dev.yml up -d
|
||||
|
||||
# Tail logs for both services
|
||||
docker compose -f docker-compose.dev.yml logs -f
|
||||
|
||||
# Stop services but keep the database volume for reuse
|
||||
docker compose -f docker-compose.dev.yml down
|
||||
|
||||
# Remove the persistent Postgres volume when you need a clean slate
|
||||
docker volume rm calminer_pg_data_dev # optional; confirm exact name with `docker volume ls`
|
||||
```
|
||||
|
||||
Environment variables used by the containers live directly in the compose file (`DATABASE_HOST=db`, `DATABASE_NAME=calminer_dev`, etc.), so no extra `.env` file is required. Adjust or override them via `docker compose ... -e VAR=value` if necessary.
|
||||
|
||||
For a deeper walkthrough (including volume naming conventions, port mappings, and how the stack fits into the broader architecture), cross-check `docs/architecture/15_development_setup.md`. That chapter mirrors the compose defaults captured here so both documents stay in sync.
|
||||
|
||||
### Compose-driven test stack
|
||||
|
||||
Use `docker-compose.test.yml` to spin up a Postgres 16 container and execute the Python test suite in a disposable worker container:
|
||||
|
||||
```powershell
|
||||
# Build images used by the test workflow
|
||||
docker compose -f docker-compose.test.yml build
|
||||
|
||||
# Run the default target (unit tests)
|
||||
docker compose -f docker-compose.test.yml run --rm tests
|
||||
|
||||
# Run a specific target (e.g., full suite)
|
||||
docker compose -f docker-compose.test.yml run --rm -e PYTEST_TARGET=tests tests
|
||||
|
||||
# Tear everything down and drop the test database volume
|
||||
docker compose -f docker-compose.test.yml down -v
|
||||
```
|
||||
|
||||
The `tests` service prepares the database via `scripts/setup_database.py` before invoking pytest, ensuring migrations and seed data mirror CI behaviour. Named volumes (`pip_cache_test`, `pg_data_test`) cache dependencies and data between runs; remove them with `down -v` whenever you want a pristine environment. An `api` service is available on `http://localhost:8001` for spot-checking API responses against the same test database.
|
||||
|
||||
### Compose-driven production stack
|
||||
|
||||
Use `docker-compose.prod.yml` for operator-managed deployments. The file defines:
|
||||
|
||||
- `api`: FastAPI container with configurable CPU/memory limits and a `/health` probe.
|
||||
- `traefik`: Optional (enable with the `reverse-proxy` profile) to terminate TLS and route traffic based on `CALMINER_DOMAIN`.
|
||||
- `postgres`: Optional (enable with the `local-db` profile) when a managed database is unavailable; persists data in `pg_data_prod` and mounts `./backups`.
|
||||
|
||||
Commands (run from the repository root):
|
||||
|
||||
```powershell
|
||||
# Prepare environment variables once per environment
|
||||
copy config\setup_production.env.example config\setup_production.env
|
||||
|
||||
# Start API behind Traefik
|
||||
docker compose ^
|
||||
--env-file config/setup_production.env ^
|
||||
-f docker-compose.prod.yml ^
|
||||
--profile reverse-proxy ^
|
||||
up -d
|
||||
|
||||
# Add the local Postgres profile when running without managed DB
|
||||
docker compose ^
|
||||
--env-file config/setup_production.env ^
|
||||
-f docker-compose.prod.yml ^
|
||||
--profile reverse-proxy --profile local-db ^
|
||||
up -d
|
||||
|
||||
# Apply migrations/seed data
|
||||
docker compose ^
|
||||
--env-file config/setup_production.env ^
|
||||
-f docker-compose.prod.yml ^
|
||||
run --rm api ^
|
||||
python scripts/setup_database.py --run-migrations --seed-data
|
||||
|
||||
# Check health (FastAPI exposes /health)
|
||||
docker compose -f docker-compose.prod.yml ps
|
||||
|
||||
# Stop services (volumes persist unless -v is supplied)
|
||||
docker compose -f docker-compose.prod.yml down
|
||||
```
|
||||
|
||||
Key environment variables (documented in `config/setup_production.env.example`): container image tag, domain/ACME email, published ports, network name, and resource limits (`API_LIMIT_CPUS`, `API_LIMIT_MEMORY`, etc.).
|
||||
|
||||
For deployment topology diagrams and operational sequencing, see [docs/architecture/07_deployment_view.md](architecture/07_deployment_view.md#production-docker-compose-topology).
|
||||
See the [Database Deployment & Migrations](docs/architecture/07_deployment/07_02_database_deployment_migrations.md) document for details on database deployment and migration strategies.
|
||||
|
||||
## Usage Overview
|
||||
|
||||
- **Run the application**: Follow the [Development Setup](docs/developer/development_setup.md) to get the application running locally.
|
||||
- **Access the UI**: Open your web browser and navigate to `http://localhost:8000/ui` to access the user interface.
|
||||
- **API base URL**: `http://localhost:8000/api`
|
||||
- Key routes include creating scenarios, parameters, costs, consumption, production, equipment, maintenance, and reporting summaries. See the `routes/` directory for full details.
|
||||
- Key routes include creating scenarios, parameters, costs, consumption, production, equipment, maintenance, and reporting summaries. See the `routes/` directory for full details.
|
||||
- **UI base URL**: `http://localhost:8000/ui`
|
||||
|
||||
### Theme configuration
|
||||
|
||||
- Open `/ui/settings` to access the Settings dashboard. The **Theme Colors** form lists every CSS variable persisted in the `application_setting` table. Updates apply immediately across the UI once saved.
|
||||
- Use the accompanying API endpoints for automation or integration tests:
|
||||
- `GET /api/settings/css` returns the active variables, defaults, and metadata describing any environment overrides.
|
||||
- `PUT /api/settings/css` accepts a payload such as `{"variables": {"--color-primary": "#112233"}}` and persists the change unless an environment override is in place.
|
||||
- Environment variables prefixed with `CALMINER_THEME_` win over database values. For example, setting `CALMINER_THEME_COLOR_PRIMARY="#112233"` renders the corresponding input read-only and surfaces the override in the Environment Overrides table.
|
||||
- Acceptable values include hex (`#rrggbb` or `#rrggbbaa`), `rgb()/rgba()`, and `hsl()/hsla()` expressions with the expected number of components. Invalid inputs trigger a validation error and the API responds with HTTP 422.
|
||||
|
||||
## Dashboard Preview
|
||||
|
||||
1. Start the FastAPI server and navigate to `/`.
|
||||
2. Review the headline metrics, scenario snapshot table, and cost/activity charts sourced from the current database state.
|
||||
3. Use the "Refresh Dashboard" button to pull freshly aggregated data via `/ui/dashboard/data` without reloading the page.
|
||||
|
||||
## Testing
|
||||
|
||||
Run the unit test suite:
|
||||
|
||||
```powershell
|
||||
pytest
|
||||
```
|
||||
|
||||
E2E tests use Playwright and a session-scoped `live_server` fixture that starts the app at `http://localhost:8001` for browser-driven tests.
|
||||
|
||||
## Migrations & Baseline
|
||||
|
||||
A consolidated baseline migration (`scripts/migrations/000_base.sql`) captures all schema changes required for a fresh installation. The script is idempotent: it creates the `currency` and `measurement_unit` reference tables, provisions the `application_setting` store for configurable UI/system options, ensures consumption and production records expose unit metadata, and enforces the foreign keys used by CAPEX and OPEX.
|
||||
|
||||
Configure granular database settings in your PowerShell session before running migrations:
|
||||
|
||||
```powershell
|
||||
$env:DATABASE_DRIVER = 'postgresql'
|
||||
$env:DATABASE_HOST = 'localhost'
|
||||
$env:DATABASE_PORT = '5432'
|
||||
$env:DATABASE_USER = 'calminer'
|
||||
$env:DATABASE_PASSWORD = 's3cret'
|
||||
$env:DATABASE_NAME = 'calminer'
|
||||
$env:DATABASE_SCHEMA = 'public'
|
||||
python scripts/setup_database.py --run-migrations --seed-data --dry-run
|
||||
python scripts/setup_database.py --run-migrations --seed-data
|
||||
```
|
||||
|
||||
The dry-run invocation reports which steps would execute without making changes. The live run applies the baseline (if not already recorded in `schema_migrations`) and seeds the reference data relied upon by the UI and API.
|
||||
|
||||
> ℹ️ When `--seed-data` is supplied without `--run-migrations`, the bootstrap script automatically applies any pending SQL migrations first so the `application_setting` table (and future settings-backed features) are present before seeding.
|
||||
>
|
||||
> ℹ️ The application still accepts `DATABASE_URL` as a fallback if the granular variables are not set.
|
||||
|
||||
## Database bootstrap workflow
|
||||
|
||||
Provision or refresh a database instance with `scripts/setup_database.py`. Populate the required environment variables (an example lives at `config/setup_test.env.example`) and run:
|
||||
|
||||
```powershell
|
||||
# Load test credentials (PowerShell)
|
||||
Get-Content .\config\setup_test.env.example |
|
||||
ForEach-Object {
|
||||
if ($_ -and -not $_.StartsWith('#')) {
|
||||
$name, $value = $_ -split '=', 2
|
||||
Set-Item -Path Env:$name -Value $value
|
||||
}
|
||||
}
|
||||
|
||||
# Dry-run to inspect the planned actions
|
||||
python scripts/setup_database.py --ensure-database --ensure-role --ensure-schema --initialize-schema --run-migrations --seed-data --dry-run -v
|
||||
|
||||
# Execute the full workflow
|
||||
python scripts/setup_database.py --ensure-database --ensure-role --ensure-schema --initialize-schema --run-migrations --seed-data -v
|
||||
```
|
||||
|
||||
Typical log output confirms:
|
||||
|
||||
- Admin and application connections succeed for the supplied credentials.
|
||||
- Database and role creation are idempotent (`already present` when rerun).
|
||||
- SQLAlchemy metadata either reports missing tables or `All tables already exist`.
|
||||
- Migrations list pending files and finish with `Applied N migrations` (a new database reports `Applied 1 migrations` for `000_base.sql`).
|
||||
|
||||
After a successful run the target database contains all application tables plus `schema_migrations`, and that table records each applied migration file. New installations only record `000_base.sql`; upgraded environments retain historical entries alongside the baseline.
|
||||
|
||||
### Local Postgres via Docker Compose
|
||||
|
||||
For local validation without installing Postgres directly, use the provided compose file:
|
||||
|
||||
```powershell
|
||||
docker compose -f docker-compose.postgres.yml up -d
|
||||
```
|
||||
|
||||
#### Summary
|
||||
|
||||
1. Start the Postgres container with `docker compose -f docker-compose.postgres.yml up -d`.
|
||||
2. Export the granular database environment variables (host `127.0.0.1`, port `5433`, database `calminer_local`, user/password `calminer`/`secret`).
|
||||
3. Run the setup script twice: first with `--dry-run` to preview actions, then without it to apply changes.
|
||||
4. When finished, stop and optionally remove the container/volume using `docker compose -f docker-compose.postgres.yml down`.
|
||||
|
||||
The service exposes Postgres 16 on `localhost:5433` with database `calminer_local` and role `calminer`/`secret`. When the container is running, set the granular environment variables before invoking the setup script:
|
||||
|
||||
```powershell
|
||||
$env:DATABASE_DRIVER = 'postgresql'
|
||||
$env:DATABASE_HOST = '127.0.0.1'
|
||||
$env:DATABASE_PORT = '5433'
|
||||
$env:DATABASE_USER = 'calminer'
|
||||
$env:DATABASE_PASSWORD = 'secret'
|
||||
$env:DATABASE_NAME = 'calminer_local'
|
||||
$env:DATABASE_SCHEMA = 'public'
|
||||
|
||||
python scripts/setup_database.py --ensure-database --ensure-role --ensure-schema --initialize-schema --run-migrations --seed-data --dry-run -v
|
||||
python scripts/setup_database.py --ensure-database --ensure-role --ensure-schema --initialize-schema --run-migrations --seed-data -v
|
||||
```
|
||||
|
||||
When testing is complete, shut down the container (and optional persistent volume) with:
|
||||
|
||||
```powershell
|
||||
docker compose -f docker-compose.postgres.yml down
|
||||
docker volume rm calminer_postgres_local_postgres_data # optional cleanup
|
||||
```
|
||||
|
||||
### Seeding reference data
|
||||
|
||||
`scripts/seed_data.py` provides targeted control over the baseline datasets when the full setup script is not required:
|
||||
|
||||
```powershell
|
||||
python scripts/seed_data.py --currencies --units --dry-run
|
||||
python scripts/seed_data.py --currencies --units
|
||||
```
|
||||
|
||||
The seeder upserts the canonical currency catalog (`USD`, `EUR`, `CLP`, `RMB`, `GBP`, `CAD`, `AUD`) using ASCII-safe symbols (`USD$`, `EUR`, etc.) and the measurement units referenced by the UI (`tonnes`, `kilograms`, `pounds`, `liters`, `cubic_meters`, `kilowatt_hours`). The setup script invokes the same seeder when `--seed-data` is provided and verifies the expected rows afterward, warning if any are missing or inactive.
|
||||
|
||||
### Rollback guidance
|
||||
|
||||
`scripts/setup_database.py` now tracks compensating actions when it creates the database or application role. If a later step fails, the script replays those rollback actions (dropping the newly created database or role and revoking grants) before exiting. Dry runs never register rollback steps and remain read-only.
|
||||
|
||||
If the script reports that some rollback steps could not complete—for example because a connection cannot be established—rerun the script with `--dry-run` to confirm the desired end state and then apply the outstanding cleanup manually:
|
||||
|
||||
```powershell
|
||||
python scripts/setup_database.py --ensure-database --ensure-role --dry-run -v
|
||||
|
||||
# Manual cleanup examples when automation cannot connect
|
||||
psql -d postgres -c "DROP DATABASE IF EXISTS calminer"
|
||||
psql -d postgres -c "DROP ROLE IF EXISTS calminer"
|
||||
```
|
||||
|
||||
After a failure and rollback, rerun the full setup once the environment issues are resolved.
|
||||
|
||||
### CI pipeline environment
|
||||
|
||||
The `.gitea/workflows/test.yml` job spins up a temporary PostgreSQL 16 container and runs the setup script twice: once with `--dry-run` to validate the plan and again without it to apply migrations and seeds. No external secrets are required; the workflow sets the following environment variables for both invocations and for pytest:
|
||||
|
||||
| Variable | Value | Purpose |
|
||||
| ----------------------------- | ------------- | ------------------------------------------------- |
|
||||
| `DATABASE_DRIVER` | `postgresql` | Signals the driver to the setup script |
|
||||
| `DATABASE_HOST` | `postgres` | Hostname of the Postgres job service container |
|
||||
| `DATABASE_PORT` | `5432` | Default service port |
|
||||
| `DATABASE_NAME` | `calminer_ci` | Target database created by the workflow |
|
||||
| `DATABASE_USER` | `calminer` | Application role used during tests |
|
||||
| `DATABASE_PASSWORD` | `secret` | Password for both admin and app role |
|
||||
| `DATABASE_SCHEMA` | `public` | Default schema for the tests |
|
||||
| `DATABASE_SUPERUSER` | `calminer` | Setup script uses the same role for admin actions |
|
||||
| `DATABASE_SUPERUSER_PASSWORD` | `secret` | Matches the Postgres service password |
|
||||
| `DATABASE_SUPERUSER_DB` | `calminer_ci` | Database to connect to for admin operations |
|
||||
|
||||
The workflow also updates `DATABASE_URL` for pytest to point at the CI Postgres instance. Existing tests continue to work unchanged, since SQLAlchemy reads the URL exactly as it does locally.
|
||||
|
||||
Because the workflow provisions everything inline, no repository or organization secrets need to be configured for basic CI runs. If you later move the setup step to staging or production pipelines, replace these inline values with secrets managed by the CI platform. When running on self-hosted runners behind an HTTP proxy or apt cache, ensure Playwright dependencies and OS packages inherit the same proxy settings that the workflow configures prior to installing browsers.
|
||||
|
||||
### Staging environment workflow
|
||||
|
||||
Use the staging checklist in `docs/staging_environment_setup.md` when running the setup script against the shared environment. A sample variable file (`config/setup_staging.env`) records the expected inputs (host, port, admin/application roles); copy it outside the repository or load the values securely via your shell before executing the workflow.
|
||||
|
||||
Recommended execution order:
|
||||
|
||||
1. Dry run with `--dry-run -v` to confirm connectivity and review planned operations. Capture the output to `reports/setup_staging_dry_run.log` (or similar) for auditing.
|
||||
2. Execute the live run with the same flags minus `--dry-run` to provision the database, role grants, migrations, and seed data. Save the log as `reports/setup_staging_apply.log`.
|
||||
3. Repeat the dry run to verify idempotency and record the result (for example `reports/setup_staging_post_apply.log`).
|
||||
|
||||
## Database Objects
|
||||
|
||||
The database contains tables such as `capex`, `opex`, `chemical_consumption`, `fuel_consumption`, `water_consumption`, `scrap_consumption`, `production_output`, `equipment_operation`, `ore_batch`, `exchange_rate`, and `simulation_result`.
|
||||
|
||||
## Current implementation status (2025-10-21)
|
||||
|
||||
- Currency normalization: a `currency` table and backfill scripts exist; routes accept `currency_id` and `currency_code` for compatibility.
|
||||
- Simulation engine: scaffolding in `services/simulation.py` and `/api/simulations/run` return in-memory results; persistence to `models/simulation_result` is planned.
|
||||
- Reporting: `services/reporting.py` provides summary statistics used by `POST /api/reporting/summary`.
|
||||
- Tests & coverage: unit and E2E suites exist; recent local coverage is >90%.
|
||||
- Remaining work: authentication, persist simulation runs, CI/CD and containerization.
|
||||
Theming is laid out in [Theming](docs/architecture/05_03_theming.md).
|
||||
|
||||
## Where to look next
|
||||
|
||||
- Architecture overview & chapters: [architecture](architecture/README.md) (per-chapter files under `docs/architecture/`)
|
||||
- [Testing & CI](architecture/07_deployment/07_01_testing_ci.md.md)
|
||||
- [Development setup](architecture/15_development_setup.md)
|
||||
- [Development setup](developer/development_setup.md)
|
||||
- Implementation plan & roadmap: [Solution strategy](architecture/04_solution_strategy.md)
|
||||
- Routes: [routes](../routes/)
|
||||
- Services: [services](../services/)
|
||||
|
||||
37
docs/roadmap.md
Normal file
37
docs/roadmap.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# Roadmap
|
||||
|
||||
## Overview
|
||||
|
||||
## Scenario Enhancements
|
||||
|
||||
For each scenario, the goal is to evaluate financial viability, operational efficiency, and risk factors associated with the mining project. This data is used to perform calculations, generate reports, and visualize results through charts and dashboards, enabling users to make informed decisions based on comprehensive analysis.
|
||||
|
||||
### Scenario & Data Management
|
||||
|
||||
Scenarios are the core organizational unit within CalMiner, allowing users to create, manage, and analyze different mining project configurations. Each scenario encapsulates a unique set of parameters and data inputs that define the mining operation being modeled.
|
||||
|
||||
#### Scenario Creation
|
||||
|
||||
Users can create new scenarios by providing a unique name and description. The system will generate a new scenario with default parameters, which can be customized later.
|
||||
|
||||
#### Scenario Management
|
||||
|
||||
Users can manage existing scenarios by modifying their parameters, adding new data inputs, or deleting them as needed.
|
||||
|
||||
#### Data Inputs
|
||||
|
||||
Users can define and manage various data inputs for each scenario, including:
|
||||
|
||||
- **Geological Data**: Input data related to the geological characteristics of the mining site.
|
||||
- **Operational Parameters**: Define parameters such as mining methods, equipment specifications, and workforce details.
|
||||
- **Financial Data**: Input cost structures, revenue models, and financial assumptions.
|
||||
- **Environmental Data**: Include data related to environmental impact, regulations, and sustainability practices.
|
||||
- **Technical Data**: Specify technical parameters such as ore grades, recovery rates, and processing methods.
|
||||
- **Social Data**: Incorporate social impact assessments, community engagement plans, and stakeholder analysis.
|
||||
- **Regulatory Data**: Include data related to legal and regulatory requirements, permits, and compliance measures.
|
||||
- **Market Data**: Input market conditions, commodity prices, and economic indicators that may affect the mining operation.
|
||||
- **Risk Data**: Define risk factors, probabilities, and mitigation strategies for the mining project.
|
||||
- **Logistical Data**: Include data related to transportation, supply chain management, and infrastructure requirements.
|
||||
- **Maintenance Data**: Input maintenance schedules, costs, and equipment reliability metrics.
|
||||
- **Human Resources Data**: Define workforce requirements, training programs, and labor costs.
|
||||
- **Health and Safety Data**: Include data related to workplace safety protocols, incident rates, and health programs.
|
||||
@@ -1,78 +0,0 @@
|
||||
# Baseline Seed Data Plan
|
||||
|
||||
This document captures the datasets that should be present in a fresh CalMiner installation and the structure required to manage them through `scripts/seed_data.py`.
|
||||
|
||||
## Currency Catalog
|
||||
|
||||
The `currency` table already exists and is seeded today via `scripts/seed_data.py`. The goal is to keep the canonical list in one place and ensure the default currency (USD) is always active.
|
||||
|
||||
| Code | Name | Symbol | Notes |
|
||||
| ---- | ------------------- | ------ | ---------------------------------------- |
|
||||
| USD | US Dollar | $ | Default currency (`DEFAULT_CURRENCY_CODE`) |
|
||||
| EUR | Euro | EUR symbol | |
|
||||
| CLP | Chilean Peso | $ | |
|
||||
| RMB | Chinese Yuan | RMB symbol | |
|
||||
| GBP | British Pound | GBP symbol | |
|
||||
| CAD | Canadian Dollar | $ | |
|
||||
| AUD | Australian Dollar | $ | |
|
||||
|
||||
Seeding behaviour:
|
||||
|
||||
- Upsert by ISO code; keep existing name/symbol when updated manually.
|
||||
- Ensure `is_active` remains true for USD and defaults to true for new rows.
|
||||
- Defer to runtime validation in `routes.currencies` for enforcing default behaviour.
|
||||
|
||||
## Measurement Units
|
||||
|
||||
UI routes (`routes/ui.py`) currently rely on the in-memory `MEASUREMENT_UNITS` list to populate dropdowns for consumption and production forms. To make this configurable and available to the API, introduce a dedicated `measurement_unit` table and seed it.
|
||||
|
||||
Proposed schema:
|
||||
|
||||
| Column | Type | Notes |
|
||||
| ------------- | -------------- | ------------------------------------ |
|
||||
| id | SERIAL / BIGINT | Primary key. |
|
||||
| code | TEXT | Stable slug (e.g. `tonnes`). Unique. |
|
||||
| name | TEXT | Display label. |
|
||||
| symbol | TEXT | Short symbol (nullable). |
|
||||
| unit_type | TEXT | Category (`mass`, `volume`, `energy`).|
|
||||
| is_active | BOOLEAN | Default `true` for soft disabling. |
|
||||
| created_at | TIMESTAMP | Optional `NOW()` default. |
|
||||
| updated_at | TIMESTAMP | Optional `NOW()` trigger/default. |
|
||||
|
||||
Initial seed set (mirrors existing UI list plus type categorisation):
|
||||
|
||||
| Code | Name | Symbol | Unit Type |
|
||||
| --------------- | ---------------- | ------ | --------- |
|
||||
| tonnes | Tonnes | t | mass |
|
||||
| kilograms | Kilograms | kg | mass |
|
||||
| pounds | Pounds | lb | mass |
|
||||
| liters | Liters | L | volume |
|
||||
| cubic_meters | Cubic Meters | m3 | volume |
|
||||
| kilowatt_hours | Kilowatt Hours | kWh | energy |
|
||||
|
||||
Seeding behaviour:
|
||||
|
||||
- Upsert rows by `code`.
|
||||
- Preserve `unit_type` and `symbol` unless explicitly changed via administration tooling.
|
||||
- Continue surfacing unit options to the UI by querying this table instead of the static constant.
|
||||
|
||||
## Default Settings
|
||||
|
||||
The application expects certain defaults to exist:
|
||||
|
||||
- **Default currency**: enforced by `routes.currencies._ensure_default_currency`; ensure seeds keep USD active.
|
||||
- **Fallback measurement unit**: UI currently auto-selects the first option in the list. Once units move to the database, expose an application setting to choose a fallback (future work tracked under "Application Settings management").
|
||||
|
||||
## Seeding Structure Updates
|
||||
|
||||
To support the datasets above:
|
||||
|
||||
1. Extend `scripts/seed_data.py` with a `SeedDataset` registry so each dataset (currencies, units, future defaults) can declare its loader/upsert function and optional dependencies.
|
||||
2. Add a `--dataset` CLI selector for targeted seeding while keeping `--all` as the default for `setup_database.py` integrations.
|
||||
3. Update `scripts/setup_database.py` to:
|
||||
- Run migration ensuring `measurement_unit` table exists.
|
||||
- Execute the unit seeder after currencies when `--seed-data` is supplied.
|
||||
- Verify post-seed counts, logging which dataset was inserted/updated.
|
||||
4. Adjust UI routes to load measurement units from the database and remove the hard-coded list once the table is available.
|
||||
|
||||
This plan aligns with the TODO item for seeding initial data and lays the groundwork for consolidating migrations around a single baseline file that introduces both the schema and seed data in an idempotent manner.
|
||||
Reference in New Issue
Block a user