Store Asked Reflux Controller Documentation

File: /controllers/storeAskedRefluxController.php

Purpose: Inter-store transfer management system with approval workflow and inventory tracking

Last Updated: December 21, 2024

Total Functions: 15+

Lines of Code: ~2,000+

---

📋 Overview

The Store Asked Reflux Controller manages complex inter-store transfer operations with approval workflows and inventory tracking. It handles:

• • Multi-step store transfer processes with approval workflows
• • Size/color variant product transfers
• • Driver management and delivery tracking
• • Operation number generation and tracking
• • Store supervisor approval systems
• • Inventory validation and adjustment
• • Complete audit trail for all transfers
• • Transaction rollback capabilities for data integrity

Primary Functions

• ✅ Inter-store product transfer management
• ✅ Multi-step approval workflow (request → approval → delivery)
• ✅ Size/color variant handling
• ✅ Driver assignment and tracking
• ✅ Operation number generation and tracking
• ✅ Inventory validation before transfers
• ✅ Complete audit trail and reporting
• ✅ Transaction management with rollback

Related Controllers

• • storemovementController.php - Basic store movements
• • storeHousingController.php - Inventory management
• • inventoryController.php - Core inventory operations
• • userController.php - User and driver management

---

🗄️ Database Tables

Primary Transfer Tables

🔑 Key Functions

1. Default Action - Transfer Request Interface

Location: Line 188

Purpose: Display the main transfer request interface

Process Flow:

1. Load authentication and permissions

2. Load available stores based on user permissions

3. Load driver information (user group "سائقين")

4. Generate next operation number

5. Display transfer request form

Key Features:

• • Multi-store access control
• • Driver selection interface
• • Operation number auto-generation
• • Store permission validation

---

2. add() - Full Transfer Process

Location: Line 652

Purpose: Complete transfer process with inventory validation

Function Signature:

function add()

Process Flow:

1. Pre-validate all products for sufficient quantity

2. Process each product in transaction

3. Handle size/color variants

4. Decrease source store inventory

5. Increase destination store inventory

6. Create audit trail entries

7. Generate operation number

Key Variables:

• • $storeidfrom / $storeidto - Source and destination stores
• • $operationnum - Unique operation identifier
• • $productItr - Number of products being transferred
• • $productsBeforeValid - Validation flag

---

3. addDealWithStoreFromOnly() - Source Store Processing

Location: Line 896

Purpose: Handle transfers that only affect source store (approval pending)

Process Flow:

1. Similar to add() but only processes source store

2. Used when destination approval is required

3. Creates pending transfer records

4. Awaits confirmation from destination store

---

4. addDealWithStoreToOnly() - Destination Store Processing

Location: Line 1099

Purpose: Complete transfer by processing destination store

Function Signature:

function addDealWithStoreToOnly($storeMovementObject)

Process Flow:

1. Load existing transfer record

2. Process destination store inventory increase

3. Update cost tracking

4. Complete transfer workflow

5. Update audit trail

---

5. show Actions - Transfer Reporting

Multiple locations

Purpose: Various reporting and tracking functions

Key Functions:

• • showByDate() - Date range transfer reports
• • showByoperationnum() - Operation-specific details
• • showBystoreidfrom() - Store-specific reports

---

🔄 Workflows

Workflow 1: Complete Inter-Store Transfer Process

---

🌐 URL Routes & Actions

Transfer Request (do=add):

• • storeidfrom - Source store ID
• • storeidto - Destination store ID
• • productitr - Number of products
• • product{N} - Product ID for item N
• • productamount{N} - Quantity for item N
• • driver - Driver ID (optional)
• • recieveType - Workflow type

Search/Filter (do=show):

• • from - Start date
• • to - End date
• • operationnum - Operation number filter
• • storeidfrom - Store filter

---

🧮 Calculation Methods

Size/Color Variant Processing

// Parse complex product ID for variants
if (strpos($productId, "hasSizeColor") !== false) {
    $productIdComplex = explode('-', str_replace("hasSizeColor", "", $productId));
    $productId = $productIdComplex[0];
    $sizeId = $productIdComplex[1];
    $colorId = $productIdComplex[2];
    
    // Load size/color specific inventory
    $sizeColorStoreDetailId = $sizeColorStoreDetailEX->getIdByProductStoreSizeAndColorEX(
        $productId, $storeid, $sizeId, $colorId
    );
}

Inventory Validation Logic

// Pre-validation before transfer processing
$productsBeforeValid = 1;
if ($productquantityFromBefore > 0 && count($allStoredetailFromData) > 0) {
    $productsAfterValid = $productquantityFromBefore - $transferproductAmount;
    
    if ($productsAfterValid >= 0) {
        $productsBeforeValid = 1;  // Sufficient inventory
    } else {
        $productsBeforeValid = 0;  // Insufficient inventory - abort
    }
} else {
    $productsBeforeValid = 0;  // No inventory record
}

Driver Time Tracking

// Calculate delivery delays
if ($mystoremovementData->driverid > 0) {
    if ($mystoremovementData->deliverdate == NULL) {
        $mystoremovementData->deliverdate = date("Y-m-d H:i:s");
    }
    
    $hours = dateTimeDiff($mystoremovementData->driverdate, $mystoremovementData->deliverdate);
    if ($hours > $mystoremovementData->drivertimeout) {
        $mystoremovementData->lateHours = $hours - $mystoremovementData->drivertimeout;
    } else {
        $mystoremovementData->lateHours = 0;
    }
}

