Developer notes

File map

Path	Purpose
app/addons/kv_size_guide_fit/addon.xml	Settings, tables, install/uninstall functions
app/addons/kv_size_guide_fit/init.php, func.php	Hook registration, helpers, hook handlers, licence gate
Tygh/Addons/KvSizeGuideFit/Chart.php	Table model: columns, rows, range parsing, units, size-name matching
Tygh/Addons/KvSizeGuideFit/Repository.php	Charts, texts, conditions, product assignments
Tygh/Addons/KvSizeGuideFit/Resolver.php	Which chart a product uses
Tygh/Addons/KvSizeGuideFit/Presenter.php	Storefront payload (chart, selector target, fit totals, reference charts)
Tygh/Addons/KvSizeGuideFit/Feedback.php	Fit feedback, moderation, totals
Tygh/Addons/KvSizeGuideFit/Presets.php, Csv.php	Templates, CSV import/export
controllers/backend/kv_size_guide_fit.php	Charts, assignments, feedback, import/export pages
controllers/backend/products.post.php	Size guide tab of the product editor
controllers/frontend/kv_size_guide_fit.php, orders.post.php	Fit feedback endpoint and order page data
schemas/	Menus, privileges, vendor access, block cache, CSRF opt-in, settings variants
design/backend/templates/addons/kv_size_guide_fit/	Admin pages and the product tab
var/themes_repository/responsive/templates/addons/kv_size_guide_fit/	Size guide link, product tab block, order page feedback
js/addons/kv_size_guide_fit/recommender.js	Recommendation rules (pure functions)
js/addons/kv_size_guide_fit/func.js, backend.js	Storefront window and finder; admin table editor
var/langs/en/addons/kv_size_guide_fit.po	Texts

Tables

Table	Contents
?:kv_sgf_charts	Chart: owner company, status, priority, unit, reference/finder flags, table JSON
?:kv_sgf_chart_descriptions	Name, how-to text and column labels per language
?:kv_sgf_links	Conditions: category (with subcategory flag), brand variant, vendor
?:kv_sgf_products	Product assignment: chart id or -1 (no size guide)
?:kv_sgf_feedback	One answer per order and product: fit S/T/L, status P/A/D
?:kv_sgf_fit	Approved totals per product (variation groups share the row of their lowest product id)

The table JSON is {"columns":[{"key":"chest","type":"num"}],"rows":[{"size":"M","aliases":["38"],"cells":{"chest":[94,100]}}]}; numeric cells are [min, max] in the chart unit.

Which chart a product uses

1. The product’s own assignment: a chart (if active and visible to the storefront/vendor) or “no size guide”.
2. Otherwise every active chart whose conditions match. Highest priority wins; ties go to more matched condition types, then the deepest matched category, then the lower chart ID.

Vendor charts (Multi-Vendor) match only the vendor’s products; Ultimate storefront charts match only on their storefront; charts of company 0 match everywhere. The rules are cached in the Registry with the add-on tables as cache conditions.

Recommendation rules

KvSgfRecommender.recommend(chart, {unit, values}, {fit}) converts the input to the chart unit and scores every size: for each measurement the distance outside the size range in “size steps” (the median difference between neighbouring sizes), weighted (girths and foot length weigh most, height and weight less), plus a small centring term. Single values are widened to half the distance to the neighbouring sizes. The best size wins; when the girth measurements point to different sizes the result is “between sizes” and the larger one is suggested (the smaller one when buyers say the item runs large). Confidence is high when every measurement is inside the size, medium when close or between two neighbouring sizes, low when outside the chart. fromReference() matches a size from another chart by a shared label column (EU, US, …), then by its body measurements, then by the same size name. The functions are pure and run in Node for tests.

Hooks used

Hook	Use
gather_additional_products_data_post	Adds the size guide data to single products on the storefront (product page, quick view, option reload)
update_product_post	Saves the product editor’s Size guide tab
delete_product_post, clone_product, delete_company, post_delete_user	Cleanup and copying

Template hooks: products:product_option_content (post; link + payload), orders:product_info (post; feedback), products:tabs_content (admin product tab), index:scripts / index:styles. Product tab block: blocks/product_tabs/kv_size_guide_fit.tpl.

The storefront markup is a div.kv-sgf with the JSON payload in data-kv-sgf; the script moves the link next to the selector label (#opt_<prefix><id>_<option_id> for options, the matching .ty-product-options__item of .cm-picker-product-variation-features for variations) and builds the window when it is opened. Override the look with CSS scoped under .kv-sgf, .kv-sgf-modal, .kv-sgf-tab and .kv-sgf-feedback.

Full page cache and privacy

The product page output depends only on the product and the add-on data, so it is identical for every visitor. Measurements are kept in localStorage (kv_sgf_profile) and never sent to the server. The feedback endpoint is a POST of the logged-in buyer (or a guest with access to the order) and requires the form security hash.

License check

fn_kv_size_guide_fit_is_licensed() (License\Client::isActive()) together with Enable the size guide gates the storefront output (link, window, finder, product tab, fit hint) and the feedback form and endpoint. The admin pages, import/export and all data stay available. The product page cache key includes the licence state. The licence check itself runs only in the admin panel or from cron.