{{ site.title }}

{{ theme.darkModeSwitchLabel || 'Appearance' }}

Frontend Integration: Flow Meter Asset ID ​

Date: 2026-01-15
Related Migration: 20260115000000_add_asset_id_to_flow_meters.sql

Overview ​

This document describes the frontend changes made to use the new asset_id foreign key for flow meters, replacing the legacy string-based flow_meter identifier.

Changes Made ​

1. Type Definitions ​

File: src/features/flow-meter/types.ts

Updated type definitions to include assetId field:

typescript
export type FlowMeterRecord = {
  site: string;
  flowMeter: string; // Legacy field, use assetId instead
  assetId?: string;  // NEW: Foreign key to data_assets
  litresDispensed: number;
  dateTimeDispensed: Date;
  scrapedAt: Date;
};

export type FlowMeterAsset = {  // NEW TYPE
  assetId: string;
  displayId: string;
  description?: string;
};

export type DustLocRefill = {
  id?: number;
  site: string;
  flowMeter?: string; // Legacy field, use assetId instead
  assetId?: string;   // NEW: Foreign key to data_assets
  litresRefilled: number;
  // ... other fields
};

2. Database Service Updates ​

File: src/features/flow-meter/services/databaseService.ts

Added New Function ​

typescript
export async function fetchFlowMeterAssets()
  • Fetches flow meter assets from data_assets table
  • Filters for assets with asset_type_code containing "flow" or display_id containing "FM"
  • Returns active (non-archived) assets only
  • Orders by display_id

Updated Mapping Functions ​

  • mapFlowMeterRow: Now includes assetId field
  • mapDustLocRefillRow: Now includes assetId field

Updated CRUD Functions ​

  • insertRefill: Accepts asset_id parameter
  • updateRefill: Accepts asset_id parameter

3. Component Updates ​

File: src/features/flow-meter/components/AddRefillModal.tsx

Major changes:

  • Added useEffect hook to load flow meter assets when modal opens
  • Added assetId state and flowMeterAssets state
  • Updated flow meter selector to use asset dropdown
  • Smart Fallback: If no assets found for site, falls back to legacy string-based selector
  • Enhanced UI with asset descriptions
  • Validation updated to check for asset selection
  • Passes assetId to submission handler

User Experience:

  • When assets are available: Shows dropdown with "FM-01", "FM-02 - Description", etc.
  • When no assets found: Falls back to legacy string input (shows amber warning)
  • Loading state while fetching assets

File: src/app/(admin)/(pages)/refill-management/index.tsx

Updates:

  • handleAddRefill callback now accepts and passes assetId
  • Sends asset_id to insertRefill database function

Backward Compatibility ​

The implementation maintains full backward compatibility:

  1. Legacy Data: Old records with only flow_meter string continue to work
  2. Fallback UI: If no assets registered for a site, shows legacy string selector
  3. Database: Both flow_meter and asset_id columns exist, neither is required
  4. Mixed Data: System handles records with:
    • Only flow_meter (legacy records)
    • Only asset_id (new records)
    • Both fields (transitional records)

User Interface Changes ​

Add Refill Modal - Before ​

  • Simple text dropdown showing flow meter strings ("FM-01", "FM-02")
  • No connection to asset database
  • No asset metadata available

Add Refill Modal - After ​

  • Dropdown populated from data_assets table
  • Shows asset display ID + description
  • Filtered by selected mine site
  • Only shows active (non-archived) assets
  • Falls back to legacy mode if no assets found
  • Clear indicator when using legacy vs. asset mode

Benefits ​

  1. Data Integrity: Foreign key constraint prevents invalid references
  2. Rich Metadata: Access to operational status, descriptions, provider info
  3. Better UX: Users see descriptive names, not just IDs
  4. Unified Management: Flow meters managed in central asset system
  5. Future-Proof: Easy to add asset-based features (status checks, maintenance schedules)

Testing ​

Manual Testing Checklist ​

  • [x] TypeScript compilation passes
  • [x] Build succeeds without errors
  • [ ] Add refill modal opens successfully
  • [ ] Asset dropdown populates with flow meters
  • [ ] Can select asset and submit refill
  • [ ] Legacy fallback works when no assets available
  • [ ] Refill records save with asset_id
  • [ ] Existing refills still display correctly
  • [ ] Edit refill modal works (if updated)
  • [ ] Calibration management works (if updated)

Integration Testing ​

  1. New Refill with Asset:

    • Select site with registered flow meter assets
    • Should see asset dropdown
    • Submit refill → check database for asset_id

  2. New Refill without Assets:

    • Select site with NO registered assets
    • Should see legacy string dropdown
    • Submit refill → check database for flow_meter

  3. View Existing Refills:

    • Records with asset_id should display
    • Records with only flow_meter should display
    • Mixed records should display

Future Enhancements ​

  1. Update EditRefillModal:

    • Add asset selector similar to AddRefillModal
    • Allow editing asset assignment

  2. Calibration Management:

    • Update CalibrationModal to use asset selector
    • Already has assetId field in types

  3. Asset Status Integration:

    • Show operational status in dropdown (color-coded)
    • Filter out offline/error assets
    • Show last contact time

  4. Bulk Migration UI:

    • Admin tool to map legacy flow_meter strings to assets
    • Preview matches before applying
    • Handle unmapped records

  5. Reports Integration:

    • Join with data_assets for richer reports
    • Include asset metadata in exports
    • Show asset operational history

Phase 3 (Long-term) ​

  1. Deprecate Legacy Fields:

    • Once all records migrated, remove flow_meter columns
    • Update all queries to use asset_id only
    • Remove fallback UI logic

  2. Enhanced Asset Features:

    • Maintenance scheduling
    • Alert on offline assets
    • Usage analytics per asset
    • Asset lifecycle tracking

Migration Impact ​

Database ​

  • ✅ Migration applied successfully
  • ✅ 971/971 flow meter records mapped (100%)
  • ✅ 21/22 refill records mapped (95.5%)
  • ✅ Foreign keys created
  • ✅ Indexes added

Frontend ​

  • ✅ Types updated
  • ✅ Service functions updated
  • ✅ Components updated
  • ✅ Backward compatibility maintained
  • ✅ Build passes

Next Steps ​

  1. Deploy to staging environment
  2. Test with real users
  3. Monitor for issues
  4. Update EditRefillModal (similar changes)
  5. Update CalibrationModal (similar changes)
  6. Create admin migration UI for unmapped records

Rollback Plan ​

If issues arise:

  1. Frontend Rollback: Revert component changes, use legacy flow_meter only
  2. Database Rollback: See database migration doc
  3. Hybrid Mode: System can operate with mix of old and new records
  • Migration: supabase/migrations/20260115000000_add_asset_id_to_flow_meters.sql
  • Types: src/features/flow-meter/types.ts
  • Service: src/features/flow-meter/services/databaseService.ts
  • Component: src/features/flow-meter/components/AddRefillModal.tsx
  • Page: src/app/(admin)/(pages)/refill-management/index.tsx
  • Supabase Types: src/lib/supabaseTypes.ts