Feature: Append-only product inventory movement ledger & history API (shipped) #280

Status

Shipped: the focused product movement ledger and history API landed in PR #775 on 2026-09-18. This issue remains the canonical product-ledger record and the completed dependency for the follow-on planning issues below. This planning update does not authorize any follow-on implementation.

Problem or motivation

FloCafe had product-level stock availability and order lifecycle deduction/restoration, but no append-only history explaining how a product count changed. The ledger needed to build on the existing products.stock_quantity cache and order_items.inventory_deducted_quantity provenance rather than introduce a parallel product-stock model.

Current behavior

The merged delivery provides an append-only product movement history with atomic cache-plus-ledger writes for opening balances, sales, cancellation restores, and reasoned manual adjustments. It includes actor/reason/reference attribution, idempotent lifecycle handling, owner/manager history access with filtering and cursor pagination, and inventory-aware import/backup/restore validation.

Desired outcome

Keep the delivered product ledger as the finished-product stock baseline. Future inventory work must preserve its offline, additive-migration, atomic, auditable, and idempotent behavior.

Delivered technical approach

• Retain products.stock_quantity as the current-state cache and order_items.inventory_deducted_quantity as order-line provenance.
• Record signed product movements for opening balance, sale, cancellation restore, and manual adjustment in the append-only ledger.
• Keep movement writes and cache changes atomic, with stable references preventing duplicate lifecycle movements.
• Expose owner/manager movement history with bounded filtering and cursor pagination.
• Preserve movement provenance through validated import and restore paths.

Acceptance criteria

• Append-only product movement history exists for the delivered movement types.
• Every supported product stock mutation updates the ledger and cache atomically.
• Movement history is auditable and access-controlled with the existing role model.
• Fresh and upgraded databases preserve existing product/order data and reject unsafe history replacement.

Explicit exclusions

Recipes/BOM depletion, held supplies stock, add-on stock, suppliers, purchasing, receiving, waste workflows for non-products, accounts payable, valuation, multi-location inventory, and ERP behavior are separate scopes. Do not infer or implement them from this issue.

Follow-on issue map and sequencing

1. Completed baseline: this issue / #280, delivered by PR #775.
2. Supplies stock: #768, manual offline stock items and movements only.
3. Recipe/BOM pilot: #769, evidence-gated and dependent on a maintained supplies/item base.
4. Materials expense: #645, a separate finance scope; it is not inventory.
5. Receipt tender/change projection: #770, after the queued inventory follow-ons; it changes print projection only and does not change payment settlement.

The cash-drawer foundation is separately delivered in PR #772. The follow-on issues are related planning records, not approval to start implementation.

Review request

@itsbkm, please review this completed baseline and the linked follow-on boundaries. I would appreciate your thoughts on the sequencing and whether you are willing to take over or collaborate on the next scoped issue.

Additional context

This issue originated from a fork proposal. The historical fork-specific migration and file paths are not the current contract; the merged implementation is the authoritative baseline.