docs(phase2): reconcile requirements and migrate capabilities/contracts
Surface-matrix sweep of every source doc; added nine missed behaviors (METADATA-115, REVIEW-50, APP-55/60/65, SETTINGS-45 mode, Generate-text availability, defaults-off). 153 requirements, 0 coverage gaps. Migrated capabilities to docs/capabilities/ and contracts to docs/contracts/; added WOO-API, API, DATA-MODEL, PROMPTS, UX, TEST-SPEC. Populated MILESTONES; branch-neutral trunk docs; renamed umbrella term to Woo Slab Taxonomy. Archived reconciliation working records under .audit/archive/.
This commit is contained in:
@@ -0,0 +1,97 @@
|
||||
# UX contract — mill-owner flow
|
||||
|
||||
Status: SPEC · 2026-09-18. Presentation spec for the mill-owner flow on phone and PC browsers.
|
||||
|
||||
## Requirements impact
|
||||
|
||||
| Requirement | Impact on this design |
|
||||
|---|---|
|
||||
| CAPTURE-10 | supported browsers, hard stop |
|
||||
| CAPTURE-15 | online only |
|
||||
| CAPTURE-20, CAPTURE-25, CAPTURE-30 | photo intake and calibration choice |
|
||||
| CAPTURE-40, CAPTURE-41, CAPTURE-45, CAPTURE-50, CAPTURE-55 | sheet/sensitivity controls, overlay, retake |
|
||||
| CAPTURE-60, CAPTURE-65, CAPTURE-70, CAPTURE-80, CAPTURE-85, CAPTURE-90 | axis, entry, derived numbers |
|
||||
| CAPTURE-105, CAPTURE-135, CAPTURE-141, CAPTURE-145, CAPTURE-150, CAPTURE-155 | crop guard, upload, preview/controls, failure |
|
||||
| METADATA-10, METADATA-15, METADATA-30 | required taxonomy fields and cardinality |
|
||||
| METADATA-45, METADATA-55, METADATA-110 | pre-fill, Generate text availability |
|
||||
| PUBLISH-10, PUBLISH-15, PUBLISH-20, PUBLISH-25, PUBLISH-30, PUBLISH-35, PUBLISH-36, PUBLISH-37, PUBLISH-38, PUBLISH-50 | publish outcomes and messaging |
|
||||
| REVIEW-5, REVIEW-10, REVIEW-15, REVIEW-20, REVIEW-25, REVIEW-30, REVIEW-40, REVIEW-45, REVIEW-50 | ready set, gating, fields, limits |
|
||||
| SETTINGS-65 | create-status default |
|
||||
|
||||
## 1. Shape
|
||||
|
||||
One column of screens: capture → review → publish. No dashboard and no batch view. The reader is a
|
||||
mill owner photographing one slab at a time, online. Capture often starts on a phone; the same
|
||||
flow runs on a PC browser.
|
||||
|
||||
## 2. Capture
|
||||
|
||||
1. **Photos.** Take one or more photos; the first is top-down with the lens parallel to the broad
|
||||
face. The owner chooses which photo is the calibration photo.
|
||||
2. **Mask overlay and controls.** The app draws the mask on the source photo. The controls are
|
||||
exactly **Sheet** (auto, green, black) and **Sensitivity** (0–100). A Sheet change runs
|
||||
immediately; a Sensitivity change debounces 2000 ms; a worker recomputes and the last good
|
||||
overlay stays visible. There is no apply step and no server round trip; values persist until
|
||||
reset.
|
||||
3. **Confirm the mask.** The owner confirms the edge; approval is blocked when the mask has no
|
||||
slab pixels. A broken or non-contiguous mask resolves as a retake.
|
||||
4. **Length axis.** The app draws the bounding rectangle and the length axis; the owner rotates it
|
||||
to the prevailing length and confirms. On a nearly square slab the owner chooses the axis.
|
||||
5. **Numbers.** The owner enters length and thickness in 1/8-inch steps and the SKU. The browser
|
||||
computes widths, sqft, and bdft. These are display only; the server never recomputes them.
|
||||
6. **Continue.** Uploads originals, processed PNGs, and the numbers as a calibrated draft; status
|
||||
becomes `calibrated`.
|
||||
|
||||
The preview is display-only and never drives the math. Failures such as a broken mask or an
|
||||
undersized source never guess; the resolution is retake.
|
||||
|
||||
## 3. Review
|
||||
|
||||
- **Vision pre-fill.** At or above the threshold (default 0.7) a field is pre-filled and shown
|
||||
with an "AI" badge; below it the field starts empty. The badge is presentation only and clears
|
||||
on edit.
|
||||
- **Required set.** Exactly one species and at least one wood-category leaf; one Edge Type, at
|
||||
least one Figure, exactly one Grade, one Thickness band, one Moisture; fig-* and feat-* tags
|
||||
optional; price; title, short_description, and description.
|
||||
- **Primary category.** The owner declares one primary wood category and any secondary ones; the
|
||||
default is the first selected.
|
||||
- **Inline nudges.** Every empty required field shows an inline nudge as the owner works; there is
|
||||
no single submit-time gap list.
|
||||
- **Calculated fields.** Widths, sqft, and bdft are read-only and not overridable.
|
||||
- **Generate text.** The control appears only when content generation is enabled and the endpoint
|
||||
is reachable; it is disabled when the text service is down; it never runs automatically.
|
||||
|
||||
## 4. Publish
|
||||
|
||||
- A normal SKU uses `woo_create_status` (default draft); a `SLAB-UAT-*` SKU always creates a draft.
|
||||
"Published" means the store create succeeded, not that it is live.
|
||||
- **Success.** The local draft and photos are gone; the store product reference is shown.
|
||||
- **Duplicate SKU.** "This SKU already exists in the store (any status)." with Edit SKU and Open
|
||||
Existing.
|
||||
- **Stale value.** "This value is no longer valid. Pick from the current list," with current
|
||||
options.
|
||||
- **Failure.** A plain message on the affected field or action, classified recoverable or
|
||||
unrecoverable, with Retry while the draft and photos are retained; no raw code.
|
||||
|
||||
## 5. Browser gate
|
||||
|
||||
Supported families are iOS Safari and Android Chrome, plus desktop Chrome, Edge, and Firefox. An
|
||||
unsupported client gets a hard stop with an update or switch link; there are no polyfills.
|
||||
|
||||
## 6. Canonical error and empty copy
|
||||
|
||||
| Situation | Copy |
|
||||
|---|---|
|
||||
| Mask failure | "Cannot isolate the slab edge. Adjust the controls or retake." |
|
||||
| Axis check | "Rotate the axis to match the prevailing length of the slab." |
|
||||
| Source too small | "Photo will be too small after cropping. Please retake with a closer shot." |
|
||||
| Duplicate SKU | "This SKU already exists in the store (any status)." |
|
||||
| Stale value | "This value is no longer valid. Pick from the current list." |
|
||||
| Store unreachable | "Cannot reach the store. Check your connection and settings." |
|
||||
| Missing field nudge | per-field, in place (e.g. "Select species") |
|
||||
| Browser gate | "This app requires a recent browser. Please update or switch, then try again." |
|
||||
|
||||
## 7. Presentation-only details
|
||||
|
||||
First-run guidance card, "AI" badge styling, and the separate title/description step are
|
||||
presentation detail, not requirements.
|
||||
Reference in New Issue
Block a user