Developer notes

File map

Path	Purpose
app/addons/kv_vendor_analytics_dashboard/addon.xml	Settings, install/uninstall queries (counter table, privilege)
func.php	Licence gate fn_kv_vendor_analytics_dashboard_is_licensed(), post_add_to_cart handler, tiles/chart/export helpers, settings variants, uninstall
init.php	Hook registration, synchronizer and licence blocks
controllers/backend/kv_vendor_analytics.php	Pages dashboard, vendors, export, maintenance
controllers/frontend/products.post.php	Product view counter (mode view)
Tygh/Addons/KvVendorAnalyticsDashboard/Analytics.php	All aggregate queries for one scope (one vendor or the marketplace)
.../Report.php	Page data, comparison rows, TTL cache
.../Period.php	Date ranges, comparison ranges, chart buckets (PHP and SQL)
.../Tracker.php	View/cart-add counters, daily maintenance
.../Config.php	Typed settings, counted order statuses
.../Csv.php	CSV builder (BOM, formula-injection safe)
.../StorageData.php	Run marks (files while the full page cache is active)
.../License/Client.php, License/Ed25519.php	Domain-bound licence client (generated)
.../Upgrade/Synchronizer.php	Self-healing in-place upgrades (generated)
controllers/backend/kv_vendor_analytics_dashboard_license.php	“Check now” and cron licence check (generated)
schemas/menu/menu_multivendor.post.php, menu_vendor.post.php	Orders → Analytics (vendor), Orders → Vendor analytics (admin), incl. the Vendor panel configurator menu
schemas/permissions/admin.post.php, vendor_multivendor.post.php	Privilege mapping; vendor access to dashboard and export only
schemas/full_page_cache/varnish.post.php	Adds the counter table to ignore_cache_tags
design/backend/templates/addons/kv_vendor_analytics_dashboard/views/kv_vendor_analytics/{dashboard,vendors}.tpl	Pages
.../components/{filters,change,value,products_table}.tpl	Page parts
.../license/{card,status_bar,badge,info}.tpl	Licence UI (generated)
design/backend/css/addons/kv_vendor_analytics_dashboard/styles.less	Styles, scoped under .kv-vad
js/addons/kv_vendor_analytics_dashboard/func.js	SVG chart, filters (no external libraries)

Table

cscart_kv_vad_product_stats (product_id, day, company_id, views, cart_adds), primary key (product_id, day), keys (company_id, day) and (day). day is an integer YYYYMMDD in the store time zone; company_id is the product’s vendor at the time of the event. One row per product and day, updated with INSERT … ON DUPLICATE KEY UPDATE. Rows older than the retention are deleted by the daily maintenance.

Everything else is read from core tables: orders (child orders only, is_parent_order != 'Y'), order_details, vendor_payouts (+ the commission columns of Vendor plans when present), rma_returns (RMA), companies, product_descriptions.

Hooks

Hook	Where (4.21.2 / 4.17.2)	Handler
post_add_to_cart	fn_add_product_to_cart(), fn.cart.php 6905 / 6723, identical arguments	Counts cart adds (storefront only, not for quantity updates)
before_dispatch (static)	licence client	Admin licence checks and notices
init_templater_post (only while an upgrade sync is pending)	synchronizer	Upgrade synchronization

Product views use a post controller (products.post.php, mode view, GET) because fn_update_product_popularity() has no hook. A product is counted once per session (session key kv_vad_viewed, the rule core uses for product_popularity), never for crawlers (CRAWLER), administrators or vendor staff.

Counted orders

Config::salesStatuses(): the checked statuses of the Order statuses counted as sales setting, or the order statuses with calculate_for_payouts = Y when none is checked (the definition of core vendor accounting). An empty value re-saved as #M#=Y while the add-on is disabled is treated as “none checked”.

Data isolation

Analytics takes the scope in its constructor (int company id or null for the marketplace) and filters every query by it. In the controller the scope of a vendor is always runtime.company_id; a company_id in the request is ignored in the vendor panel. The vendor permission schema allows only dashboard and export; the controller additionally denies vendors, maintenance and the vendors export for vendors. Cache keys contain the scope.

Caching and performance

Report::cached() stores page data in the CS-Cart cache (Registry::registerCache with a TTL, no table handlers, so busy order tables do not invalidate it every second). The key contains the scope, the period (rounded to the minute), the counted statuses and the list size. refresh=1 recalculates at most once a minute. The per-vendor comparison data is cached once per period and shared by the comparison page and the benchmark of every vendor.

Queries use the core keys orders.company_id and orders.timestamp, order_details (order_id, product_id) and the counter table’s own keys. Ranges are limited to 1,100 days.

Full page cache (4.21)

The add-on prints nothing on the storefront. The only storefront writes go to cscart_kv_vad_product_stats (on product pages that reach PHP, i.e. cache misses, and on add-to-cart POSTs), and that table is in ignore_cache_tags, so the writes never purge cached pages. No ?:storage_data writes happen on the storefront (the daily maintenance mark uses StorageData, from the admin/vendor panel or cron only). Page views served by Varnish from the cache never reach CS-Cart, so they are not counted (the same applies to core’s popularity counter).

License check

fn_kv_vendor_analytics_dashboard_is_licensed() (cached per request, License\Client::isActive()) gates:

• the dashboard, vendors and export pages (a notice instead of figures; the export redirects back);
• the view and cart-add counters (Tracker::canTrack()).

The licence check itself runs only in the admin panel or from cron (php admin.php --dispatch=kv_vendor_analytics_dashboard_license.check). Orders, payouts and the storefront never depend on it.

Extension points

• Subclass-free: call new \Tygh\Addons\KvVendorAnalyticsDashboard\Analytics($company_id, $period, $statuses) from your own code to reuse the queries; Period::fromRequest() builds the ranges.
• Cron: php admin.php --dispatch=kv_vendor_analytics.maintenance runs the counter cleanup.
• Kill switch for the upgrade synchronizer: define('KV_UPGRADE_SYNC_DISABLED', true);.