fix: enforce one-time-per-customer offers (server gate + offline/online sync)

[engahmed1190]

Summary

PR #319 introduced the One-Time Offer per Customer feature, but a review found the limit was not actually being enforced — online or offline. This PR fixes the server-side gate, closes a transaction-rule bypass, makes the offline/online frontend consistent, and hardens the recording hook so it can never break a sale.

No schema change and no data migration — the original One Time Customer Offer Usage doctype and its format:{customer}:{pricing_rule} autoname are kept. All lookups now use field filters instead of reconstructing the composite name.

---

The bugs this fixes

🔴 1. Server gate never matched recorded redemptions

apply_offers checked existence with a double-colon key — f"{customer}::{record.name}" — but the doctype autoname generates a single-colon name (CUST:RULE). The lookup never matched, so a customer could redeem the same one-time offer unlimited times online. Proven on a live site.

Fix: field-filter lookup frappe.db.exists("One Time Customer Offer Usage", {"customer": customer, "pricing_rule": record.name}) — immune to the autoname format.

🔴 2. Transaction-scoped one-time offers bypassed the gate entirely

The transaction-rule top-up loop didn't select one_time_per_customer and applied no gate, so cart-level one-time offers applied on every invoice, including walk-ins and repeat customers.

Fix: added the field to the query and routed both loops through a shared _skip_one_time_rule.

🔴 3. Offline redemption recording was silently dropped

A refactor (commit cf035dc2) removed the call that caches a redemption on offline checkout, leaving the whole recordOfflineRedemptions chain orphaned. The same customer could re-apply a one-time offer on every offline sale; on sync the server strips the discount, causing a receipt/cash vs. server grand_total mismatch.

Fix: recording restored in the real offline checkout path (POSSale.vue), keyed by the offline invoice id.

🟠 4. Walk-in / return sales recorded redemptions

update_invoice stamped pos_applied_one_time_rules unconditionally, which would write a usage row against the shared default/walk-in customer (blocking everyone) or consume a redemption on a credit note.

Fix: stamp only for an identified, non-default, non-return customer via the new is_one_time_eligible_customer helper.

---

Changes

Backend — pos_next/api/

• invoices.py
  • apply_offers: field-filter existence check (docs: update README to clarify POS access steps #1); shared _skip_one_time_rule applied in both the per-item and transaction loops (fix: cart header layout. #2); customer's redeemed set fetched once into a set (1 query instead of one exists() per rule).
  • update_invoice: walk-in/return guard on stamping (feat: add lazy loading to item images for improved performance #4).
  • New is_one_time_eligible_customer(customer, default_customer, is_return) — single source of truth shared by the grant side and record side.
• sales_invoice_hooks.py
  • record_one_time_offer_usage: never fails the sale — guards an over-long composite name and logs-and-skips any insert error; idempotency via ignore_if_duplicate. Removed the redundant per-rule pre-skip.

Frontend — POS/src/

• utils/offline/db.js — redemption cache row reshaped to { serverRules, offlineRules: { [invoiceId]: [...] } }:
  • serverRules — authoritative, replaced wholesale on each online fetch so a server-side release self-heals.
  • offlineRules — per-invoice unsynced redemptions, so a voided offline sale releases only its own.
  • Backward-compatible with legacy flat rules rows. Shared _putRedemptionRow read-mutate-write helper; releaseOfflineRedemptions returns the effective set.
• stores/posOffers.js — online fetch is authoritative (replace, preserve offline); recordOfflineRedemptions keyed by invoice id; new releaseOfflineRedemptionsForInvoice refreshes the in-memory gate without a re-read.
• stores/posCart.js — recordOfflineRedemptionsForSale computes applied one-time rules and delegates to the offers store.
• stores/posSync.js — deletePending releases redemptions on void; new single-chokepoint supersedeInvoice bundles worker-supersede + release.
• utils/offline/sync.js — markInvoiceSynced releases the offline-bucket entry once synced, keyed by customer (no full-table scan per invoice on the sync hot path).
• pages/POSSale.vue — records redemptions on offline checkout; routes both supersede sites through posSync.supersedeInvoice.

Offline ⇄ online parity matrix

Event	Behavior
Offline sale	Redemption cached locally (keyed by offline id) → blocks next offline sale
Online sale	Recorded server-side on submit; gate self-heals on next customer-select
Offline void / delete	Cached redemption released → customer not wrongly blocked
Offline edit (supersede)	Original's redemption released; replacement records its own
Sync to server	Offline-bucket entry dropped; repopulated as authoritative serverRule
Server-side cancel/release	Self-heals on next online fetch (server set replaced)

---

Tests

• New POS/src/utils/offline/__tests__/oneTimeRedemptions.test.js — 7 passing vitest cases covering record (P0), server∪offline union, server-authoritative self-heal (P3), per-invoice release (P2), no-customer scan, release-returns-effective-set, and legacy-row backward compat.
• Backend verified live on pos-dev: gate now fires (incl. customer names containing :), duplicate insert rejected, field-based lookup correct, long-name checkout degrades gracefully.

🤖 Generated with Claude Code

[engahmed1190]

@MohamedAliSmk @MostafaKadry