<?php

/**
 * =============================================================================
 * SHIVA JEWELLERS — MULTI-STORE USER GUIDE
 * =============================================================================
 *
 * For: Shop owners, managers, cashiers, and warehouse staff
 * Admin: http://shiva.jewels/admin
 * Storefront: http://shiva.jewels/
 * Store locator: http://shiva.jewels/stores
 *
 * Version: 2026-09
 *
 * Also see printable copy: docs/MULTI_STORE_USER_GUIDE.md
 *
 * =============================================================================
 * 1) WHAT IS MULTI-STORE?
 * =============================================================================
 *
 * Each shop / warehouse keeps its OWN stock.
 *
 * Example:
 *   Warangal Store   → 10 gold chains
 *   Hyderabad Store  → 4 gold chains
 *   Central Warehouse → 50 gold chains
 *
 * Rules to remember:
 *   - POS sells from the selected store only
 *   - Online orders allocate to one location when possible; otherwise SPLIT
 *     across stores (Split Orders ON by default)
 *   - Website “In Stock (N)” = sum of available stock at Fulfills-online locations
 *     (e.g. Item1 10@A + 2@B shows as 12)
 *
 * Always check WHICH LOCATION you are working in before selling,
 * receiving, auditing, or closing the day.
 *
 * =============================================================================
 * 2) WHO CAN DO WHAT? (ROLES & PERMISSIONS)
 * =============================================================================
 *
 * Admin / Super Admin
 *   - See all stores
 *   - Create locations, suppliers, POs, allocation rules, delivery zones
 *   - Assign staff to stores
 *   - Approve / ship transfers as permitted
 *
 * Staff (store cashier / floor)
 *   - Only assigned stores
 *   - POS for their store
 *   - Usually: Store Balances, create/receive transfers, receive POs,
 *     Day Ledger view, Location Ops (if role allows)
 *
 * Manager tip:
 *   Admin → Roles → edit the staff role → tick “Multi-Store” permissions
 *   you want that role to use.
 *
 * Common Multi-Store permissions:
 *   locations.view / locations.manage
 *   inventory.balances.view
 *   transfers.view / manage / approve / ship / receive
 *   purchase-orders.view / manage / receive
 *   suppliers.manage
 *   allocation-rules.manage
 *   delivery-zones.manage
 *   replenishment.manage
 *   reports.location-ops
 *   reports.day-ledger.view / manage / close / reopen
 *
 * If a menu item is missing → that role does not have the permission.
 *
 * =============================================================================
 * 3) ASSIGN STAFF TO STORES (REQUIRED)
 * =============================================================================
 *
 * Path: Admin → Users → Staff → Add / Edit
 *
 * On create AND edit you must set:
 *   1) Assigned Stores / Locations  (multi-select; Ctrl/Cmd click)
 *   2) Default Location             (where POS / ledger starts)
 *
 * Without an assigned store:
 *   - Staff cannot open POS (system asks to select a store)
 *   - Staff cannot sell for another branch (blocked for security)
 *
 * =============================================================================
 * 4) SELECT / SWITCH CURRENT STORE
 * =============================================================================
 *
 * Path: /admin/locations/select
 * Or use the POS location switcher when you have more than one store.
 *
 * Switch before you sell if you work at two counters.
 * Wrong store selected = wrong stock reduced.
 *
 * =============================================================================
 * 5) LOCATIONS (STORES & WAREHOUSES)
 * =============================================================================
 *
 * Path: Inventory → Locations
 * URL:  /admin/locations
 *
 * Types:
 *   store      → retail / POS / pickup
 *   warehouse  → central stock / receiving
 *
 * Flags:
 *   Active          → can be used
 *   Default         → company primary store
 *   Fulfills online → can receive website orders
 *   Allows pickup   → appears for pickup / store locator
 *   Priority        → used by “Priority Store” allocation
 *   Address / map   → nearest store + public store locator
 *
 * Tip: start with ONE default store + ONE warehouse.
 *
 * =============================================================================
 * 6) DASHBOARD (SHOP SALES)
 * =============================================================================
 *
 * Path: Admin home (/admin)
 *
 * Use the Shop dropdown at the top:
 *   - One store → KPIs for that store only
 *   - All shops → company total (admins)
 *
 * Today sales, month revenue, profit, and charts follow the selected shop.
 *
 * =============================================================================
 * 7) STORE BALANCES (STOCK BY LOCATION)
 * =============================================================================
 *
 * Path: Inventory → Store Balances
 * URL:  /admin/inventory/balances
 *
 * Columns meaning:
 *   on_hand         → physically available (minus damaged logic in available)
 *   reserved        → held for open online carts / orders
 *   damaged         → not for sale
 *   in_transit_*    → moving on a transfer
 *
 * Staff only see balances for stores they are assigned to.
 *
 * =============================================================================
 * 8) POS — SELL FROM YOUR STORE
 * =============================================================================
 *
 * Path: Top bar → POS   or   /admin/pos
 *
 * Checklist every shift:
 *   1. Confirm store name in location switcher
 *   2. Search / add products (stock is for THAT store)
 *   3. Complete payment
 *   4. Stock reduces on the selected store only
 *
 * Security:
 *   You cannot sell using another store’s location_id.
 *   If you have no store assigned, POS redirects to store selection.
 *
 * =============================================================================
 * 9) STOCK TRANSFERS
 * =============================================================================
 *
 * Path: Inventory → Stock Transfers
 * URL:  /admin/transfers
 *
 * Flow:
 *   Create → Approve → Ship → Receive
 *   (Cancel allowed before receive, when permitted)
 *
 * Typical uses:
 *   Warehouse → Store (replenish floor)
 *   Store A → Store B (balance stock)
 *
 * Ship needs enough available stock at FROM location.
 *
 * =============================================================================
 * 10) SUPPLIERS & PURCHASE ORDERS
 * =============================================================================
 *
 * Suppliers: Inventory → Suppliers
 * POs:       Inventory → Purchase Orders
 *
 * Flow:
 *   1. Create PO (supplier + receive-into location + items)
 *   2. Mark Ordered
 *   3. Receive → increases that location’s on_hand
 *
 * Best practice: receive into WAREHOUSE, then transfer to stores.
 *
 * =============================================================================
 * 11) REPLENISHMENT
 * =============================================================================
 *
 * Path: Inventory → Replenishment
 *
 * 1. Set min/max (or reorder) rules per product / location
 * 2. Review suggestions
 * 3. Create transfer from suggestions
 * 4. Approve → Ship → Receive
 *
 * =============================================================================
 * 12) ONLINE ORDERS — ALLOCATION & DELIVERY ZONES
 * =============================================================================
 *
 * Allocation Rules: Inventory → Allocation Rules
 * Delivery Zones:   Inventory → Delivery Zones
 *
 * Split Orders is ON by default. Checkout prefers one store for the whole cart;
 * if items sit in different branches, the order splits. Admin → Order shows
 * Fulfillment Locations for packing.
 *
 * Website stock = sum of Fulfills-online available (10@A + 2@B → 12).
 *
 * Default rule order (lower number runs first):
 *   10 Store Preference
 *   20 Delivery Zone
 *   30 Nearest Store
 *   40 Highest Stock
 *   50 Priority Store
 *   90 Warehouse Fallback
 *  100 Split Orders   (ON by default)
 *  110 Back Orders    (keep OFF — not built)
 *
 * Delivery Zones map pincode / area → preferred store.
 *
 * For a location to get online orders it must be:
 *   Active + Fulfills online + enough available stock
 *
 * =============================================================================
 * 13) DAY LEDGER (PER STORE CASH)
 * =============================================================================
 *
 * Path: Reports → Day Ledger
 *
 * Filter by Date + Location.
 * Staff see only their assigned stores (no “All shops”).
 * Close / reopen needs the matching day-ledger permission.
 *
 * Always close the day for the SAME store you sold from.
 *
 * =============================================================================
 * 14) LOCATION OPS REPORT
 * =============================================================================
 *
 * Path: Reports → Location Ops
 * URL:  /admin/reports/location-ops
 *
 * Quick view: sales, on-hand units, approx stock cost, open transfers
 * for a selected store (scoped to your access).
 *
 * =============================================================================
 * 15) STOREFRONT (CUSTOMERS)
 * =============================================================================
 *
 * Store locator: /stores
 * Checkout: stock is reserved at the allocated location until paid / expired.
 *
 * =============================================================================
 * 16) DAILY WORKFLOW (PRINT THIS)
 * =============================================================================
 *
 * Morning
 *   [ ] Select your store
 *   [ ] Open POS — confirm store name
 *   [ ] Glance Store Balances / low stock
 *   [ ] Open Day Ledger for that store
 *
 * During day
 *   [ ] Sell only from your store
 *   [ ] Receive transfers into your store when goods arrive
 *   [ ] Receive POs only into the correct location
 *
 * Incoming goods (warehouse)
 *   [ ] Receive PO into warehouse
 *   [ ] Transfer warehouse → stores
 *   [ ] Ship + Receive
 *
 * Closing
 *   [ ] Day Ledger close for your store
 *   [ ] Note any open transfers still in transit
 *
 * Weekly (manager)
 *   [ ] Replenishment suggestions
 *   [ ] Stock audit for high-value SKUs per location
 *   [ ] Review Location Ops + allocation / delivery zones
 *
 * =============================================================================
 * 17) MENU MAP
 * =============================================================================
 *
 * Inventory
 *   ├── Restock / Audits / Adjustments   (confirm LOCATION on form)
 *   ├── Store Balances
 *   ├── Stock Transfers
 *   ├── Purchase Orders / Suppliers
 *   ├── Locations
 *   ├── Allocation Rules
 *   ├── Delivery Zones
 *   └── Replenishment
 *
 * Reports
 *   ├── Day Ledger   (filter by location)
 *   └── Location Ops
 *
 * Users → Staff
 *   └── Assign stores + default location
 *
 * Top bar
 *   ├── POS
 *   └── Day Ledger
 *
 * =============================================================================
 * 18) TROUBLESHOOTING (USER)
 * =============================================================================
 *
 * Q: I cannot open POS / “select a store”
 * A: Ask admin to assign you a store + default location on your staff profile.
 *
 * Q: I sold but stock fell in the wrong shop
 * A: Location switcher was on the wrong store. Switch, then continue.
 *    (Past sale stays on the fulfillment location of that order.)
 *
 * Q: Menu item missing (Transfers / Balances / etc.)
 * A: Your role needs the Multi-Store permission. Admin → Roles.
 *
 * Q: Transfer cannot ship
 * A: FROM store does not have enough available (on_hand − reserved).
 *
 * Q: Online order went to unexpected store
 * A: Check Active + Fulfills online + stock, Delivery Zones, Allocation Rules.
 *
 * Q: Store Balances look empty after first go-live
 * A: Ask tech to run inventory backfill into the default store.
 *
 * Q: Screen looks cut off / sidebar icon-only
 * A: Hard refresh (Ctrl+F5). Clear browser key adminSidebarCollapsed if needed.
 *
 * =============================================================================
 * 19) GO-LIVE CHECKLIST (SHOP OWNER)
 * =============================================================================
 *
 *   [ ] Locations created (stores + warehouse) with correct flags
 *   [ ] Every staff user assigned to store(s) + default
 *   [ ] Staff roles have required Multi-Store permissions
 *   [ ] Store Balances match physical stock (spot-check 10 SKUs)
 *   [ ] Test POS sale → balance reduces for THAT store
 *   [ ] Test Day Ledger open/close for that store
 *   [ ] Test one transfer Warehouse → Store (ship + receive)
 *   [ ] Test one online paid order allocation (if selling online)
 *   [ ] Store locator page shows correct addresses
 *   [ ] Split Orders ON (default); Back Orders OFF
 *   [ ] Staff know to pack splits from Fulfillment Locations on the order screen
 *
 * =============================================================================
 */

return [
    'title' => 'Multi-Store User Guide',
    'audience' => 'owners, managers, cashiers, warehouse staff',
    'version' => '2026-09',
    'markdown' => 'docs/MULTI_STORE_USER_GUIDE.md',
    'admin_url' => '/admin',
    'store_locator' => '/stores',
];