feat(stock): migrate to PostgreSQL stored procedures for stock management

- Replace in-application stock ledger logic with PostgreSQL stored procedures (apply_stock_movement, apply_bulk_stock_movements)
- Rename Procurement.batch field to batch_managed for clarity
- Simplify StockService to act as validation layer calling stored procedures instead of direct ORM operations
- Update stock transaction processing to use parameterized SQL queries with stored procedure calls
- Add JSON serialization for bulk movement operations to stored procedures
- Remove direct ScmStock and ScmStockLedger model dependencies from service layer
- Update stock_utils validation functions to work with new stored procedure approach
- Add salon test catalogue data fixture for testing
- Add stock_management.sql with stored procedure definitions
- Improves data consistency by centralizing stock mutation logic in database layer

app/catalogues/models/model.py

@@ -47,7 +47,7 @@ class Loyalty(BaseModel):
 
 class Procurement(BaseModel):
     moq: Optional[int] = None
-    batch:Optional[bool]= False
+    batch_managed:Optional[bool]= False
     expiry_period_months: Optional[int] = 36
 
 

app/services/stock_service.py

@@ -1,18 +1,17 @@
 """
-Generic Stock Management Service for SCM.
-Handles stock ledger entries and stock snapshot updates for all inventory transactions.
+Stock Management Service using PostgreSQL Stored Procedures.
+Provides validation layer and calls stored procedures for inventory mutations.
 """
 from typing import List, Optional, Dict, Any, Tuple
 from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy import select, and_, func
-from sqlalchemy.dialects.postgresql import insert
-from uuid import uuid4
+from sqlalchemy import text, select
+from uuid import UUID
 from decimal import Decimal
-from datetime import datetime
+from datetime import datetime, date
 from enum import Enum
+import json
 import logging
 
-from app.models.inventory_model import ScmStock, ScmStockLedger
 from app.models.po_grn_model import ScmGrnItem
 
 logger = logging.getLogger(__name__)
@@ -75,25 +74,45 @@ class StockTransaction:
 
 
 class StockService:
-    """Generic stock management service"""
+    """Stock management service using PostgreSQL stored procedures"""
     
     def __init__(self, db: AsyncSession):
         self.db = db
     
     async def process_stock_transaction(self, transaction: StockTransaction) -> Tuple[str, bool]:
         """
-        Process a single stock transaction.
-        Creates ledger entry and updates stock snapshot.
+        Process a single stock transaction using simplified stored procedure.
         
         Returns:
-            Tuple of (ledger_id, success)
+            Tuple of (transaction_id, success) - transaction_id is generated for tracking
         """
         try:
-            # Create ledger entry
-            ledger_id = await self._create_ledger_entry(transaction)
+            # Validate transaction data
+            self._validate_transaction(transaction)
             
-            # Update stock snapshot
-            await self._update_stock_snapshot(transaction)
+            # Call simplified stored procedure
+            query = text("""
+                CALL apply_stock_movement(
+                    :merchant_id, :location_id, :sku, :batch_no, :qty,
+                    :txn_type, :ref_type, :ref_id, :ref_no, :created_by
+                )
+            """)
+            
+            await self.db.execute(query, {
+                "merchant_id": transaction.merchant_id,
+                "location_id": transaction.location_id,
+                "sku": transaction.sku,
+                "batch_no": transaction.batch_no,
+                "qty": float(transaction.qty),
+                "txn_type": transaction.txn_type.value,
+                "ref_type": transaction.ref_type.value,
+                "ref_id": str(transaction.ref_id),
+                "ref_no": transaction.ref_no,
+                "created_by": transaction.created_by
+            })
+            
+            # Generate transaction ID for tracking (since procedure returns VOID)
+            transaction_id = f"{transaction.ref_type.value}_{transaction.ref_id}_{transaction.sku}_{transaction.batch_no}"
             
             logger.info(
                 f"Stock transaction processed: {transaction.txn_type} "
@@ -101,7 +120,7 @@ class StockService:
                 f"REF={transaction.ref_type}:{transaction.ref_id}"
             )
             
-            return ledger_id, True
+            return transaction_id, True
             
         except Exception as e:
             logger.error(f"Error processing stock transaction: {e}")
@@ -109,24 +128,57 @@ class StockService:
     
     async def process_stock_transactions(self, transactions: List[StockTransaction]) -> List[Tuple[str, bool]]:
         """
-        Process multiple stock transactions in a single database transaction.
+        Process multiple stock transactions using bulk stored procedure.
         All succeed or all fail (atomic operation).
         
         Returns:
             List of (ledger_id, success) tuples
         """
-        results = []
-        
         try:
+            # Validate all transactions
             for transaction in transactions:
-                ledger_id, success = await self.process_stock_transaction(transaction)
-                results.append((ledger_id, success))
+                self._validate_transaction(transaction)
+            
+            # Prepare movements array for stored procedure
+            movements = []
+            for transaction in transactions:
+                movement = {
+                    "merchant_id": transaction.merchant_id,
+                    "location_id": transaction.location_id,
+                    "catalogue_id": str(transaction.catalogue_id),
+                    "sku": transaction.sku,
+                    "batch_no": transaction.batch_no,
+                    "exp_dt": transaction.exp_dt.isoformat() if transaction.exp_dt else None,
+                    "qty": str(transaction.qty),
+                    "uom": transaction.uom,
+                    "txn_type": transaction.txn_type.value,
+                    "ref_type": transaction.ref_type.value,
+                    "ref_id": str(transaction.ref_id),
+                    "ref_no": transaction.ref_no,
+                    "remarks": transaction.remarks,
+                    "created_by": transaction.created_by
+                }
+                movements.append(movement)
+            
+            # Call bulk stored procedure
+            query = text("SELECT apply_bulk_stock_movements(:movements) as results")
+            result = await self.db.execute(query, {
+                "movements": json.dumps(movements)
+            })
             
-            # Commit all transactions
+            results_json = result.scalar()
+            results = json.loads(results_json) if results_json else []
+            
+            # Convert to expected format
+            processed_results = []
+            for result_item in results:
+                processed_results.append((result_item["ledger_id"], result_item["success"]))
+            
+            # Commit transaction
             await self.db.commit()
             
             logger.info(f"Processed {len(transactions)} stock transactions successfully")
-            return results
+            return processed_results
             
         except Exception as e:
             # Rollback on any error
@@ -134,86 +186,28 @@ class StockService:
             logger.error(f"Error processing stock transactions batch: {e}")
             raise
     
-    async def _create_ledger_entry(self, transaction: StockTransaction) -> str:
-        """Create immutable ledger entry"""
-        ledger_entry = ScmStockLedger(
-            ledger_id=uuid4(),
-            merchant_id=transaction.merchant_id,
-            location_id=transaction.location_id,
-            catalogue_id=transaction.catalogue_id,
-            sku=transaction.sku,
-            batch_no=transaction.batch_no,
-            exp_dt=transaction.exp_dt,
-            txn_type=transaction.txn_type.value,
-            qty=transaction.qty,
-            uom=transaction.uom,
-            ref_type=transaction.ref_type.value,
-            ref_id=transaction.ref_id,
-            ref_no=transaction.ref_no,
-            remarks=transaction.remarks,
-            created_by=transaction.created_by,
-            created_at=datetime.utcnow()
-        )
+    def _validate_transaction(self, transaction: StockTransaction):
+        """Validate transaction data before processing"""
+        if not transaction.merchant_id:
+            raise ValueError("merchant_id is required")
         
-        self.db.add(ledger_entry)
-        await self.db.flush()  # Get the ID without committing
+        if not transaction.location_id:
+            raise ValueError("location_id is required")
         
-        return str(ledger_entry.ledger_id)
-    
-    async def _update_stock_snapshot(self, transaction: StockTransaction):
-        """Update or create stock snapshot record"""
-        # Find existing stock record
-        stock_query = select(ScmStock).where(
-            and_(
-                ScmStock.merchant_id == transaction.merchant_id,
-                ScmStock.location_id == transaction.location_id,
-                ScmStock.sku == transaction.sku,
-                ScmStock.batch_no == transaction.batch_no
-            )
-        )
+        if not transaction.sku:
+            raise ValueError("sku is required")
         
