117 lines
4.3 KiB
Markdown
117 lines
4.3 KiB
Markdown
# Quickstart & Expanded Project Documentation
|
||
|
||
This document contains the expanded development, usage, testing, and migration guidance moved out of the top-level README for brevity.
|
||
|
||
## Development
|
||
|
||
To get started locally:
|
||
|
||
```powershell
|
||
# Clone the repository
|
||
git clone https://git.allucanget.biz/allucanget/calminer.git
|
||
cd calminer
|
||
|
||
# Create and activate a virtual environment
|
||
python -m venv .venv
|
||
.\.venv\Scripts\Activate.ps1
|
||
|
||
# Install dependencies
|
||
pip install -r requirements.txt
|
||
|
||
# Start the development server
|
||
uvicorn main:app --reload
|
||
```
|
||
|
||
## Docker-based setup
|
||
|
||
To build and run the application using Docker instead of a local Python environment:
|
||
|
||
```powershell
|
||
# Build the application image (multi-stage build keeps runtime small)
|
||
docker build -t calminer:latest .
|
||
|
||
# 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
|
||
```
|
||
|
||
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.
|
||
|
||
## Usage Overview
|
||
|
||
- **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.
|
||
|
||
## 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 & Currency Backfill
|
||
|
||
The project includes a referential `currency` table and migration/backfill tooling to normalize legacy currency fields.
|
||
|
||
### Run migrations and backfill (development)
|
||
|
||
Configure the 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/run_migrations.py
|
||
python scripts/backfill_currency.py --dry-run
|
||
python scripts/backfill_currency.py --create-missing
|
||
```
|
||
|
||
> ℹ️ The application still accepts `DATABASE_URL` as a fallback if the granular variables are not set.
|
||
|
||
Use `--dry-run` first to verify what will change.
|
||
|
||
## 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.
|
||
|
||
## Where to look next
|
||
|
||
- Architecture overview & chapters: [architecture](architecture/README.md) (per-chapter files under `docs/architecture/`)
|
||
- [Testing & CI](architecture/14_testing_ci.md)
|
||
- [Development setup](architecture/15_development_setup.md)
|
||
- Implementation plan & roadmap: [Solution strategy](architecture/04_solution_strategy.md)
|
||
- Routes: [routes](../routes/)
|
||
- Services: [services](../services/)
|
||
- Scripts: [scripts](../scripts/) (migrations and backfills)
|