app/utils/stock_utils.py

"""
Stock utility functions for easy integration across SCM services.
Uses PostgreSQL stored procedures for inventory mutations.
"""
from typing import List, Tuple
from sqlalchemy.ext.asyncio import AsyncSession
from app.inventory.stock.services.service import StockService


async def process_grn_stock_update(
    db: AsyncSession,
    grn_id: str,
    completed_by: str
) -> List[Tuple[str, bool]]:
    """
    Convenience function to process GRN completion stock updates using stored procedures.
    
    Usage in GRN service:
        from app.utils.stock_utils import process_grn_stock_update
        
        # After GRN is marked as completed
        stock_results = await process_grn_stock_update(db, grn_id, user_id)
    
    Args:
        db: Database session
        grn_id: GRN identifier
        completed_by: User who completed the GRN
        
    Returns:
        List of (ledger_id, success) tuples for each stock entry created
    """
    stock_service = StockService(db)
    return await stock_service.process_grn_completion(grn_id, completed_by)


async def process_stock_adjustment(
    db: AsyncSession,
    merchant_id: str,
    warehouse_id: str,
    sku: str,
    batch_no: str,
    adjustment_qty: float,
    adjustment_type: str,
    reason: str,
    adjusted_by: str,
    ref_id: str
) -> Tuple[str, bool]:
    """
    Convenience function to process stock adjustments.
    
    Usage in adjustment service:
        from app.utils.stock_utils import process_stock_adjustment
        
        # Process adjustment
        ledger_id, success = await process_stock_adjustment(
            db, merchant_id, warehouse_id, sku, batch_no,
            adjustment_qty, "damage", "Damaged goods", user_id, adjustment_id
        )
    
    Args:
        adjustment_qty: Positive for increase, negative for decrease
    """
    from decimal import Decimal
    
    stock_service = StockService(db)
    return await stock_service.process_stock_adjustment(
        merchant_id=merchant_id,
        warehouse_id=warehouse_id,
        sku=sku,
        batch_no=batch_no,
        adjustment_qty=Decimal(str(adjustment_qty)),
        adjustment_type=adjustment_type,
        reason=reason,
        adjusted_by=adjusted_by,
        ref_id=ref_id
    )


async def get_current_stock(
    db: AsyncSession,
    merchant_id: str,
    warehouse_id: str = None,
    sku: str = None
) -> List[dict]:
    """
    Convenience function to get current stock levels.
    
    Usage:
        from app.utils.stock_utils import get_current_stock
        
        # Get all stock for merchant
        stock = await get_current_stock(db, merchant_id)
        
        # Get stock for specific location
        stock = await get_current_stock(db, merchant_id, warehouse_id="WH001")
        
        # Get stock for specific SKU
        stock = await get_current_stock(db, merchant_id, sku="PROD001")
    """
    stock_service = StockService(db)
    return await stock_service.get_stock_summary(merchant_id, warehouse_id, sku)


async def get_stock_history(
    db: AsyncSession,
    merchant_id: str,
    sku: str = None,
    batch_no: str = None,
    limit: int = 100
) -> List[dict]:
    """
    Convenience function to get stock transaction history.
    
    Usage:
        from app.utils.stock_utils import get_stock_history
        
        # Get recent transactions for merchant
        history = await get_stock_history(db, merchant_id, limit=50)
        
        # Get history for specific SKU
        history = await get_stock_history(db, merchant_id, sku="PROD001")
    """
    stock_service = StockService(db)
    return await stock_service.get_stock_ledger(merchant_id, sku, batch_no, limit)


async def reserve_stock(
    db: AsyncSession,
    merchant_id: str,
    warehouse_id: str,
    sku: str,
    batch_no: str,
    qty: float,
    ref_id: str,
    created_by: str
) -> bool:
    """
    Convenience function to reserve stock for sales orders.
    
    Usage:
        from app.utils.stock_utils import reserve_stock
        
        # Reserve stock for sales order
        success = await reserve_stock(db, merchant_id, warehouse_id, sku, 
                                    batch_no, qty, sales_order_id, user_id)
    """
    from decimal import Decimal
    
    stock_service = StockService(db)
    return await stock_service.reserve_stock(
        merchant_id, warehouse_id, sku, batch_no, 
        Decimal(str(qty)), ref_id, created_by
    )


async def release_stock_reservation(
    db: AsyncSession,
    merchant_id: str,
    warehouse_id: str,
    sku: str,
    batch_no: str,
    qty: float,
    ref_id: str,
    created_by: str
) -> bool:
    """
    Convenience function to release stock reservations.
    
    Usage:
        from app.utils.sto