Operation Number Generation

// Generate unique operation numbers using stored procedure
if ($i == 1) {
    $spData = $myStoremovementEx->callInsertUniqueOptNumSP($myStoremovement);
    $transferproductId = $spData->id;
    $operationnum = $spData->optnum;
    $myStoremovement->operationnum = $operationnum;
} else {
    $transferproductId = $myStoremovementRecord->insert($myStoremovement);
}

---

🔒 Security & Permissions

Store Access Control

// Multi-store vs single-store access
if ($_SESSION['searchinonestore'] == 0) {
    if ($_SESSION['storeids'] == 0) {
        $stores = $myStoreEx->queryByConditions();  // All stores
    } else {
        $stores = $myStoreEx->queryByConditions(' and store.storeId in (' . $_SESSION['storeids'] . ')');
    }
} else {
    $storedef = $myStoreEx->queryByConditionsOne(' and store.storeId = ' . $_SESSION['storeid']);
}

Store Supervisor Validation

// Check if user can supervise specific stores
$userData = $userDAO->load($_SESSION['userid']);
$userData->storeSupervisorStores = explode(',', $userData->storeSupervisorStores);

// Validate supervisor permissions for approval
if (in_array($storeidto, $userData->storeSupervisorStores)) {
    // User can approve transfers to this store
}

Transaction Security

// All critical operations wrapped in transactions
$mytransactions = new Transaction();
try {
    // Process transfer operations
    // Multiple database updates
    $mytransactions->commit();
} catch (Exception $ex) {
    $mytransactions->rollback();
    $product_arr = array('error');
}

---

📊 Performance Considerations

Transaction Management

1. Atomic Operations:

- All transfers processed in single transaction

- Rollback capability for data integrity

- Pre-validation prevents partial failures

2. Batch Processing:

- Multiple products processed efficiently

- Minimal database round trips

- Bulk audit trail creation

3. Index Requirements:

- storemovement(operationnum, storeidfrom, storeidto)

- storedetail(productid, storeid)

- sizecolorstoredetail(productid, storeid, sizeid, colorid)

Performance Monitoring

// Monitor for slow operations
$startTime = microtime(true);
for ($h = 1; $h <= $productItr; $h++) {
    // Process each product
}
$processingTime = microtime(true) - $startTime;

if ($processingTime > 30.0) {
    error_log("Slow transfer operation: " . $processingTime . "s for " . $productItr . " products");
}

---

🐛 Common Issues & Troubleshooting

1. Transfer Validation Failures

Issue: Transfers fail with "insufficient inventory" errors

Cause: Concurrent operations or inventory sync issues

Debug:

// Check actual inventory vs expected
$storedetailData = getStoredetailData($storeidfrom, $productId, $sizeColorStoreDetailId, $sizeId, $colorId);
echo "Current Inventory: " . $storedetailData[2] . "<br>";
echo "Transfer Amount: " . $transferproductAmount . "<br>";
echo "Remaining: " . ($storedetailData[2] - $transferproductAmount) . "<br>";

2. Size/Color Variant Issues

Issue: Variant transfers not processing correctly

Cause: Complex product ID parsing or missing variant records

Fix:

// Verify variant parsing
if (strpos($productId, "hasSizeColor") !== false) {
    echo "Original: " . $productId . "<br>";
    $productIdComplex = explode('-', str_replace("hasSizeColor", "", $productId));
    echo "Product: " . $productIdComplex[0] . "<br>";
    echo "Size: " . $productIdComplex[1] . "<br>";
    echo "Color: " . $productIdComplex[2] . "<br>";
}

3. Operation Number Conflicts

Issue: Duplicate operation numbers or missing sequences

Cause: Stored procedure issues or concurrent access

Fix:

// Check operation number generation
$nextId = $myStoremovementEx->queryAlloperationnum();
echo "Next Operation Number: " . ($nextId[0]->operationnum + 1);

// Verify uniqueness
$existing = $myStoremovementEx->querybyoperationnum($operationnum);
if (count($existing) > 0) {
    echo "Warning: Operation number already exists!";
}

---

🧪 Testing Scenarios

Test Case 1: Basic Transfer Validation

1. Create source store with known inventory
2. Attempt transfer of various quantities
3. Verify validation prevents over-transfers
4. Check audit trail completeness
5. Confirm inventory accuracy after transfer

Test Case 2: Size/Color Variant Transfer

1. Set up products with multiple size/color variants
2. Transfer specific variants between stores
3. Verify variant-specific inventory updates
4. Check parent product total recalculation
5. Confirm audit trail captures variant details

Test Case 3: Approval Workflow

1. Configure workerbetweenstores = 1 (approval required)
2. Create transfer request from Store A to Store B
3. Verify source store inventory decreases
4. Confirm destination shows pending approval
5. Approve transfer and verify completion
6. Test rejection and inventory restoration

Test Case 4: Driver Management

1. Assign driver to transfer operation
2. Set delivery timeout expectations
3. Simulate delivery confirmation
4. Test late delivery calculation
5. Verify driver performance tracking

---

📚 Related Documentation

• • CLAUDE.md - PHP 8.2 migration guide
• • storeHousingController.md - Inventory management
• • inventoryController.md - Core inventory operations
• • dailyentry.php - Accounting integration
• • Database Schema Documentation - Table relationships

---

Documented By: AI Assistant

Review Status: ✅ Complete

Next Review: When major changes occur