marketplaces/docs/backend/PHASE-3-CATALOG-OFFER-FULFILLMENT-CONTRACT.md

# Phase 3 Backend Contract — Product/Offer Split, Inventory, Executability

Companion to [PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md](../PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md) Phase 3 (Sprints 3.1–3.3). The largest structural change in the programme — nothing about multi-seller commerce works without it.

**Status: ready to build.** No open decisions block this phase.

---

## 1. Why this exists

Today price, stock and currency hang directly off a single admin `Product` mock domain, unrelated to the live storefront `Item` domain. A product cannot have two sellers, two prices, or two stock levels. `Offer/Listing` does not exist in any form.

## 2. The two-layer split

`Product` describes the item itself (content). `Offer` describes one seller's commercial proposition against that product (price, stock, currency, status). One product, many offers.

```ts
interface Product {
  id: string;
  marketplaceId: string;
  categoryId: string;
  brand?: string;
  title: string;
  description: string;
  attributes: Record<string, unknown>;
  media: string[];
  status: 'draft' | 'moderation' | 'published' | 'paused' | 'archived';
}

interface Variant {
  id: string;
  productId: string;
  sku: string;
  barcode?: string;
  optionValues: Record<string, string>; // e.g. { color: 'red', size: 'M' }
  dimensions?: { weight?: number; length?: number; width?: number; height?: number };
}

interface Category {
  id: string;
  marketplaceId: string;
  parentId: string | null;
  slug: string;
  attributesSchema: Record<string, unknown>;
  order: number;
  seo: { title?: string; description?: string };
}

interface Offer {
  id: string;
  marketplaceId: string;
  sellerId: string;
  variantId: string;
  sellerSku: string;
  price: Money;          // Money type from Phase 1 contract
  stockPolicy: 'track' | 'no_track' | 'preorder';
  status: 'draft' | 'moderation' | 'published' | 'paused' | 'archived';
  publishedAt?: string;
  executabilityChecked: boolean; // see §5
}

interface PriceHistory {
  offerId: string;
  price: Money;
  changedBy: string;      // user id or 'sync:{connectorId}'
  changedAt: string;
}
```

## 3. Inventory

```ts
interface InventoryRecord {
  offerId: string;
  available: number;
  reserved: number;
  sold: number;
  warehouse?: string;
  source: 'manual' | 'feed_sync' | 'connector';
}

interface StockReservation {
  id: string;
  offerId: string;
  qty: number;
  reason: 'checkout' | 'pre_payment';
  expiresAt: string; // TTL
  released: boolean;
}
```

Invariants:
- `available`, `reserved`, `sold` are counted separately, never derived from one another implicitly.
- Reservations are created at checkout or pre-payment (tenant-configurable strategy) and expire by TTL, releasing `reserved` back to `available`.
- Seller feed stock updates are an **idempotent upsert** — a repeated webhook must not double-decrement.
- Oversell (a sale exceeding `available`) routes to a dedicated incident queue, never silently hidden or auto-corrected.

### 3.1 Reservation must be atomic — the mechanism, not just the intent

Added 2026-08-21 (FH-2.1). The invariants above say reservations exist; they do not say how two buyers racing for the last unit are separated. Specify the mechanism, because "check availability, then reserve" is a read-then-write race and will oversell under load no matter how the code above it is written.

Reserve with a single conditional write that both tests and updates:

```sql
UPDATE inventory
SET reserved = reserved + :qty
WHERE offer_id = :offerId
  AND (available - reserved) >= :qty
RETURNING id
```

- **Zero rows returned means insufficient stock.** Respond `409` with the offending offer, do not retry, do not partially reserve. A multi-line cart reserves every line inside one transaction; any line returning zero rows rolls back all of them.
- No `SELECT` before the `UPDATE`. No advisory lock. No application-level retry loop. The `WHERE` clause is the concurrency control.
- Reservation TTL is 15 minutes from checkout-session creation. Expiry releases `reserved` back to `available` and writes a journal row (§3.2).
- The same rule governs release and consumption: one conditional statement, never read-modify-write.

**Acceptance:** two concurrent checkouts for the last unit produce exactly one payable order and one clean `409`. This is scenario 3 of the acceptance list in [FORK-HARVEST-TODO.md](../FORK-HARVEST-TODO.md) and is a required e2e test, not a code-review item.

### 3.2 Inventory movements are an append-only journal

Added 2026-08-21 (FH-2.8). Every change to `available`/`reserved`/`sold` writes one immutable row:

```ts
interface InventoryMovement {
  id: string;
  offerId: string;
  deltaAvailable: number;
  deltaReserved: number;
  deltaSold: number;
  reason: 'checkout_reservation' | 'reservation_expired' | 'reservation_released'
        | 'payment_confirmed' | 'manual_adjustment' | 'feed_sync' | 'connector_sync'
        | 'refund_restock' | 'oversell_correction';
  referenceType?: 'reservation' | 'order' | 'import' | 'connector';
  referenceId?: string;
  actor?: string;            // user id for manual adjustments, null for system
  resultingAvailable: number; // balance after this movement, not recomputed later
  occurredAt: string;
}
```

