Tank Manual Correction Feature Design

Date: 2026-02-04 Status: Approved Author: Claude (Brainstorming Session)

Overview

Since the Flow Meter data is not accurate enough, we need to add a manual correction feature. Users can estimate the tank scale line and record the actual remaining Dustloc. The system calculates the current tank remaining based on the correction value, subsequent Refill and Usage, and visualizes it with a cylinder.

Changes Summary

1. Rename existing feature - "Manage Calibration" → "Calibration Reminders"
2. Add Manage Corrections page - manage manual calibration/correction records
3. Add Tank Configuration page - configure the capacity (volume) of each tank
4. Add Tank status display to the Flow Meter main page - translate the cylindrical remaining-level visualization into English

---

Database Design

1. New Table: ops_tank_corrections

Manual corrections table

Column	Type	Description
id	uuid	Primary key
site	text	Site name
asset_id	text	Related flow meter asset
correction_datetime	timestamptz	Correction timestamp
remaining_litres	numeric	Remaining litres at correction time
corrected_by	text	Person who performed correction
evidence_url	text	Evidence photo URL
notes	text	Notes
mine_site_id	uuid	Related mine site (for RBAC)
created_by	uuid	Creator user ID
created_at	timestamptz	Created timestamp
updated_at	timestamptz	Updated timestamp

2. New Table: cfg_tank_capacities

Tank 容积配置表。

Column	Type	Description
id	uuid	Primary key
site	text	Site name
asset_id	text	Related flow meter asset
capacity_litres	numeric	Tank total capacity (litres)
mine_site_id	uuid	Related mine site
created_at	timestamptz	Created timestamp
updated_at	timestamptz	Updated timestamp

---

Tank Remaining Calculation Logic

Formula

Current Remaining = Latest Correction Value
                  + Total Refills After Correction
                  - Total Usage After Correction

Calculation Steps

1. Get latest correction - Query ops_tank_corrections ordered by correction_datetime DESC, take first
2. Sum refills after correction - Query ops_dustloc_refills where refill_datetime > correction_datetime
3. Sum usage after correction - Query data_flow_meters where datetime_dispensed > correction_datetime and is_ignored = false
4. Calculate remaining - Apply formula

Edge Cases

Case	Handling
No correction record	Show "Not Calibrated", prompt user to add first correction
Negative result	Show negative number with red warning "Data anomaly, please re-calibrate"
No tank capacity configured	Show gray cylinder, prompt "Please configure tank capacity"
Remaining > Capacity	Show overflow, orange warning "Remaining exceeds capacity, please check data"

---

Cylinder Visualization Component

Visual Design

     ╭─────────╮
     │  ███████│  ← Top ellipse cap
     ├─────────┤
     │         │
     │  ░░░░░░ │  ← Empty portion (light gray)
     │  ░░░░░░ │
     ├─────────┤  ← Liquid level line
     │  ██████ │
     │  ██████ │  ← Remaining Dustloc (blue gradient)
     │  ██████ │
     ╰─────────╯  ← Bottom ellipse

    Asset Name
    450L / 1000L (45%)
    Last Correction: 2024-01-15

Color States

Remaining %	Color	Status
> 50%	Blue	Normal
20% - 50%	Orange	Attention
0% - 20%	Red	Low warning
< 0%	Dark red + flashing border	Data anomaly
No capacity configured	Gray	Needs configuration
No correction	Gray dashed	Needs correction

Interactions

• Hover - Show detailed tooltip (latest correction value, usage since, refills since)
• Click - Navigate to Manage Corrections page, filtered by asset

Layout

• Multiple tanks displayed horizontally, responsive wrap
• Each cylinder approximately 120px wide, 180px tall
• Asset name and values displayed below cylinder

---

Page Designs

1. Manage Corrections Page

Path: /correction-management

Layout: Reference existing Manage Refills page

Features:

• Top: Statistics cards (total corrections, sites covered, latest correction time)
• Filters: Site, Asset, date range, search
• Table columns: Correction time, Site, Asset, Remaining litres, Corrected by, Notes, Evidence, Actions
• Actions: Add, Edit, Delete, View evidence photo

Add/Edit Modal Fields:

• Site (dropdown)
• Asset (cascading based on Site)
• Correction datetime (datetime picker)
• Remaining litres (number input)
• Corrected by (text input)
• Notes (textarea)
• Evidence photo (image upload)

2. Tank Configuration Page

Path: /tank-configuration

Layout: Simple configuration page

Features:

• Display all Flow Meter Assets grouped by Site
• Each Asset shows: name, configured capacity, action buttons
• Support batch setting (same capacity for multiple tanks in a Site)
• Highlight unconfigured Assets

Edit Method:

• Inline editing (click capacity number to modify directly)
• Or Modal editing

---

Menu & Routing

Menu Structure (Flat)

Flow Meter
├── Flow Meter            → /flow-meter
├── Manage Refills        → /refill-management
├── Manage Corrections    → /correction-management (NEW)
├── Tank Configuration    → /tank-configuration (NEW)
└── Calibration Reminders → /calibration-management (RENAMED)

Files to Modify

1. Route config - /src/routes/Routes.tsx

   • Add /correction-management route
   • Add /tank-configuration route

2. Sidebar menu - Find menu config file, add new items and rename Calibration

3. Existing page rename

   • "Manage Calibration" → "Calibration Reminders"
   • Page title, breadcrumbs, button text, etc.

---

File Structure

New Files

src/features/flow-meter/
├── components/
│   ├── TankCylinder.tsx              # Cylinder visualization component
│   ├── TankStatusDisplay.tsx         # Tank status display area (multiple cylinders)
│   ├── CorrectionModal.tsx           # Add/Edit correction Modal
│   └── TankCapacityModal.tsx         # Edit capacity Modal
├── services/
│   └── tankService.ts                # Tank services (correction, capacity, remaining calc)
└── types.ts                          # Add new type definitions

src/app/(admin)/(pages)/
├── correction-management/
│   └── page.tsx                      # Manage Corrections page
└── tank-configuration/
    └── page.tsx                      # Tank Configuration page

supabase/migrations/
└── YYYYMMDD_add_tank_corrections_and_capacities.sql  # Database migration

Files to Modify

src/features/flow-meter/
├── components/
│   └── (Flow Meter main page component)  # Add TankStatusDisplay
├── services/
│   └── databaseService.ts               # Add correction and capacity CRUD methods

src/routes/Routes.tsx                    # Add new routes
src/components/sidebar/                  # Add menu items, rename Calibration

---

Out of Scope

• Automatic correction reminder notifications
• Historical trend charts (correction values over time)
• Export correction reports

---

Display Location

Tank status display (cylinders) will be placed on the Flow Meter main page:

• Position: Below Date Range selector, above Daily Dustloc Usage chart
• Behavior: Always shows latest remaining amount, NOT affected by date range filter