Stock Management

This module is the operational core of inventory control. It tracks live stock quantity, inbound and outbound movement, warehouse transfer, adjustment approvals, and customer waitlists.

Part A: Non-Technical Guide (Business Users)

1. What You Can Control

• See live stock for all products and warehouses from Stock Overview.
• Check full stock-in history from purchases.
• Check stock-out history from sales.
• Transfer stock between warehouses with audit trail.
• Review timeline of every stock movement (add, sell, return, transfer, adjustment).
• Use StockGuard approval flow for risky manual stock adjustments.
• Track customer waitlists when products are out of stock.

2. Stock Menu Meaning (Detailed)

3. Daily Operations Flow (Recommended)

1. Receive goods with Stock In.
2. Verify updated quantity in Stock Overview.
3. If warehouse balancing needed, use Stock Transfer.
4. Monitor outgoing sales from Stock Out.
5. If mismatch found, use StockGuard request instead of direct unsafe edits.
6. If demand exceeds stock, monitor Waitlists.
7. Audit all events from Stock Timeline.

4. Common Business Rules

• Source and destination warehouse cannot be the same in transfer.
• Transfer quantity cannot exceed available source quantity.
• StockGuard can force approval for high quantity/value adjustments.
• Cancelled waitlist automatically releases reserved quantities.
• Returned purchase or sales updates stock movement history automatically.

5. How to Add / Edit in Each Stock Section (Step by Step)

Stock Overview

• Add: This section is read-only. New rows appear automatically after Stock In, Transfer, Return, or approved StockGuard adjustments.
• Edit: Direct edit is not done here. To change quantity, go to Stock History update flow or StockGuard request flow.
• Use: Search/filter by category, brand, warehouse, demand tag and verify final available stock.

Stock History

1. Go to Stock > Stock History.
2. Find the line by product, lot, warehouse, supplier, or date filters.
3. Click quantity update action icon on target row.
4. Enter invoice number and new quantity input (as per allowed rules).
5. If StockGuard is active, provide valid reason and note where required.
6. Submit update and recheck row plus totals.

Stock In

1. Go to Stock > Stock In (purchase create).
2. Select supplier and warehouse.
3. Add products, lot/variant/price/qty fields properly.
4. Save purchase invoice.
5. Verify stock increment from Stock Overview and Stock History.

• Edit existing Stock In: Open related purchase record, update line values, and save (subject to business/permission constraints).

Purchase Return

1. Go to Stock > Purchase Return.
2. Select original purchase/invoice.
3. Choose return items and return quantities.
4. Submit return with reason/note if your process requires.
5. Confirm stock is reduced and return record appears in history.

• Edit: Usually handled via correction entry or additional return/payment action, not arbitrary overwrite.

Stock Out

• Add: Auto-created from sales flow. You do not manually create stock-out rows from this page.
• Edit: Edit source sales invoice/return flow; stock-out reflects from source transaction.
• Use: Audit sold quantity, invoice reference, and returnable quantity.

Stock Out Screen (POS Sale) Detailed Breakdown

1. Customer Search (top): Search customer by phone/name and attach customer to invoice. If not found, use the add button to create/select a new customer.
2. Customer Info Card: Shows selected customer profile (name, email, phone, address, tax/NID, rewards). This confirms sale is going to the correct customer account.
3. Product Search Bar: Search by product name, barcode, or combo bundle. Scanned barcode also resolves here for fast billing.
4. Quick Action Icons near product search: Add product line and shortcut operations like Sell Return, Create Quotation, and Customer Waitlist (based on enabled features and permissions).
5. Item Table: Each row is a sell line. Columns include Product, Quantity, Unit Price, Discount %, VAT %, and Total Price. Quantity edits directly affect stock deduction after confirm.
6. Row Controls: Add row button creates another line; remove button deletes line before final confirm.
7. Billing Panel (right side): Calculates Subtotal, Discount (amount or percent mode), VAT, Grand Total, Paid, Due, and Change Due in real time.
8. Payment Method Area: Select payment type (Cash/Card/Other configured methods). Plus button allows split/multiple payment lines when enabled.
9. Notes: Optional sale note for cashier/admin reference (used later in audit/reporting).
10. Confirm (Ctrl+S): Finalizes sale and creates stock-out movement. Inventory is reduced from matched stock lines (lot/warehouse policy based).
11. Draft (Ctrl+D): Saves bill as pending draft without completing stock-out transaction.
12. Cancel (Ctrl+C): Clears current cart form without posting sale.
13. Draft List (Ctrl+L): Opens saved drafts to resume/edit and confirm later.