-        result = await self.db.execute(stock_query)
-        existing_stock = result.scalar_one_or_none()
+        if not transaction.batch_no:
+            raise ValueError("batch_no is required")
         
-        if existing_stock:
-            # Update existing stock
-            new_qty_on_hand = existing_stock.qty_on_hand + transaction.qty
-            new_qty_available = new_qty_on_hand - existing_stock.qty_reserved
-            
-            # Ensure quantities don't go negative
-            if new_qty_on_hand < 0:
-                raise ValueError(
-                    f"Insufficient stock: SKU={transaction.sku} "
-                    f"Current={existing_stock.qty_on_hand} Required={abs(transaction.qty)}"
-                )
-            
-            existing_stock.qty_on_hand = new_qty_on_hand
-            existing_stock.qty_available = max(new_qty_available, Decimal(0))
-            existing_stock.last_updated_at = datetime.utcnow()
-            
-        else:
-            # Create new stock record (for IN transactions only)
-            if transaction.qty < 0:
-                raise ValueError(
-                    f"Cannot create negative stock: SKU={transaction.sku} QTY={transaction.qty}"
-                )
-            
-            new_stock = ScmStock(
-                stock_id=uuid4(),
-                merchant_id=transaction.merchant_id,
-                location_id=transaction.location_id,
-                catalogue_id=transaction.catalogue_id,
-                sku=transaction.sku,
-                batch_no=transaction.batch_no,
-                qty_on_hand=transaction.qty,
-                qty_reserved=Decimal(0),
-                qty_available=transaction.qty,
-                uom=transaction.uom,
-                last_updated_at=datetime.utcnow(),
-                created_at=datetime.utcnow()
-            )
-            
-            self.db.add(new_stock)
+        if transaction.qty == 0:
+            raise ValueError("qty cannot be zero")
+        
+        if not transaction.uom:
+            raise ValueError("uom is required")
+        
+        if not transaction.created_by:
+            raise ValueError("created_by is required")
     
     async def process_grn_completion(self, grn_id: str, completed_by: str) -> List[Tuple[str, bool]]:
         """
@@ -227,42 +221,46 @@ class StockService:
             List of (ledger_id, success) tuples for each item
         """
         try:
-            # Get all GRN items for this GRN
-            grn_items_query = select(ScmGrnItem).where(ScmGrnItem.grn_id == grn_id)
-            result = await self.db.execute(grn_items_query)
-            grn_items = result.scalars().all()
+            # Get all GRN items for this GRN with related data
+            grn_items_query = text("""
+                SELECT gi.catalogue_id, gi.sku, gi.batch_no, gi.exp_dt, gi.acc_qty, gi.rej_qty, gi.uom,
+                       g.grn_no, g.wh_location, po.buyer_id as merchant_id
+                FROM scm_grn_item gi
+                JOIN scm_grn g ON gi.grn_id = g.grn_id
+                JOIN scm_po po ON g.po_id = po.po_id
+                WHERE gi.grn_id = :grn_id AND gi.acc_qty > 0
+            """)
+            
+            result = await self.db.execute(grn_items_query, {"grn_id": grn_id})
+            grn_items = result.fetchall()
             
             if not grn_items:
-                raise ValueError(f"No GRN items found for GRN: {grn_id}")
+                logger.warning(f"No accepted items found in GRN: {grn_id}")
+                return []
             
             # Create stock transactions for each accepted item
             transactions = []
             
             for item in grn_items:
-                if item.acc_qty > 0:  # Only process accepted quantities
-                    transaction = StockTransaction(
-                        merchant_id=item.grn.purchase_order.buyer_id,  # Assuming buyer_id is merchant_id
-                        location_id=item.grn.wh_location or "default",
-                        catalogue_id=str(item.catalogue_id),
-                        sku=item.sku,
-                        batch_no=item.batch_no,
-                        exp_dt=item.exp_dt,
-                        qty=item.acc_qty,  # Positive quantity for stock IN
-                        uom=item.uom,
-                        txn_type=TransactionType.GRN_IN,
-                        ref_type=ReferenceType.GRN,
-                        ref_id=str(grn_id),
-                        ref_no=item.grn.grn_no,
-                        remarks=f"GRN completion - Accepted: {item.acc_qty}, Rejected: {item.rej_qty}",
-                        created_by=completed_by
-                    )
-                    transactions.append(transaction)
-            
-            if not transactions:
-                logger.warning(f"No accepted items found in GRN: {grn_id}")
-                return []
+                transaction = StockTransaction(
+                    merchant_id=item.merchant_id,
+                    location_id=item.wh_location or "default",
+                    catalogue_id=str(item.catalogue_id),
+                    sku=item.sku,
+                    batch_no=item.batch_no,
+                    exp_dt=item.exp_dt,
+                    qty=Decimal(str(item.acc_qty)),  # Positive quantity for stock IN
+                    uom=item.uom,
+                    txn_type=TransactionType.GRN_IN,
+                    ref_type=ReferenceType.GRN,
+                    ref_id=str(grn_id),
+                    ref_no=item.grn_no,
+                    remarks=f"GRN completion - Accepted: {item.acc_qty}, Rejected: {item.rej_qty}",
+                    created_by=completed_by
+                )
+                transactions.append(transaction)
             
-            # Process all transactions atomically
+            # Process all transactions atomically using bulk stored procedure
             results = await self.process_stock_transactions(transactions)
             
             logger.info(f"GRN {grn_id} completion processed: {len(results)} stock entries created")
@@ -285,50 +283,60 @@ class StockService:
         ref_id: str
     ) -> Tuple[str, bool]:
         """
-        Process stock adjustment (positive or negative).
+        Process stock adjustment using stored procedure.
         
         Args:
             adjustment_qty: Positive for increase, negative for decrease
         """
