Developer notes

Data model (InnoDB)

Table	Contents
?:kv_auc_auctions	Auction configuration and status: product, company (vendor / storefront), start, end (moved by late bids), prices, increment, anti-sniping values, result, current winner claim. Written on create/edit/extension/close/cancel only.
?:kv_auc_live	Live state per auction: current price, leader, leader’s maximum, bids and bidders count, reserve met. Written by every bid (kept apart so bids never purge the product page block cache).
?:kv_auc_bids	Bid history: customer bids (manual / maximum), automatic bids, Buy Now; canceled bids stay with their reason.
?:kv_auc_bidders	Per auction and customer: maximum, first/last bid, outbid time, watch flag.
?:kv_auc_users	Bidder accounts: status (approved / pending / blocked), terms acceptance time, hash of the terms text, IP address.
?:kv_auc_claims	The right to buy at the winning bid: winner, second chance or Buy Now; unpaid / ordered / paid / expired / declined / canceled; payment deadline; order.
?:kv_auc_meta	Run marks of the closer.

Auction status: A active (scheduled, running or ended and waiting for the closer), C closed, X canceled, R archived (no longer the product’s auction). Results: W won, B bought now, N reserve not met, Z no bids, X canceled.

Bid engine

Tygh\Addons\KvAuctionBidding\Engine is pure (integer cents, no database): every bid is a maximum; manual bids set the price to the amount, maximum bids to min(max, other maximum + step); equal maximums: the earlier one leads; the reserve rule moves the price to the reserve once a maximum reaches it. Engine::replay() rebuilds the state from the remaining customer bids after a bid was canceled.

Locking and concurrency

Every change of the bidding state runs in one READ COMMITTED transaction that first locks the auction row (SELECT ... FOR UPDATE) and reads the time after the lock (Placement, Closer, Tx with a jittered retry on deadlocks). The closer takes the same lock, so no bid can land after a close and an auction can only have one winner. Claims are reserved for an order with one conditional UPDATE ... WHERE status = 'U' AND pay_until >= now (single use).

Closing

Closer::run() (cron admin.php --dispatch=kv_auction_bidding.cron, cron URL index.php?dispatch=kv_auction_bidding.cron&cron_password=..., the admin fallback every 5 minutes, and the storefront state request of an ended auction) closes due auctions and expires unpaid claims. Each transition happens under the lock or with a conditional UPDATE; only the process that made it sends the e-mails.

Price enforcement

CartBridge: only Pay now / Buy Now add a line with extra.kv_auc = {claim_id}; markers from requests are removed (pre_add_to_cart); every calculation (exclude_products_from_calculation) checks owner, claim status, deadline and product and sets quantity 1 and the stored hammer price; catalog promotions are removed from the line (get_cart_product_data_post); pre_place_order reserves the claim, place_order links the order (Multi-Vendor: the child order), change_order_status marks it paid (core “payment received” statuses) or gives it back on failed/declined/canceled orders.

Hooks used

gather_additional_products_data_post, pre_add_to_cart, generate_cart_id, exclude_products_from_calculation, get_cart_product_data_post, pre_place_order, place_order, change_order_status, delete_order, delete_product_post, delete_company, post_delete_user, before_dispatch. Template hooks: products:buttons_block / products:prices_block / products:qty (override, auction products only), products:product_data (list badge), checkout:product_options, profiles:my_account_menu, index:scripts, index:styles.

Own hook: kv_auction_bidding_notify_pre($event, &$data, &$rules) before every notification.

Full page cache

Product pages and lists print static markup per auction (no visitor data). The live state comes from kv_auction_bidding.state / kv_auction_bidding.badges (own dispatch, never cached, no session writes). The products.view and categories.view main blocks get kv_auc_auctions as an update handler and the enabled/licence state as a cache key.

Controllers

Dispatch	Area	Purpose
kv_auction_bidding.state, .badges	storefront GET	Live state JSON (per visitor) / list badges
kv_auction_bidding.bid, .buy_now, .watch	storefront POST (CSRF)	JSON answers
kv_auction_bidding.pay, .decline	storefront POST	Won auction to the cart / decline a second-chance offer
kv_auction_bidding.my	storefront	My auctions
kv_auction_bidding.cron	console / URL with key	Closer
kv_auction_bidding.manage, .export, .create, .update, .cancel, .cancel_bid, .relist, .archive, .close_now, .bids_export, .bidders, .bidder_status	admin / vendor	Back end

File map

app/addons/kv_auction_bidding/
  addon.xml  init.php  func.php  resources/email_templates.xml
  controllers/backend/kv_auction_bidding.php, products.post.php, kv_auction_bidding_license.php
  controllers/frontend/kv_auction_bidding.php, products.post.php
  schemas/block_manager/blocks.post.php        cache keys
  schemas/menu/menu.post.php, menu_vendor.post.php, actions.post.php
  schemas/notifications/events.post.php, events_multivendor.post.php
  schemas/permissions/admin.post.php, vendor_multivendor.post.php
  schemas/security/csrf_validation.post.php
  Tygh/Addons/KvAuctionBidding/
    AuctionDataProvider.php  e-mail data          AuctionService.php  admin create/edit/cancel/list/stats
    AuctionState.php   derived state, limits       Bidders.php         eligibility, terms, approval, masks
    CartBridge.php     cart lines, single use      Closer.php          close, expiry, second chance, relist
    Config.php         settings, statuses          Engine.php          bid math (pure)
    Exporter.php       CSV                         Increments.php      cents, tiers
    Notifier.php       events                      Placement.php       bids, Buy Now, cancel, rebuild
    Presenter.php      storefront data             Repository.php      data access
    Time.php           store time zone             Tx.php              transactions, retry
    License/  Upgrade/   license client, self-healing upgrades
design/backend/templates/addons/kv_auction_bidding/   admin pages, form, product editor section
var/themes_repository/responsive/templates/addons/kv_auction_bidding/   panel, overrides, badge, My auctions, cart badge
js/addons/kv_auction_bidding/func.js                 panel, polling, badges
var/langs/en/addons/kv_auction_bidding.po