M2: the full job lifecycle — chat, hiring, geocoding, quotes, bookings, reviews

Closes the funnel. Before this the product could match two people and then
stopped: `quotes`, `bookings` and `reviews` had tables and state machines and
nothing that wrote a row, the entry deck's right swipe was wired to an empty
handler, and every address resolved to the city centre.

Jobs tab and chat
- message router: thread, send, markRead, unreadTotal. A thread is a MATCH, not
  a job — one job with three interested pros is three private conversations.
- Current/Past segments derived from ACTIVE_JOB_STATUSES, job detail listing the
  pros who accepted, and the conversation itself with attachments.

Hiring from the deck
- A right swipe on the entry deck opened nothing. It now resolves "which job?"
  through a sheet — sign in, pick an open job, or post one — and calls the same
  deck.swipe the per-job deck does, so the open-request cap and row lock apply
  exactly once. Swipes are vetoable so closing the sheet returns the card.

Geocoding
- ST_Distance and ST_DWithin rank and filter every deck, and both operands were
  placeholders. Addresses now resolve through Mapbox (permanent=true, which is
  what licenses storing the coordinates), the server resolves points rather than
  trusting client-supplied lat/lng, and every stored point records how it was
  obtained. A `city`-precision base cannot reach the verification queue.

Quote -> booking -> review
- The commercial chain, minus payments. Accepting a quote is the only place a
  booking is created; confirming completion is what unlocks reviews and moves
  the pro's completed_jobs.
- Reviews publish double-blind with no sweeper: each is written with
  published_at already set to its embargo deadline and every read filters
  published_at <= now(), so it publishes itself. The second review pulls both
  forward. A silent counterparty cannot bury a bad review by never replying.

State machine changes, both deliberate
- booked -> matched: a cancelled booking is not a cancelled job.
- scheduled -> awaiting_confirmation: in_progress is optional, so a pro who
  never tapped Start can still say the work is done.

Test suite
- api tests ran files in parallel against one database and failed roughly one
  run in three on whichever file lost the race. Serialised, and three fixtures
  that grabbed "the first client" pinned to the seeded accounts.

Also includes work from a parallel session: admin verification queue, pro
public profile and reviews read path, notification sending, denormalised stats
recompute, search, and observability.