-        txn_type = TransactionType.ADJUST_IN if adjustment_qty > 0 else TransactionType.ADJUST_OUT
-        
-        # Get catalogue_id from existing stock or require it as parameter
-        stock_query = select(ScmStock).where(
-            and_(
-                ScmStock.merchant_id == merchant_id,
-                ScmStock.location_id == location_id,
-                ScmStock.sku == sku,
-                ScmStock.batch_no == batch_no
+        try:
+            txn_type = TransactionType.ADJUST_IN if adjustment_qty > 0 else TransactionType.ADJUST_OUT
+            
+            # Get catalogue_id and uom from existing stock
+            stock_query = text("""
+                SELECT catalogue_id, uom FROM scm_stock
+                WHERE merchant_id = :merchant_id AND location_id = :location_id 
+                  AND sku = :sku AND batch_no = :batch_no
+            """)
+            
+            result = await self.db.execute(stock_query, {
+                "merchant_id": merchant_id,
+                "location_id": location_id,
+                "sku": sku,
+                "batch_no": batch_no
+            })
+            
+            stock_info = result.fetchone()
+            
+            if not stock_info and adjustment_qty < 0:
+                raise ValueError(f"Cannot adjust non-existent stock: SKU={sku}")
+            
+            if not stock_info:
+                raise ValueError(f"Catalogue ID and UOM required for new stock: SKU={sku}")
+            
+            catalogue_id = str(stock_info.catalogue_id)
+            uom = stock_info.uom
+            
+            transaction = StockTransaction(
+                merchant_id=merchant_id,
+                location_id=location_id,
+                catalogue_id=catalogue_id,
+                sku=sku,
+                batch_no=batch_no,
+                exp_dt=None,  # Adjustments don't change expiry
+                qty=adjustment_qty,
+                uom=uom,
+                txn_type=txn_type,
+                ref_type=ReferenceType.ADJUSTMENT,
+                ref_id=ref_id,
+                remarks=f"{adjustment_type}: {reason}",
+                created_by=adjusted_by
             )
-        )
-        
-        result = await self.db.execute(stock_query)
-        existing_stock = result.scalar_one_or_none()
-        
-        if not existing_stock and adjustment_qty < 0:
-            raise ValueError(f"Cannot adjust non-existent stock: SKU={sku}")
-        
-        catalogue_id = str(existing_stock.catalogue_id) if existing_stock else None
-        if not catalogue_id:
-            raise ValueError(f"Catalogue ID required for new stock: SKU={sku}")
-        
-        transaction = StockTransaction(
-            merchant_id=merchant_id,
-            location_id=location_id,
-            catalogue_id=catalogue_id,
-            sku=sku,
-            batch_no=batch_no,
-            exp_dt=None,  # Adjustments don't change expiry
-            qty=adjustment_qty,
-            uom=existing_stock.uom if existing_stock else "PCS",
-            txn_type=txn_type,
-            ref_type=ReferenceType.ADJUSTMENT,
-            ref_id=ref_id,
-            remarks=f"{adjustment_type}: {reason}",
-            created_by=adjusted_by
-        )
-        
-        return await self.process_stock_transaction(transaction)
+            
+            return await self.process_stock_transaction(transaction)
+            
+        except Exception as e:
+            logger.error(f"Error processing stock adjustment: {e}")
+            raise
     
     async def get_stock_summary(
         self,
@@ -336,31 +344,36 @@ class StockService:
         location_id: Optional[str] = None,
         sku: Optional[str] = None
     ) -> List[Dict[str, Any]]:
-        """Get current stock summary with filters"""
-        query = select(ScmStock).where(ScmStock.merchant_id == merchant_id)
-        
-        if location_id:
-            query = query.where(ScmStock.location_id == location_id)
-        
-        if sku:
-            query = query.where(ScmStock.sku == sku)
-        
-        result = await self.db.execute(query)
-        stocks = result.scalars().all()
-        
-        return [
-            {
-                "stock_id": str(stock.stock_id),
-                "location_id": stock.location_id,
-                "sku": stock.sku,
-                "batch_no": stock.batch_no,
-                "qty_on_hand": float(stock.qty_on_hand),
-                "qty_reserved": float(stock.qty_reserved),
-                "qty_available": float(stock.qty_available),
-                "last_updated": stock.last_updated_at.isoformat()
-            }
-            for stock in stocks
-        ]
+        """Get current stock summary using stored procedure"""
+        try:
+            query = text("SELECT * FROM get_stock_summary(:merchant_id, :location_id, :sku)")
+            result = await self.db.execute(query, {
+                "merchant_id": merchant_id,
+                "location_id": location_id,
+                "sku": sku
+            })
+            
+            stocks = result.fetchall()
+            
+            return [
+                {
+                    "stock_id": str(stock.stock_id),
+                    "location_id": stock.location_id,
+                    "catalogue_id": str(stock.catalogue_id),
+                    "sku": stock.sku,
+                    "batch_no": stock.batch_no,
+                    "qty_on_hand": float(stock.qty_on_hand),
+                    "qty_reserved": float(stock.qty_reserved),
+                    "qty_available": float(stock.qty_available),
+                    "uom": stock.uom,
+                    "last_updated": stock.last_updated_at.isoformat()
+                }
+                for stock in stocks
+            ]
+            
+        except Exception as e:
+            logger.error(f"Error getting stock summary: {e}")
+            raise
     
     async def get_stock_ledger(
         self,
@@ -369,34 +382,112 @@ class StockService:
         batch_no: Optional[str] = None,
         limit: int = 100
     ) -> List[Dict[str, Any]]:
-        """Get stock ledger entries with filters"""
-        query = select(ScmStockLedger).where(ScmStockLedger.merchant_id == merchant_id)
-        
-        if sku:
-            query = query.where(ScmStockLedger.sku == sku)
-        
-        if batch_no:
-            query = query.where(ScmStockLedger.batch_no == batch_no)
-        
-        query = query.order_by(ScmStockLedger.created_at.desc()).limit(limit)
-        
-        result = await self.db.execute(query)
-        ledger_entries = result.scalars().all()
-        
-        return [
-            {
-                "ledger_id": str(entry.ledger_id),
-                "location_id": entry.location_id,
-                "sku": entry.sku,
-                "batch_no": entry.batch_no,
-                "txn_type": entry.txn_type,
-                "qty": float(entry.qty),
-                "ref_type": entry.ref_type,
-                "ref_id": str(entry.ref_id),
-                "ref_no": entry.ref_no,
-                "remarks": entry.remarks,
-                "created_at": entry.created_at.isoformat(),
-                "created_by": entry.created_by
-            }
-            for entry in ledger_entries
-        ]
+        """Get stock ledger entries using stored procedure"""
+        try:
+            query = text("SELECT * FROM get_stock_ledger(:merchant_id, :sku, :batch_no, :limit)")
+            result = await self.db.execute(query, {
+                "merchant_id": merchant_id,
+                "sku": sku,
+                "batch_no": batch_no,
+                "limit": limit
+            })
+            
+            ledger_entries = result.fetchall()
+            
+            return [
+                {
+                    "ledger_id": str(entry.ledger_id),
+                    "location_id": entry.location_id,
+                    "catalogue_id": str(entry.catalogue_id),
+                    "sku": entry.sku,
+                    "batch_no": entry.batch_no,
+                    "txn_type": entry.txn_type,
+                    "qty": float(entry.qty),
+                    "uom": entry.uom,
+                    "ref_type": entry.ref_type,
+                    "ref_id": str(entry.ref_id),
+                    "ref_no": entry.ref_no,
+                    "remarks": entry.remarks,
+                    "created_by": entry.created_by,
+                    "created_at": entry.created_at.isoformat()
+                }
+                for entry in ledger_entries
+            ]
+            
+        except Exception as e:
+            logger.error(f"Error getting stock ledger: {e}")
+            raise
+    
+    async def reserve_stock(
+        self,
+        merchant_id: str,
+        location_id: str,
+        sku: str,
+        batch_no: str,
+        qty: Decimal,
+        ref_id: str,
+        created_by: str
+    ) -> bool:
+        """Reserve stock using stored procedure"""
+        try:
+            query = text("""
+                SELECT reserve_stock(:merchant_id, :location_id, :sku, :batch_no, :qty, :ref_id, :created_by)
+            """)
+            
+            result = await self.db.execute(query, {
+                "merchant_id": merchant_id,
+                "location_id": location_id,
+                "sku": sku,
+                "batch_no": batch_no,
+                "qty": float(qty),
+                "ref_id": ref_id,
+                "created_by": created_by
+            })
+            
+            success = result.scalar()
+            await self.db.commit()
+            
+            logger.info(f"Stock reserved: SKU={sku} QTY={qty} REF={ref_id}")
+            return success
+            
+        except Exception as e:
+            await self.db.rollback()
+            logger.error(f"Error reserving stock: {e}")
+            raise
+    
+    async def release_stock_reservation(
+        self,
+        merchant_id: str,
+        location_id: str,
+        sku: str,
+        batch_no: str,
+        qty: Decimal,
+        ref_id: str,
+        created_by: str
+    ) -> bool:
+        """Release stock reservation using stored procedure"""
+        try:
+            query = text("""
+                SELECT release_stock_reservation(:merchant_id, :location_id, :sku, :batch_no, :qty, :ref_id, :created_by)
+            """)
+            
+            result = await self.db.execute(query, {
+                "merchant_id": merchant_id,
+                "location_id": location_id,
+                "sku": sku,
+                "batch_no": batch_no,
+                "qty": float(qty),
+                "ref_id": ref_id,
+                "created_by": created_by
+            })
+            
+            success = result.scalar()
+            await self.db.commit()
+            
+            logger.info(f"Stock reservation released: SKU={sku} QTY={qty} REF={ref_id}")
+            return success
+            
+        except Exception as e:
+            await self.db.rollback()
+            logger.error(f"Error releasing stock reservation: {e}")
+            raise

app/utils/stock_utils.py

@@ -1,5 +1,6 @@
 """
 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
@@ -12,7 +13,7 @@ async def process_grn_stock_update(
     completed_by: str
 ) -> List[Tuple[str, bool]]:
     """
-    Convenience function to process GRN completion stock updates.
+    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
@@ -120,4 +121,50 @@ async def get_stock_history(
         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)
+    return await stock_service.get_stock_ledger(merchant_id, sku, batch_no, limit)
+
+
+async def reserve_stock(
+    db: AsyncSession,
+    merchant_id: str,
+    location_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, location_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, location_id, sku, batch_no, 
+        Decimal(str(qty)), ref_id, created_by
+    )
+
+
+async def release_stock_reservation(
+    db: AsyncSession,
+    merchant_id: str,
+    location_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

examples/create_salon_test_catalogues.py

@@ -12,13 +12,13 @@ This script creates comprehensive salon test data including:
 import asyncio
 import json
 import uuid
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from typing import Dict, Any, List
 import sys
 import os
 
-# Add the app directory to Python path
-sys.path.append(os.path.join(os.path.dirname(__file__), 'app'))
+# Add the parent directory to Python path to access app module
+sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
 
 from motor.motor_asyncio import AsyncIOMotorClient
 from app.catalogues.models.model import (
@@ -180,7 +180,7 @@ class SalonCatalogueGenerator:
                     "barcode_number": f"BC{uuid.uuid4().hex[:10].upper()}"
                 },
                 
-                "attributes": product["attributes"],
+                "attributes": Attributes(**product["attributes"]).model_dump(),
                 
                 "pricing": {
                     **product["pricing"],
@@ -203,9 +203,8 @@ class SalonCatalogueGenerator:
                 
                 "procurement": {
                     "moq": 10,
-                    "manufacturing_date": datetime.utcnow() - timedelta(days=30),
-                    "expiry_date": datetime.utcnow() + timedelta(days=730),
-                    "vendor_ref": f"VEN-{uuid.uuid4().hex[:6].upper()}"
+                    "batch_managed": False,
+                    "expiry_period_months": 24
                 },
                 
                 "inventory": {
@@ -310,7 +309,7 @@ class SalonCatalogueGenerator:
                     "sku": f"SRV-{uuid.uuid4().hex[:8].upper()}",
                 },
                 
-                "attributes": service["attributes"],
+                "attributes": Attributes(**service["attributes"]).model_dump(),
                 
                 "pricing": {
                     **service["pricing"],
@@ -402,9 +401,7 @@ class SalonCatalogueGenerator:
                     "sku": f"PKG-{uuid.uuid4().hex[:8].upper()}",
                 },
                 
-                "attributes": {
-                    "services_included": ", ".join(package["services_included"])
-                },
+                "attributes": Attributes().model_dump(),
                 
                 "pricing": {
                     **package["pricing"],
@@ -503,10 +500,6 @@ class SalonCatalogueGenerator:
                 json_data = []
                 for cat in all_catalogues:
                     cat_copy = cat.copy()
-                    if cat_copy.get("procurement", {}).get("manufacturing_date"):
-                        cat_copy["procurement"]["manufacturing_date"] = cat_copy["procurement"]["manufacturing_date"].isoformat()
-                    if cat_copy.get("procurement", {}).get("expiry_date"):
-                        cat_copy["procurement"]["expiry_date"] = cat_copy["procurement"]["expiry_date"].isoformat()
                     if cat_copy.get("meta", {}).get("created_at"):
                         cat_copy["meta"]["created_at"] = cat_copy["meta"]["created_at"].isoformat()
                     json_data.append(cat_copy)

salon_catalogues_data.json

@@ -0,0 +1,1262 @@
+[
+  {
+    "catalogue_id": "d8376e76-7279-470d-b129-a3bc3c26ffb6",
+    "catalogue_name": "L'Or\u00e9al Professional Shampoo - Hydrating",
+    "catalogue_type": "Product",
+    "category": "Hair Care",
+    "brand": "L'Or\u00e9al Professional",
+    "description": "Professional hydrating shampoo for dry and damaged hair",
+    "identifiers": {
+      "sku": "SKU-ED7878D9",
+      "ean_code": "890103018244b",
+      "barcode_number": "BCC6DD9A5549"
+    },
+    "attributes": {
+      "size": "500ml",
+      "variant": null,
+      "hair_type": "Dry/Damaged",
+      "skin_type": null,
+      "nail_type": null,
+      "gender": null,
+      "fragrance": null,
+      "color": null,
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 1200.0,
+      "mrp": 1500.0,
+      "trade_margin": 20.0,
+      "retail_margin": 20.0,
+      "currency": "INR",
+      "discount": 0.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 5.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 12,
+      "redeem_allowed": true
+    },
+    "procurement": {
+      "moq": 10,
+      "batch_managed": false,
+      "expiry_period_months": 24
+    },
+    "inventory": {
+      "track_inventory": true,
+      "stock_on_hand": 50,
+      "ordered_quantity": 0,
+      "reorder_level": 10,
+      "unit": "PCS",
+      "warehouse": "Main Warehouse"
+    },
+    "tax": {
+      "hsn_code": "33051000",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/images/l'or\u00e9al-professional-shampoo---hydrating-1.jpg",
+        "https://example.com/images/l'or\u00e9al-professional-shampoo---hydrating-2.jpg"
+      ],
+      "banner_image": "https://example.com/banners/l'or\u00e9al-professional-shampoo---hydrating-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754103",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97e1"
+  },
+  {
+    "catalogue_id": "63dabde8-3b8a-4d49-b156-6051a7d11a67",
+    "catalogue_name": "Matrix Biolage Conditioner - Smoothing",
+    "catalogue_type": "Product",
+    "category": "Hair Care",
+    "brand": "Matrix",
+    "description": "Smoothing conditioner for frizzy and unmanageable hair",
+    "identifiers": {
+      "sku": "SKU-7EBA0728",
+      "ean_code": "8901030d61a59",
+      "barcode_number": "BC10C4E5723D"
+    },
+    "attributes": {
+      "size": "400ml",
+      "variant": null,
+      "hair_type": "Frizzy",
+      "skin_type": null,
+      "nail_type": null,
+      "gender": null,
+      "fragrance": null,
+      "color": null,
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 950.0,
+      "mrp": 1200.0,
+      "trade_margin": 18.0,
+      "retail_margin": 18.0,
+      "currency": "INR",
+      "discount": 0.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 5.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 9,
+      "redeem_allowed": true
+    },
+    "procurement": {
+      "moq": 10,
+      "batch_managed": false,
+      "expiry_period_months": 24
+    },
+    "inventory": {
+      "track_inventory": true,
+      "stock_on_hand": 50,
+      "ordered_quantity": 0,
+      "reorder_level": 10,
+      "unit": "PCS",
+      "warehouse": "Main Warehouse"
+    },
+    "tax": {
+      "hsn_code": "33051000",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/images/matrix-biolage-conditioner---smoothing-1.jpg",
+        "https://example.com/images/matrix-biolage-conditioner---smoothing-2.jpg"
+      ],
+      "banner_image": "https://example.com/banners/matrix-biolage-conditioner---smoothing-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754142",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97e2"
+  },
+  {
+    "catalogue_id": "6f6c6810-461d-4d0a-af95-a5345e5f355d",
+    "catalogue_name": "Schwarzkopf Hair Color - Ash Blonde",
+    "catalogue_type": "Product",
+    "category": "Hair Color",
+    "brand": "Schwarzkopf",
+    "description": "Professional permanent hair color in ash blonde shade",
+    "identifiers": {
+      "sku": "SKU-8A61124C",
+      "ean_code": "8901030e40e76",
+      "barcode_number": "BC52F2E2BAB0"
+    },
+    "attributes": {
+      "size": "60ml",
+      "variant": null,
+      "hair_type": null,
+      "skin_type": null,
+      "nail_type": null,
+      "gender": null,
+      "fragrance": null,
+      "color": "Ash Blonde",
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 450.0,
+      "mrp": 600.0,
+      "trade_margin": 25.0,
+      "retail_margin": 25.0,
+      "currency": "INR",
+      "discount": 0.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 5.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 4,
+      "redeem_allowed": true
+    },
+    "procurement": {
+      "moq": 10,
+      "batch_managed": false,
+      "expiry_period_months": 24
+    },
+    "inventory": {
+      "track_inventory": true,
+      "stock_on_hand": 50,
+      "ordered_quantity": 0,
+      "reorder_level": 10,
+      "unit": "PCS",
+      "warehouse": "Main Warehouse"
+    },
+    "tax": {
+      "hsn_code": "33051000",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/images/schwarzkopf-hair-color---ash-blonde-1.jpg",
+        "https://example.com/images/schwarzkopf-hair-color---ash-blonde-2.jpg"
+      ],
+      "banner_image": "https://example.com/banners/schwarzkopf-hair-color---ash-blonde-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754162",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97e3"
+  },
+  {
+    "catalogue_id": "917c150d-9431-4674-9132-926e3248dee3",
+    "catalogue_name": "Wella Hair Serum - Shine & Protection",
+    "catalogue_type": "Product",
+    "category": "Hair Treatment",
+    "brand": "Wella",
+    "description": "Lightweight serum for shine and heat protection",
+    "identifiers": {
+      "sku": "SKU-C0E97B3E",
+      "ean_code": "89010302a12e6",
+      "barcode_number": "BCD6FF3E5B29"
+    },
+    "attributes": {
+      "size": "100ml",
+      "variant": null,
+      "hair_type": "All Types",
+      "skin_type": null,
+      "nail_type": null,
+      "gender": null,
+      "fragrance": null,
+      "color": null,
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 800.0,
+      "mrp": 1000.0,
+      "trade_margin": 20.0,
+      "retail_margin": 20.0,
+      "currency": "INR",
+      "discount": 0.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 5.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 8,
+      "redeem_allowed": true
+    },
+    "procurement": {
+      "moq": 10,
+      "batch_managed": false,
+      "expiry_period_months": 24
+    },
+    "inventory": {
+      "track_inventory": true,
+      "stock_on_hand": 50,
+      "ordered_quantity": 0,
+      "reorder_level": 10,
+      "unit": "PCS",
+      "warehouse": "Main Warehouse"
+    },
+    "tax": {
+      "hsn_code": "33051000",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/images/wella-hair-serum---shine-&-protection-1.jpg",
+        "https://example.com/images/wella-hair-serum---shine-&-protection-2.jpg"
+      ],
+      "banner_image": "https://example.com/banners/wella-hair-serum---shine-&-protection-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754176",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97e4"
+  },
+  {
+    "catalogue_id": "0e7aaae0-aeed-41ff-a5db-b918e954a43a",
+    "catalogue_name": "Olay Regenerist Face Cleanser",
+    "catalogue_type": "Product",
+    "category": "Skin Care",
+    "brand": "Olay",
+    "description": "Anti-aging face cleanser with amino-peptides",
+    "identifiers": {
+      "sku": "SKU-FC983357",
+      "ean_code": "8901030188ba8",
+      "barcode_number": "BC490EF5A83C"
+    },
+    "attributes": {
+      "size": "150ml",
+      "variant": null,
+      "hair_type": null,
+      "skin_type": "Mature",
+      "nail_type": null,
+      "gender": null,
+      "fragrance": null,
+      "color": null,
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 650.0,
+      "mrp": 799.0,
+      "trade_margin": 15.0,
+      "retail_margin": 15.0,
+      "currency": "INR",
+      "discount": 0.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 5.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 6,
+      "redeem_allowed": true
+    },
+    "procurement": {
+      "moq": 10,
+      "batch_managed": false,
+      "expiry_period_months": 24
+    },
+    "inventory": {
+      "track_inventory": true,
+      "stock_on_hand": 50,
+      "ordered_quantity": 0,
+      "reorder_level": 10,
+      "unit": "PCS",
+      "warehouse": "Main Warehouse"
+    },
+    "tax": {
+      "hsn_code": "33049900",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/images/olay-regenerist-face-cleanser-1.jpg",
+        "https://example.com/images/olay-regenerist-face-cleanser-2.jpg"
+      ],
+      "banner_image": "https://example.com/banners/olay-regenerist-face-cleanser-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754189",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97e5"
+  },
+  {
+    "catalogue_id": "1965ac40-2056-4b80-9ff1-3d8d524bd084",
+    "catalogue_name": "Neutrogena Hydrating Face Mask",
+    "catalogue_type": "Product",
+    "category": "Face Mask",
+    "brand": "Neutrogena",
+    "description": "Intensive hydrating face mask for dry skin",
+    "identifiers": {
+      "sku": "SKU-AFBB0DC6",
+      "ean_code": "890103022de49",
+      "barcode_number": "BC51977E3095"
+    },
+    "attributes": {
+      "size": "50ml",
+      "variant": null,
+      "hair_type": null,
+      "skin_type": "Dry",
+      "nail_type": null,
+      "gender": null,
+      "fragrance": null,
+      "color": null,
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 350.0,
+      "mrp": 450.0,
+      "trade_margin": 22.0,
+      "retail_margin": 22.0,
+      "currency": "INR",
+      "discount": 0.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 5.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 3,
+      "redeem_allowed": true
+    },
+    "procurement": {
+      "moq": 10,
+      "batch_managed": false,
+      "expiry_period_months": 24
+    },
+    "inventory": {
+      "track_inventory": true,
+      "stock_on_hand": 50,
+      "ordered_quantity": 0,
+      "reorder_level": 10,
+      "unit": "PCS",
+      "warehouse": "Main Warehouse"
+    },
+    "tax": {
+      "hsn_code": "33049900",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/images/neutrogena-hydrating-face-mask-1.jpg",
+        "https://example.com/images/neutrogena-hydrating-face-mask-2.jpg"
+      ],
+      "banner_image": "https://example.com/banners/neutrogena-hydrating-face-mask-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754205",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97e6"
+  },
+  {
+    "catalogue_id": "09c24693-a18e-479d-b043-4300d60c6570",
+    "catalogue_name": "The Body Shop Vitamin E Moisturizer",
+    "catalogue_type": "Product",
+    "category": "Moisturizer",
+    "brand": "The Body Shop",
+    "description": "Daily moisturizer with Vitamin E for all skin types",
+    "identifiers": {
+      "sku": "SKU-B7966891",
+      "ean_code": "8901030530f24",
+      "barcode_number": "BC4A3C8688A7"
+    },
+    "attributes": {
+      "size": "100ml",
+      "variant": null,
+      "hair_type": null,
+      "skin_type": "All Types",
+      "nail_type": null,
+      "gender": null,
+      "fragrance": null,
+      "color": null,
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 1200.0,
+      "mrp": 1495.0,
+      "trade_margin": 20.0,
+      "retail_margin": 20.0,
+      "currency": "INR",
+      "discount": 0.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 5.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 12,
+      "redeem_allowed": true
+    },
+    "procurement": {
+      "moq": 10,
+      "batch_managed": false,
+      "expiry_period_months": 24
+    },
+    "inventory": {
+      "track_inventory": true,
+      "stock_on_hand": 50,
+      "ordered_quantity": 0,
+      "reorder_level": 10,
+      "unit": "PCS",
+      "warehouse": "Main Warehouse"
+    },
+    "tax": {
+      "hsn_code": "33049900",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/images/the-body-shop-vitamin-e-moisturizer-1.jpg",
+        "https://example.com/images/the-body-shop-vitamin-e-moisturizer-2.jpg"
+      ],
+      "banner_image": "https://example.com/banners/the-body-shop-vitamin-e-moisturizer-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754217",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97e7"
+  },
+  {
+    "catalogue_id": "209b07ad-a0b8-41b3-8c3a-627ec517d64c",
+    "catalogue_name": "OPI Nail Polish - Classic Red",
+    "catalogue_type": "Product",
+    "category": "Nail Care",
+    "brand": "OPI",
+    "description": "Long-lasting nail polish in classic red shade",
+    "identifiers": {
+      "sku": "SKU-6B7E72FE",
+      "ean_code": "8901030f609e8",
+      "barcode_number": "BC813A6E1E60"
+    },
+    "attributes": {
+      "size": "15ml",
+      "variant": null,
+      "hair_type": null,
+      "skin_type": null,
+      "nail_type": null,
+      "gender": null,
+      "fragrance": null,
+      "color": "Classic Red",
+      "finish": "Glossy"
+    },
+    "pricing": {
+      "retail_price": 750.0,
+      "mrp": 950.0,
+      "trade_margin": 21.0,
+      "retail_margin": 21.0,
+      "currency": "INR",
+      "discount": 0.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 5.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 7,
+      "redeem_allowed": true
+    },
+    "procurement": {
+      "moq": 10,
+      "batch_managed": false,
+      "expiry_period_months": 24
+    },
+    "inventory": {
+      "track_inventory": true,
+      "stock_on_hand": 50,
+      "ordered_quantity": 0,
+      "reorder_level": 10,
+      "unit": "PCS",
+      "warehouse": "Main Warehouse"
+    },
+    "tax": {
+      "hsn_code": "33043000",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/images/opi-nail-polish---classic-red-1.jpg",
+        "https://example.com/images/opi-nail-polish---classic-red-2.jpg"
+      ],
+      "banner_image": "https://example.com/banners/opi-nail-polish---classic-red-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754231",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97e8"
+  },
+  {
+    "catalogue_id": "889923e2-3ee3-4169-809a-37f30c01bd49",
+    "catalogue_name": "Essie Base Coat - Strong Start",
+    "catalogue_type": "Product",
+    "category": "Nail Care",
+    "brand": "Essie",
+    "description": "Strengthening base coat for healthy nails",
+    "identifiers": {
+      "sku": "SKU-E0D8EE03",
+      "ean_code": "89010304da911",
+      "barcode_number": "BC95174F1F0C"
+    },
+    "attributes": {
+      "size": "13.5ml",
+      "variant": null,
+      "hair_type": null,
+      "skin_type": null,
+      "nail_type": "Weak",
+      "gender": null,
+      "fragrance": null,
+      "color": null,
+      "finish": "Clear"
+    },
+    "pricing": {
+      "retail_price": 550.0,
+      "mrp": 699.0,
+      "trade_margin": 21.0,
+      "retail_margin": 21.0,
+      "currency": "INR",
+      "discount": 0.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 5.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 5,
+      "redeem_allowed": true
+    },
+    "procurement": {
+      "moq": 10,
+      "batch_managed": false,
+      "expiry_period_months": 24
+    },
+    "inventory": {
+      "track_inventory": true,
+      "stock_on_hand": 50,
+      "ordered_quantity": 0,
+      "reorder_level": 10,
+      "unit": "PCS",
+      "warehouse": "Main Warehouse"
+    },
+    "tax": {
+      "hsn_code": "33043000",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/images/essie-base-coat---strong-start-1.jpg",
+        "https://example.com/images/essie-base-coat---strong-start-2.jpg"
+      ],
+      "banner_image": "https://example.com/banners/essie-base-coat---strong-start-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754243",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97e9"
+  },
+  {
+    "catalogue_id": "b78c33c5-d15a-4c72-a183-4fb67d7a04f4",
+    "catalogue_name": "Sally Hansen Cuticle Oil",
+    "catalogue_type": "Product",
+    "category": "Nail Treatment",
+    "brand": "Sally Hansen",
+    "description": "Nourishing cuticle oil with vitamin E",
+    "identifiers": {
+      "sku": "SKU-975BB8C6",
+      "ean_code": "890103029066d",
+      "barcode_number": "BC68188D6AE4"
+    },
+    "attributes": {
+      "size": "11ml",
+      "variant": null,
+      "hair_type": null,
+      "skin_type": null,
+      "nail_type": "All Types",
+      "gender": null,
+      "fragrance": null,
+      "color": null,
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 400.0,
+      "mrp": 525.0,
+      "trade_margin": 24.0,
+      "retail_margin": 24.0,
+      "currency": "INR",
+      "discount": 0.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 5.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 4,
+      "redeem_allowed": true
+    },
+    "procurement": {
+      "moq": 10,
+      "batch_managed": false,
+      "expiry_period_months": 24
+    },
+    "inventory": {
+      "track_inventory": true,
+      "stock_on_hand": 50,
+      "ordered_quantity": 0,
+      "reorder_level": 10,
+      "unit": "PCS",
+      "warehouse": "Main Warehouse"
+    },
+    "tax": {
+      "hsn_code": "33043000",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/images/sally-hansen-cuticle-oil-1.jpg",
+        "https://example.com/images/sally-hansen-cuticle-oil-2.jpg"
+      ],
+      "banner_image": "https://example.com/banners/sally-hansen-cuticle-oil-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754254",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97ea"
+  },
+  {
+    "catalogue_id": "edaf1100-f650-4dbb-9e85-f8a3c0d7ab87",
+    "catalogue_name": "Hair Cut & Styling - Women",
+    "catalogue_type": "Service",
+    "category": "Hair Services",
+    "brand": null,
+    "description": "Professional hair cut and styling for women",
+    "identifiers": {
+      "sku": "SRV-356C5783"
+    },
+    "attributes": {
+      "size": null,
+      "variant": null,
+      "hair_type": "All Types",
+      "skin_type": null,
+      "nail_type": null,
+      "gender": "Female",
+      "fragrance": null,
+      "color": null,
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 800.0,
+      "mrp": 1000.0,
+      "retail_margin": 40.0,
+      "trade_margin": 0.0,
+      "currency": "INR",
+      "discount": 0.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 10.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 16,
+      "redeem_allowed": true
+    },
+    "inventory": {
+      "track_inventory": false,
+      "unit": "SERVICE"
+    },
+    "tax": {
+      "hsn_code": "99820000",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/services/hair-cut-&-styling---women-1.jpg"
+      ],
+      "banner_image": "https://example.com/services/hair-cut-&-styling---women-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754283",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97eb"
+  },
+  {
+    "catalogue_id": "5afddf66-7f53-4bf0-a6eb-bee47c93a133",
+    "catalogue_name": "Hair Cut & Styling - Men",
+    "catalogue_type": "Service",
+    "category": "Hair Services",
+    "brand": null,
+    "description": "Professional hair cut and styling for men",
+    "identifiers": {
+      "sku": "SRV-21481FBE"
+    },
+    "attributes": {
+      "size": null,
+      "variant": null,
+      "hair_type": "All Types",
+      "skin_type": null,
+      "nail_type": null,
+      "gender": "Male",
+      "fragrance": null,
+      "color": null,
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 500.0,
+      "mrp": 650.0,
+      "retail_margin": 40.0,
+      "trade_margin": 0.0,
+      "currency": "INR",
+      "discount": 0.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 10.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 10,
+      "redeem_allowed": true
+    },
+    "inventory": {
+      "track_inventory": false,
+      "unit": "SERVICE"
+    },
+    "tax": {
+      "hsn_code": "99820000",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/services/hair-cut-&-styling---men-1.jpg"
+      ],
+      "banner_image": "https://example.com/services/hair-cut-&-styling---men-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754302",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97ec"
+  },
+  {
+    "catalogue_id": "5006d81d-fd12-4763-b06f-23a3d3f2718d",
+    "catalogue_name": "Hair Color - Full Head",
+    "catalogue_type": "Service",
+    "category": "Hair Services",
+    "brand": null,
+    "description": "Complete hair coloring service with professional products",
+    "identifiers": {
+      "sku": "SRV-77142B53"
+    },
+    "attributes": {
+      "size": null,
+      "variant": null,
+      "hair_type": "All Types",
+      "skin_type": null,
+      "nail_type": null,
+      "gender": null,
+      "fragrance": null,
+      "color": null,
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 2500.0,
+      "mrp": 3000.0,
+      "retail_margin": 40.0,
+      "trade_margin": 0.0,
+      "currency": "INR",
+      "discount": 0.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 10.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 50,
+      "redeem_allowed": true
+    },
+    "inventory": {
+      "track_inventory": false,
+      "unit": "SERVICE"
+    },
+    "tax": {
+      "hsn_code": "99820000",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/services/hair-color---full-head-1.jpg"
+      ],
+      "banner_image": "https://example.com/services/hair-color---full-head-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754314",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97ed"
+  },
+  {
+    "catalogue_id": "99593e1a-d439-4b42-8d33-e5fdc16eeccc",
+    "catalogue_name": "Facial - Deep Cleansing",
+    "catalogue_type": "Service",
+    "category": "Skin Services",
+    "brand": null,
+    "description": "Deep cleansing facial with extraction and moisturizing",
+    "identifiers": {
+      "sku": "SRV-E32BBE70"
+    },
+    "attributes": {
+      "size": null,
+      "variant": null,
+      "hair_type": null,
+      "skin_type": "All Types",
+      "nail_type": null,
+      "gender": null,
+      "fragrance": null,
+      "color": null,
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 1200.0,
+      "mrp": 1500.0,
+      "retail_margin": 40.0,
+      "trade_margin": 0.0,
+      "currency": "INR",
+      "discount": 0.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 10.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 24,
+      "redeem_allowed": true
+    },
+    "inventory": {
+      "track_inventory": false,
+      "unit": "SERVICE"
+    },
+    "tax": {
+      "hsn_code": "99820000",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/services/facial---deep-cleansing-1.jpg"
+      ],
+      "banner_image": "https://example.com/services/facial---deep-cleansing-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754322",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97ee"
+  },
+  {
+    "catalogue_id": "b452213a-d3ed-471d-b416-5cce037da8eb",
+    "catalogue_name": "Manicure - Classic",
+    "catalogue_type": "Service",
+    "category": "Nail Services",
+    "brand": null,
+    "description": "Classic manicure with nail shaping, cuticle care, and polish",
+    "identifiers": {
+      "sku": "SRV-65EA6C35"
+    },
+    "attributes": {
+      "size": null,
+      "variant": null,
+      "hair_type": null,
+      "skin_type": null,
+      "nail_type": "All Types",
+      "gender": null,
+      "fragrance": null,
+      "color": null,
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 600.0,
+      "mrp": 750.0,
+      "retail_margin": 40.0,
+      "trade_margin": 0.0,
+      "currency": "INR",
+      "discount": 0.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 10.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 12,
+      "redeem_allowed": true
+    },
+    "inventory": {
+      "track_inventory": false,
+      "unit": "SERVICE"
+    },
+    "tax": {
+      "hsn_code": "99820000",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/services/manicure---classic-1.jpg"
+      ],
+      "banner_image": "https://example.com/services/manicure---classic-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754331",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97ef"
+  },
+  {
+    "catalogue_id": "a6786f4c-33cf-433b-bf92-fc04225be916",
+    "catalogue_name": "Pedicure - Spa",
+    "catalogue_type": "Service",
+    "category": "Nail Services",
+    "brand": null,
+    "description": "Relaxing spa pedicure with foot massage and polish",
+    "identifiers": {
+      "sku": "SRV-98F4A078"
+    },
+    "attributes": {
+      "size": null,
+      "variant": null,
+      "hair_type": null,
+      "skin_type": null,
+      "nail_type": "All Types",
+      "gender": null,
+      "fragrance": null,
+      "color": null,
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 800.0,
+      "mrp": 1000.0,
+      "retail_margin": 40.0,
+      "trade_margin": 0.0,
+      "currency": "INR",
+      "discount": 0.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 10.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 16,
+      "redeem_allowed": true
+    },
+    "inventory": {
+      "track_inventory": false,
+      "unit": "SERVICE"
+    },
+    "tax": {
+      "hsn_code": "99820000",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/services/pedicure---spa-1.jpg"
+      ],
+      "banner_image": "https://example.com/services/pedicure---spa-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754338",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97f0"
+  },
+  {
+    "catalogue_id": "2553a8ba-d48d-4b1d-bd40-d54bc57c4e52",
+    "catalogue_name": "Bridal Beauty Package",
+    "catalogue_type": "Package",
+    "category": "Beauty Packages",
+    "brand": null,
+    "description": "Complete bridal beauty package including hair, makeup, and nail services",
+    "identifiers": {
+      "sku": "PKG-6B180B14"
+    },
+    "attributes": {
+      "size": null,
+      "variant": null,
+      "hair_type": null,
+      "skin_type": null,
+      "nail_type": null,
+      "gender": null,
+      "fragrance": null,
+      "color": null,
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 8000.0,
+      "mrp": 10000.0,
+      "retail_margin": 45.0,
+      "trade_margin": 0.0,
+      "currency": "INR",
+      "discount": 10.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 15.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 240,
+      "redeem_allowed": true
+    },
+    "inventory": {
+      "track_inventory": false,
+      "unit": "PACKAGE"
+    },
+    "tax": {
+      "hsn_code": "99820000",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/packages/bridal-beauty-package-1.jpg"
+      ],
+      "banner_image": "https://example.com/packages/bridal-beauty-package-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754361",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97f1"
+  },
+  {
+    "catalogue_id": "3e840d3f-9597-4790-bc30-43b10a1c5292",
+    "catalogue_name": "Monthly Hair Care Package",
+    "catalogue_type": "Package",
+    "category": "Hair Packages",
+    "brand": null,
+    "description": "Monthly hair care package with cut, treatment, and styling",
+    "identifiers": {
+      "sku": "PKG-418995E2"
+    },
+    "attributes": {
+      "size": null,
+      "variant": null,
+      "hair_type": null,
+      "skin_type": null,
+      "nail_type": null,
+      "gender": null,
+      "fragrance": null,
+      "color": null,
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 3000.0,
+      "mrp": 3500.0,
+      "retail_margin": 45.0,
+      "trade_margin": 0.0,
+      "currency": "INR",
+      "discount": 10.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 15.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 90,
+      "redeem_allowed": true
+    },
+    "inventory": {
+      "track_inventory": false,
+      "unit": "PACKAGE"
+    },
+    "tax": {
+      "hsn_code": "99820000",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/packages/monthly-hair-care-package-1.jpg"
+      ],
+      "banner_image": "https://example.com/packages/monthly-hair-care-package-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754374",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97f2"
+  },
+  {
+    "catalogue_id": "d4d54115-c091-4b14-809c-0d7367c11d63",
+    "catalogue_name": "Skin Rejuvenation Package",
+    "catalogue_type": "Package",
+    "category": "Skin Packages",
+    "brand": null,
+    "description": "Complete skin rejuvenation with multiple facial treatments",
+    "identifiers": {
+      "sku": "PKG-4F4338FC"
+    },
+    "attributes": {
+      "size": null,
+      "variant": null,
+      "hair_type": null,
+      "skin_type": null,
+      "nail_type": null,
+      "gender": null,
+      "fragrance": null,
+      "color": null,
+      "finish": null
+    },
+    "pricing": {
+      "retail_price": 4500.0,
+      "mrp": 5500.0,
+      "retail_margin": 45.0,
+      "trade_margin": 0.0,
+      "currency": "INR",
+      "discount": 10.0
+    },
+    "commission": {
+      "enabled": true,
+      "type": "Percent",
+      "value": 15.0
+    },
+    "loyalty": {
+      "enabled": true,
+      "points": 135,
+      "redeem_allowed": true
+    },
+    "inventory": {
+      "track_inventory": false,
+      "unit": "PACKAGE"
+    },
+    "tax": {
+      "hsn_code": "99820000",
+      "gst_rate": 18.0
+    },
+    "media": {
+      "images": [
+        "https://example.com/packages/skin-rejuvenation-package-1.jpg"
+      ],
+      "banner_image": "https://example.com/packages/skin-rejuvenation-package-banner.jpg"
+    },
+    "meta": {
+      "created_by": "system",
+      "created_at": "2025-12-15T04:04:52.754383",
+      "status": "Active"
+    },
+    "_id": "693f88e44189f9495e2f97f3"
+  }
+]

sql/stored_procedures/stock_management.sql

@@ -0,0 +1,238 @@
+-- Stock Management Stored Procedures
+-- Centralized inventory mutation logic in PostgreSQL
+
+-- Simplified stock movement function with idempotency
+CREATE OR REPLACE FUNCTION apply_stock_movement(
+    p_merchant_id TEXT,
+    p_location_id TEXT,
+    p_sku TEXT,
+    p_batch_no TEXT,
+    p_qty NUMERIC,
+    p_txn_type TEXT,
+    p_ref_type TEXT,
+    p_ref_id UUID,
+    p_ref_no TEXT,
+    p_user TEXT
+) RETURNS VOID AS $$
+BEGIN
+    -- Idempotency check - prevent duplicate processing
+    IF EXISTS (
+        SELECT 1 FROM scm_stock_ledger 
+        WHERE ref_type = p_ref_type AND ref_id = p_ref_id AND sku = p_sku AND batch_no = p_batch_no
+    ) THEN
+        RETURN;
+    END IF;
+    
+    -- Insert ledger entry (immutable audit trail)
+    INSERT INTO scm_stock_ledger (
+        ledger_id, merchant_id, location_id, sku, batch_no,
+        qty, txn_type, ref_type, ref_id, ref_no, created_by
+    ) VALUES (
+        gen_random_uuid(), p_merchant_id, p_location_id, p_sku, p_batch_no,
+        p_qty, p_txn_type, p_ref_type, p_ref_id, p_ref_no, p_user
+    );
+    
+    -- Stock snapshot upsert (create or update)
+    INSERT INTO scm_stock (
+        stock_id, merchant_id, location_id, sku, batch_no,
+        qty_on_hand, qty_reserved, qty_available
+    ) VALUES (
+        gen_random_uuid(), p_merchant_id, p_location_id, p_sku, p_batch_no,
+        p_qty, 0, p_qty
+    )
+    ON CONFLICT (merchant_id, location_id, sku, batch_no)
+    DO UPDATE SET
+        qty_on_hand = scm_stock.qty_on_hand + p_qty,
+        qty_available = scm_stock.qty_available + p_qty,
+        last_updated_at = NOW();
+END;
+$$ LANGUAGE plpgsql;
+
+-- Function to process multiple stock movements atomically (for GRN completion)
+CREATE OR REPLACE FUNCTION apply_bulk_stock_movements(
+    p_movements JSONB
+) RETURNS JSONB
+LANGUAGE plpgsql
+AS $$
+DECLARE
+    v_movement JSONB;
+    v_ledger_id UUID;
+    v_results JSONB := '[]'::JSONB;
+    v_result JSONB;
+BEGIN
+    -- Process each movement in the array
+    FOR v_movement IN SELECT * FROM jsonb_array_elements(p_movements)
+    LOOP
+        -- Apply individual stock movement
+        SELECT apply_stock_movement(
+            (v_movement->>'merchant_id')::VARCHAR(64),
+            (v_movement->>'location_id')::VARCHAR(64),
+            (v_movement->>'catalogue_id')::UUID,
+            (v_movement->>'sku')::VARCHAR(64),
+            (v_movement->>'batch_no')::VARCHAR(50),
+            (v_movement->>'exp_dt')::DATE,
+            (v_movement->>'qty')::NUMERIC(14,3),
+            (v_movement->>'uom')::VARCHAR(10),
+            (v_movement->>'txn_type')::VARCHAR(30),
+            (v_movement->>'ref_type')::VARCHAR(30),
+            (v_movement->>'ref_id')::UUID,
+            (v_movement->>'ref_no')::VARCHAR(50),
+            (v_movement->>'remarks')::TEXT,
+            (v_movement->>'created_by')::VARCHAR(64)
+        ) INTO v_ledger_id;
+        
+        -- Build result object
+        v_result := jsonb_build_object(
+            'ledger_id', v_ledger_id,
+            'sku', v_movement->>'sku',
+            'qty', v_movement->>'qty',
+            'success', true
+        );
+        
+        -- Add to results array
+        v_results := v_results || v_result;
+    END LOOP;
+    
+    RETURN v_results;
+END;
+$$;
+
+-- Function to reserve stock (for sales orders)
+CREATE OR REPLACE FUNCTION reserve_stock(
+    p_merchant_id VARCHAR(64),
+    p_location_id VARCHAR(64),
+    p_sku VARCHAR(64),
+    p_batch_no VARCHAR(50),
+    p_qty NUMERIC(14,3),
+    p_ref_id UUID,
+    p_created_by VARCHAR(64)
+) RETURNS BOOLEAN
+LANGUAGE plpgsql
+AS $$
+DECLARE
+    v_available_qty NUMERIC(14,3);
+BEGIN
+    -- Get current available quantity
+    SELECT qty_available
+    INTO v_available_qty
+    FROM scm_stock
+    WHERE merchant_id = p_merchant_id
+      AND location_id = p_location_id
+      AND sku = p_sku
+      AND batch_no = p_batch_no;
+    
+    -- Check if sufficient stock available
+    IF v_available_qty IS NULL OR v_available_qty < p_qty THEN
+        RAISE EXCEPTION 'Insufficient available stock for SKU: %. Available: %, Required: %', 
+            p_sku, COALESCE(v_available_qty, 0), p_qty;
+    END IF;
+    
+    -- Update stock reservation
+    UPDATE scm_stock
+    SET qty_reserved = qty_reserved + p_qty,
+        qty_available = qty_available - p_qty,
+        last_updated_at = NOW()
+    WHERE merchant_id = p_merchant_id
+      AND location_id = p_location_id
+      AND sku = p_sku
+      AND batch_no = p_batch_no;
+    
+    RETURN TRUE;
+END;
+$$;
+
+-- Function to release stock reservation
+CREATE OR REPLACE FUNCTION release_stock_reservation(
+    p_merchant_id VARCHAR(64),
+    p_location_id VARCHAR(64),
+    p_sku VARCHAR(64),
+    p_batch_no VARCHAR(50),
+    p_qty NUMERIC(14,3),
+    p_ref_id UUID,
+    p_created_by VARCHAR(64)
+) RETURNS BOOLEAN
+LANGUAGE plpgsql
+AS $$
+BEGIN
+    -- Update stock reservation
+    UPDATE scm_stock
+    SET qty_reserved = GREATEST(qty_reserved - p_qty, 0),
+        qty_available = qty_on_hand - GREATEST(qty_reserved - p_qty, 0),
+        last_updated_at = NOW()
+    WHERE merchant_id = p_merchant_id
+      AND location_id = p_location_id
+      AND sku = p_sku
+      AND batch_no = p_batch_no;
+    
+    RETURN TRUE;
+END;
+$$;
+
+-- Function to get current stock summary
+CREATE OR REPLACE FUNCTION get_stock_summary(
+    p_merchant_id VARCHAR(64),
+    p_location_id VARCHAR(64) DEFAULT NULL,
+    p_sku VARCHAR(64) DEFAULT NULL
+) RETURNS TABLE (
+    stock_id UUID,
+    location_id VARCHAR(64),
+    catalogue_id UUID,
+    sku VARCHAR(64),
+    batch_no VARCHAR(50),
+    qty_on_hand NUMERIC(14,3),
+    qty_reserved NUMERIC(14,3),
+    qty_available NUMERIC(14,3),
+    uom VARCHAR(10),
+    last_updated_at TIMESTAMP
+)
+LANGUAGE plpgsql
+AS $$
+BEGIN
+    RETURN QUERY
+    SELECT s.stock_id, s.location_id, s.catalogue_id, s.sku, s.batch_no,
+           s.qty_on_hand, s.qty_reserved, s.qty_available, s.uom, s.last_updated_at
+    FROM scm_stock s
+    WHERE s.merchant_id = p_merchant_id
+      AND (p_location_id IS NULL OR s.location_id = p_location_id)
+      AND (p_sku IS NULL OR s.sku = p_sku)
+    ORDER BY s.sku, s.batch_no;
+END;
+$$;
+
+-- Function to get stock ledger history
+CREATE OR REPLACE FUNCTION get_stock_ledger(
+    p_merchant_id VARCHAR(64),
+    p_sku VARCHAR(64) DEFAULT NULL,
+    p_batch_no VARCHAR(50) DEFAULT NULL,
+    p_limit INTEGER DEFAULT 100
+) RETURNS TABLE (
+    ledger_id UUID,
+    location_id VARCHAR(64),
+    catalogue_id UUID,
+    sku VARCHAR(64),
+    batch_no VARCHAR(50),
+    txn_type VARCHAR(30),
+    qty NUMERIC(14,3),
+    uom VARCHAR(10),
+    ref_type VARCHAR(30),
+    ref_id UUID,
+    ref_no VARCHAR(50),
+    remarks TEXT,
+    created_by VARCHAR(64),
+    created_at TIMESTAMP
+)
+LANGUAGE plpgsql
+AS $$
+BEGIN
+    RETURN QUERY
+    SELECT l.ledger_id, l.location_id, l.catalogue_id, l.sku, l.batch_no,
+           l.txn_type, l.qty, l.uom, l.ref_type, l.ref_id, l.ref_no,
+           l.remarks, l.created_by, l.created_at
+    FROM scm_stock_ledger l
+    WHERE l.merchant_id = p_merchant_id
+      AND (p_sku IS NULL OR l.sku = p_sku)
+      AND (p_batch_no IS NULL OR l.batch_no = p_batch_no)
+    ORDER BY l.created_at DESC
+    LIMIT p_limit;
+END;
+$$;