turash/docs/api/resources.md

# Resources API

API endpoints for managing resource flows and exchanges.

## Resource Flow Object

```json
{
  "id": "uuid-string",
  "organization_id": "org-uuid",
  "site_id": "site-uuid",
  "resource_type": "waste_heat",
  "direction": "output",
  "name": "Boiler Waste Heat",
  "description": "Excess heat from industrial boiler system",
  "quantity": {
    "amount": 500.0,
    "unit": "kW",
    "precision_level": "measured"
  },
  "temporal_profile": {
    "pattern": "continuous",
    "availability_hours_per_week": 168,
    "peak_hours": ["06:00-22:00"],
    "seasonal_variation": "stable"
  },
  "quality": {
    "temperature_range": {
      "min_celsius": 70.0,
      "max_celsius": 90.0
    },
    "pressure_range": {
      "min_bar": 1.0,
      "max_bar": 3.0
    },
    "purity_pct": 95.0,
    "contamination_levels": {
      "heavy_metals_mg_kg": 50.0,
      "organic_compounds_mg_kg": 100.0
    },
    "ph_range": {
      "min": 6.0,
      "max": 8.0
    },
    "viscosity_cp": 1.0,
    "particle_size_microns": 10.0
  },
  "pricing": {
    "base_price_per_unit": 0.10,
    "currency": "EUR",
    "billing_cycle": "monthly",
    "volume_pricing_tiers": [
      {
        "min_volume": 0,
        "max_volume": 1000,
        "price_per_unit": 0.10,
        "discount_pct": 0
      },
      {
        "min_volume": 1000,
        "price_per_unit": 0.08,
        "discount_pct": 20
      }
    ]
  },
  "logistics": {
    "transportation_required": true,
    "preferred_methods": ["piping", "truck"],
    "maximum_transport_distance_km": 50.0,
    "storage_requirements": {
      "temperature_controlled": false,
      "special_containers": false,
      "shelf_life_days": 30
    }
  },
  "environmental_impact": {
    "carbon_footprint_kg_co2_eq": 0.5,
    "water_usage_liters": 2.0,
    "energy_consumption_kwh": 0.1,
    "waste_generation_kg": 0.05,
    "emissions_by_type": {
      "CO2": 0.4,
      "NOx": 0.01,
      "SO2": 0.005
    },
    "renewable_energy_pct": 0.0,
    "circularity_score": 0.8
  },
  "performance_metrics": {
    "average_efficiency_pct": 85.0,
    "peak_performance_value": 600.0,
    "degradation_rate_pct_year": 2.0,
    "maintenance_interval_days": 90,
    "expected_lifespan_years": 15.0,
    "reliability_score": 0.95
  },
  "reliability_history": [
    {
      "date": "2025-01-01",
      "uptime_pct": 98.5,
      "outages_count": 2,
      "total_downtime_hours": 8.5
    }
  ],
  "certifications": ["ISO9001", "ISO14001"],
  "regulatory_requirements": {
    "permits_required": ["waste_disposal_permit"],
    "compliance_standards": ["REACH", "RoHS"],
    "monitoring_requirements": ["temperature", "flow_rate"]
  },
  "source_type": "device",
  "data_source": "SCADA_system",
  "last_updated": "2025-01-15T10:30:00Z",
  "verification_status": "verified",
  "tags": ["industrial", "continuous", "high_temperature"],
  "metadata": {
    "equipment_id": "BLR-001",
    "process_type": "steam_generation",
    "installation_date": "2020-03-15"
  }
}
```

## Resource Types

| Type | Description | Typical Units |
|------|-------------|---------------|
| `waste_heat` | Thermal waste heat | kW, MW |
| `excess_electricity` | Surplus electrical power | kW, MWh |
| `industrial_waste` | Manufacturing byproducts | kg, tonnes |
| `water_waste` | Wastewater or process water | m³, liters |
| `byproducts` | Production byproducts | kg, m³ |
| `cooling_water` | Excess cooling capacity | kW, m³ |
| `compressed_air` | Surplus compressed air | m³/min, bar |
| `logistics` | Transportation capacity | tonne-km |
| `materials` | Recyclable materials | kg, tonnes |
| `service` | Service offerings | hours, units |

## Resource Directions

- `input`: Resource consumption (demand)
- `output`: Resource production (supply)

## Precision Levels

- `rough`: Estimated values (±50%)
- `estimated`: Calculated values (±25%)
- `measured`: Sensor/monitored values (±5%)

## Supply Patterns

- `continuous`: 24/7 availability
- `batch`: Periodic production
- `seasonal`: Seasonal availability
- `on_demand`: Available when requested
- `irregular`: Unpredictable availability

## Source Types

- `declared`: Self-reported by organization
- `device`: From IoT sensors/SCADA systems
- `calculated`: Derived from other data sources

## API Endpoints

### List Resources

```http
GET /api/v1/resources
```

**Query Parameters:**
- `organization_id` (string, optional): Filter by organization
- `site_id` (string, optional): Filter by site
- `resource_type` (string, optional): Filter by resource type
- `direction` (string, optional): Filter by direction (input/output)
- `limit` (int, optional): Maximum results (default: 50)

**Response:**
```json
{
  "data": [ResourceFlow],
  "pagination": {
    "total": 250,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}
```

### Get Resource by ID

```http
GET /api/v1/resources/{id}
```

**Response:** Single ResourceFlow object

### Get Resources by Site

```http
GET /api/v1/resources/site/{siteId}
```

**Response:** Array of ResourceFlow objects for the site

### Get Resources by Organization

```http
GET /api/v1/resources/organization/{organizationId}
```

