Mine Commissioning System: Dynamic Minerals, Custom Parameters, and Admin Workflow

[vtz]

Summary

Implement a comprehensive mine commissioning system that allows administrators to onboard new mines through a structured multi-step workflow. This replaces the current simple mine creation with a full commissioning process that includes dynamic mineral management and configurable custom parameters per mine.

Key Features

1. Dynamic Mineral Catalog

• New minerals table replacing hardcoded SUPPORTED_METALS
• Admins can add/edit/remove minerals (e.g. Cu, Au, Li, Zn) without code changes
• Many-to-many mine_minerals table linking mines to their primary and byproduct minerals
• Admin UI at /admin/minerals

2. Custom Parameter Definitions

• New parameter_definitions table for reusable parameter templates (name, type, unit, category, validation rules)
• New mine_parameters table for per-mine parameter values
• Parameters grouped by category: recovery, commercial, operational, environmental
• Dynamic form generation based on parameter data types and validation rules

3. Mine Commissioning Workflow

• Mine status lifecycle: draft → active → suspended / decommissioned
• Multi-step commissioning wizard:
  1. Basic Info (name, region, mining method)
  2. Select Minerals (primary + byproducts)
  3. Custom Parameters (dynamic form by category)
  4. Assign Users (roles: admin/editor/viewer)
  5. Enable Features (Goal Seek, Block Model, etc.)
  6. Review & Commission
• Validation before commissioning (minerals, required params, users)
• Admin-only access

Technical Scope

Backend (FastAPI + SQLAlchemy)

• New models: Mineral, MineMineral, ParameterDefinition, MineParameter
• New columns on Mine: status, commissioned_at, commissioned_by
• New routers: /api/v1/minerals, /api/v1/parameters
• New endpoints: commission, decommission, suspend, activate
• Alembic migration 005_mine_commissioning.py with seed data

Frontend (Next.js + React)

• New admin page: /admin/minerals
• New commissioning wizard: /admin/mines/commission
• Updated mine list with status badges and filtering
• Updated sidebar with Minerals link
• Full i18n support (pt-BR, en, es)

Migration Strategy

• Backward-compatible: existing mines get active status
• Seed minerals table from current SUPPORTED_METALS constants
• Backfill mine_minerals from existing mines.primary_metal
• Keep primary_metal column for backward compatibility