[ArtRiv]

Item 1 of the order suggested in docs/admin-api.md — the only one that
blocks real data today. The twelve AVESSO pieces carry a single variant
labelled Único that the #19 migration created, and the store sells clothes
with no size until that can be changed.

Stacked on #21 (docs only). Merge that first and this rebases clean.

The routes

PATCH	/products/{id}/variants/order	products.update
PATCH	/products/{id}/variants/{variantId}	products.update
DELETE	/products/{id}/variants/{variantId}	products.delete

39 operations → 42. Spec: docs/specs/variant-management.md.

DELETE asks for products.delete rather than products.update on purpose.
It changes nothing today — only admin holds either — and it matters the day
someone gets products.update to fix labels and stock, and should not thereby
be able to discard sold-out sizes and other people's cart lines.

The removal policy, which is most of the spec

Three walls, and only the third is negotiable.

1. The last variant never goes. Every product has at least one size;
   one with none is unbuyable. No parameter overrides it — archive the product
   instead.

2. A sold size never goes. order_items RESTRICTs it. The route turns
   that refusal into a 409 with a sentence rather than a leaked 500 — and
   when it closes, renaming is the way out, which still unblocks the twelve
   even in the worst case, because variantLabel is a snapshot.

3. Carts do not veto, but nothing is discarded by accident. CartItem
   cascades, so creating this route makes a silent deletion real. Refusing
   while a cart holds the size would hand an abandoned bag a veto over the
   catalogue — this cart has no TTL, no reservation, no expiry, and nothing
   ever clears it. Letting it cascade shrinks somebody's bag with no
   explanation.

   So: refuse by default with the count, and require a confirmation of two
   halves — discardCartLines=true authorises the destruction,
   expectedCartLineCount=N confirms its size. If the number moved in
   either direction, nothing is deleted and the 409 carries the new one.

Concurrency

The destructive path runs in one transaction that opens by locking the
product's variant rows. Inserting a cart line takes FOR KEY SHARE on the
variant it points at, and FOR UPDATE conflicts with that — so no cart can
slip in between the recount and the delete, and two concurrent removals cannot
both read "two variants left" and both delete one. The cart lines are then
deleted by this code, not by the FK cascade: the cascade stays as a
referential net, but a rule that deletes customer data should be a line
somebody can read and test.

Two things found on the way

• discardCartLines is this repo's first boolean query parameter, and the
  obvious implementation inverts it. @Type(() => Boolean) runs
  Boolean('false'), which is true — the value asking for the protection
  would have switched it off. Strict transform, with an e2e pinning it.
• addVariant defaulted a new position to the count of variants, not one
  past the highest. Sparse positions were already reachable, and deleting
  from the middle produces them routinely; a new size then landed on top of an
  existing one and a UUID tiebreaker decided display order. Fixed.

The e2e had nowhere safe to run

The suite TRUNCATEs, and DATABASE_URL points at the development project —
which is also the one serving the published store. With no third Supabase
project to spend, it now runs in a dedicated schema built by
pnpm e2e:setup from the real migrations plus the production seed.

Worth a look in review: search_path moves raw SQL and does not move
Prisma. With no schema on the driver adapter the query compiler qualifies
everything with public. The first build of this reported success while the
test schema sat empty — it had seeded the development database and read its
own answer back. A suite in that state truncates empty test tables and then
reads and writes real data, green the whole time. The schema is now parsed out
of the URL once and feeds both halves, and the suite refuses to start without
E2E_DATABASE_URL or if the server answers public.

Verified

492 unit tests (24 new) · 206 e2e in 9 files (17 new, no regressions in the
existing 189) · lint:check, typecheck, build · openapi:generate
reproduces the committed document.

Three e2e assertions only a real database can falsify: a sold size refused
with the order intact, a cart line disappearing with the variant and the
owner's cart re-totalling, and the recount aborting when a fourth cart arrives
between the warning and the confirmation.

Not in this PR

docs/status.md still says "39 rotas" and "468 testes unitários". Left alone
because chore/stale-test-counts is already in flight on exactly that.

🤖 Generated with Claude Code