**Response:** Array of ResourceFlow objects for the organization

### Create Resource Flow

```http
POST /api/v1/resources
```

**Request Body:** Complete ResourceFlow object

**Required Fields:**
- `organization_id`
- `resource_type`
- `direction`
- `quantity.amount`
- `quantity.unit`

**Response:** Created ResourceFlow object

### Update Resource Flow

```http
PUT /api/v1/resources/{id}
```

**Request Body:** Partial ResourceFlow object

**Response:** Updated ResourceFlow object

### Delete Resource Flow

```http
DELETE /api/v1/resources/{id}
```

**Response:**
```json
{
  "message": "Resource flow deleted successfully"
}
```

## Quantity Specifications

### Unit Standards

**Energy:**
- `W`, `kW`, `MW` (power)
- `Wh`, `kWh`, `MWh` (energy)

**Mass:**
- `g`, `kg`, `tonne`, `tonnes`

**Volume:**
- `ml`, `liter`, `liters`, `m³`, `m3`

**Flow Rates:**
- `m³/h`, `m³/day`, `kg/h`, `kg/day`

### Temporal Units

- `per_second`
- `per_minute`
- `per_hour`
- `per_day`
- `per_week`
- `per_month`
- `per_year`
- `continuous`

## Quality Parameters

### Temperature Resources
```json
{
  "temperature_range": {
    "min_celsius": 70.0,
    "max_celsius": 90.0
  },
  "pressure_range": {
    "min_bar": 1.0,
    "max_bar": 3.0
  }
}
```

### Material Resources
```json
{
  "purity_pct": 95.0,
  "contamination_levels": {
    "heavy_metals_mg_kg": 50.0,
    "organic_compounds_mg_kg": 100.0
  },
  "particle_size_microns": 10.0,
  "moisture_pct": 5.0
}
```

### Water Resources
```json
{
  "ph_range": {
    "min": 6.0,
    "max": 8.0
  },
  "conductivity_us_cm": 500.0,
  "turbidity_ntu": 2.0,
  "dissolved_oxygen_mg_l": 8.0
}
```

## Pricing Models

### Volume-Based Pricing
```json
{
  "volume_pricing_tiers": [
    {
      "min_volume": 0,
      "max_volume": 1000,
      "price_per_unit": 0.10,
      "discount_pct": 0
    },
    {
      "min_volume": 1000,
      "max_volume": 5000,
      "price_per_unit": 0.08,
      "discount_pct": 20
    },
    {
      "min_volume": 5000,
      "price_per_unit": 0.06,
      "discount_pct": 40
    }
  ]
}
```

### Time-Based Pricing
```json
{
  "time_based_pricing": {
    "peak_hours_rate": 0.15,
    "off_peak_hours_rate": 0.08,
    "seasonal_adjustments": {
      "winter_multiplier": 1.2,
      "summer_multiplier": 0.9
    }
  }
}
```

## Logistics Requirements

### Transportation Methods
- `piping`: Fixed infrastructure for fluids
- `truck`: Road transportation (flexible)
- `rail`: Rail transportation (bulk)
- `ship`: Water transportation
- `conveyor`: Mechanical transport systems

### Storage Requirements
```json
{
  "temperature_controlled": true,
  "special_containers": false,
  "hazard_class": "non_hazardous",
  "shelf_life_days": 30,
  "special_handling": ["flammable"]
}
```

## Environmental Impact Tracking

### Carbon Accounting
```json
{
  "carbon_footprint_kg_co2_eq": 0.5,
  "scope_classification": "Scope 1",
  "calculation_method": "IPCC Guidelines",
  "baseline_year": 2020,
  "reduction_potential_pct": 75.0
}
```

### Water Footprint
```json
{
  "water_usage_liters": 2.0,
  "water_stress_impact": "medium",
  "recycling_rate_pct": 60.0,
  "water_quality_impact": "neutral"
}
```

## Performance Monitoring

### Reliability Metrics
```json
{
  "uptime_pct": 98.5,
  "mean_time_between_failures_days": 45.0,
  "mean_time_to_repair_hours": 4.0,
  "availability_score": 0.985
}
```

### Efficiency Tracking
```json
{
  "energy_efficiency_ratio": 0.85,
  "resource_recovery_rate_pct": 92.0,
  "waste_reduction_pct": 75.0
}
```

## Regulatory Compliance

### Permit Requirements
```json
{
  "permits_required": [
    "waste_disposal_permit",
    "environmental_impact_assessment",
    "transport_permit"
  ],
  "permit_status": "active",
  "next_renewal_date": "2025-12-31"
}
```

### Standards Compliance
```json
{
  "compliance_standards": ["REACH", "RoHS", "ISO14001"],
  "certification_status": "certified",
  "last_audit_date": "2024-06-15",
  "next_audit_date": "2025-06-15"
}
```

## Data Validation Rules

### Quantity Validation
- Must be positive number
- Unit must be valid for resource type
- Precision level must match data source quality

### Quality Parameters
- Temperature ranges must be physically possible
- Purity percentages must be 0-100
- pH values must be 0-14

### Pricing Validation
- Prices must be non-negative
- Volume tiers must be sequential
- Currency codes must be valid ISO 4217

## Error Responses

### Validation Errors
```json
{
  "error": "Resource validation failed",
  "details": {
    "quantity.amount": "Amount must be positive",
    "quality.temperature_range": "Temperature range invalid"
  }
}
```

### Resource Not Found
```json
{
  "error": "Resource flow not found"
}
```

### Permission Denied
```json
{
  "error": "Insufficient permissions to modify resource"
}
```