Developer notes

← Overview

File map

app/addons/kv_vendor_performance_sla/
  addon.xml                       settings, 5 tables, 2 privileges, 2 e-mail templates, install/uninstall functions
  init.php / func.php             hooks, storefront data, settings info handlers, licence helpers
  controllers/backend/kv_vendor_performance_sla.php   league table, CSV, drill-down, policies, vendor page, cron
  controllers/backend/index.post.php                  vendor dashboard notice
  controllers/frontend/init.post.php                  badge data for the storefront templates
  controllers/backend/kv_vendor_performance_sla_license.php   "Check now" and licence cron
  schemas/menu/*.post.php                  admin menu (Vendors) and vendor panel menu
  schemas/permissions/*.post.php           privileges, vendor mode, cron as trusted controller
  schemas/settings/variants.functions.post.php   order status and actor variants
  schemas/block_manager/blocks.post.php    block cache: our table + licence/settings key on product and vendor blocks
  schemas/vendor_rating/criteria.post.php  variables of the core vendor rating formula
  Tygh/Addons/KvVendorPerformanceSla/
    Config.php       settings, metric definitions
    Policies.php     SLA policies (default + per plan), handling time
    Orders.php       per-order timestamps, nightly sync, due dates
    Metrics.php      KPI aggregation and rating
    Vendors.php      levels, actions, league table, storefront map
    Snapshots.php    daily results (trend, sorting, CSV)
    Notifier.php     e-mails
    Cron.php         nightly run and pseudo-cron
    Log.php          history
    RatingCriteria.php   vendor rating criteria provider
    StorageData.php  run marks and cursors (files instead of storage_data while the full page cache is on)
    License/, Upgrade/   licence client, self-healing upgrades
design/backend/templates/addons/kv_vendor_performance_sla/   admin + vendor panel views, components, licence UI
var/themes_repository/responsive/templates/addons/kv_vendor_performance_sla/   badge component + hooks
var/langs/en/addons/kv_vendor_performance_sla.po

Tables

Table	Purpose
?:kv_vpsla_orders	One row per vendor order: placed_at, accepted_at, shipped_at, tracking_at, cancelled_at, cancel_actor (V/A/C/S), due_at, status, flags (1 = backfilled), excluded + note. Key (company_id, placed_at). Rows older than the window + 60 days are removed.
?:kv_vpsla_policies	plan_id (0 = default), custom, handling_days, min_orders, metrics (JSON: on/warn/breach per KPI), notification and action flags, grace_days.
?:kv_vpsla_vendors	Per vendor: handling override, exempt, level + since, breach since, last result (JSON), flagged/hidden/paused, override until, badge values, computed at.
?:kv_vpsla_snapshots	Daily result per vendor (level, every KPI, score); 400 days kept.
?:kv_vpsla_log	History of level changes, actions and administrator decisions.

Core hooks used

Identical in 4.17.2 and 4.21.2 Multi-Vendor: place_order, change_order_status_post, create_shipment_post, delete_order, delete_company, get_products, get_product_data (hidden products, storefront only), pre_add_to_cart, allow_place_order_post (paused vendors, storefront only), before_dispatch (pseudo-cron, panel GETs only). update_shipment_post exists only in 4.21; on older versions the nightly sync picks up tracking numbers added later. Template hooks: companies:view (pre), companies:products (pre), companies:product_company_data (post), index:styles (post).

Nightly run

Cron::run() (cron, pseudo-cron, Recalculate now):

1. Orders::sync(): new orders by an id cursor in batches of 2,000 (first run: the window), new shipments by a shipment id cursor, tracking numbers added later, statuses changed behind the hooks’ back, rows of deleted orders.
2. Metrics::counters(): one GROUP BY company_id query over ?:kv_vpsla_orders for the window, plus one each for returns, conversations and reviews.
3. Metrics::evaluate() per vendor with its effective policy, Vendors::apply() (level, flag, actions, badges, snapshot), e-mails.

A database lock (GET_LOCK) prevents parallel runs. Measured on the development store: 100,000 order rows aggregated in about 0.13 s.

Rating criteria

schemas/vendor_rating/criteria.post.php adds kv_vpsla_* entries with 'addon' => 'kv_vendor_performance_sla', so they are offered only while this add-on is active. The provider is the container service addons.kv_vendor_performance_sla.rating_criteria (RatingCriteria, implements Tygh\Addons\VendorRating\Criteria\CriteriaInterface), registered in init.php; it reads the stored result, no order queries.

Full page cache (4.21)

The storefront reads only precomputed data from ?:kv_vpsla_vendors (the same for every visitor), so cached pages stay cacheable and carry that table as a cache tag. Block caches of product and vendor blocks get the table in update_handlers and a licence/settings key. No storefront request writes to the database or storage_data.

Template overrides

Storefront templates live in design/themes/<theme>/templates/addons/kv_vendor_performance_sla/. To customize the badges, copy components/badges.tpl to your own theme’s folder; do not edit the add-on’s files, they are replaced on update. Styles are scoped to .kv-vpsla-* classes.

License check

fn_kv_vendor_performance_sla_is_licensed() (License\Client::isActive()) together with the Enable setting gates the nightly computation, the e-mails, the storefront badges and the enforcement of hidden products and paused orders. The admin pages, the stored results, the CSV export, the order timestamps and the rating criteria values always work. The licence check itself runs only in the admin panel or from cron (php admin.php --dispatch=kv_vendor_performance_sla_license.check).