Back-office surfaces

The back office (/manage) exposes seven surfaces around stock and supplier ordering. They all read the same tables (Product.stockLedger, StockAction, SupplierOrder), but they do not all write — and when they do, every movement goes through the canonical write paths (recordPhysicalMovement, manageStock checked, a StockAction emitted in the same transaction). This page tells you which screen to open for which need, and what each button actually does in the database.

Which screen do I need?

flowchart TD
  Q0{"What do you want to do?"}
  Q0 --> A["Fix a stock figure"]
  Q0 --> B["Understand a stock figure"]
  Q0 --> C["Drive replenishment"]
  A --> A1{"How big?"}
  A1 -->|"A few products"| S1["vendors/stocks<br/>inline editing"]
  A1 -->|"Warehouse count"| S2["inventory/counts<br/>physical count"]
  B --> B1{"Which angle?"}
  B1 -->|"Line-by-line journal"| S3["inventory/stock-actions"]
  B1 -->|"Timeline + KPIs"| S4["inventory/stock-ledger"]
  C --> C1{"What exactly?"}
  C1 -->|"What will run out?"| S5["inventory/mon-stock"]
  C1 -->|"Review supplier emails"| S6["vendors/orders/email-review"]
  C1 -->|"Suspiciously inflated stock"| S7["vendors/orders/phantom-stock"]

And if the question is "is everything OK?": /manage/inventory/health (a read-only dashboard) plus the cron-5 health chip on the stock-ledger screen.

At a glance

Vendor stocks — /manage/ecommerce/vendors/stocks

The workhorse grid: every product with its default vendor, current stock, on-order and draft quantities. This is the spot-correction screen.

