<?php

/**
 * =============================================================================
 * ONLINE MULTI-STORE FULFILLMENT — FULL ANALYSIS
 * =============================================================================
 *
 * Audience: Owner / manager (how website stock & orders work)
 * Related code: OrderAllocationService, CartService, LocationInventoryService,
 *               CheckoutController, Product::onlineAvailableStock(), MultiStoreSeeder
 * Version: 2026-09 (split ON + online stock sum)
 * Markdown: docs/ONLINE_MULTI_STORE_FULFILLMENT.md
 *
 * =============================================================================
 * A) SHORT ANSWER TO YOUR SCENARIO
 * =============================================================================
 *
 * Two warehouses; one order with two items:
 *   Item A only in Loc1, Item B only in Loc2
 *
 * NOW (Split Orders ON by default):
 *   → Website “In Stock” = sum of Fulfills-online available
 *   → Checkout prefers ONE location that has every line
 *   → Else SPLIT: Item A @ Loc1, Item B @ Loc2
 *   → Admin order → Fulfillment Locations packing table
 *
 * Config: locations Active + Fulfills online = Yes; keep Split ON
 * under Inventory → Allocation Rules.
 *
 * =============================================================================
 * B) HOW STOCK IS SHOWN TO ONLINE USERS
 * =============================================================================
 *
 * Product::onlineAvailableStock() (and listings via scopeInStock):
 *   Sum of available at Active + Fulfills-online locations
 *   Example: Item1 10@A + 2@B → shows 12
 *
 * Cart / checkout enforce the same online available totals.
 * Per-location: /api/products/{id}/store-availability
 *
 * =============================================================================
 * C) ALLOCATION FLOW
 * =============================================================================
 *
 * Prefer single location with full cart → else Split (if ON) → else central WH
 * Checkout may show: “This order may ship from more than one store…”
 *
 * =============================================================================
 * D) ALLOCATION RULES (DEFAULTS)
 * =============================================================================
 *
 *  10 Store Preference      ON
 *  20 Delivery Zone         ON
 *  30 Nearest Store         ON (weak without lat/lng)
 *  40 Highest Stock         ON
 *  50 Priority Store        ON
 *  90 Warehouse Fallback    ON
 * 100 Split Orders          ON  ← cross-branch carts
 * 110 Back Orders           OFF (not implemented)
 *
 * =============================================================================
 * E) WORKED EXAMPLES
 * =============================================================================
 *
 * Example 1 — One place has both → one shipment
 * Example 2 — Cross-branch cart → split packs
 * Example 3 — Prefer single branch when possible (no split)
 * Example 4 — POS uses selected store only; online uses Fulfills-online
 *
 * =============================================================================
 * F) OPS
 * =============================================================================
 *
 * Pack split orders from Admin → Order → Fulfillment Locations.
 * Courier auto dual-labels are out of scope; ops packs manually.
 *
 * =============================================================================
 */

return [
    'title' => 'Online Multi-Store Fulfillment',
    'version' => '2026-09',
    'markdown' => 'docs/ONLINE_MULTI_STORE_FULFILLMENT.md',
    'default_mode' => 'prefer_single_then_split',
    'split_orders_default' => true,
    'checkout_allow_split' => true,
    'online_stock_display' => 'sum_fulfills_online_available',
    'cross_store_cart_default_result' => 'split_when_no_single_location_has_all_lines',
];