318 tests passing; typecheck and lint clean across 7 packages.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
serfa
2026-08-21 06:29:59 -04:00
co-authored by Claude Opus 5
parent 8f3509d1dd
commit 974e312534
115 changed files with 19994 additions and 569 deletions
+138
View File
@@ -301,6 +301,144 @@ buttons are 64px circles, 2px border, `ink-0` fill.
---
### 6.9 Search field
The §6.2 input, 48px, with a 20px `Search` glyph inset 16px from the left in `ink-500`, and a
44px circular clear button on the right that exists only while the field has content.
The label is **visible above the field**, never the placeholder — §6.2 applies here more than
anywhere, because a placeholder disappears at exactly the moment someone needs reminding what
the box searches. The placeholder carries examples of what to type, not the name of the field.
### 6.10 Result row
`radius-card`, `1px ink-200`, `raised` fill, 16px padding, **12px between rows**. A 56px
`radius-md` thumbnail leads; where there is no image, its initial on an `inset` fill — never an
empty grey square. Title in `h4`, one `body-sm ink-600` line, one `meta` line of figures in
`tabular-nums`, trailing chevron in `accent`.
Hover and press move the border to `brand-500`. Rows do not lift, scale or shadow: a list of
twenty is a scanning surface, and twenty things that react is noise.
A row is **not** a deck card. The deck card is a single-decision object with its own gesture;
reusing it in a list costs the list its scroll.
### 6.11 Skeletons
`inset` fill with `animate-pulse`, at the exact height and radius of whatever it stands in for.
Never more than one screenful — three rows is enough to say "loading"; twenty is a lie about
what is coming.
While REFRESHING existing content, keep the old content on screen instead. A list that blanks on
every keystroke reads as "no results", repeatedly.
### 6.12 Empty and no-result
Two different states, two different messages.
- **Empty** — nothing asked yet. Say what this screen can do and give a way in.
- **No result** — something asked, nothing found. Name what was searched and offer the single
most effective filter to relax. Never a bare "No results."
Both use `EmptyState` (§6.3): dashed hairline, centred, `h4` title, `body-sm ink-600` body.
### 6.13 Segmented control
Two or three mutually exclusive views of **the same list** — "Current / Past", not navigation.
Full width, `radius-pill`, `ink-100` track, 4px inset padding. The selected segment is an
`ink-0` pill on `shadow-sm` with `ink-950` text at weight 600; unselected is `ink-600` on the
bare track. Each segment is a 40px-high target inside a 44px row.
A segment may carry a count after its label in `tabular-nums`; a zero count is rendered, not
hidden, because "Past 0" is information and a missing number reads as a loading state.
Use it only where the segments are the same kind of thing and the user is switching lens. Where
the destinations differ in kind, that is the tab bar's job (§6.7), and where one option is a
filter on a list that has other filters too, use chips (§6.4). Never more than three segments —
at four, the labels truncate at 360px and it becomes a worse tab bar.
Implemented as a `radiogroup`: the selected segment carries `aria-checked`, and selection is
never signalled by fill alone (§8) — the weight change carries it too.
### 6.14 Bottom sheet
The only modal this product has. It rises from the bottom edge, because that is where the thumb
already is (§4) and a centred dialog on a 390px screen is just a card with the page greyed out.
`radius-card` on the **top two corners only**, `page` surface, `shadow-lg`, full width, capped
at 85% of the viewport height with its body scrolling inside. A 36×4px `ink-200` grab handle sits
centred at the top — the affordance that says this can be dismissed downward. Behind it, a
`rgb(0 6 36 / .45)` scrim.
Layout is title (`h3`), optional one-line body (`body-sm ink-600`), content, then actions pinned
at the bottom of the sheet: primary full-width, dismissal as a `ghost` beneath it. Actions never
scroll out of reach.
Dismissal is by scrim tap, Escape, or the grab handle — and **all three mean the same thing**.
A sheet whose scrim tap silently confirms is a trap. Anything destructive or irreversible gets an
explicit button; the sheet closing is always "no".
Enter and exit use `motion-slow` with the sheet translating and the scrim fading; under
`prefers-reduced-motion` both simply appear. `role="dialog"` with `aria-modal`, focus moves to the
sheet on open and returns to the trigger on close.
Use it for a decision that needs context the current screen cannot show — picking which job to
send a pro, confirming a cancellation. Not for navigation, and not for anything with more than one
input: a form belongs on a screen.
### 6.15 Pro profile
What a result row (§6.10) opens onto, and the only screen in the app whose job is *reading*
rather than deciding. It is a pushed screen (§6.6): 44px back chevron top-left labelled with
where it came from, never a bare arrow.
Order is fixed, because it is an argument and the parts only work in sequence: lead photo,
name in `h1`, headline, then one `meta tabular-nums` line of figures — rating, distance, rate,
years, jobs done. The verification line sits directly under it in `go-700` with a shield glyph;
it is the one claim this marketplace is actually selling, so it is never further down the page.
Then titled blocks, each skipped entirely when empty rather than rendered as a heading over
nothing: **Trades** and **Specialises in** as `Tag` pills (§6.4), **About**, **Their work** as a
horizontally scrolling strip, and **Reviews**.
Reviews are a page, not a history. The heading says so — "Showing the most recent of 47" —
because `ratingCount` in the header counts every rating and the list below it never will, and two
numbers that disagree without explanation read as a bug. Each review is a `radius-card` row: 36px
round avatar or initial, author name, five stars filled to the rating, relative date, then the
body. Stars carry their value in the accessible name (§8); an unrated pro gets the `New` pill and
never `0.0 ★`.
The primary action is pinned to the bottom of the screen, not placed after the reviews — a page
of reviews is exactly the length that buries a button (§9). It opens the send sheet (§6.14)
rather than acting directly, because "which job?" is a question this screen cannot answer.
### 6.16 Address field
An address is the only input in this product that must resolve to something real: distance is
what the deck ranks on, so a typed line that never became a coordinate is not an answer.
The §6.9 search field geometry, with a suggestion list below it and a **precision line** beneath
that. Suggestions are §6.10 result rows at 56px, no thumbnail, title plus one `meta` line, and
the list caps at five — a sixth is a scroll inside a form and nobody reads it.
The precision line is the component's whole reason for existing and is never optional:
| State | Line | Tone |
|---|---|---|
| Resolved to a street address | "Matched to <address>" | `go-600` with a check |
| Resolved to a street/area only | "Approximate — we will match from <area>" | `sun-500` with an alert |
| Nothing resolved | "No address yet — matching from <city>" | `ink-600`, no icon |
Never show only a tick. "We found something" and "we found the right thing" are different
claims, and a field that renders them identically is how a placeholder gets stored as a
location.
A "use my current location" control sits below, and on success **must** fill the text with a
reverse-geocoded label — a button that silently sets an invisible pin gives the user nothing to
check.
---
## 7. Motion
| Token | Duration | Easing | Use |