diff --git a/Slab capture app PRD.txt b/Slab capture app PRD.txt index 6d80d3f..7021cf4 100644 --- a/Slab capture app PRD.txt +++ b/Slab capture app PRD.txt @@ -1,217 +1,240 @@ -# Slab Capture & WooCommerce Publishing App — PRD - -## Overview -**Purpose** -Build a mobile‑first, self‑hosted web app that streamlines publishing one‑of‑one wood slabs to a WooCommerce store. The app is a field capture → enrichment → publish pipeline that enforces deterministic core logic (measurements, pricing, normalization, sync) and uses inference only in tightly scoped areas (species/character detection and optional content refinement) via a configurable OpenAI‑compatible endpoint. - -**Primary constraints** -- No slab versioning in v1. -- No staff accounts or role complexity in v1. -- No bulk publishing; slab‑by‑slab submission only. -- Measurements must be accurate; manual length entry is authoritative and used to extrapolate widths and bdft. -- No analytics in v1. -- No pricing tiers in v1 — flat price-per-bdft per species/character. -- No app-level auth in v1 — no JWT/login; app relies on HTTPS + trusted network. -- Single SKU per slab; duplicate SKU publish is blocked. -- Images are purged after successful publish (retained only while draft/retry). -- Deploy target: .201, Docker Compose + Caddy. - -## Decisions log (2026-08-24, Ty) -1. Widths: sample 3–5 widths at peaks/troughs of the slab edge (see Open items for the bdft formula). -2. Fallback chain: ruler shot if readable → manual length entry; from manual length + a top-down photo, derive pixel scale and extrapolate widths. -3. Ruler is always in inches. -4. Species/character list = synced from WooCommerce categories (FR25); user sets price-per-bdft per value. -5. No tiers — price = bdft × price_per_bdft, user override before Woo submission. -6. All inference models must support vision (species/character detection operates on slab photos). -7. v1 target store: www.whidbeywoodstore.com. -8. Aspect ratio: 1:1 (Woo best practice), ≥1000×1000 px, slab centered at ~80% fill. -9. Same SKU = blocked (simple dedupe). -10. No app-level auth; Woo API auth = username (consumer key) + app password. -11. Single FastAPI backend (Node service dropped — Python handles WooCommerce REST). -12. Images not needed after WooCommerce submission; purged on successful publish. -13. Deploy on .201; Docker + Caddy preferred. -14. UATs built after the prototype. -15. The schema in the Security section is the pricing-rule shape — confirmed. -16. (Orphan ```md fence fixed.) -17. Bolt.dev deliverable disregarded — this is a Hermes project. -18. bdft formula: average of sampled widths → bdft = L × w_avg × t / 12 (accepted 2026-08-24). -19. No usable top-down photo → manual width entry (accepted 2026-08-24). -20. Normalized image size: 1600×1600 preferred output, 1000×1000 minimum (accepted 2026-08-24). - -## Open items -- (none — all resolved 2026-08-24; see Decisions log items 18–20) - -## Goals and success metrics -**Goals** -- Reduce per‑slab prep time (target: 20–30 → 5–10 minutes). -- Produce consistent, high‑quality product pages (title, description, taxonomy, images). -- Keep deterministic business logic testable and auditable. -- Mobile‑first UX with offline capture and fast feedback. -- Allow Ty to host and control inference via a configurable OpenAI endpoint. - -**Success metrics** -- Average time from first photo to published product ≤ 10 minutes. -- OCR SKU accuracy ≥ 95% in staged conditions. -- Dimension extraction accuracy within ±0.25 in when ruler photo usable. -- Photo normalization produces consistent aspect ratio and ~80% frame fill for 95% of inventory photos. -- Price recommendation accepted or adjusted by user in ≤ 2 edits for 90% of slabs. - -## Non‑goals -- Multi‑tenant SaaS or ERP integrations in v1. -- Generic SKU inventory management. -- Complex user roles or staff permissions. -- Bulk import/publish workflows. - -## Users and core use cases - -**Primary user** -- Ty (Owner/Expert): captures, configures pricing rules, reviews and publishes slabs. - -**Secondary user** -- Field operator (optional): may capture photos and basic data; no special permissions required. - -**Core use cases** -- Capture: Stage slab (green sheet, SKU label, ruler), take calibration photos (SKU close‑up, ruler shot), then 1–5 inventory photos. -- Fallbacks: If SKU or ruler unreadable, allow manual entry (SKU or length). Manual length is authoritative and used to extrapolate widths and sqft. -- Enrich: Species detection (optional inference) or manual selection; character selection (manual or optional inference); thickness manual entry. -- Pricing: Apply bdft pricing rules (species + character) to compute price recommendation; allow override. -- Photo normalization: Background removal, auto‑crop to ~80% frame fill, enforce 1:1 aspect ratio, optional merchandising filter. -- Review & publish: Final review screen with full override capability; publish single slab to WooCommerce using App Passwords. -- Configuration: Configure OpenAI endpoint, WooCommerce credentials, pricing rules, brand voice, and GEO context. - -## High level requirements summary -- Deterministic core: all measurement math, pricing, normalization, and WooCommerce sync must be deterministic and unit‑tested. -- Scoped inference: species/character detection and optional content refinement only; inference must be toggleable and use Ty’s configured OpenAI endpoint. -- Mobile first: usable on modern iPhone and Android browsers; offline capture and local drafts. -- Single slab workflow: no batch publish in v1; each slab is captured, enriched, reviewed, and published individually. - -## Functional requirements (detailed) - -### Capture and calibration -- **FR1:** Camera capture for calibration photos (SKU close‑up, ruler shot) and 1–5 inventory photos. -- **FR2:** Calibration photos are internal only and never uploaded to WooCommerce. -- **FR3:** Client runs deterministic SKU OCR (Tesseract.js) on SKU close‑up; if OCR fails, prompt manual SKU entry. -- **FR4:** Client runs lightweight ruler detection (OpenCV.js). If client pass fails, upload ruler photo to server for advanced deterministic processing. -- **FR5:** If ruler detection fails or ruler photo missing, prompt manual length entry. Manual length is authoritative; system extrapolates widths using pixel ratios from inventory photos when available. -- **FR6:** All capture flows must be offline‑first with local caching and an upload queue. - -### Dimensions, thickness, and calculations -- **FR7:** Compute length, one or more widths, sqft, and bdft deterministically. -- **FR8:** Thickness is always manually entered and treated as authoritative. -- **FR9:** All dimension math must be deterministic, unit‑tested, and reproducible. - -### Species and character -- **FR10:** Support species selection via optional inference or manual selection from a controlled list. Inference must return a confidence score; below threshold require manual confirmation. -- **FR11:** Character selection is manual by default; optional inference allowed but must be confirmable. -- **FR12:** User can override species/character at any time prior to publish. - -### Pricing engine -- **FR13:** UI to define bdft pricing rules by species and character (flat price per bdft; no tiers in v1). Species/character values come from the synced WooCommerce category list (FR25). -- **FR14:** Deterministic bdft calculation and application of pricing rules to produce a price recommendation. -- **FR15:** Price recommendation editable by user; final price stored as authoritative. - -### Content generation (scoped inference) -- **FR16:** Generate title, short title, and description using deterministic templates augmented by optional LLM refinement via Ty’s OpenAI endpoint. -- **FR17:** Generated content must be SEO/GEO aligned and reflect configured brand voice; LLM use is optional and toggleable. -- **FR18:** All generated content is editable before publish; no automatic publishing of LLM output. - -### Photo normalization and merchandising -- **FR19:** Remove green‑sheet background deterministically (RemBG/U²Net or equivalent). -- **FR20:** Detect slab boundaries and auto‑crop so slab fills ~80% of frame; enforce 1:1 aspect ratio, slab centered; output 1600×1600 px preferred (1000×1000 minimum). -- **FR21:** Store both original and normalized images. -- **FR22:** Optional merchandising filter (contrast, warmth, grain enhancement) applied deterministically; toggleable per slab. -- **FR23:** Provide photo review UI to reorder, delete, or retake images. - -### WooCommerce sync and taxonomy -- **FR24:** Authenticate to WooCommerce using consumer key (username) + consumer secret (App Password) against www.whidbeywoodstore.com. -- **FR24a:** Publish is blocked if the slab SKU already exists in WooCommerce (simple dedupe, no update path in v1). -- **FR25:** Sync categories, tags, and attributes from WooCommerce and cache locally. -- **FR26:** Auto‑assign taxonomy based on species/character mapping; allow manual override. -- **FR27:** Create/update single WooCommerce product per slab with SKU, titles, description, price, categories, attributes, and normalized images. -- **FR28:** Log sync results and surface errors; store WooCommerce product ID on success. - -### Drafts, review, and publish -- **FR29:** Maintain a draft slab state with full metadata and photos. -- **FR30:** Provide a single review screen showing all fields and normalized images; every field is editable. -- **FR31:** Publish action performs deterministic server‑side processing and WooCommerce sync; update status to Published/Failed with error details. - -### Configuration and hosting -- **FR32:** Settings UI for OpenAI base URL, OpenAI API key, model name, WooCommerce URL, WooCommerce App Password, pricing rules, brand voice, GEO context. -- **FR33:** App deploys via Docker Compose on .201 with Caddy for HTTPS (single domain, reverse proxy to frontend + fastapi). -- **FR34:** All secrets stored encrypted at rest; all client‑server traffic over HTTPS. - -## Non‑functional requirements -- **Performance:** Client capture and local OCR within 1–2s; server normalization and inference within 3–5s per slab target. -- **Reliability:** Offline capture and queued sync; deterministic logic fully unit‑tested. -- **Security:** Encrypted secrets, HTTPS, minimal persistent credentials on client. -- **Maintainability:** Clear separation of deterministic code and inference code; modular services. -- **Usability:** One‑hand operation, large touch targets, clear distinction between internal and customer photos. - -## Architecture and tech stack - -**Client (mobile web / PWA)** -- SvelteKit (mobile‑first) -- TailwindCSS for UI -- Tesseract.js for client SKU OCR (deterministic) -- OpenCV.js for lightweight ruler detection and preview cropping -- IndexedDB for offline drafts and photo caching -- Camera API for capture and immediate preview - -**Server (self‑hosted, containerized)** -- FastAPI (Python) for deterministic image pipeline, advanced ruler detection, bdft math, RemBG/U²Net background removal, species/character inference endpoint (optional), content generation wrapper that calls Ty’s OpenAI endpoint, and WooCommerce REST integration (taxonomy sync, product creation, sync logging) — the Node.js service from the original draft was folded in (see Decision 11). -- SQLite for v1 (slab records, pricing rules, taxonomy cache, sync history). Optional Postgres later. - -**Inference** -- Configurable OpenAI‑compatible endpoint (user supplies base URL and key). **The endpoint/model must support vision** — species/character detection operates on slab photos. Inference limited to species/character detection and optional content refinement. All inference calls logged and include confidence scores. - -**Deployment** -- Docker Compose with `frontend` and `fastapi` services on .201. -- Caddy for HTTPS and reverse proxy. -- Docker compose as the service supervisor. - -**Security** -- AES encryption for stored secrets. -- No app-level auth in v1 (single owner; app protected by HTTPS + network trust). -- HTTPS enforced. - -### Pricing rule schema (confirmed as the pricing-rule shape — Decision 15) -id: uuid -species: string -character: string -price_per_bdft: float -created_at: timestamp -updated_at: timestamp - - -## Key flows and acceptance criteria - -### Capture → Enrich → Publish flow -1. New slab: user stages slab and opens app. -2. Calibration: take SKU close‑up and ruler shot (internal only). Client runs SKU OCR and lightweight ruler detection. If either fails, prompt manual SKU or length. Manual length is authoritative. -3. Inventory photos: capture 1–5 customer‑facing photos. Client stores originals locally. -4. Upload: client uploads draft to server for advanced processing. -5. Server processing: advanced ruler detection → pixel→inch scaling → widths inference → bdft calc → species/character inference (optional) → pricing engine → photo normalization → content generation (optional via configured OpenAI endpoint). -6. Review: client receives enriched draft; user edits/overrides any field. -7. Publish: user triggers publish; FastAPI syncs taxonomy and creates the WooCommerce product with normalized images (SKU-deduped per FR24a). Status updated and logged. - -### Acceptance criteria -- End‑to‑end slab capture to published product works on modern iPhone and Android browsers. -- Manual length override correctly recalculates widths, sqft, and bdft. -- Photo normalization produces theme‑compliant images with slab occupying ~80% frame in 95% of tests. -- WooCommerce product created with normalized images and correct taxonomy mapping. -- Deterministic functions covered by unit tests; inference calls logged and stored for audit. - -## Operational and debugging notes -- Local dev: Docker Compose with `frontend` and `fastapi`. Mobile testing over LAN/Tailscale against the Caddy-served domain (no public tunnel needed). -- Logging: centralized logs per service; store inference request/response payloads for audit. -- Testing: unit tests for deterministic math and image processing; integration tests for WooCommerce sync against a staging store. -- Secrets: store App Passwords and OpenAI keys encrypted; rotate keys periodically. -- Monitoring: health endpoints and job queue visibility for image normalization and publish tasks. - -## Next recommended deliverables -1. Technical spec for the deterministic image pipeline and ruler→inch math (algorithms and test vectors). -2. OpenAPI contract between SvelteKit client and FastAPI. -3. (Disregarded — this is a Hermes project, not bolt.diy.) -4. Deployment playbook (Docker Compose, Caddy, backup, key rotation). - - +# Slab Capture & WooCommerce Publishing App — PRD + +## Overview +Build a mobile-first, self-hosted web app that streamlines publishing one-of-a-one wood +slabs to a WooCommerce store. The app is a photo capture → calibration → inference → +publish pipeline. + +**Primary constraints** +- No slab versioning in v1. +- No staff accounts or role complexity in v1. +- No bulk publishing; slab-by-slab submission only. +- No analytics in v1. +- No pricing tiers in v1 — flat price-per-bdft per species/wood-category. +- No app-level auth in v1 — app relies on HTTPS + trusted network. +- Single SKU per slab; duplicate SKU publish is blocked. +- Images are purged after successful publish (retained only while draft/retry). +- Deploy target: .201, Docker Compose + Caddy. + +## Decisions log (2026-08-27, Ty) +1. No calibration photos — user manually enters SKU, length, thickness. +2. First photo is the measurement photo (must be top-down, lens parallel to broad side). +3. All photos go through background removal + 80% frame-fill crop. +4. Output: transparent PNGs, minimum 1600 px on the smaller dimension, aspect ratio preserved. +5. Green or black sheet — algorithm auto-detects background color from image borders. +6. WooCommerce categories synced from store: Species (1 required, leaf-only), Wood Category (1+ required, leaf-only). +7. WooCommerce attributes: Edge Type (1 required), Figure (1+ required), Grade (1+ required), Thickness (1 required, rounded up to nearest Woo attribute range). +8. WooCommerce tags: fig-* only (1+ required, e.g., fig-chat = Chatoyant). +9. Two-call inference: Call 1 (vision, wood expert) → Call 2 (text, content gen). Both configurable. +10. Call 1 runs automatically after calibration. User reviews/corrects before triggering Call 2. +11. Inference timeout >45s or non-200 → error with retry. User can fill fields manually. +12. Woo product status set to "published" by default (configurable in settings). +13. All inference prompts stored server-side, editable in settings with reset-to-default. +14. Brand voice + GEO context injected into Call 2 prompt. +15. WooCommerce credentials (username + App Password) stored client-side in settings. +16. Inference endpoint: configurable OpenAI-compatible API (user provides base URL, key, model). +17. Test connection verifies text completion + vision support. +18. Offline capture not required for MVP. + +## Open items +- (none — all resolved 2026-08-27) + +## Goals and success metrics +**Goals** +- Reduce per-slab prep time (target: 20-30 to 5-10 minutes). +- Produce consistent, high-quality product pages (title, description, taxonomy, images). +- Keep deterministic core logic testable and auditable. +- Mobile-first UX with fast feedback. +- Allow Ty to host and control inference via a configurable OpenAI endpoint. + +**Success metrics** +- Average time from first photo to published product <= 10 minutes. +- Dimension extraction accuracy within +/- 0.25 in. +- Photo normalization produces consistent 80% frame fill for 95% of inventory photos. +- Inference results accepted or corrected by user in <= 2 edits for 90% of slabs. + +## Non-goals +- Multi-tenant SaaS or ERP integrations in v1. +- Generic SKU inventory management. +- Complex user roles or staff permissions. +- Bulk import/publish workflows. +- Offline capture for MVP. + +## Users and core use cases + +**Primary user** +- Ty (Owner/Expert): captures, configures, reviews, and publishes slabs. + +**Core use cases** +- Capture: Stage slab on green or black sheet with lights, take 1-5 photos. +- Enter metadata: SKU, length (in), thickness (in). +- Calibration: App processes first photo - BG removal, longest dimension detection, + area measurement (sqft), bdft calc, then processes all photos for BG removal + crop. +- Inference: Call 1 (vision) auto-runs, populating taxonomy/content. User reviews/corrects. + Call 2 (text) user-triggered for title/description/short description. +- Review & publish: Final review screen with full override capability; publish to WooCommerce. +- Configuration: Settings for inference endpoint, Woo credentials, pricing rules, + brand voice, GEO context, prompts. + +## High level requirements summary +- Deterministic core: all measurement math, pricing, normalization, and WooCommerce sync + must be deterministic and unit-tested. +- Scoped inference: species/category/attribute detection and content generation only; + inference must be toggleable and use Ty's configured OpenAI endpoint. +- Mobile first: usable on modern iPhone and Android browsers. +- Single slab workflow: no batch publish in v1; each slab is captured, enriched, + reviewed, and published individually. + +## Functional requirements (detailed) + +### Capture and calibration +- **FR1:** Camera capture for 1-5 inventory photos. First photo must be top-down, + lens parallel to the slab's broad side. +- **FR2:** User manually enters SKU (3-24 chars, [A-Z0-9-]), length (in), thickness (in). +- **FR3:** App detects background color from image borders (green or black sheet). +- **FR4:** First photo: BG removal - find longest dimension - compute scale + (longest_px / user-length) - compute area (sqft) - bdft = sqft * thickness / 12. +- **FR5:** All photos: BG removal - crop to 80% frame fill - save as transparent PNG, + minimum 1600 px on smaller dimension, aspect ratio preserved. +- **FR6:** User can retake the first photo or abort and start fresh. + +### Dimensions and calculations +- **FR7:** Compute length (user-entered), area (sqft), and bdft deterministically. +- **FR8:** Thickness is always manually entered and treated as authoritative. +- **FR9:** All dimension math must be deterministic, unit-tested, and reproducible. + +### Taxonomy (WooCommerce sync) +- **FR10:** Sync categories, attributes, and tags from WooCommerce and cache locally. +- **FR11:** Species category: 1 required, leaf-only selection. +- **FR12:** Wood Category: 1+ required, leaf-only selection (parents shown for grouping only). +- **FR13:** Edge Type attribute: 1 required. +- **FR14:** Figure attribute: 1+ required. +- **FR15:** Grade attribute: 1+ required. +- **FR16:** Thickness attribute: 1 required, mapped by rounding up user-entered + thickness to nearest Woo attribute range. +- **FR17:** Tags: fig-* only, 1+ required. +- **FR18:** Auto-assign taxonomy based on inference results; allow manual override. + +### Pricing engine +- **FR19:** UI to define bdft pricing rules by species and wood category. +- **FR20:** Deterministic bdft calculation and application of pricing rules to produce + a price recommendation. +- **FR21:** Price recommendation editable by user; final price stored as authoritative. + +### Inference (two-call architecture) +- **FR22:** Call 1 (vision): auto-run after calibration. Input: all inventory photos + (downscaled to 1024px max, using original pre-crop photos), user metadata, synced + Woo taxonomy. Output: species, wood categories, edge type, figure, grade, + character/inclusions/voids/checks with severity, top 3 wood categories with + confidence. If no species match above threshold, omit and require manual selection. +- **FR23:** Call 2 (text): user-triggered after Call 1 curation. Input: deterministic + data + Call 1 results + brand voice + GEO context. Output: title, description, + short description. +- **FR24:** Inference prompts stored server-side, editable in settings, reset-to-default available. +- **FR25:** Progress indicator during inference calls (latency expected). +- **FR26:** Timeout >45s or non-200 - visible error with retry option. +- **FR27:** All inference results editable; no automatic publish of LLM output. +- **FR28:** Inference endpoint configured via settings: base URL, API key, model name. + Test connection verifies text + vision support. + +### Photo normalization and output +- **FR29:** Background removal: chroma-key for green/black, fallback to U2Net matting. +- **FR30:** Crop to 80% frame fill, slab centered, aspect ratio preserved, + minimum 1600 px on smaller dimension. +- **FR31:** Output as transparent PNG (ideal for WooCommerce). +- **FR32:** Store both original and processed images. Purge after successful publish. + +### WooCommerce sync and publish +- **FR33:** Authenticate to WooCommerce using consumer key + App Password. +- **FR34:** Publish is blocked if the slab SKU already exists (simple dedupe, no update path). +- **FR35:** Create WooCommerce product with SKU, title, description, short description, + price, categories, attributes, tags, and normalized PNG images. +- **FR36:** Default product status: "published" (configurable in settings). +- **FR37:** Log sync results and surface errors; store WooCommerce product ID on success. + +### Drafts, review, and publish +- **FR38:** Maintain a draft slab state with full metadata and photos. +- **FR39:** Provide a single review screen showing all fields; every field is editable. +- **FR40:** Publish action performs deterministic server-side processing and WooCommerce + sync; update status to Published/Failed with error details. + +### Configuration and hosting +- **FR41:** Settings UI for inference endpoint, Woo credentials, pricing rules, + brand voice, GEO context, prompts. +- **FR42:** App deploys via Docker Compose on .201 with Caddy for HTTPS. +- **FR43:** All secrets stored encrypted at rest; all client-server traffic over HTTPS. + +## Non-functional requirements +- **Performance:** Client capture and local processing within 1-2s; server normalization + within 3-5s per slab; inference calls within 45s. +- **Reliability:** Deterministic logic fully unit-tested. +- **Security:** Encrypted secrets, HTTPS, minimal persistent credentials on client. +- **Maintainability:** Clear separation of deterministic code and inference code. +- **Usability:** One-hand operation, large touch targets, clear distinction between + internal processing and customer-facing output. + +## Architecture and tech stack + +**Client (mobile web / PWA)** +- SvelteKit (mobile-first) +- TailwindCSS for UI +- Camera API for capture and immediate preview +- No OCR, no OpenCV on client + +**Server (self-hosted, containerized)** +- FastAPI (Python) for deterministic image pipeline, bdft math, pricing, + background removal, crop/normalize, WooCommerce REST integration, + inference wrappers, taxonomy sync +- SQLite for v1 (slab records, pricing rules, taxonomy cache, sync history) + +**Inference** +- Configurable OpenAI-compatible endpoint (user supplies base URL, key, model). + Must support vision. Two calls: wood expert (vision) + content generation (text). + All inference calls logged. + +**Deployment** +- Docker Compose with frontend and fastapi services on .201. +- Caddy for HTTPS and reverse proxy. + +**Security** +- AES encryption for stored secrets. +- No app-level auth in v1. +- HTTPS enforced. + +### Pricing rule schema +id: uuid +species: string +wood_category: string +price_per_bdft: float +created_at: timestamp +updated_at: timestamp + +## Key flows and acceptance criteria + +### Capture -> Calibrate -> Infer -> Publish flow +1. New slab: user stages slab and opens app. +2. Capture: take 1-5 inventory photos. +3. Enter metadata: SKU, length, thickness. +4. Calibration: server processes first photo (BG removal, area, bdft), + processes all photos (BG removal, crop, PNG). +5. Inference: Call 1 auto-runs (vision), populating taxonomy/content. + User reviews/corrects. Call 2 user-triggered (text), generating + title/description/short description. +6. Review: user edits/overrides any field. +7. Publish: user triggers publish; FastAPI syncs taxonomy, creates + WooCommerce product, purges images. Status updated and logged. + +### Acceptance criteria +- End-to-end slab capture to published product works on modern iPhone and Android browsers. +- Area measurement accuracy within +/- 0.25 in^2. +- Photo normalization produces 80% frame fill, transparent PNG, 1600px min on smaller dim. +- WooCommerce product created with normalized images, correct taxonomy, and correct content. +- Deterministic functions covered by unit tests; inference calls logged. + +## Operational and debugging notes +- Local dev: Docker Compose with frontend and fastapi. Mobile testing over LAN/Tailscale. +- Logging: centralized logs per service; inference request/response payloads stored for audit. +- Testing: unit tests for deterministic math and image processing; integration tests + for WooCommerce sync against a staging store. +- Secrets: store App Passwords and inference keys encrypted; rotate keys periodically. +- Monitoring: health endpoints and job queue visibility. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index cab129e..5be38a2 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,174 +1,137 @@ # Architecture -Status: SPEC · 2026-08-24 · SlabUploader -Companion to: PRD (root), TECH-SPEC-PIPELINE.md, DATA-MODEL.md, OPENAPI.md, DEPLOYMENT.md. +Status: SPEC · 2026-08-27 · SlabUploader +Locked so far: topology C (hybrid), swimlane, what-runs-where. Remaining sections TBD. -## 1. Service topology (2 containers + 1 reverse proxy) +Companion: PRD (root), TECH-SPEC-PIPELINE.md. -Per Decision 11 the original Node service is folded into FastAPI. Final v1 topology: +## 1. Topology (hybrid) + +Phone does the happy-path pipeline (mask, length axis, sqft/bdft, 3:4 PNG). +FastAPI stores drafts, runs U2Net only on demand, proxies inference, talks to Woo. +reverse proxy terminates HTTPS. ``` - ┌──────────────────────────────────────────┐ - mobile (PWA) │ .201 host │ - ┌──────────────┐ HTTPS │ ┌─────────┐ ┌──────────────────┐ │ - │ SvelteKit │───────┼─▶│ Caddy │───────▶│ frontend (nginx │ │ - │ browser │ │ │ :443 │ :5173 │ static + /api │ │ - │ IndexedDB │ │ │ slab.* │ ─────▶│ proxy) │ │ - │ camera API │ │ └─────────┘ └──────────────────┘ │ - └──────────────┘ │ │ /api → :8000 │ - │ (offline: │ ▼ │ - all local) │ ┌──────────────────┐ │ - │ │ fastapi │ │ - │ │ :8000 │ │ - │ │ ┌────────────┐ │ │ - │ │ │ pipeline │ │ │ - │ │ │ (determin. │ │ │ - │ │ └────────────┘ │ │ - │ │ ┌────────────┐ │ │ - │ │ │ woo client │ │ │ - │ │ └────────────┘ │ │ - │ │ ┌────────────┐ │ │ - │ │ │ inference │ │ │ - │ │ └────────────┘ │ │ - │ └───────┬──────────┘ │ - │ │ │ - │ SQLite + image vols (named volumes)│ - └──────────────────────────────────────────┘ - │ (configurable OpenAI-compat - ▼ vision endpoint, e.g. .202) +phone (SvelteKit) + capture, mask, sliders, length axis, sqft/bdft, 3:4 PNG + if mask still bad → POST one photo → FastAPI U2Net → mask back → user continues + +server + reverse proxy → frontend (static) + → fastapi : store, settings, prompts, taxonomy, Woo, inference proxy, U2Net ``` -- **frontend** — SvelteKit (SSG/SPA mode) + Tailwind. Built to static, served by an - nginx container. Pure client app; talks to `/api` on the same origin. No build-time - secrets. This is the PWA (SW + IndexedDB). -- **fastapi** — one Python service owning: deterministic image pipeline, bdft math, - pricing engine, WooCommerce REST client, taxonomy sync, inference wrapper, - content generation. SQLite + image storage in named volumes. -- **caddy** — reverse proxy + automatic HTTPS. Fronts `frontend` and routes `/api` - to `fastapi`. No separate Traefik/systemd — compose is the supervisor (Decision 13). +- Happy path never leaves the phone. +- U2Net is explicit “Try harder” (or coverage failure), not every slab. +- Woo + LLM keys stay on the server. Browser does not call Woo or the vision endpoint directly. -No message broker in v1. Long jobs (normalization, publish) run in-process via a -small background worker (FastAPI `BackgroundTasks` + a lightweight in-process queue, -or `arq` on SQLite/Redis only if needed). See §6. +## 2. Swimlane -## 2. Client/server split (authoritative vs hint) +```mermaid +flowchart TB + subgraph Phone["Phone — SvelteKit"] + P1[New Wood: 1–5 photos] + P2[BG overlay + sheet / sensitivity / edge / feather] + P3{Edge OK?} + P4[Length axis overlay — rotate / confirm] + P5[User length + thickness + SKU] + P6[sqft, bdft, 6in widths, 3:4 PNGs] + P7[Review Call 1 fields] + P8[Tap Generate text] + P9[Review title / desc — publish] + end -Per TECH-SPEC §1.5: the client runs a *light* pass for instant feedback; the server -runs the *authoritative* pass. Stored and published values are always the server's. + subgraph API["server — FastAPI"] + A1[U2Net: one photo in, mask out] + A2[Store draft: originals + PNGs + numbers] + A3[Call 1 proxy — vision] + A4[Call 2 proxy — text] + A5[Woo: taxonomy, SKU check, create product] + end -| Capability | Client (hint) | Server (authoritative) | -|---|---|---| -| SKU OCR | Tesseract.js (accept/manual) | re-run; on mismatch surface both, user picks | -| Ruler scale | OpenCV.js quick check | full tick detection + cross-check | -| Widths / bdft | none (needs server geometry) | full pipeline | -| Green removal / crop | preview only | full normalization | -| Species/character | none | inference (vision) + manual | -| Pricing | none | pricing engine | -| Content (title/desc) | none | templates + optional LLM | + subgraph LLM["Your OpenAI-compatible endpoint"] + L1[Wood expert — all photos at 1024] + L2[Title / desc / short desc] + end -The client never publishes. Only the server writes to WooCommerce (FR24/FR27). + subgraph Woo["WooCommerce store"] + W1[Categories / attributes / fig-* tags] + W2[New product live or draft per setting] + end -## 3. Offline-first PWA (Decision: full offline per PRD) - -### 3.1 What lives on the client (IndexedDB) -- **Draft slabs**: full metadata (all review-screen fields) + photo blobs - (originals). Calibration photos included. IndexedDB object stores: - `slabs`, `photos` (blob), `syncQueue`. -- **Service Worker**: precache app shell (SvelteKit build). API is *not* cached — - network-first for API, but the capture flow itself needs no network. - -### 3.2 Capture → queue → sync flow -1. Capture is fully offline: photos → IndexedDB, OCR/ruler hints run locally. -2. Draft persists to IndexedDB after every step (no "save" button — always saved). -3. **Upload queue**: when online, the PWA pushes pending drafts (metadata + photo - blobs) to `POST /api/slabs/{id}/upload`. Server runs the authoritative pipeline, - returns the enriched draft. Client merges enriched values, marks synced. -4. **Publish** is always an online action (needs Woo). If offline, the slab stays - `ready`; publish is enabled when connectivity returns. -5. Reconciliation: each draft carries a `client_rev` (monotonic int). Server rejects - an upload whose `client_rev` < the stored rev for that slab (stale). Conflict - surfaces in UI for the user to resolve. v1 has a single owner, so conflicts are - rare; the mechanism is there for correctness. - -### 3.3 Connectivity detection -`navigator.onLine` + a lightweight `GET /api/health` probe. UI shows offline banner -and disables publish. No hard dependency on either — capture works regardless. - -## 4. Data flow (happy path) - -``` -[client] capture (offline) - → OCR SKU (hint) / ruler (hint) / 1–5 photos → IndexedDB draft (rev=1) -[online] PWA → POST /api/slabs {draft, rev=1} - POST /api/slabs/{id}/upload {photo blobs} -[server] authoritative pipeline: - ruler→scale → geometry → widths → bdft → species/char (inference, opt) - → pricing → normalization → content (opt LLM) - → store enriched draft (status=review, rev=2), store original+normalized images -[client] GET /api/slabs/{id} → review screen (all fields editable) -[client] PUT /api/slabs/{id} {overrides, rev=2} -[client] POST /api/slabs/{id}/publish -[server] taxonomy sync (if needed) → Woo create (draft/pending) → store woo_product_id - → status=published → purge images (Decision 12) + P1 --> P2 --> P3 + P3 -->|no — Try harder| A1 + A1 --> P2 + P3 -->|no — Retake| P1 + P3 -->|yes| P4 --> P5 --> P6 + P6 --> A2 + A2 --> A3 --> L1 --> A3 --> P7 + P7 --> P8 --> A4 --> L2 --> A4 --> P9 + P9 --> A5 + A5 --> W1 + A5 --> W2 ``` -## 5. Determinism boundary +## 3. Clarifications -Everything left of the "inference" and "content" boxes is deterministic and unit- -tested (PRD "Deterministic core"). The two inference-touching paths are: -- species/character detection (vision) — toggleable, returns confidence -- optional content refinement (text LLM) — toggleable +1. **Happy path** stays on the phone through PNG + numbers. FastAPI is idle until the user has a confirmed mask (or taps Try harder). +2. **Try harder** is U2Net on **one photo** (the one on screen). Mask comes back; sliders still apply. Not a full re-pipeline on the server. +3. **Draft upload** sends **originals + processed PNGs + length/thickness/SKU/sqft/bdft/widths**. Originals are needed if Call 1 or a later retry must not depend on the tab still being open. After successful Woo publish, server deletes both. +4. **Call 1** is server-side so the vision key never sits in the browser. Body: all originals downscaled to 1024 + Woo taxonomy snapshot + SKU/length/thickness. Timeout 45s → error + retry on the phone. User **must** curate before Call 2. +5. **Call 2** does not auto-fire. User taps Generate text. Server sends curated Call 1 + deterministic numbers + brand/GEO + prompt. +6. **Woo** is only FastAPI. Browser never sees the App Password. Duplicate SKU → stop, show error, no edit-same-SKU in MVP. +7. **Settings** (species $/bdft, prompts, endpoint, Woo, publish status) live on the server; the phone is just the form. -Both are wrapped so that toggling them OFF leaves a fully functional deterministic -app. The app must pass its entire test suite with inference disabled. +## 4. What runs where -## 6. Concurrency & jobs - -- v1 is single-owner, single-slab workflow (no bulk). Concurrency is minimal. -- Long ops (normalization ~3–5s, publish with image upload) use FastAPI - `BackgroundTasks` + a per-slab status field (`processing`/`ready`/`publishing`/ - `published`/`failed`). Client polls `GET /api/slabs/{id}` (short, exponential backoff). -- If a job dies, the slab is `failed` with a reason; re-publish is idempotent by - SKU-dedupe (FR24a) — but v1 has no update path, so a failed publish that already - created the Woo product is surfaced for manual handling (see IMPL-PLAN risk). -- No external broker (Redis) in v1. If the in-process queue proves insufficient, - add `arq` + a single Redis container — a documented, reversible extension. - -## 7. Security (Decision 10, PRD Security) - -- No app-level auth. App is reachable only on the trusted LAN/Tailscale - (domain `slab.tyubumini.local`). HTTPS enforced by Caddy. -- Secrets (Woo consumer key/secret, inference key, AES master key) stored encrypted - at rest (AES-GCM) in SQLite; the AES key itself is an env var injected by compose, - never in the DB. Config is editable via the Settings UI (FR32) but values are - re-encrypted on save. -- Client stores no persistent secrets. The PWA needs none — all secrets server-side. -- All client↔server traffic HTTPS. - -## 8. Deployment target - -- Host: **.201** (no inference there; inference is a remote configurable endpoint). -- Stack: Docker Compose (`frontend`, `fastapi`) + Caddy (container or host-managed — - see DEPLOYMENT.md). Domain: `slab.tyubumini.local` (Decision: LAN/Tailscale only). -- Named volumes: `slab_db` (SQLite), `slab_images` (original+normalized). Backed up - per DEPLOYMENT.md. - -## 9. Extensibility (documented, not built) - -- Postgres swap for SQLite (DATA-MODEL keeps the schema portable). -- Redis/arq if job volume grows. -- Update path for existing Woo products (v2; v1 is create-only by SKU dedupe). -- Multi-slab bulk (explicit non-goal v1). -- Staff accounts/roles (explicit non-goal v1). - -## 10. Tech stack (pinned intent — exact versions at scaffold) - -| Layer | Choice | +| Job | Where | |---|---| -| Client | SvelteKit, TailwindCSS, Tesseract.js, OpenCV.js, IndexedDB, Camera API, Workbox/SW | -| Server | Python 3.12, FastAPI, Pydantic v2, OpenCV (cv2), numpy, Pillow, RemBG/U²Net (onnx), httpx | -| Woo | WooCommerce REST v3 via httpx (consumer key/secret, Basic auth) | -| DB | SQLite (stdlib `sqlite3` or SQLAlchemy; see DATA-MODEL) | -| Inference | OpenAI-compatible client (configurable base_url/key/model; must be vision-capable) | -| Proxy/HTTPS | Caddy | -| Packaging | Docker Compose | +| Camera, 1-5 photos | Client | +| Sheet detect, chroma-key / black threshold, sliders, flood-fill | Client | +| U2Net | Server, on demand | +| Length axis overlay, 6" widths, sqft, bdft | Client | +| 3:4 PNG, 80% fill | Client | +| Draft + originals + processed PNGs | Server (after user continues) | +| Species $/bdft, Woo creds, prompts, brand/GEO | Server | +| Call 1 (vision, all photos @1024) | Server proxy | +| Call 2 (title/desc) | Server proxy, after Call 1 curation | +| Woo taxonomy sync + publish | Server | + +## 5. Secrets and settings + +**Server-side only (never in browser JS):** +1. WooCommerce consumer key + consumer secret (App Password). Server uses HTTP Basic Auth to call `/wp-json/wc/v3/`. Stored encrypted at rest in SQLite (AES-GCM). +2. Inference endpoint base URL + API key. Stored encrypted. Server proxies all inference calls. +3. AES master key. Env var on server, never in the DB. + +**Browser-side (no secrets):** +1. User preferences: sheet mode, sensitivity, edge offset, feather. Persisted in localStorage, reset-to-default available. +2. Species list with $/bdft. Read from server settings sync. +3. Taxonomy snapshot (categories, attributes, tags). Read from server. No auth needed. + +**Flow:** +1. User enters Woo credentials in Settings UI on the phone. +2. Browser POSTs them to `/api/settings` on FastAPI. Server stores encrypted. +3. Server syncs taxonomy from Woo, caches in SQLite. +4. Client reads taxonomy from `/api/admin/taxonomy` — no auth needed. +5. All Woo calls go server-to-woo. Browser never calls Woo REST directly. + +This is the canonical WooCommerce App Password integration pattern. Browser-to-Woo REST requires CORS configuration on the Woo site, which is not under your control. + +## 6. Status machine + +``` +draft → calibrated → ready → publishing → published + │ │ ↑ + └→ failed ────┴────────────────┘ (woo_product_id set) +any → failed (with error) +``` + +1. **draft** — user took photos, no mask confirmed yet. +2. **calibrated** — user confirmed the BG edge, confirmed length axis, entered length/thickness/SKU. Client computed sqft/bdft/widths. Draft uploaded to server. +3. **ready** — all mandatory fields populated (species, wood category, edge type, figure, grade, thickness, price, title/desc/short desc, at least one photo). Values can come from Call 1, manual entry, or a mix. Inference is optional; the user can fill everything by hand and go straight to ready. +4. **publishing** — Woo create in flight. Poll for result. +5. **published** — Woo product created, woo_product_id stored. Images purged. +6. **failed** — pipeline, inference, or publish error. Error detail stored. Retry available. + +Call 1 and Call 2 are assist-only. They do not gate the flow. If the user skips inference, the path is: calibrated → ready → publishing → published. diff --git a/docs/CONTENT-WOO.md b/docs/CONTENT-WOO.md deleted file mode 100644 index 9903c91..0000000 --- a/docs/CONTENT-WOO.md +++ /dev/null @@ -1,151 +0,0 @@ -# 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": } ], - "tags": [ { "id": }, … ], - "images": [ - { "src": "", "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=)`. 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). diff --git a/docs/DATA-MODEL.md b/docs/DATA-MODEL.md index 175a1f4..5bcb751 100644 --- a/docs/DATA-MODEL.md +++ b/docs/DATA-MODEL.md @@ -1,166 +1,220 @@ -# Data Model (SQLite, v1) +# Data Model -Status: SPEC · 2026-08-24 · SlabUploader -Storage: single SQLite file (volume `slab_db`). Schema kept portable to Postgres -(DATETIME→TIMESTAMPTZ, TEXT blobs→bytea/objects). All math values stored full -precision (float64); display rounding is a presentation concern (TECH-SPEC §2). +Status: SPEC · 2026-08-27 · SlabUploader +Storage: single SQLite file. Schema portable to Postgres. -## Conventions -- IDs: `TEXT` UUIDv4 (client-generated for slabs so the PWA can reference a slab - before it exists server-side). -- Timestamps: UTC ISO-8601 `TEXT` (`YYYY-MM-DDTHH:MM:SSZ`). -- Soft state via `status` column; no hard deletes for slabs (audit). Images purged - on publish (Decision 12) but the slab row + metadata retained. -- Money stored as float64 USD, rounded half-up to cents at write (TECH-SPEC §2). -- `client_rev` / `server_rev`: monotonic ints for optimistic concurrency (ARCH §3.2). +Conventions: +- IDs: client-generated UUIDv4 for slabs so the PWA can reference a slab before it exists server-side. +- Timestamps: UTC ISO-8601 TEXT. +- Soft state via status column; no hard deletes for slabs (audit). +- Money: float64 USD, rounded half-up to cents at write. +- All rounded values are what gets stored. No full-precision internal storage. +- Inches stored as 1/8" increments. Sqft/bdft to 2 decimals. +- Multi-select fields stored as JSON arrays of Woo IDs. + +--- + +## slabs + +Draft-only. Deleted on successful publish. WooCommerce is the source of truth for product data. + +| Column | Type | Notes | +|---|---|---| +| `id` | TEXT PK | client-generated UUID | +| `sku` | TEXT UNIQUE NOT NULL | 3-24 [A-Z0-9-] | +| `status` | TEXT NOT NULL | draft \| calibrated \| ready \| publishing \| published \| failed | +| `length_in` | REAL NOT NULL | 1/8" step | +| `thickness_in` | REAL NOT NULL | 1/8" step | +| `sqft` | REAL | 2 decimals | +| `bdft` | REAL | 2 decimals | +| `width_min_in` | REAL | min width at 6" stations, 2 decimals | +| `width_max_in` | REAL | max width at 6" stations, 2 decimals | +| `width_avg_in` | REAL | avg width at 6" stations, 2 decimals | +| `species_id` | INTEGER | → woo_categories (leaf only, 1 required) | +| `wood_category_ids` | INTEGER[] JSON | → woo_categories (leaf, 1+) | +| `edge_type_term_id` | INTEGER | → woo_attribute_terms (1 required) | +| `figure_term_ids` | INTEGER[] JSON | → woo_attribute_terms (1+) | +| `grade_term_ids` | INTEGER[] JSON | → woo_attribute_terms (1+) | +| `thickness_term_id` | INTEGER | → woo_attribute_terms (round-up) | +| `moisture_term_id` | INTEGER | → woo_attribute_terms (1 required, defaults to kiln-dried term; user overrides; not inferred) | +| `fig_tag_ids` | INTEGER[] JSON | → woo_tags (fig-*, 1+) | +| `price_per_bdft` | REAL | from pricing_rules for species | +| `price` | REAL NOT NULL | 2 decimals | +| `price_source` | TEXT | 'recommendation' \| 'override' | +| `title` | TEXT | | +| `short_title` | TEXT | | +| `description` | TEXT | | +| `content_source` | TEXT | 'manual' \| 'llm' | +| `client_rev` | INTEGER NOT NULL DEFAULT 1 | | +| `server_rev` | INTEGER NOT NULL DEFAULT 1 | | +| `created_at` | TEXT NOT NULL | | +| `updated_at` | TEXT NOT NULL | | + +Indexes: `sku` (unique), `status`, `updated_at`. + +### Status state machine -## ERD (text) ``` -slabs 1─N slab_photos -slabs 1─0..1 sync_log (latest) [sync_log is an append-only history; 1 per publish attempt] -pricing_rules N─1 (species, character) [unique pair] -woo_taxonomy (cache) categories / tags / attributes -settings 1 row (key→encrypted value) -``` - -## Tables - -### slabs -| col | type | notes | -|---|---|---| -| id | TEXT PK | client-generated UUID | -| sku | TEXT UNIQUE NOT NULL | from OCR or manual; dedupe key (FR24a) | -| status | TEXT NOT NULL | `draft` `processing` `ready` `review` `publishing` `published` `failed` | -| species | TEXT | controlled value (from woo_taxonomy categories) or free until confirmed | -| species_confidence | REAL NULL | from inference, if used | -| species_source | TEXT | `inference` `manual` | -| character | TEXT | controlled value | -| character_confidence | REAL NULL | | -| character_source | TEXT | `inference` `manual` | -| length_in | REAL NOT NULL | authoritative (ruler-derived or manual) | -| length_source | TEXT | `ruler` `manual` | -| width_avg_in | REAL | average of sampled widths (TECH-SPEC §5.2) | -| width_source | TEXT | `sampled` `manual` | -| thickness_in | REAL NOT NULL | always manual (FR8) | -| sqft | REAL | (L×w_avg)/144 | -| bdft | REAL | (L×w_avg×t)/12 (Decision 18) | -| price_per_bdft | REAL NULL | copied from pricing rule at compute time (snapshot) | -| price | REAL NOT NULL | final authoritative price (override or recommendation) | -| price_source | TEXT | `recommendation` `override` | -| title | TEXT | generated/edited | -| short_title | TEXT | | -| description | TEXT | | -| content_source | TEXT | `template` `llm` `manual` | -| normalized_fill_ok | INTEGER | 0/1 — met ~80% fill target (TECH-SPEC TV-6) | -| woo_product_id | INTEGER NULL | set on successful publish (FR28) | -| published_at | TEXT NULL | | -| client_rev | INTEGER NOT NULL DEFAULT 1 | | -| server_rev | INTEGER NOT NULL DEFAULT 1 | | -| created_at | TEXT NOT NULL | | -| updated_at | TEXT NOT NULL | | - -Index: `sku` (unique), `status`, `updated_at`. - -### slab_photos -| col | type | notes | -|---|---|---| -| id | TEXT PK | | -| slab_id | TEXT FK→slabs.id ON DELETE CASCADE | | -| kind | TEXT NOT NULL | `calibration_sku` `calibration_ruler` `inventory` | -| role | TEXT | for inventory: `topdown` (the width-sampling photo) or `extra` | -| seq | INTEGER | display order (FR23 reorder) | -| original_path | TEXT | relative to images volume | -| normalized_path | TEXT NULL | set after normalization | -| is_customer_facing | INTEGER | calibration=0, inventory=1 (FR2: calibration never uploaded) | -| created_at | TEXT | | - -Rule: only `kind=inventory` photos are uploaded to WooCommerce. Calibration photos -are internal-only (FR2). - -### pricing_rules -| col | type | notes | -|---|---|---| -| id | TEXT PK | uuid (PRD pricing schema) | -| species | TEXT NOT NULL | | -| character | TEXT NOT NULL | | -| price_per_bdft | REAL NOT NULL | flat (Decision 5; no tiers) | -| created_at | TEXT | | -| updated_at | TEXT | | - -`UNIQUE (species, character)`. Seeded from synced Woo categories (Decision 4); -user sets `price_per_bdft` per value in Settings (FR13). - -### woo_taxonomy (cache) -| col | type | notes | -|---|---|---| -| kind | TEXT | `category` `tag` `attribute` | -| woo_id | INTEGER | Woo term id | -| name | TEXT | | -| parent_id | INTEGER NULL | categories | -| slug | TEXT | | -| synced_at | TEXT | | - -`UNIQUE (kind, woo_id)`. Rebuilt by `POST /api/admin/taxonomy/sync` (FR25). This is -the controlled list for species (Decision 4 — species drawn from categories) and -the taxonomy auto-assign source (FR26). - -### sync_log (append-only history) -| col | type | notes | -|---|---|---| -| id | INTEGER PK AUTOINCREMENT | | -| slab_id | TEXT FK | | -| attempt | INTEGER | 1,2,… per slab | -| action | TEXT | `create` | -| woo_product_id | INTEGER NULL | | -| status | TEXT | `success` `failed` `blocked_duplicate_sku` | -| http_status | INTEGER NULL | | -| error | TEXT NULL | machine-readable code | -| detail | TEXT NULL | human-readable message / Woo error body | -| payload_hash | TEXT | sha256 of the Woo product payload sent (audit, FR28) | -| created_at | TEXT | | - -FR28: log sync results, surface errors, store Woo product ID on success. - -### settings (key/value, encrypted values) -| col | type | notes | -|---|---|---| -| key | TEXT PK | | -| value_enc | BLOB | AES-GCM ciphertext (see Security) | -| updated_at | TEXT | | - -Keys: -- `woo_base_url` (plaintext-OK, but encrypted for uniformity) -- `woo_consumer_key`, `woo_consumer_secret` (secret) -- `inference_base_url`, `inference_api_key` (secret), `inference_model` -- `inference_enabled` (bool), `content_llm_enabled` (bool) -- `brand_voice` (text), `geo_context` (text) -- `content_templates` (JSON: title/short_title/description templates, FR16) -- `aspect_ratio` = `1:1`, `output_px` = 1600, `output_px_min` = 1000 (Decision 20) -- `fill_target` = 0.80 - -The AES-GCM master key is an env var (`SLAB_AES_KEY`, 32 bytes base64) injected by -compose — never stored in the DB. Each `value_enc` = `nonce(12) || ciphertext`. - -## Status state machine -``` -draft → processing → ready → review → publishing → published - │ ↑ (woo_product_id set) - └→ failed (retry → publishing) +draft → calibrated → ready → publishing → published + │ │ ↑ + └→ failed ────┴────────────────┘ (woo_product_id in sync_log) any → failed (with error) ``` -- `processing`: server pipeline running. -- `ready`: enriched, awaiting user review. -- `review`: user has opened/edited the review screen. -- `publishing`: Woo create in flight. -- `published`: Woo product created (draft/pending on the store — never live without - human action, per test-target decision). -- `failed`: pipeline or publish error; `sync_log.detail` has the reason. -## Concurrency -- Single owner. Optimistic locking via `server_rev`: an update must send the `server_rev` - it last read; server rejects on mismatch (409) → client re-fetches. This is the - server-side counterpart to the client `client_rev` (ARCH §3.2). +1. **draft** — photos taken, no mask confirmed. +2. **calibrated** — BG edge confirmed, length axis confirmed, length/thickness/SKU entered. Client computed sqft/bdft/widths. Draft uploaded to server. +3. **ready** — all mandatory fields populated. Values from Call 1, manual, or mix. Inference is optional. Publishable. +4. **publishing** — Woo create in flight. Poll for result. +5. **published** — Woo product created. This row + all photos deleted. sync_log retained. +6. **failed** — pipeline, inference, or publish error. Error detail stored. Retry available. -## Backup -- SQLite file + images volume are the only durable state. Backup = `sqlite3 .backup` - of the DB file (WAL-safe) + `tar` of the images volume. See DEPLOYMENT.md. +--- + +## slab_photos + +| Column | Type | Notes | +|---|---|---| +| `id` | TEXT PK | | +| `slab_id` | TEXT FK → slabs.id ON DELETE CASCADE | | +| `kind` | TEXT NOT NULL | 'inventory' | +| `role` | TEXT | 'topdown' \| 'extra' | +| `seq` | INTEGER | display order | +| `original_path` | TEXT | relative to images volume | +| `processed_path` | TEXT | relative to images volume | +| `created_at` | TEXT | | + +Rule: only inventory photos. Calibration photos do not exist in this design. + +--- + +## pricing_rules + +| Column | Type | Notes | +|---|---|---| +| `id` | TEXT PK UUID | | +| `species` | TEXT NOT NULL | matches woo_categories.name (leaf) | +| `price_per_bdft` | REAL NOT NULL | flat, no tiers | +| `created_at` | TEXT | | +| `updated_at` | TEXT | | + +`UNIQUE(species)`. Seeded from synced Woo categories. User sets price per species. + +--- + +## woo_categories + +| Column | Type | Notes | +|---|---|---| +| `woo_id` | INTEGER PK | | +| `name` | TEXT | | +| `slug` | TEXT | | +| `parent_id` | INTEGER | NULL for root | +| `synced_at` | TEXT | | + +Only species + wood category. Sync pulls all Woo categories; the app filters to the two we use. + +`UNIQUE(woo_id)`. + +--- + +## woo_attributes + +| Column | Type | Notes | +|---|---|---| +| `woo_id` | INTEGER PK | | +| `name` | TEXT | | +| `slug` | TEXT | | +| `type` | TEXT | 'select' | +| `synced_at` | TEXT | | + +Only the five first-class attributes: Edge Type, Figure, Grade, Thickness, Moisture. + +`UNIQUE(woo_id)`. + +--- + +## woo_attribute_terms + +| Column | Type | Notes | +|---|---|---| +| `woo_id` | INTEGER PK | | +| `attribute_id` | INTEGER FK → woo_attributes.woo_id | | +| `name` | TEXT | | +| `slug` | TEXT | | +| `synced_at` | TEXT | | + +The actual selectable values. E.g., "Cathedral" under Figure, "1\"–1 1/2\"" under Thickness. + +`UNIQUE(woo_id)`. + +--- + +## woo_tags + +| Column | Type | Notes | +|---|---|---| +| `woo_id` | INTEGER PK | | +| `name` | TEXT | | +| `slug` | TEXT | | +| `synced_at` | TEXT | | + +Only `fig-*` tags. Other Woo tags ignored. + +`UNIQUE(woo_id)`. + +--- + +## settings + +| Column | Type | Notes | +|---|---|---| +| `key` | TEXT PK | | +| `value_enc` | BLOB | AES-GCM ciphertext | +| `updated_at` | TEXT | | + +Keys: +- `woo_base_url`, `woo_consumer_key`, `woo_consumer_secret` +- `inference_base_url`, `inference_api_key`, `inference_model` +- `inference_enabled`, `content_llm_enabled` +- `brand_voice`, `geo_context` +- `prompts` (JSON: call1_prompt, call2_prompt, reset-to-default) +- `publish_status` ('published' | 'draft') +- `aspect_ratio` ('3:4'), `output_px` (1600), `output_px_min` (1600), `fill_target` (0.80) +- `user_sensitivity`, `user_edge_offset`, `user_feather`, `user_sheet_mode` + +AES master key is an env var (`SLAB_AES_KEY`, 32 bytes base64). Never in the DB. +Each `value_enc` = `nonce(12) || ciphertext`. + +--- + +## sync_log + +Append-only history. Not deleted on publish. + +| Column | Type | Notes | +|---|---|---| +| `id` | INTEGER PK AUTOINCREMENT | | +| `slab_id` | TEXT FK | | +| `sku` | TEXT | | +| `woo_product_id` | INTEGER | | +| `status` | TEXT | 'success' \| 'failed' | +| `http_status` | INTEGER | | +| `error` | TEXT | machine-readable code | +| `detail` | TEXT | Woo error body | +| `payload_hash` | TEXT | sha256 of Woo payload sent | +| `created_at` | TEXT | | + +--- + +## inference_log + +Append-only audit. + +| Column | Type | Notes | +|---|---|---| +| `id` | INTEGER PK AUTOINCREMENT | | +| `slab_id` | TEXT FK | | +| `call` | TEXT | '1' \| '2' | +| `request_payload` | TEXT | JSON of what was sent | +| `response_payload` | TEXT | JSON of what came back | +| `created_at` | TEXT | | diff --git a/docs/OPENAPI.md b/docs/OPENAPI.md index a4f84fe..312efe2 100644 --- a/docs/OPENAPI.md +++ b/docs/OPENAPI.md @@ -1,186 +1,290 @@ # OpenAPI Contract — SvelteKit Client ↔ FastAPI -Status: SPEC (deliverable #2) · 2026-08-24 · SlabUploader -This is the binding API contract. The machine-readable `openapi.yaml` is generated -from the FastAPI app at implementation time and must match this doc. Base path: -`/api`. All requests/responses JSON unless noted. All timestamps UTC ISO-8601. +Status: SPEC · 2026-08-27 · SlabUploader +Base path: `/api/v1`. All requests/responses JSON unless noted. +All timestamps UTC ISO-8601. ## Conventions -- **Auth**: none (ARCH §7). Trusted LAN/Tailscale + HTTPS. -- **Errors** — uniform envelope: - ```json - { "error": { "code": "string", "message": "string", "detail": "object|null" } } - ``` - - `400` `validation` — payload failed validation (Pydantic). - - `404` `not_found` — unknown slab/setting. - - `409` `revision_conflict` — `client_rev`/`server_rev` mismatch (send `detail.current_server_rev`). - - `409` `duplicate_sku` — SKU already exists (FR24a). - - `422` `unpublishable` — slab not in a publishable state / missing required field. - - `502` `woo_error` — WooCommerce rejected the request (`detail` carries Woo body). - - `500` `internal` — unexpected. -- **Revisions**: create/update carry `client_rev`; server echoes `server_rev`. Client - stores `server_rev` and sends it back on the next update. Mismatch → `409 revision_conflict`. -- **Pagination**: v1 lists are small (single owner, slab-by-slab); lists return full - arrays. If volume grows, add `?limit&cursor` (documented, not built). -## Schemas (Pydantic v2) +### Auth +No client auth. Trusted LAN/Tailscale + HTTPS. + +### Errors +Uniform envelope: +```json +{ "error": { "code": "string", "message": "string", "detail": "object|null" } } +``` +- `400 validation` — payload failed validation. +- `404 not_found` — unknown slab/photo/setting. +- `409 revision_conflict` — client_rev/server_rev mismatch. `detail` carries `current_server_rev`. +- `409 duplicate_sku` — SKU already published in WooCommerce. +- `422 unpublishable` — slab not in a publishable state or missing required field. +- `502 woo_error` — WooCommerce rejected the request. `detail` carries Woo error body. +- `500 internal` — unexpected. + +### Revisions +Create/update carry `client_rev`. Server echoes `server_rev`. Client stores `server_rev` and sends it back on the next update. Mismatch → `409 revision_conflict`. + +### Photos +Uploaded as `multipart/form-data`. Max 40 MB per request. Two fields per photo: +- `files[]` — the original image file +- `meta[]` — JSON `{ kind: "inventory", role: "topdown"|"extra", seq: 1 }` + +### Pagination +Lists are small (single owner, slab-by-slab). Lists return full arrays. + +### API Version +URL is `/api/v1`. Breaking changes bump to `/api/v2`. + +--- + +## Schemas ### SlabCreate ```jsonc { "id": "uuid (client-generated)", "sku": "string 3..24 [A-Z0-9-]", - "length_in": 0, // optional at create; required before publish - "length_source": "manual|ruler|null", - "thickness_in": 0, // optional at create; required before publish - "species": "string|null", - "character": "string|null", - "title": "string|null", "short_title": "string|null", "description": "string|null", - "price": 0, "price_source": "recommendation|override|null", + "length_in": 96.0, // 1/8" step + "thickness_in": 1.5, // 1/8" step + "sqft": 0.64, // computed by client + "bdft": 0.96, // computed by client + "width_min_in": 14.0, + "width_max_in": 22.0, + "width_avg_in": 18.2, + "species_id": 42, // → woo_categories (leaf) + "wood_category_ids": [15, 23], // JSON array → woo_categories (leaf, 1+) + "edge_type_term_id": 8, // → woo_attribute_terms + "figure_term_ids": [3], // JSON array → woo_attribute_terms (1+) + "grade_term_ids": [7], // JSON array → woo_attribute_terms (1+) + "thickness_term_id": 12, // → woo_attribute_terms (round-up) + "moisture_term_id": 5, // → woo_attribute_terms (defaults kiln-dried) + "fig_tag_ids": [99], // JSON array → woo_tags (fig-*, 1+) + "price_per_bdft": 12.50, // from pricing_rules + "price": 12.00, // 2 decimals + "price_source": "recommendation|override|null", + "title": "string|null", + "short_title": "string|null", + "description": "string|null", + "content_source": "manual|llm|null", "client_rev": 1 } ``` +Photos come as multipart `files[]` + `meta[]` alongside this JSON (wrapped in a multipart request where one part is the JSON and the others are the files). ### Slab (read model) -All of `SlabCreate` fields (resolved) plus: -`status`, `width_avg_in`, `width_source`, `sqft`, `bdft`, `price_per_bdft`, -`species_confidence`, `character_confidence`, `normalized_fill_ok`, -`woo_product_id`, `published_at`, `server_rev`, `created_at`, `updated_at`, -`photos: [PhotoRead]`. +All `SlabCreate` fields (resolved) plus: +`status`, `species_confidence`, `woo_product_id`, `published_at`, +`server_rev`, `created_at`, `updated_at`, `photos: [PhotoRead]`, +`inference_status: null|inferring|done|failed`, `inference_error: string|null`. ### PhotoRead ```jsonc -{ "id":"uuid","kind":"calibration_sku|calibration_ruler|inventory", - "role":"topdown|extra|null","seq":1, - "original_url":"/api/slabs/{id}/photos/{pid}/original", - "normalized_url":"/api/slabs/{id}/photos/{pid}/normalized|null", - "is_customer_facing":0|1 } +{ "id": "uuid", "kind": "inventory", "role": "topdown|extra", + "seq": 1, "original_url": "/api/v1/slabs/{id}/photos/{pid}/original", + "processed_url": "/api/v1/slabs/{id}/photos/{pid}/processed|null" } +``` + +### InferenceCall1Result (returned by infer-taxon) +```jsonc +{ "species_id": 42, "species_confidence": 0.92, + "wood_category_ids": [15, 23], + "edge_type_term_id": 8, + "figure_term_ids": [3], "figure_confidence": 0.87, + "grade_term_ids": [7], "grade_confidence": 0.75, + "character": { "type": "knot", "severity": "minor" }, + "inclusions": { "type": "bark pocket", "severity": "none" }, + "voids": "none", + "checks": "none", + "wood_categories": [ { "name": "Live edge", "confidence": 0.95 }, + { "name": "Bowl blank", "confidence": 0.82 }, + { "name": "Table slab", "confidence": 0.61 } ] } +``` + +### InferenceCall2Result (returned by infer-content) +```jsonc +{ "title": "string", "short_title": "string", "description": "string" } ``` ### PriceRule -`{ id, species, character, price_per_bdft, created_at, updated_at }` +```jsonc +{ "id": "uuid", "species": "string", "price_per_bdft": 12.50, + "created_at": "timestamp", "updated_at": "timestamp" } +``` ### SettingsView (read; secrets masked) ```jsonc -{ "woo_base_url":"https://www.whidbeywoodstore.com", +{ "woo_base_url": "https://www.whidbeywoodstore.com", "woo_credentials_configured": true, - "inference_base_url":"http://192.168.1.202:8080", - "inference_model":"", "inference_enabled": true, + "inference_base_url": "http://192.168.1.202:8080/v1", + "inference_model": "", "inference_enabled": true, "content_llm_enabled": false, - "brand_voice":"…", "geo_context":"…", - "aspect_ratio":"1:1","output_px":1600,"output_px_min":1000,"fill_target":0.80 } + "brand_voice": "...", "geo_context": "...", + "publish_status": "published", + "aspect_ratio": "3:4", "output_px": 1600, "output_px_min": 1600, + "fill_target": 0.80, + "user_sensitivity": 0.5, "user_edge_offset": 0, "user_feather": 1, + "user_sheet_mode": "auto" } ``` -Secrets (keys) are never returned; only a `*_configured` boolean. +Secrets (keys) are never returned. Only a `*_configured` boolean. --- ## Endpoints ### Health & meta -- `GET /api/health` → `{ "status":"ok","version":"…","woo_reachable":bool }` - (light probe; used by PWA connectivity check, ARCH §3.3) -- `GET /api/meta` → `{ "version":"…","templates_configured":bool }` +- `GET /api/v1/health` → `{ "status":"ok", "version":"...", "woo_reachable": bool }` +- `GET /api/v1/meta` → `{ "version":"...", "templates_configured": bool }` ### Slabs -- `POST /api/slabs` body `SlabCreate` → `201` `Slab` (status `draft`). - - `409 duplicate_sku` if SKU exists. -- `GET /api/slabs` → `200` `[Slab]` (all, most-recent first). -- `GET /api/slabs/{id}` → `200` `Slab` / `404`. -- `PUT /api/slabs/{id}` body `SlabUpdate` (any subset of editable fields + `client_rev`) - → `200` `Slab`. Re-runs derived math (sqft/bdft/price recommendation) server-side when - inputs change. `409 revision_conflict`, `409 duplicate_sku`. -- `DELETE /api/slabs/{id}` → `204` (soft: only allowed while unpublished; published - slabs are retained for audit). +- `POST /api/v1/slabs` — Create a calibrated draft. Body: multipart with `data` (SlabCreate JSON) + `files[]` (photos) + `meta[]` (photo metadata). + - Returns `201` `Slab` (status `draft`). + - Server auto-runs Call 1 (vision inference). `inference_status` becomes `inferring`, then `done`/`failed`. + - `409 duplicate_sku` if SKU already published. +- `GET /api/v1/slabs` → `200` `[Slab]` (most recent first). +- `GET /api/v1/slabs/{id}` → `200` `Slab` / `404`. + - Also used as the poll endpoint for inference and publish. Long-running ops set status to `inferring`/`publishing`; client backs off (1s, 2s, 4s, cap 10s). +- `PUT /api/v1/slabs/{id}` — Update draft fields. Body: partial `SlabCreate` (any subset of editable fields + `client_rev`). + - Server re-runs derived math when inputs change. + - `409 revision_conflict`, `409 duplicate_sku`. +- `DELETE /api/v1/slabs/{id}` → `204`. Soft: only unpublished drafts. Published slabs cannot be deleted from the app. -### Photo upload (offline queue, ARCH §3.2) -- `POST /api/slabs/{id}/upload` body: JSON manifest - ```jsonc - { "client_rev":2, - "photos":[ { "id":"uuid","kind":"inventory","role":"topdown","seq":1, - "blob":"" , "filename":"slab1_topdown.jpg" } ] } - ``` - (Photos are base64 in v1 for transport simplicity; total request cap 40 MB. - If that proves heavy, switch to multipart — documented extension.) - → `202` `{ "status":"processing" }`. Server runs the authoritative pipeline - (ruler→scale→geometry→widths→bdft→species/char→pricing→normalization→content) - asynchronously. Client polls `GET /api/slabs/{id}`. - - `409 revision_conflict` on stale `client_rev`. - - Pipeline failure → slab `failed` (poll returns the error). +### Photo operations +- `POST /api/v1/slabs/{id}/u2net/{pid}` — "Try harder." Server runs U2Net on this one photo, returns a better mask. + - Returns `202` `{ mask_url: "..." }`. Client uses the mask to re-compute area/widths locally. + - `404` if photo not found. +- `GET /api/v1/slabs/{id}/photos/{pid}/original` → `image/*` (original, while retained). +- `GET /api/v1/slabs/{id}/photos/{pid}/processed` → `image/*` (processed PNG, while retained). + - After publish, both → `410 Gone`. + +### Inference +- `POST /api/v1/slabs/{id}/infer-taxon` — Trigger or retry Call 1 (vision). + - Server uses cached taxonomy + original photos downscaled to 1024px + user metadata. + - Returns `202` `{ "status": "inferring" }`. Client polls `GET /api/v1/slabs/{id}` for results. + - Timeout > 45s → `504 gateway_timeout` with error detail. +- `POST /api/v1/slabs/{id}/infer-content` — Trigger Call 2 (text). + - Server uses curated Call 1 results + deterministic numbers + brand voice + GEO context + prompt. + - Returns `202` `{ "status": "inferring" }`. Client polls for results. + - Timeout > 45s → `504` with error detail. ### Publish -- `POST /api/slabs/{id}/publish` → `202` `{ "status":"publishing" }`. - Pre-conditions (else `422 unpublishable`): status in `ready`/`review`, length+width+ - thickness present, price present, ≥1 inventory photo, species/character confirmed. - - Dedupe: if SKU already has a published slab → `409 duplicate_sku` (FR24a). +- `POST /api/v1/slabs/{id}/publish` — Publish to WooCommerce. + - Pre-conditions: status in `ready`, all required fields set. Else `422 unpublishable`. + - Dedupe: if SKU already has a published product → `409 duplicate_sku`. + - Returns `202` `{ "status": "publishing" }`. Client polls. - Woo failure → slab `failed`, `sync_log` written, poll returns `502 woo_error`. - - Success → slab `published`, `woo_product_id` set, images purged (Decision 12). + - Success → slab `published`, `woo_product_id` set, images purged, draft row deleted. -### Status poll -- `GET /api/slabs/{id}` (same as above) is the poll endpoint. Long-running ops set - `status` to `processing`/`publishing`; client backs off (1s,2s,4s… cap 10s). +### Taxonomy +- `GET /api/v1/admin/taxonomy` → `200` taxonomy grouped by kind: + ```jsonc + { "categories": [...], "attributes": [{ name, slug, terms: [...] }], + "tags": [...] } + ``` +- `POST /api/v1/admin/taxonomy/sync` → `200` `{ "categories": n, "attributes": n, "tags": n, "synced_at": "..." }`. + - Pulls from Woo, rebuilds the cache. `502 woo_error` on failure; previous cache retained. -### Photos (serve) -- `GET /api/slabs/{id}/photos/{pid}/original` → `image/*` (original, while retained) -- `GET /api/slabs/{id}/photos/{pid}/normalized` → `image/*` (normalized, while retained) - - After publish, both → `410 Gone` (images purged, Decision 12). +### Pricing +- `GET /api/v1/admin/pricing` → `[PriceRule]` +- `POST /api/v1/admin/pricing` → `201` `PriceRule` +- `PUT /api/v1/admin/pricing/{id}` → `200` `PriceRule` +- `DELETE /api/v1/admin/pricing/{id}` → `204` -### Taxonomy (FR25/FR26) -- `POST /api/admin/taxonomy/sync` → `200` `{ "categories":n,"tags":n,"attributes":n,"synced_at":"…" }` - Pulls from Woo, rebuilds `woo_taxonomy` cache. `502 woo_error` on failure. -- `GET /api/admin/taxonomy` → `200` the cached taxonomy (grouped by kind). - This is the controlled list for species (Decision 4) and auto-assign (FR26). - -### Pricing rules (FR13/14/15) -- `GET /api/pricing-rules` → `[PriceRule]` -- `POST /api/pricing-rules` body `{ species, character, price_per_bdft }` → `201` `PriceRule` - (`409` if pair exists → use PUT). -- `PUT /api/pricing-rules/{id}` body `{ price_per_bdft }` → `200` `PriceRule` -- `DELETE /api/pricing-rules/{id}` → `204` -- `GET /api/pricing-rules/recommend`?species=…&character=…&bdft=… → `200` - `{ "price_per_bdft":n|null, "recommendation":n|null }` (FR14; null if no rule). - -### Settings (FR32) -- `GET /api/settings` → `200` `SettingsView` -- `PUT /api/settings` body: partial `{ key: value }` for non-secret fields, and - secret fields by name (values re-encrypted server-side, ARCH §7). - → `200` `SettingsView`. -- `POST /api/settings/test-woo` → `200` `{ "ok":bool,"detail":"…" }` (validates Woo creds). -- `POST /api/settings/test-inference` → `200` `{ "ok":bool,"vision_capable":bool,"detail":"…" }` - (sends a tiny image; `vision_capable` false → UI warns, species inference disabled). +### Settings +- `GET /api/v1/settings` → `200` `SettingsView` +- `PUT /api/v1/settings` — Update settings. Body: partial `{ key: value }`. + - Secrets re-encrypted server-side. `200` `SettingsView` returned. +- `POST /api/v1/settings/test-woo` → `200` `{ "ok": bool, "detail": "..." }` +- `POST /api/v1/settings/test-inference` → `200` `{ "ok": bool, "vision_capable": bool, "detail": "..." }` --- ## Request/response examples -### Create a slab +### Create a slab (multipart) ``` -POST /api/slabs -{ "id":"9f1c…","sku":"BW-0042","length_source":null,"client_rev":1 } -→ 201 -{ "id":"9f1c…","sku":"BW-0042","status":"draft","server_rev":1, "photos":[], … } +POST /api/v1/slabs +Content-Type: multipart/form-data; boundary=--- + +--- +Content-Disposition: form-data; name="data" +Content-Type: application/json + +{ "id":"9f1c...","sku":"BW-0042","length_in":96.0,"thickness_in":1.5, + "sqft":0.64,"bdft":0.96,"width_min_in":14.0,"width_max_in":22.0, + "width_avg_in":18.2,"species_id":42,"wood_category_ids":[15,23], + "edge_type_term_id":8,"figure_term_ids":[3],"grade_term_ids":[7], + "thickness_term_id":12,"moisture_term_id":5,"fig_tag_ids":[99], + "price_per_bdft":12.50,"price":12.00,"price_source":"recommendation", + "title":null,"short_title":null,"description":null, + "content_source":null,"client_rev":1 } + +--- +Content-Disposition: form-data; name="files[]"; filename="topdown.jpg" +Content-Type: image/jpeg + + +--- +Content-Disposition: form-data; name="meta[]" +Content-Type: application/json + +{ "kind": "inventory", "role": "topdown", "seq": 1 } +--- +``` +Response: `201` +```json +{ "id":"9f1c...","sku":"BW-0042","status":"draft", + "inference_status":"inferring","server_rev":1,"photos":[...],... } ``` -### Upload photos (triggers pipeline) +### Call 1 completes (poll) ``` -POST /api/slabs/9f1c…/upload -{ "client_rev":1, "photos":[ …base64… ] } -→ 202 { "status":"processing" } -GET /api/slabs/9f1c… (poll) -→ 200 { "status":"ready","bdft":218.4,"width_avg_in":18.2,"price":2730.0, - "species":"Black Walnut","character":"Cathedral","server_rev":2, … } +GET /api/v1/slabs/9f1c... +→ 200 { "status":"draft","inference_status":"done", + "species_id":42,"species_confidence":0.92, + "wood_category_ids":[15],"edge_type_term_id":8, + "figure_term_ids":[3],"grade_term_ids":[7], + "inference_error":null, ... } +``` + +### Call 2 (user taps Generate) +``` +POST /api/v1/slabs/9f1c.../infer-content +→ 202 { "status":"inferring" } +GET /api/v1/slabs/9f1c... +→ 200 { "title":"Black Walnut 8ft 0in × 18.2in Slab — Cathedral", + "short_title":"Black Walnut Slab — Cathedral", + "description":"A one-of-a-one cathedral black walnut slab...", + "content_source":"llm", ... } ``` ### Publish ``` -POST /api/slabs/9f1c…/publish +POST /api/v1/slabs/9f1c.../publish → 202 { "status":"publishing" } -GET /api/slabs/9f1c… (poll) -→ 200 { "status":"published","woo_product_id":1042,"published_at":"…", … } +GET /api/v1/slabs/9f1c... +→ 200 { "status":"published","woo_product_id":1042,"published_at":"..." } ``` +### Taxonomy sync +``` +POST /api/v1/admin/taxonomy/sync +→ 200 { "categories": 24, "attributes": 5, "tags": 12, "synced_at": "..." } +``` + +### Test connections +``` +POST /api/v1/settings/test-woo +→ 200 { "ok": true, "detail": "Connected to Whidbey Wood Store" } + +POST /api/v1/settings/test-inference +→ 200 { "ok": true, "vision_capable": true, "detail": "Model Qwen3.8-27B confirmed" } +``` + +--- + ## Versioning -URL is `/api/v1` at implementation (this doc omits the prefix for brevity). Breaking -changes bump to `/api/v2`; the PWA pins the version it was built against. +URL is `/api/v1`. Breaking changes bump to `/api/v2`. The PWA pins the version it was built against. ## Out of contract (v1) -- Bulk endpoints, staff/role endpoints, webhook push (client polls), analytics. +- Bulk endpoints, staff/role endpoints, webhook push, analytics. diff --git a/docs/TECH-SPEC-PIPELINE.md b/docs/TECH-SPEC-PIPELINE.md index 67cf01d..02bd900 100644 --- a/docs/TECH-SPEC-PIPELINE.md +++ b/docs/TECH-SPEC-PIPELINE.md @@ -1,271 +1,218 @@ -# Technical Spec: Deterministic Image Pipeline & Ruler→Inch Math +# Technical Spec: Deterministic Image Pipeline & Area → Bdft -Status: SPEC (pre-implementation) · 2026-08-24 · TyTech / SlabUploader +Status: SPEC · 2026-08-27 · TyTech / SlabUploader Scope: PRD deliverable #1 — algorithms and test vectors for the deterministic core. -No inference, no LLM. Everything here is pure functions of (pixels, inputs) → outputs. -Every threshold/constant lives in §8 (single source of truth) and is unit-tested. +No inference, no LLM. Everything here is a pure function of (pixels, user inputs) → outputs. +Inference, Woo payload, API, and schema live in other docs. --- ## 1. Invariants -1. **Determinism** — same inputs → bit-identical outputs. No randomness, no timestamps in math, no network calls. -2. **Manual entry is authoritative** — a user-entered value (length, width, thickness, SKU, price) always wins over any computed value. +1. **Determinism** — same inputs → bit-identical outputs. No randomness, no timestamps in math, no network calls for the math. +2. **Manual entry is authoritative** — user-entered length, thickness, SKU, and price always win over any computed value. 3. **Fallback chain is explicit** — every computed value has a defined fallback; the system never silently guesses. -4. **All math in inches and board feet** — stored as float64; display rounding per §2. -5. **Client vs server split** — client runs the *light* pass (preview, OCR, quick ruler check) for feedback; server runs the *authoritative* pass. Server values are what get stored and published. Client results are hints only. + - BG removal: chroma-key / threshold → user slider / sheet toggle → U2Net → retake. + - Length axis: min-area bounding rect → user rotate/confirm → retake if the photo is unusable. + - Area: requires a single contiguous slab mask; broken mask → flag and retake. +4. **Units** — inches in 1/8" steps; sqft and bdft to 2 decimals; price half-up to 2 decimals. Those rounded values are what get stored. No sqin in the UI, tests, or product copy. +5. **Client is authoritative** — all deterministic processing runs in the browser. The server stores the numbers and files the client sends, and handles Woo sync. -## 2. Units & rounding +## 2. Units and rounding -| Quantity | Internal | Display | Stored | -|---|---|---|---| -| Length, widths | float64 inches | 1 decimal | full precision | -| Thickness | float64 inches (manual) | 2 decimals (eighths OK in UI) | full precision | -| sqft | float64 | 1 decimal | full precision | -| bdft | float64 | 1 decimal | full precision | -| Price | float64 USD | 2 decimals | 2 decimals (round half-up) | +| Quantity | Source | Stored / displayed | +|---|---|---| +| Length | user, 1/8" steps | nearest 1/8" | +| Thickness | user pick, 1/8" steps | that pick (used in math and copy) | +| Thickness Woo attribute | same pick, rounded **up** into a Woo range | Woo term, not the 1/8" value | +| sqft | computed from mask | 2 decimals | +| bdft | sqft × thickness (inches) | 2 decimals | +| Price | species $/bdft × bdft, or override | 2 decimals, half-up | -- bdft is **never rounded up to whole units** (ASSUMPTION — flag to Ty: lumber-trade practice sometimes rounds up; v1 does not). -- Price computed from unrounded bdft, then rounded half-up to cents. -- Pixel→inch scale is float64 px/inch, never pre-rounded. +- bdft is never rounded up to whole board feet. +- Pixel→inch scale is an implementation detail. Users never see pixels. -## 3. Ruler → inch scale +## 3. Background removal -### 3.1 Inputs -- `ruler.png` — calibration photo: a standard **12-inch ruler** (Decision 3: always inches), placed flat and parallel to the slab's long axis on the green sheet. -- Known: `RULER_INCHES = 12.0` (§8). +The user must see where the cut will land and be able to fix it. Edge quality is the foundation of sqft and bdft. -### 3.2 Server algorithm (authoritative) -``` -1. Grayscale, GaussianBlur (k=5, σ=1.0) -2. Detect the ruler: - a. Canny (40, 120) → contours → candidate quads (4 corners, area > 5% of frame) - b. Score candidates: high straight-line edge density (Hough, minLineLength=10% of ruler width), - regular tick spacing (see 3.3), aspect ratio within 12:0.5..12:2 band - c. Take highest score; none above TICK_SPACING_TOL → RULER_FAIL -3. Perspective-correct the ruler to a top-down rect using its 4 corners - → rect of W_r × H_r px, long axis horizontal -4. Tick detection on the corrected rect: - a. Column-wise dark-pixel projection over the central 60% band of the rect - b. Local minima with prominence > MIN_TICK_PROMINENCE → tick x-positions - c. Cluster ticks; compute gaps; identify the modal gap g_mode - d. Tick labels: integer inches where cumulative distance from the first - labeled tick ≈ k × g_mode for k = 1..12 - e. Scale candidate: s = (x_{12th tick} − x_{1st tick}) / 11.0 [px per inch] - (11 gaps between tick 1 and tick 12) - f. Validation: |g_mode − (s/1)| < TICK_SPACING_TOL and tick count ≥ 12 -5. Cross-check with the ruler rect edges: s_edge = (W_r − 2·margin) / 12.0 - where margin is the detected pre-"1" and post-"12" padding (mode tick gap). - If |s − s_edge| / s < RULER_CROSS_CHECK_TOL → use s. - Else → prefer s (tick-based), log warning. -6. Emit: scale_px_per_inch = s, ruler_confidence = f(tick_count, tol residuals) -``` -`RULER_FAIL` → the pipeline proceeds via the manual-length path (§5.3). +### 3.1 Auto-detect sheet +1. Sample a 2–5% strip on all four borders. +2. Average HSV per side. +3. Hue in [35, 85] and saturation ≥ 40 → green. +4. Else value ≤ 30 and saturation ≤ 20 → black. +5. Else prompt: pick green or black. -### 3.3 Client light pass (OpenCV.js, preview only) -Canny + largest 4-point contour + tick projection. Emits a *hint* scale for live -feedback ("~201 px/in — looks right"). Never stored. If it fails, UI says -"ruler unclear — you can enter length manually." +### 3.2 Visual feedback (required) +- Overlay the mask on the photo (what will be removed vs kept). +- Show the slab edge clearly — that edge is the measurement boundary. +- User confirms the edge before length / area run. -### 3.4 SKU OCR (client, Tesseract.js) -- Preprocess: grayscale → contrast stretch → upscale ×2 if ruler-width < 800 px → binarize (Otsu) -- PSM: 7 (single line), character whitelist: `ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-` -- Accept if: confidence ≥ OCR_CONF_MIN AND regex `^[A-Z0-9-]{3,24}$` -- Else → manual SKU entry (FR3). Server re-runs OCR on upload as a secondary check; mismatch → surface both, user picks. +### 3.3 Persisted settings (reset-to-default available) +Factory values live in code. If the user changes them, the new values persist until reset. -## 4. Top-down photo → pixel geometry +1. **Sheet** — auto / green / black. +2. **Sensitivity** — one slider; tighter vs looser detection (green: HSV range width; black: brightness cutoff). +3. **Edge offset** — pull the mask in or out a few pixels so the cut sits on the wood, not in the sheet or into the grain. +4. **Feather** — hard cut vs a couple of pixels of alpha blend. -The inventory photo used for width sampling must be **top-down** (slab flat on the -green sheet, camera above). Selection rule: the first inventory photo whose slab -contour aspect ratio matches (L_px : w_px ≈ reported L : expected w) — else the -user picks which photo is top-down in the review UI (FR23). +### 3.4 Algorithms +- **Green:** chroma-key in HSV. Border flood-fill so only sheet pixels connected to the image edge are removed (protects green-ish grain inside the slab). +- **Black:** grayscale threshold. Same flood-fill (protects dark grain). +- **Fallback:** if the edge is still wrong after adjustment, U2Net matting. Last resort. +- Morphological close, then feather per the setting. + +### 3.5 Edge quality +- The mask must be one contiguous slab contour. +- If the user cannot get a clean edge, retake is the resolution. + +## 4. Length axis, widths, sqft, bdft + +### 4.1 Contour and length axis +1. Binary mask M from §3. +2. Largest contour → convex hull. +3. Minimum-area bounding rectangle on the hull. +4. Long side = length axis; short side = width axis. + This follows the **prevailing** length, not a diagonal cut on one end. + +### 4.2 Visual feedback (required) +- Overlay the bounding rectangle and the length axis. +- Width sample lines drawn perpendicular to that axis. +- User confirms the axis matches the slab’s prevailing length. +- **Rotate axis** if it is skewed; samples and sqft scale update live. +- Nearly square slabs: user says which axis is length. + +### 4.3 Scale +User length L (inches, 1/8") is authoritative. ``` -1. Green-sheet removal (see §7.1) → slab mask M -2. Contour of M → C (largest contour) -3. Rotate C so its principal axis is horizontal (PCA) -4. Length in px: L_px = max extent along the axis -5. If ruler scale available: L_in = L_px / s. Cross-check vs any user-entered - length (manual is authoritative; if |L_in − L_manual| / L_manual > LEN_MISMATCH_TOL - → warn in UI, use manual). -6. Edge profiles: for x ∈ [0, L_px], y_top(x), y_bot(x) from C. - Width profile: w(x) = y_bot(x) − y_top(x) +scale = longest_axis_px / L ``` -## 5. Dimensions → sqft → bdft +### 4.4 Widths (listing only, not bdft) +- Sample every **6"** along the confirmed length axis, perpendicular to it. +- Report min, max, and average width for the description. +- Auto-dimension overlay on the photo is **v1.5**, out of this spec. + +### 4.5 sqft +Projected top-down area of the mask. Live-edge thickness and the underside are not in the area. -### 5.1 Width sampling at peaks & troughs (Decision 1) ``` -1. Smooth w(x) with a moving average (window = L_px / 50) -2. Find local maxima (peaks) and minima (troughs) of w(x) with - prominence > WIDTH_FEATURE_PROM -3. Candidate sample x-positions: - - x = 0.05·L_px and x = 0.95·L_px (near both ends, always) - - all peak/trough x-positions (trimmed to interior) -4. Select 3–5 points (WIDTH_SAMPLES_MIN..MAX): - always keep the two end points; add interior points ranked by prominence - until 5, or stop at 3 if fewer interior features exist. -5. w_i = w(x_i) in px → inches via scale (or via manual length, §5.3) -6. w_avg = (Σ w_i) / n (Decision 18) +sqft = (mask_pixel_count / scale²) / 144 ``` -### 5.2 Core math +Round to 2 decimals. + +### 4.6 bdft + ``` -sqft = (L_in × w_avg_in) / 144 -bdft = (L_in × w_avg_in × t_in) / 12 (Decision 18) +bdft = sqft × thickness_in ``` -### 5.3 Fallbacks (Decisions 2, 19) -| Available | Scale source | Length | Widths | -|---|---|---|---| -| Ruler OK | ruler px/in | computed (cross-checked vs manual) | sampled from top-down photo | -| Ruler FAIL, manual L, top-down photo OK | L_manual / L_px | manual (authoritative) | sampled from photo via derived scale | -| Ruler FAIL, manual L, NO usable top-down photo | — | manual | **manual width entry** (Decision 19; single width = w_avg) | -| No length at all (no ruler, user declines) | — | BLOCK publish — length is required | — | +Round to 2 decimals. Identity: 1 sqft at 1" thick = 1 bdft. -## 6. Pricing (Decisions 4, 5, 13) -``` -rule = pricing_rules[species, character] (seeded from synced Woo categories) -recommendation = bdft × rule.price_per_bdft (unrounded bdft) -final_price = user override if edited, else recommendation -stored_price = round_half_up(final_price, 2) -``` -- No rule for (species, character) → recommendation = null, UI shows "no pricing rule — set price manually". Publish still allowed with a manual price. +## 5. Photo normalization -## 7. Photo normalization (Decisions 8, 20) +Applies to every inventory photo of the slab (first photo and the rest). -### 7.1 Green-sheet background removal (deterministic first) -The sheet is a uniform green; chroma-key beats a general matting model here: +- Crop aspect: **3:4 portrait** (settings default; matches the current PIP). +- Transparent **PNG only**. +- Slab centered. **80% fill at the extremes** (widest and tallest points of the slab). Extra margin where the slab is narrower. +- After crop, if the source has enough pixels, shorter side ≥ **1600 px**. If it cannot, warn and ask for a retake — do not invent pixels. +- Original + processed kept while draft/retry; both purged after successful publish (server storage; see Data Model). + +## 6. Pricing + +- Settings: sync **species** from Woo; user sets **$/bdft per species**. +- Capture: `recommendation = bdft × species.price_per_bdft`, pre-fills price. +- User may override. Override sticks for that slab. +- No rule for that species → empty price; user types it. Publish still allowed. +- Stored price: half-up to 2 decimals. +- Figure- or category-weighted price is **v1.5**. + +## 7. Constants + +### 7.1 Code (not in Settings) ``` -1. Convert to HSV (OpenCV 8-bit: H 0–179) -2. Sheet mask: H ∈ [GREEN_HUE_LO, GREEN_HUE_HI] AND S ≥ GREEN_SAT_MIN AND V ≥ GREEN_VAL_MIN -3. Border flood-fill: keep only sheet pixels connected to the image border - (protects greenish wood tones inside the slab) -4. Morphological close (kernel 9) then 1–2px feather on the alpha edge -5. Fallback: if sheet coverage < SHEET_COV_MIN of frame (wrong background), - escalate to U²Net matting for that photo and flag it in the log +FILL_TARGET = 0.80 +ASPECT_W, ASPECT_H = 3, 4 +OUTPUT_PX_MIN = 1600 +WIDTH_SAMPLE_IN = 6 +INCH_STEP = 0.125 +AREA_DECIMALS = 2 +BDFT_DECIMALS = 2 +PRICE_DECIMALS = 2 ``` -### 7.2 Boundary detection & 1:1 crop (FR20) +### 7.2 Factory defaults for persisted BG settings ``` -1. Slab bbox from mask M (after removal) -2. Target: slab occupies FILL_TARGET of the final 1:1 frame - → frame side (px) = min(bbox_w, bbox_h) / FILL_TARGET -3. Crop window: square of that side, centered on the bbox center - (clamped to source bounds; if clamped, re-center on the clamp-constrained side) -4. Upscale/crop to 1600×1600 (Decision 20; 1000×1000 is the hard minimum — - if source can't supply 1000 px of slab in the short dimension, keep source - resolution, flag "low-res" in the review UI) -5. Output: 1600×1600 PNG (transparency preserved), plus a JPEG (q=85) copy - for the WooCommerce upload +SHEET = auto +GREEN_HUE_LO/HI = 35, 85 +GREEN_SAT_MIN = 40 +GREEN_VAL_MIN = 40 +BLACK_THRESH = 30 ``` +Sensitivity, edge offset, and feather map onto these at runtime. Users do not edit the raw HSV numbers. -### 7.3 Merchandising filter (FR22, optional, per-slab toggle) -Deterministic LUT: contrast +12% (linear stretch), warmth +8 (R/B channel shift -toward warm), grain = unsharp mask (radius 2, amount 0.4). Fixed constants in §8 — -no per-photo tuning. Applied after §7.2, before encode. +## 8. Test vectors -### 7.4 What gets stored (Decision 12) -- While draft / retry: original + normalized, both on disk (Docker volume) -- After successful publish: both purged (SQLite rows keep metadata only) +Users think in inches, sqft, and bdft. Pixels are only how the computer gets there. -## 8. Deterministic constants (single source of truth) +### TV-1 Green sheet +Synthetic: green border, wood in the center. Interior green-ish patch that does not touch the border stays. Coverage enough that U2Net does not run. -```python -RULER_INCHES = 12.0 # known physical ruler length -CANNY_LO, CANNY_HI = 40, 120 -MIN_TICK_PROMINENCE = 0.15 # of projection peak amplitude -TICK_SPACING_TOL = 0.05 # 5% -RULER_CROSS_CHECK_TOL = 0.03 # 3% -OCR_CONF_MIN = 70 # Tesseract 0–100 -LEN_MISMATCH_TOL = 0.05 # 5% -WIDTH_FEATURE_PROM = 0.02 # 2% of L_px, in width-profile prominence -WIDTH_SAMPLES_MIN, WIDTH_SAMPLES_MAX = 3, 5 -END_TRIM = 0.05 # sample at 5% and 95% of length -GREEN_HUE_LO, GREEN_HUE_HI = 35, 85 -GREEN_SAT_MIN = 40 -GREEN_VAL_MIN = 40 -SHEET_COV_MIN = 0.25 # sheet must cover ≥25% of frame -FILL_TARGET = 0.80 # slab fill of final frame -OUTPUT_PX = 1600 # 1:1 output size (Decision 20) -OUTPUT_PX_MIN = 1000 # hard minimum -JPEG_QUALITY = 85 -FILTER_CONTRAST = 0.12 -FILTER_WARMTH = 8 -FILTER_GRAIN_RADIUS = 2 -FILTER_GRAIN_AMOUNT = 0.4 -``` -All of these are importable module-level constants (`pipeline/constants.py` when -implemented) and each test vector in §9 pins at least one of them. +### TV-2 Black sheet +Same layout, black border, mid-tone wood. Dark interior wood that does not touch the border stays. -## 9. Test vectors +### TV-3 Scale, sqft, bdft +Slab **96" long**, **1.5" thick**. Mask measures **0.64 sqft**. +bdft = 0.64 × 1.5 = **0.96**. -### TV-1: Ruler scale (pure math) -Ruler rect corrected; ticks detected at px [100, 300, 500, …, 2300] (12 ticks, 200 px apart). -- scale = (2300 − 100) / 11 = **200.0 px/in** -- s_edge with margin 100 px each side, W_r = 2500: (2500 − 200) / 12 = 191.67 → Δ = 4.2% > 3% → use tick scale, log warning. ✔ expected branch. +### TV-4 Width samples +96" length axis, stations every 6". Widths perpendicular to the confirmed axis. Listing gets min, max, avg. -### TV-2: Full happy path -- scale = 200 px/in (from TV-1) -- L_px = 19,200 → L = 96.0 in -- widths (px) at x = 960, 4800, 9600, 14400, 18240: [3500, 3640, 3800, 3560, 3700] - → inches: [17.5, 18.2, 19.0, 17.8, 18.5] → w_avg = **18.2 in** -- t = 1.5 in (manual) -- sqft = (96 × 18.2) / 144 = **12.13** -- bdft = (96 × 18.2 × 1.5) / 12 = **218.40** -- rule: (Black Walnut, Cathedral) = $12.50/bdft -- recommendation = 218.40 × 12.50 = **$2,730.00** +### TV-5 Angled end +One square end, one 45° cut. Length axis follows prevailing length, not the diagonal. Widths stay perpendicular after user confirm. -### TV-3: Manual length, derived scale -- RULER_FAIL; manual L = 96.0 in; L_px = 19,200 → scale = 200.0 px/in (derived) -- Same width px as TV-2 → identical downstream results (18.2 in avg, 218.40 bdft). -- Asserts the fallback chain is value-equivalent when inputs match. +### TV-6 3:4 crop, 80% at extremes +Slab centered in a 3:4 frame. At the widest and tallest points, fill = 0.80. PNG with alpha. Shorter side ≥ 1600 when the source allows. -### TV-4: No top-down photo (Decision 19) -- Manual L = 96.0, manual width = 18.0, t = 1.5 -- w_avg = 18.0 → bdft = (96 × 18 × 1.5) / 12 = **216.00** -- No photo used in math; publish allowed. +### TV-7 Too-small source +After 80% crop, shorter side would be below 1600 and the source cannot supply it. Warn. Do not upscale from nothing. That photo is not publishable until retake. -### TV-5: Pricing edge cases -- bdft = 218.4, rule $12.34 → rec = 2695.056 → stored **$2,695.06** (half-up) -- bdft = 0 (degenerate) → rec = $0.00, UI blocks publish (slab must have positive dims) -- No rule → rec = null; manual price $999.99 stored as-is. +### TV-8 Pricing +bdft 0.96, species $12.50/bdft → rec **12.00**. +Override **150.00** stored as 150.00. +No rule → rec empty; manual 99.99 stored as 99.99. -### TV-6: Normalization geometry -- Source 4000×3000; slab bbox (px): x 400..3600, y 600..2400 → w=3200, h=1800 -- frame side = 1800 / 0.80 = 2250 -- crop: 2250×2250 centered on (2000, 1500) → x 875..3125, y 275..2525 (in bounds ✔) -- slab fill check: 1800 / 2250 = **0.80** ✔ -- Output: 1600×1600. Slab in output: 1800·(1600/2250) = 1280 px → 80% of 1600 ✔ -- Clamp case: bbox center (1000, 1000), side 2250 → clamp x to 0..2250, y to 0..2250; re-center rule applies; expected crop x 0..2250, y 0..2250 with slab offset left/up — fill still 0.80. +### TV-9 Thickness → Woo range +User pick **1"** stored as 1". Attribute bucket is the Woo range that 1" rounds **up** into (e.g. `1"–1 1/2"`). Exact range labels come from the synced Woo attribute, not this file. -### TV-7: Green-sheet key -- Synthetic: 1000×1000, H=60 S=120 V=120 background; center 400×200 rect H=20 S=60 V=80 (wood) -- Expected: mask covers background minus the wood rect; border-flood removes any - interior sheet-colored islands; sheet coverage = 60% ≥ 25% ✔ (no U²Net escalation) -- Wood rect with a green-ish tone (H=45 S=50 V=100) touching no border → NOT removed (border flood) ✔ +### TV-10 Rounding +Length 96.04" → **96"** (nearest 1/8"). +sqft 0.641 → **0.64**. +bdft 11.525 → **11.53**. +Price 12.345 → **12.35**. -### TV-8: Width sampler selection -- w(x) profile: ends 100, peak 140 at x=0.3L, trough 90 at x=0.6L, end 105 - (prominences: peak 40 ≥ 2% of L_px-scale ✔, trough 50 ✔) -- Expected sample points: {0.05L, 0.95L, 0.3L(peak), 0.6L(trough)} = 4 points (≤5 ✔) -- n=4 → w_avg = (100+105+140+90)/4 = 108.75 (px) → inches via scale. +## 9. Assumptions -### TV-9: OCR acceptance -- "BW-0042" conf 85, regex ✔ → accept -- "BW-004?" conf 78 → regex ✘ → manual entry -- "BW-0042" conf 65 → conf < 70 → manual entry +1. The first photo is top-down, lens parallel to the broad face. Tilted shots make sqft/bdft wrong; retake is the fix. +2. User length is the prevailing length of that face, in 1/8". The bounding-box axis is confirmed in the UI. +3. Thickness is the declared 1/8" pick, not measured from any photo. +4. sqft is the projected top-down area of the mask. Live-edge thickness and underside are not in the area. +5. bdft = sqft × thickness (inches). Not rounded up to whole board feet. +6. Sheet is uniform green or black. Odd colors → user picks sheet mode or retakes. +7. 3:4 is the PIP crop. Changing it later is a settings/code change. +8. Client does all of this math. Server stores the numbers the client sends. -## 10. Assumptions (flagged for Ty) +## 10. Out of scope here (covered in other docs) -1. **bdft not rounded up** to whole units (§2). Say the word and it's a one-line change. -2. **12-inch ruler** with inch ticks is the standard calibration tool (Decision 3 implies; spec assumes a 1-ft rule with ticks at every inch). -3. **Top-down photo selection** = best aspect-ratio match, user-overridable (FR23). No inference used for this. -4. **Ruler parallel to long axis** — if the user places it diagonally, tick scale is still valid (it's a linear scale), only the cross-check margin logic degrades; acceptable for v1. -5. Green sheet is the standard bright craft green. A different sheet color → U²Net fallback path (§7.1 step 5), not a config item in v1. - -## 11. Out of scope for this spec (next: OpenAPI contract, deliverable #2) -- Endpoint shapes, request/response schemas, error taxonomy -- SQLite schema beyond the pricing-rule shape (PRD) -- WooCommerce product payload mapping -- Content generation templates (FR16) — deterministic template design is a separate short doc +| Topic | Doc | +|---|---| +| Call 1 / Call 2 prompts, taxonomy mapping | Content / Woo | +| Woo payload, publish, duplicate SKU | Content / Woo, OpenAPI | +| SQLite tables, status machine | Data Model | +| HTTP contract | OpenAPI | +| Client vs server topology | Architecture | +| Auto-dimension overlay, figure-weighted price | Impl plan (v1.5) | +| Offline capture | PRD non-goal |