Ty_Tech/SlabUploader
6
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: lock revised capture pipeline and hybrid architecture

Browse Source 
Rewrite PRD, tech spec, data model, and OpenAPI around the 2026-08-27
decisions: client-side mask/measure/crop, U2Net on demand, Woo as product
source of truth, draft-only local state. Architecture records topology C
through the status machine. Drop the old CONTENT-WOO spec until the
Call 2 prompt review finishes.
This commit is contained in:
Ty
2026-08-27 19:26:45 -07:00
parent bee3bcc278
commit 4e97770373
6 changed files with 962 additions and 1022 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Slab capture app PRD.txt
+160 -137
View File
@@ -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.
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.
- Measurements must be accurate; manual length entry is authoritative and used to extrapolate widths and bdft.
- No bulk publishing; slab-by-slab submission only.
- 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.
- 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-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).
## 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-24; see Decisions log items 18–20)
- (none — all resolved 2026-08-27)
## 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.
- 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.
- 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.
- 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.
## 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 pricing rules, reviews and publishes slabs.
**Secondary user**
- Field operator (optional): may capture photos and basic data; no special permissions required.
- Ty (Owner/Expert): captures, configures, reviews, and publishes slabs.
**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.
- 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/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.
- 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 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.
- **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, thickness, and calculations
- **FR7:** Compute length, one or more widths, sqft, and bdft deterministically.
### 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.
- **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.
### 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
- **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.
- **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.
### 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.
### 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 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.
### 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 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.
### 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
- **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.
- **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
- **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.
- **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 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.
## 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; modular services.
- **Usability:** One‑hand operation, large touch targets, clear distinction between internal and customer photos.
- **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)
- 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
- No OCR, no OpenCV on client
**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.
**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 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.
- 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.
- 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).
- No app-level auth in v1.
- HTTPS enforced.
### Pricing rule schema (confirmed as the pricing-rule shape — Decision 15)
### Pricing rule schema
id: uuid
species: string
character: string
wood_category: string
price_per_bdft: float
created_at: timestamp
updated_at: timestamp
## Key flows and acceptance criteria
### Capture → Enrich → Publish flow
### Capture -> Calibrate -> Infer -> 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.
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.
- 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.
- 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 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).
- 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.
docs/ARCHITECTURE.md
+117 -154
View File
@@ -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.
docs/CONTENT-WOO.md
-151
View File
@@ -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": <species category id> } ],
"tags": [ { "id": <char tag id> }, … ],
"images": [
{ "src": "<data URL or pre-uploaded attachment URL>", "alt": "{species} {character} slab" }
],
"attributes": [ … if present … ],
"virtual": false,
"downloadable": false,
"catalog_visibility": "visible"
}
```
**Image upload strategy** (Woo v3): `images[].src` accepts a URL or a data URL.
For reliability the server:
1. For each customer-facing (inventory, normalized) photo in `seq` order:
`POST /media` with the JPEG bytes → get attachment `source_url`.
2. Reference those `source_url` values in `images` (≤5, per PRD 1–5 inventory photos).
3. Calibration photos are excluded (FR2).
**Status = `pending`** by default (test-target decision: test products must never go
live without human action). The Settings key `woo_publish_status` (default `pending`)
controls this; Ty flips it to `publish` only when intentionally going live.
### 2.5 Dedupe & idempotency (FR24a)
Before create: `GET /products?sku={sku}`.
- Found → `409 duplicate_sku` (v1 has no update path; human resolves).
- Not found → proceed. (Single-owner, slab-by-slab, so no TOCTOU concern in practice;
the check is still done for correctness.)
### 2.6 Sync result & logging (FR28)
- On success: set `slabs.woo_product_id`, `status=published`, `published_at`, write
`sync_log(status=success, woo_product_id, payload_hash)`.
- On Woo HTTP error: `status=failed`, `sync_log(status=failed, http_status, error,
detail=<Woo error body>)`. Surface in UI + poll response.
- **Partial-failure note** (risk, see IMPL-PLAN): if media uploads succeed but the
final product POST fails, orphaned Woo attachments may exist. v1: log it; a manual
cleanup note is surfaced. Not auto-deleted (could delete a real image).
## 3. End-to-end publish sequence (server side)
```
1. validate slab publishable (length,width,thickness,price,species,char,≥1 photo)
2. dedupe by SKU (GET /products?sku=) → 409 duplicate_sku if exists
3. (re)sync taxonomy if cache older than 1h → best-effort; use existing cache on fail
4. resolve category/tags/attributes (auto-assign + overrides)
5. upload normalized inventory images → media → source_urls
6. POST /products (status=pending) → woo_product_id
7. write sync_log(success), set slab published, purge images
on any failure at 2–6: write sync_log(failed), slab=failed, (images retained for retry)
```
## 4. What is deterministic vs scoped-inference here
- Deterministic: templates, all dimension text, category/tag/attribute resolution,
payload assembly, dedupe, logging.
- Scoped inference: optional LLM title/description refinement only, with the
numeric-accuracy guardrail (§1.2).
docs/DATA-MODEL.md
+212 -158
View File
@@ -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 | |
docs/OPENAPI.md
+228 -124
View File
@@ -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":"<model>", "inference_enabled": true,
"inference_base_url": "http://192.168.1.202:8080/v1",
"inference_model": "<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":"<base64>" , "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
<binary>
---
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.
docs/TECH-SPEC-PIPELINE.md
+166 -219
View File
@@ -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
```
### 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.
### 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)
## 8. Deterministic constants (single source of truth)
```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
SHEET = auto
GREEN_HUE_LO/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
BLACK_THRESH = 30
```
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.
Sensitivity, edge offset, and feather map onto these at runtime. Users do not edit the raw HSV numbers.
## 9. Test vectors
## 8. Test vectors
### 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.
Users think in inches, sqft, and bdft. Pixels are only how the computer gets there.
### 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-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.
### 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-2 Black sheet
Same layout, black border, mid-tone wood. Dark interior wood that does not touch the border stays.
### 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-3 Scale, sqft, bdft
Slab **96" long**, **1.5" thick**. Mask measures **0.64 sqft**.
bdft = 0.64 × 1.5 = **0.96**.
### 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-4 Width samples
96" length axis, stations every 6". Widths perpendicular to the confirmed axis. Listing gets min, max, avg.
### 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-5 Angled end
One square end, one 45° cut. Length axis follows prevailing length, not the diagonal. Widths stay perpendicular after user confirm.
### 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-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-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.
### 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-9: OCR acceptance
- "BW-0042" conf 85, regex ✔ → accept
- "BW-004?" conf 78 → regex ✘ → manual entry
- "BW-0042" conf 65 → conf < 70 → manual entry
### 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.
## 10. Assumptions (flagged for Ty)
### 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.
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.
### 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**.
## 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
## 9. Assumptions
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. Out of scope here (covered in other docs)
| 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 |