Stock Out Processing Rules

• Stock is deducted only after Confirm, not while typing line items.
• If item stock is insufficient, system should block confirmation or require valid override flow based on permissions/settings.
• Discount and VAT are calculated line-wise and invoice-wise, then reflected in billing totals.
• On successful sale, stock-out records become visible in stock-out report/list and timeline audit.
• If sale return is processed later, corresponding return movement adjusts previously deducted stock.

Special Buttons Near Product Search

• These buttons are feature-driven and permission-driven. If feature is disabled or right is missing, the button may not appear.
• Sell Return affects stock movement immediately after return approval/confirmation.
• Quotation keeps commercial data for follow-up but does not behave as completed invoice.
• Waitlist helps capture missed sales opportunities and supports later reservation/claim flow.

Stock Transfer

1. Go to Stock > Stock Transfer.
2. Select From Warehouse and To Warehouse.
3. Select transfer date.
4. Select source stock item line (product/variant/lot).
5. Enter transfer quantity and click Add Line.
6. Add all required lines, review before/after qty preview.
7. Click Create Transfer.
8. Verify transfer appears in Recent Transfers list and Stock Overview.

• Edit: Existing transfer is typically immutable for audit safety. Do reverse transfer/correction transaction if needed.

Stock Timeline

• Add/Edit: Timeline is auto-generated from stock events; manual add/edit is not allowed.
• Use: Filter by movement type, warehouse, date range, and trace before/after quantities with reference id.

StockGuard

A) Create Adjustment Request

1. Go to Stock > StockGuard.
2. Select inventory item.
3. Enter quantity change (+/-), choose reason, add note if required.
4. Submit request.
5. If below thresholds, it may auto-apply; otherwise it goes pending.

B) Approve / Reject Request

1. Open pending request list.
2. Review qty change, reason, flags, and user info.
3. Click Approve to apply stock change or Reject with note.

C) Edit Rules

1. Open Rules tab.
2. Update unit threshold and value threshold.
3. Save rules and validate with a test request.

Waitlists

A) Add Waitlist

1. Waitlist rows are commonly created from sales/POS out-of-stock flow.
2. Required data: customer + product + requested qty.

B) View / Manage

1. Go to Stock > Waitlists.
2. Search/filter by customer/product/status.
3. Open details drawer from view action.

C) Cancel / Release / Claim

1. Cancel action closes waitlist and releases reserved quantities back to stock.
2. Claim marks reserved quantity as completed pickup/sale.
3. Release returns reservation to available stock without full cancellation.

Part B: Technical Documentation (Developers / Technical Admin)

1. Frontend File Map

• frontend-source/src/pages/stock/Stock.jsx - stock overview list, filters, export/copy, page totals, timeline modal trigger.
• frontend-source/src/pages/stock/StockHistory.jsx - stock-in history list, filters, quantity update modal.
• frontend-source/src/pages/stock/StockTransfers.jsx - warehouse transfer create form and transfer history.
• frontend-source/src/pages/stock/StockTimeline.jsx - global movement timeline with summary cards and filters.
• frontend-source/src/pages/stock/StockGuard.jsx - adjustment request review, approve/reject, threshold rules setup.
• frontend-source/src/pages/stock/Waitlists.jsx - waitlist list/details/cancel flow.

2. Backend File Map

