# Stock-Out UI Available MT Display Bugfix - Summary

## Bug Fixed
**Issue**: Stock-out UI displayed total MT across ALL warehouses (440 MT) instead of warehouse-specific MT (20 MT) when selecting a specific warehouse.

## Root Cause
The `findBatches` method in `items.service.ts` was using `li.totalMt` (global total) instead of `li.warehouseBags[warehouseId]` (warehouse-specific bags) to calculate available MT.

## Fix Implementation

### File Modified
`api/src/items.service.ts` - `findBatches` method (lines ~140-165)

### Changes Made
**Before (Buggy)**:
```typescript
// Use the stored totalMt directly (most accurate — already computed on save)
if (li.totalMt && li.totalMt > 0) {
  availableMt += li.totalMt;
} else {
  // Fallback: compute from all warehouse bags × kgPerBag
  const allBags = Object.values(li.warehouseBags ?? {}).reduce(
    (s: number, v: any) => s + (Number(v) || 0), 0
  );
  const kgPerBag = bagWeightKgFromItem || (() => {
    const unit = li.unit ?? "";
    const m = unit.match(/(\d+)x(\d+(?:\.\d+)?)kg/i);
    return m ? parseFloat(m[1]) * parseFloat(m[2]) : 0;
  })();
  if (kgPerBag > 0) availableMt += (allBags * kgPerBag) / 1000;
}
```

**After (Fixed)**:
```typescript
// FIXED: Use warehouse-specific bag count instead of global totalMt
const warehouseBags = (li.warehouseBags ?? {})[warehouseId] ?? 0;
if (warehouseBags > 0) {
  const kgPerBag = bagWeightKgFromItem || (() => {
    const unit = li.unit ?? "";
    const m = unit.match(/(\d+)x(\d+(?:\.\d+)?)kg/i);
    return m ? parseFloat(m[1]) * parseFloat(m[2]) : 0;
  })();
  if (kgPerBag > 0) {
    availableMt += (warehouseBags * kgPerBag) / 1000;
  }
}
```

## Test Results

### Bug Condition Exploration Tests (Property 1)
✅ **4/4 tests pass** after fix (all failed before fix, confirming bug existed)

1. **Abu Dhabi Warehouse Test**: Returns 20 MT (warehouse-specific) ✅
   - Before: 440 MT (global total) ❌
   - After: 20 MT (correct) ✅

2. **Dubai Warehouse Test**: Returns 200 MT (warehouse-specific) ✅
   - Before: 440 MT (global total) ❌
   - After: 200 MT (correct) ✅

3. **Zero Bags Test**: Batch filtered out when warehouse has 0 bags ✅
   - Before: Returns batch with 440 MT ❌
   - After: Empty array (correct) ✅

4. **Single-Warehouse Test**: Returns 10 MT (works by coincidence) ✅
   - Before: 10 MT (correct by coincidence) ✅
   - After: 10 MT (still correct) ✅

### Preservation Tests (Property 2)
✅ **6/6 tests pass** after fix (all passed before fix, confirming no regressions)

1. **Global Inventory Summary**: Totals across all warehouses preserved ✅
2. **Expiry Reference**: Aggregation across warehouses preserved ✅
3. **Batch Exclusion**: `stockedOut: true` batches still excluded ✅
4. **Fallback Logic**: Falls back to `inventory_balance` when no sheets ✅
5. **Single-Warehouse Batches**: Continue to work correctly ✅
6. **Other Service Methods**: `getBatches()` in `inventory.service.ts` unchanged ✅

### Overall Test Suite
✅ **44/44 tests pass** (100% pass rate)
- 4 Bug 3 exploration tests ✅
- 6 Bug 3 preservation tests ✅
- 21 Bug 1 tests (from previous bugfix) ✅
- 13 Bug 2 tests (from previous bugfix) ✅

## Impact

### Fixed Behavior
- **Abu Dhabi Musaffah** with 1,000 bags: Now shows **20 MT** (was 440 MT)
- **Dubai Warehouse** with 10,000 bags: Now shows **200 MT** (was 440 MT)
- **Sharjah Warehouse** with 11,000 bags: Now shows **220 MT** (was 440 MT)
- **Warehouses with 0 bags**: Batches now correctly filtered out (were showing 440 MT)

### Preserved Behavior
- Global inventory metrics continue to show totals across all warehouses
- Expiry reference modal continues to aggregate across warehouses
- Batch exclusion logic unchanged
- Fallback to inventory_balance unchanged
- Other inventory service methods unchanged

## Verification

### Manual Testing Scenario
1. Navigate to stock-out page
2. Select warehouse: "Abu Dhabi Musaffah"
3. Select item: "Rice - Najam - 20 Kg"
4. Select batch: "BATCH-12"
5. **Expected**: Right panel shows "Total MT to stock out: 20.000 MT"
6. **Before Fix**: Showed 440.000 MT ❌
7. **After Fix**: Shows 20.000 MT ✅

### API Endpoint
- **Endpoint**: `GET /items/:itemId/batches?warehouseId=:warehouseId`
- **Before**: Returned `availableMt: 440` (global total)
- **After**: Returns `availableMt: 20` (warehouse-specific)

## Files Created/Modified

### Modified
- `api/src/items.service.ts` - Fixed `findBatches` method

### Created (Test Files)
- `api/src/items.service.bug3.test.ts` - Bug condition exploration tests
- `api/src/items.service.bug3.preservation.test.ts` - Preservation property tests
- `api/src/items.service.bug3.exploration.results.md` - Exploration test results
- `api/src/items.service.bug3.preservation.results.md` - Preservation test results
- `api/src/items.service.bug3.fix.summary.md` - This summary

### Spec Files
- `.kiro/specs/stock-out-ui-available-mt-display/.config.kiro`
- `.kiro/specs/stock-out-ui-available-mt-display/bugfix.md`
- `.kiro/specs/stock-out-ui-available-mt-display/design.md`
- `.kiro/specs/stock-out-ui-available-mt-display/tasks.md`

## Conclusion

✅ **Bug Fixed Successfully**
- All bug condition tests pass
- All preservation tests pass
- No regressions in existing functionality
- 100% test coverage for the fix

The stock-out UI now correctly displays warehouse-specific available MT instead of the global total across all warehouses.