Reads: vendors.getVendorsStocks (vendor filter via autocomplete). The query also triggers the server-side stock valuation (#2796) — total value in euros at wholesale price, with a missingPriceCount counter for in-stock products missing a purchase price (and therefore unvalued).

Writes:

The export dialog produces a CSV/XLSX of the current state; the import dialog feeds it back. Snapshots (#2796) keep a dated valuation history, with a per-vendor breakdown derived from the frozen items — useful for month-end accounting.

Stock ledger — /manage/ecommerce/inventory/stock-ledger

The densest screen: the ledger's truth made readable. Four areas:

1. KPI cards — Physical stock (with a backorder subtitle when the signed ledger is negative), Reserved, Available, Pending outflows (undelivered orders).
2. Overview table (stockActions.getProductStockOverview) — one product per row, URL-persistent filters: category, vendor, critical-only, health, divergences only (stock ≠ stockLedger), untracked products in/out, sorting, date window (default today → +14 days).
3. Product timeline (stockActions.getStockLedger) — the line-by-line movie of a selected product's inflows/outflows, with detail modals for customer orders and supplier orders.
4. Cron-5 health chip — keeps liveness and activity apart. Its headline is liveness ("did the cron run?"), read from the heartbeat the task stamps in bext-KV at the end of every run (health:auto-validate:{tenantId}:{siteId}, 7-day TTL): ≤ 5 h green, ≤ 12 h amber, > 12 h red — against the expected cadence (12:01 canonical + a 2-hourly sweep via /etc/cron.d). The timestamps of the last auto-validation (supplier-reception ⇣ and client-delivery ⇡ sides) are shown as secondary info, "last activity" — a quiet day legitimately produces no row, so seal age alone never means the cron is dead. If bext is unreachable, the chip falls back to the activity-age status and says so in the popover. See Safety nets.

Writes (three modals, all stock:write — except the reconcile preview previewLedgerReconciliation, which is stock:read; only its apply applyLedgerReconciliation writes):

My stock — /manage/ecommerce/inventory/mon-stock

The merchant's daily view: "What will run out, and what's on the way?". A rolling 30-day projection over the same source as the ledger overview (stockActions.getProductStockOverview), presented as product cards with:

• the uncovered demand panel (customer orders with no supplier order to match);
• group by vendor (?group=true, deep-linkable);
• ad-hoc supplier-order creation straight from a card (URL-driven modals: ?newOrder=1 for a blank composer, ?orderVendor=<id> + ?orderSlot=yyyy-MM-dd to target a vendor/slot, #2832).

Writes very little: deleting a supplier draft (vendors.deleteSupplierOrder) from the demand panel, and creating orders through the modal — which goes through the same guarded chain as event-driven ordering. No direct stock movement.

This is the screen to hand a non-technical operator: they read the projection, they never touch the ledger.

Physical counts — /manage/ecommerce/inventory/counts

The warehouse counting flow, in three phases:

inventoryCount.cancel abandons an unfinalized session with no stock trace.

Stock actions — /manage/ecommerce/inventory/stock-actions

The journal. Each row is a StockAction: type (INCREMENT/DECREMENT/ADJUSTMENT), source (MANUAL, ORDER_UPDATE, SUPPLIER_DELIVERY, INVENTORY_ADJUSTMENT…), status (PENDING/COMPLETED/CANCELLED), before/delta/after quantities, author, reason. Read via stockActions.getAll (stock:read), with filters and per-row detail.

Writes — deletion only, and this is the tricky part:

• Two-way delete (stockActions.deleteWithOptionalStockEffect, stock:write): the dialog explicitly asks whether Product.stock/stockLedger should be adjusted back (the movement is physically reversed) or whether only the journal row is removed (stock stays as is). There is no generic confirm — this choice is the confirmation.
• Bulk delete (stockActions.bulkDelete): a single server round-trip that processes the ids in order, server-side — two stock-affecting deletes on the same product must never race.

Supplier orders — /manage/ecommerce/vendors/orders

The replenishment hub. Tabs: orders, history, per-site view, per-vendor view, and a calendar (VendorOrderCalendarView, with drag-and-drop of orders between slots). Header stats via vendors.getSupplierOrdersStats.

Email review queue — /manage/ecommerce/vendors/orders/email-review

The "what you reviewed is what gets sent" guarantee of the stage → review → send pipeline. Lists vendors.listStagedSupplierOrders (filters: vendor, dates, today-only, deferred, modified, group-by-vendor); each row shows the effective values (merged overrides) and a drift chip when the items changed since staging.

Phantom stock — /manage/ecommerce/vendors/orders/phantom-stock

Hunting inflated stock (typically fictional stock inherited from the online storefront — see PrestaShop sync). Reads vendors.getStockCoveragePage (products:read) with server-side search (350 ms debounce) and a "suspects only" filter; the trusted column shows what the ordering engine will actually use — capped by the 8 weeks of coverage when the raw stock looks phantom.

Two trust actions (stock:write):

• vendors.setProductStock — fix the figure (physical movement, SA emitted);
• vendors.setProductStockTrusted — flip the trust flag without touching the figure (the engine ignores or re-uses the raw stock).

Work through this before switching to more stock-driven ordering: every unresolved suspect translates into under-ordering.

Inventory health — /manage/inventory/health

A read-only dashboard (inventory.getDashboardData): stock alerts, aggregated indicators. No write action — it is the visual companion to the safety nets (the stock-ledger-audit task, the daily 06:30 probe, the cron-5 chip on the ledger screen).

Permissions

Every procedure is RBAC-protected (permissionProtectedProcedure):

A read-only "daily operator" profile lives happily on stock:read + vendors:read plus access to my-stock and the email queue; the write actions on my-stock (deleting a supplier draft, creating an ad-hoc order) do require vendors:write, though. Keep stock:write for people who understand the difference between deleting a journal row with and without stock effect.

See also

• Overview — the whole model on one page
• The stock ledger — signed authority, clamped mirror, invariants
• Write paths — the contract every write button honors
• Supplier orders — event-driven ordering, slots, the write lock
• A day in the life — the 06:00 / 06:30 / 07:15 / 12:01 crons
• Safety nets — audit, probe, pinned tests
• Configuration — the gates (STOCK_LEDGER_ALLOW_BACKORDER, STOCK_TRUST_MAX_COVER_WEEKS…)