# Shoe Customizer — WooCommerce plugin

In-house product customizer for custom-branded sneakers. Runtime multiply-tint compositor,
no external service — replaces the Kickflip/MyCustomizer iframe on corporatekicks.com.au.

This folder is the **deployable plugin**. The proof-of-concept and design docs live one level
up in `../` (`poc/`, `docs/ARCHITECTURE.md`). Version history in [CHANGELOG.md](CHANGELOG.md).

**What's new in 0.4.0 (Phase 1b):** paid **option groups** (delta pricing + required +
conditional visibility), a **size-run** quantity grid (total pairs = line qty, min 2), and
customer **logo upload** with live drag/scale within a print area — all re-validated and
re-priced server-side. See [../docs/GUIDE_OPTIONS_SIZES_LOGO.md](../docs/GUIDE_OPTIONS_SIZES_LOGO.md).

## What Phase 1 ships

- **Data model** — 8 tables via `dbDelta` (`wp_sc_shoe`, `zone`, `zone_layer`, `swatch`,
  `option_group`, `option`, `visibility_rule`, `design`).
- **No-code admin builder** — *Shoe Customizer* menu in wp-admin. Create a shoe, pick its base
  photo and each zone's slice(s) from the media library, name/order zones, edit the palette.
- **REST config endpoint** — `GET /wp-json/shoe-customizer/v1/shoe/<slug>` returns the exact
  JSON the Phase-2 frontend engine consumes (base + zones with ordered layer URLs + palette).
- **Seed importer** — one click imports the five reverse-engineered Corporate Kicks models
  (AF1, Samba, Dunk, Advantage, Court) with their real slices, bundled in `seed/assets/`.

- **Frontend customizer** (Phase 2) — the `[shoe_customizer slug="af1"]` shortcode renders an
  inline live-tint widget on any page/post: canvas preview, per-zone swatches, running price,
  mockup download. It fetches the shoe's config from the REST endpoint above, so the same
  proven compositor drives it with no bundled data.

- **Cart / order integration** (Phase 3) — **Add to cart** POSTs the design + a scaled mockup
  PNG to WooCommerce. The server **re-validates every selection** against the shoe's own
  palette (arbitrary hex is rejected), **recomputes the price server-side**, saves the mockup
  under `uploads/` and a `sc_design` row, then adds the product to the cart. The chosen colours
  show in cart/checkout/emails, the mockup replaces the line thumbnail, and hidden order-item
  meta (`_sc_design_id`, `_sc_shoe`, `_sc_selections`, `_sc_mockup`) carries the self-describing
  design for fulfilment and the future Evolution order pull.

Scope is the **colour path** (matches the POC). Priced option groups, logo upload and the
size-run matrix are Phase 1b/3b. To wire Add-to-cart, either drop the shortcode on the
**product description** of the mapped product (auto-detected), or pass `product="123"`:

```
[shoe_customizer slug="af1" product="123"]
```

If no product is resolved, Add-to-cart falls back to emitting the design JSON (Phase-2 demo
behaviour) so the widget still works on a plain page. Link a shoe to its Woo product in the
builder (**Shoe Customizer → shoe → Product ID**).

**Buy-path guard.** For any product that uses the customizer (mapped to a shoe *or* whose
description contains the shortcode), the plugin makes the customizer the **only** way to buy:
it removes WooCommerce's default add-to-cart form on the product page, swaps the shop/archive
"Add to cart" button for a **Customize** link, and blocks a bare add-to-cart server-side
(direct POST or a stray theme button) with a "please design your shoe first" notice. So a
customer can't accidentally order an undesigned pair — no theme configuration needed.

## Use the customizer on a page

Drop the shortcode on any page, post, or product description:

```
[shoe_customizer slug="af1"]
```

`slug` matches a shoe in **Shoe Customizer** (e.g. `af1`, `samba`, `dunk`, `advantage`,
`court`). Assets and CSS/JS load only on pages where the shortcode is present.

## Install

1. Copy `shoe-customizer/` into `wp-content/plugins/` (or zip it and upload).
2. **Plugins → Activate** "Shoe Customizer" (creates the tables).
3. **Shoe Customizer → Import seed shoes** to populate the five models, or **Add shoe** to
   build one from scratch.
4. Check a config: **Shoe Customizer → (a shoe) → View config JSON**, or hit
   `/wp-json/shoe-customizer/v1/shoe/af1`.

Requires PHP 8.0+ and WooCommerce (capability gate is `manage_woocommerce`, falling back to
`manage_options`).

## Notes

- Follows **WordPress** conventions (`$wpdb`, `dbDelta`, nonces, `wp.media`) — this is a
  separate app from Evolution ERP, so it does **not** use Evolution's `DB::` class.
- All PHP is `php -l` clean. It has **not** been runtime-tested inside WordPress in the dev
  environment (no WP there) — validate on a staging site before production.
- Seed assets are copied into `wp-content/uploads/shoe-customizer/<slug>/`; the config stores
  plain upload URLs (no media-attachment rows needed for the compositor).