• app/Http/Controllers/Api/PurchaseController.php + app/Services/Api/PurchaseControllerService.php - stock overview, stock-in list, quantity update.
• app/Http/Controllers/Api/StockController.php + app/Services/Api/StockService.php - stock-out and stock movement timeline API.
• app/Http/Controllers/Api/StockTransferController.php + app/Services/Api/StockTransferService.php.
• app/Http/Controllers/Api/StockGuardController.php + app/Services/Api/StockGuardService.php.
• app/Http/Controllers/Api/WaitlistController.php + app/Services/Api/WaitlistService.php.

3. Core Endpoints (Stock Domain)

4. Stock Overview Logic Notes

• Data source: Inventory with inventory_items.quantity > 0.
• Demand tag filter uses whereJsonContains('demand_tags').
• Category filter includes child categories recursively.
• Visible stock is adjusted by reserved bundle component quantity.
• Response returns grand_total_qty and grand_total_purchase_price.

5. Stock Transfer Technical Rules

• Validation: source warehouse, destination warehouse, transfer date, item lines required.
• Execution uses DB transaction + row locking (lockForUpdate).
• Deducts quantity from source inventory_items and source inventory.
• Creates/updates destination inventory and inserts destination inventory_items line.
• Writes auditable transfer lines in stock_transfer_items.
• Generates timeline entries: transferred_out and transferred_in.

6. StockGuard Deep Technical Explanation

A) Feature Switch and Access

• Primary feature code: ftr_stockguard.
• Defined in app/Data/FeaturePreference.php as STOCKGUARD.
• Service-level guard: StockGuardService::ensureEnabled() blocks API when feature is disabled.
• Routes: /stockguard/options, /stockguard/rules, /stockguard/requests, approve/reject endpoints.

B) Database Structure (from migrations)

1. Adjustment Table: stock_adjustment_requests (created by migration 2026_05_15_000006)

2. Company Rule Columns: migration 2026_05_24_000010 adds:

• company.stockguard_unit_threshold (default 5)
• company.stockguard_value_threshold (default 100)

C) Reason, Status, and Flag Enums

• Reasons: stock_count_correction, damaged, expired, lost, internal_use, found_stock, supplier_shortage, other.
• Note required: when reason is other.
• Statuses: pending, approved, rejected, applied.
• Flags: high_quantity, high_value, suspicious_reason.

D) Approval Decision Algorithm

Implemented in app/Data/StockGuardConfig.php:

• Approval required if abs(qty_change) >= unit_threshold.
• Approval required if abs(qty_change * unit_cost) >= value_threshold.
• Also forced pending if suspicious reason rule triggers for negative adjustment.

requiresApproval = abs(qty_change) >= unit_threshold
               OR abs(qty_change * unit_cost) >= value_threshold

E) Request Lifecycle

1. User submits adjustment request from StockGuard screen.
2. System validates inventory item, reason, note requirement.
3. System calculates flags and decides immediate apply vs pending.
4. If immediate: updates inventory_items.quantity and inventory.quantity, marks request applied.
5. If pending: creates request with pending, no stock mutation yet.
6. Approver can approve/reject pending request.
7. On approve: adjustment applied and status becomes applied.
8. On reject: status becomes rejected with optional rejection note.

F) Stock Movement Integration

• Every applied adjustment writes an audit entry via StockMovementService::record().
• Movement type: adjusted.
• Reference type: manual_adjustment.
• Stock Timeline module then shows this event with before/after quantity and actor.

G) Quantity Update from Stock History and StockGuard

• PurchaseControllerService::updateQuantity() is StockGuard-aware.
• When StockGuard feature is enabled, reason validation and threshold checks apply before stock mutation.
• If approval is required, a pending adjustment request is created instead of direct quantity apply.

7. Waitlist State Behavior

• Status flow includes pending, partially_reserved, reserved, notified, completed, cancelled.
• Claim marks reserved rows claimed and closes waitlist as completed.
• Release or cancel restores reserved quantities back to inventory and inventory items.
• Cancel prevents action on already closed waitlists.

8. Key Filters and Sort Fields

9. Troubleshooting