Rules:
- Rows are never updated or deleted. A correction is a new compensating row.
- `resultingAvailable` is written at the time of the movement. Replaying the journal must reproduce the current record exactly; a divergence is a defect to investigate, not a number to overwrite.
- A manual adjustment without an `actor` is rejected.

**Why this is in the contract rather than left to implementation.** Product Plan v3.1 §10.2 opens with the complaint that our numbers cannot be explained. A quantity you cannot reconstruct is a quantity you cannot defend to a bank, an inspector, or a seller disputing a payout. This journal is what turns "the stock says 3" into "the stock says 3, and here is every movement that made it 3."

## 4. Lifecycle

```
draft -> moderation -> published -> paused/archived
```

Applies independently to both `Product` and `Offer`. Wires to the already-existing (mock) Admin Moderation module — no new frontend module needed, just a real gateway behind `ADMIN_MODERATION_GATEWAY` (token already added this session).

## 5. Publish-time executability

**An offer that cannot actually be fulfilled must not be publishable.** Before allowing `status: 'published'`, the backend validates:
- The offer has a valid `Fulfillment` type it can realistically satisfy (see [Phase 2 contract](PHASE-2-ORDERS-NOTIFICATIONS-CONTRACT.md) `Fulfillment.type`).
- Stock policy is `track` with `available > 0`, or `no_track`/`preorder` explicitly.
- Required attributes for the offer's category (`Category.attributesSchema`) are present.

This is the mechanism behind the plan's §3.6/§10.2 requirement: **no branch anywhere may distinguish a normal buyer from an inspector.** The only way to guarantee that is to make every published offer genuinely executable at publish time, not to special-case checkout behavior later.

## 6. Bulk import

```
POST /api/admin/v2/products/bulk-import
Content-Type: multipart/form-data (CSV) or application/json (array)
```

Response returns a **preview** of validation errors before anything is applied — required-field validation, category-attribute validation, duplicate-SKU detection — with a separate `POST .../bulk-import/{importId}/apply` to commit after review.

Added 2026-08-21 (FH-2.15): the import is idempotent by SKU/external key, so re-running the same file updates rather than duplicating. A row-level error never publishes a partial result. An applied import can be rolled back **as long as none of its products have appeared on a paid order** — after that, archive rather than delete.

## 6a. Digital fulfilment — code pools

Added 2026-08-21 (FH-2.11). We have no digital-goods story today, and it is one table.

```ts
type FulfillmentMode = 'manual' | 'code_pool';

interface DigitalCode {
  id: string;
  marketplaceId: string;
  offerId: string;
  encryptedValue: string;                       // see Track S §4.2 envelope
  valueHash: string;                            // unique per (marketplaceId, offerId)
  status: 'available' | 'reserved' | 'assigned' | 'revoked';
  orderLineId?: string;
  createdAt: string;
  assignedAt?: string;
}
```

Rules:
- `FulfillmentMode` is a property of the offer. `code_pool` offers derive `available` from the count of `available` codes — the two must not be maintained independently.
- `valueHash` is unique per `(marketplaceId, offerId)`, so importing the same code twice is refused by the database rather than by a check somebody can forget.
- A code moves `available → reserved` under the same conditional-write rule as §3.1, and `reserved → assigned` only on confirmed payment.
- **A code is returned to the browser only when the order is `paid`, `processing`, or `fulfilled`.** Any earlier state returns the line with an empty code list — not a masked value, not a placeholder.
- Revocation is terminal and audited (Track S §3).

**Acceptance:** an unpaid order never yields a code, through the UI or through a direct API call with a valid session.

## 7. Endpoints

```
GET    /api/admin/v2/products?marketplaceId=&status=&search=&page=&pageSize=
GET    /api/admin/v2/products/{id}
POST   /api/admin/v2/products
PATCH  /api/admin/v2/products/{id}
GET    /api/admin/v2/offers?productId=&sellerId=&status=
POST   /api/admin/v2/offers
PATCH  /api/admin/v2/offers/{id}
POST   /api/admin/v2/offers/{id}/publish   -> runs §5 executability check, 422 with details[] on failure
GET    /api/admin/v2/offers/lookup?sku=&sellerSku=&externalId=   -- "find any offer by internal SKU, seller SKU, product ID, or external mapping" per plan §2.1
```

Replaces `AdminProductsLocalGateway` behind `ADMIN_PRODUCTS_GATEWAY` (token already wired this session).

## 8. What the frontend will start doing once this ships

- Unify the admin mock product domain with the live storefront `Item` domain — currently two unrelated shapes.
- Multi-seller product page: same product card, multiple offers/sellers/prices — undefined behaviour today.
- Wire the Moderation module to real lifecycle transitions instead of mock data.