SlabUploader/docs/CONTENT-WOO.md

# Content Generation & WooCommerce Integration

Status: SPEC · 2026-08-24 · SlabUploader
Covers: FR16 (deterministic content templates + optional LLM refinement), FR17
(brand voice / GEO), FR18 (editable, never auto-published), FR25–28 (taxonomy sync,
product create, sync log), and the exact WooCommerce REST v3 payload.

## 1. Content generation (FR16–18)

### 1.1 Deterministic templates (always on)
Templates are configured in Settings (`content_templates`, editable per FR32).
Defaults below. Placeholders use `{field}`.

**title** (default):
```
{species} {length_ft}ft {length_in_remainder}in × {width_avg_in}in Wood Slab — {character}
```
Example: `Black Walnut 16ft 0in × 18.2in Wood Slab — Cathedral`
- `length_ft` = floor(length_in / 12), `length_in_remainder` = length_in mod 12 (1 dp).

**short_title** (default):
```
{species} Slab — {character}
```
Example: `Black Walnut Slab — Cathedral`

**description** (default, multi-paragraph):
```
A one-of-a-one {character} {species} slab, {length_ft}ft {length_in_remainder}in long with an
average width of {width_avg_in}in and {thickness_in}in thickness ({bdft} bdft).

Each slab is naturally shaped — width varies along the length at {width_min_in}in to
{width_max_in}in. Sold by the slab; dimensions as measured. {geo_sentence}
```
`geo_sentence` = GEO context sentence from Settings (FR17), e.g.
`"Locally milled and shipped from the Pacific Northwest."` (default if unset: none).

All template math fields come from the deterministic pipeline (never from the LLM).

### 1.2 Optional LLM refinement (FR17, toggleable)
- Triggered only if `content_llm_enabled` is true AND the user taps "Refine with AI"
  on the review screen (never automatic — FR18).
- Prompt (server-side, assembled): system = brand voice + GEO context; user = the
  template-generated title/description + slab facts; task = "improve the title and
  description for a premium one-of-a-one wood slab listing. Keep all measurements
  exact. Do not invent features. Return JSON: {title, short_title, description}."
- **Guardrail (deterministic)**: after the LLM returns, the server re-checks that every
  numeric dimension in the LLM text still matches the pipeline values (regex on
  numbers). Mismatch → reject the LLM output, keep the template version, log the
  rejection. This keeps measurement accuracy deterministic even when the LLM is on.
- Output is always editable (FR18); `content_source` = `llm` when used.
- If the inference endpoint is text-only or unreachable → the button is disabled,
  templates still work. No failure mode blocks publish.

### 1.3 Audit
Every content generation (template or LLM) is logged with inputs (template version,
slab facts), the LLM request/response payload when used (PRD "inference calls logged"),
and the final stored content.

## 2. WooCommerce integration (FR24–28)

### 2.1 Auth & client
- REST v3: `GET/POST/PATCH/DELETE {woo_base_url}/wp-json/wc/v3/…`
- Basic auth: `woo_consumer_key:woo_consumer_secret` (Decision 10; the "username" is
  the consumer key, the "app password" is the consumer secret).
- Client: `httpx` with timeouts (connect 10s, read 60s for image-heavy create).
- `woo_base_url` default: `https://www.whidbeywoodstore.com`.

### 2.2 Taxonomy sync (FR25)
`POST /api/admin/taxonomy/sync` pulls, in order:
1. `GET /products/categories?per_page=100` (paginate) → `woo_taxonomy(kind=category)`
2. `GET /products/tags?per_page=100` → `kind=tag`
3. `GET /products/attributes` → `kind=attribute`
Rebuilds the cache table (delete + insert, single transaction). Returns counts.
Failure → `502 woo_error`; previous cache retained (never delete-then-fail).

### 2.3 Auto-assign taxonomy (FR26)
- **Category**: species value is matched to a Woo category by name (case-insensitive,
  trimmed). Match → that category id. No match → the slab's `category_override`
  (user picks in review) or empty (Woo required-field validation will surface it).
- **Tags**: `[character]` plus optional `[species]` if present as a tag.
- **Attributes**: species/character/length/thickness as product attributes if the
  corresponding Woo attributes exist in the cache (by name). Missing attributes are
  skipped, not created (v1: no attribute creation).
- Every assignment is overridable in the review screen (FR26).

### 2.4 Product create payload (FR27)
`POST /products` — body (only non-null fields sent):
```jsonc
{
  "name": "{title}",
  "type": "simple",
  "status": "pending",            // test-target decision: NEVER "publish" automatically
  "sku": "{sku}",
  "regular_price": "{price}",     // 2 dp string, e.g. "2730.00"
  "description": "{description}",
  "short_description": "{short_title}",
  "categories": [ { "id": <species category id> } ],
  "tags": [ { "id": <char tag id> }, … ],
  "images": [
    { "src": "<data URL or pre-uploaded attachment URL>", "alt": "{species} {character} slab" }
  ],
  "attributes": [ … if present … ],
  "virtual": false,
  "downloadable": false,
  "catalog_visibility": "visible"
}
```
**Image upload strategy** (Woo v3): `images[].src` accepts a URL or a data URL.
For reliability the server:
1. For each customer-facing (inventory, normalized) photo in `seq` order:
   `POST /media` with the JPEG bytes → get attachment `source_url`.
2. Reference those `source_url` values in `images` (≤5, per PRD 1–5 inventory photos).
3. Calibration photos are excluded (FR2).

**Status = `pending`** by default (test-target decision: test products must never go
live without human action). The Settings key `woo_publish_status` (default `pending`)
controls this; Ty flips it to `publish` only when intentionally going live.

### 2.5 Dedupe & idempotency (FR24a)
Before create: `GET /products?sku={sku}`.
- Found → `409 duplicate_sku` (v1 has no update path; human resolves).
- Not found → proceed. (Single-owner, slab-by-slab, so no TOCTOU concern in practice;
  the check is still done for correctness.)

### 2.6 Sync result & logging (FR28)
- On success: set `slabs.woo_product_id`, `status=published`, `published_at`, write
  `sync_log(status=success, woo_product_id, payload_hash)`.
- On Woo HTTP error: `status=failed`, `sync_log(status=failed, http_status, error,
  detail=<Woo error body>)`. Surface in UI + poll response.
- **Partial-failure note** (risk, see IMPL-PLAN): if media uploads succeed but the
  final product POST fails, orphaned Woo attachments may exist. v1: log it; a manual
  cleanup note is surfaced. Not auto-deleted (could delete a real image).

## 3. End-to-end publish sequence (server side)
```
1. validate slab publishable (length,width,thickness,price,species,char,≥1 photo)
2. dedupe by SKU (GET /products?sku=)            → 409 duplicate_sku if exists
3. (re)sync taxonomy if cache older than 1h       → best-effort; use existing cache on fail
4. resolve category/tags/attributes (auto-assign + overrides)
5. upload normalized inventory images → media     → source_urls
6. POST /products (status=pending)                → woo_product_id
7. write sync_log(success), set slab published, purge images
   on any failure at 2–6: write sync_log(failed), slab=failed, (images retained for retry)
```

## 4. What is deterministic vs scoped-inference here
- Deterministic: templates, all dimension text, category/tag/attribute resolution,
  payload assembly, dedupe, logging.
- Scoped inference: optional LLM title/description refinement only, with the
  numeric-accuracy guardrail (§1.2).