marketplaces/docs/backend/PHASE-2-ORDERS-NOTIFICATIONS-CONTRACT.md

Phase 2 Backend Contract — Canonical Orders, Event Bus, Notification Center

Companion to PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md Phase 2 (Sprints 2.1–2.2). Depends on Phase 1 (Money/PriceSnapshot/PaymentIntent) being implemented first — an Order line references a priceSnapshotId from that contract.

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

---

1. Why this exists

Today AdminOrdersLocalGateway is a static 24-row in-memory seed with no create path — a real order can never appear. AdminOrderWatcherService already polls for new orders to toast/badge the admin, but is functionally inert against the mock. This contract makes both real.

2. Multi-seller model — Sprint 0.1 decision: unified

One Order per checkout, regardless of how many sellers are represented. Lines are grouped into per-seller Fulfillment entries internally. There is no parent/child order splitting, no separate order-per-seller. A seller only ever sees their own Fulfillment group within a shared order (see Phase 5 contract for the seller-scoped view).

3. Entities

interface Order {
  id: string;
  marketplaceId: string;
  source: 'storefront' | 'external' | 'backoffice' | 'api_partner';
  externalOrderRef?: string;       // set when source === 'external', see Phase 4
  customerId?: string;
  currency: string;
  subtotal: Money;
  discount: Money;
  delivery: Money;
  total: Money;
  paymentStatus: 'pending_payment' | 'paid' | 'failed' | 'refunded' | 'partially_refunded';
  orderStatus: 'pending_payment' | 'paid' | 'processing' | 'fulfilled' | 'completed' | 'cancelled';
  createdAt: string;
  paidAt?: string;
}

interface OrderLine {
  id: string;
  orderId: string;
  offerId: string;                 // see Phase 3 contract
  sellerId: string;
  skuSnapshot: string;
  titleSnapshot: string;
  qty: number;
  unitPrice: Money;
  lineTotal: Money;
  priceSnapshotId: string;         // references Phase 1's PriceSnapshot
}

interface Fulfillment {
  id: string;
  orderId: string;
  sellerId: string;                // the seller-scoping unit for the unified-order model
  type: 'manual' | 'warehouse' | 'pickup' | 'digital';
  status: 'pending' | 'assigned' | 'in_progress' | 'issued' | 'shipped' | 'cancelled';
  assignedTo?: string;
  issuedAt?: string;
  shippedAt?: string;
  evidence?: { type: string; url: string }[]; // e.g. shipment proof, digital delivery receipt
}

interface OrderEvent {
  id: string;
  orderId: string;
  type: 'created' | 'paid' | 'seller_notified' | 'accepted' | 'fulfilled' | 'cancelled' | 'refunded';
  actor?: string;                  // user/system id, null for automated system events
  occurredAt: string;
  metadata?: Record<string, unknown>;
}

interface OrderContactSnapshot {
  orderId: string;
  name: string;
  email?: string;
  phone?: string;
  preferredChannel?: 'telegram' | 'vk' | 'max' | 'email' | 'sms';
  capturedAt: string; // immutable after order creation, independent of later Customer profile edits
}

3.1 Public addressing and snapshot completeness

Added 2026-08-21 (FH-2.13).

• Order carries a publicToken: at least 24 random bytes, base64url, unique. Every customer-facing route addresses an order by this token, never by id. Order confirmation links, status polling, and support lookups all use it. A sequential or guessable public identifier turns "check my order" into an enumeration of the tenant's order book.
• GET /api/v2/storefront/orders/{publicToken} is scoped to the resolved tenant. A valid token from a different marketplace is 404.
• OrderLine already snapshots SKU, title and price. Extend that to everything that must survive a later edit: currency, per-line discount, delivery option and price, and the tax/fee components. Together with OrderContactSnapshot, an order must be fully reconstructable from its own rows — renaming an offer, changing a price, or deleting a delivery option must not alter what a historical order says was bought and charged.
• Snapshot fields are written once at order creation and never updated. A correction is a new order event, a refund, or an amendment record — never an in-place rewrite of what the customer agreed to.

4. Endpoints

GET    /api/admin/v2/orders?marketplaceId=&status=&source=&page=&pageSize=
GET    /api/admin/v2/orders/{id}
PATCH  /api/admin/v2/orders/{id}/status         { status }
POST   /api/admin/v2/orders/{id}/refund-request { reason }
POST   /api/admin/v2/orders/{id}/notes          { note, internal: boolean }
POST   /api/admin/v2/orders/{id}/archive
POST   /api/admin/v2/orders/{id}/restore
DELETE /api/admin/v2/orders/{id}

GET    /api/seller/v1/orders?fulfillmentStatus=&page=&pageSize=
  -> returns Order + only the Fulfillment groups belonging to the authenticated seller,
     OrderLines filtered to that seller's lines. Never the full order's other-seller lines.

Replaces AdminOrdersLocalGateway behind the ADMIN_ORDERS_GATEWAY token already wired this session (see BACKEND-API-REFERENCE.md §8) — no facade change needed, only binding a real AdminOrdersApiGateway.

5. Event bus

type PlatformEvent =
  | { type: 'order.created'; orderId: string; marketplaceId: string }
  | { type: 'order.paid'; orderId: string; marketplaceId: string }
  | { type: 'payment.failed'; orderId: string; reason: string }
  | { type: 'webhook.error'; source: string; traceId: string }
  | { type: 'stock.low'; offerId: string; available: number }
  | { type: 'oversell'; offerId: string; requested: number; available: number }
  | { type: 'refund.requested'; orderId: string; refundId: string }
  | { type: 'refund.completed'; orderId: string; refundId: string }
  | { type: 'external_order.imported'; orderId: string; connectorId: string };

Backend owns the bus implementation (queue, pub/sub, whatever fits existing infra). Frontend's only contract: the Notification entity below, and the requirement that order.paid always produces a backoffice notification even if every external channel is down (see Phase 8 §5 for the messenger-side orchestration).

6. Notification Center

interface Notification {
  id: string;
  marketplaceId: string;
  entityType: 'order' | 'payment' | 'offer' | 'connector' | 'refund';
  entityId: string;
  severity: 'info' | 'warning' | 'critical';
  eventType: PlatformEvent['type'];
  read: boolean;
  deepLink: string;     // e.g. /admin/orders/{id}
  createdAt: string;
}

interface DeliveryAttempt {
  notificationId: string;
  channel: 'telegram' | 'email' | 'sms' | 'vk' | 'max';
  status: 'sent' | 'failed';
  error?: string;
  attemptedAt: string;
}

GET   /api/admin/v2/notifications?marketplaceId=&unreadOnly=&eventType=
PATCH /api/admin/v2/notifications/{id}/read

Invariant: a DeliveryAttempt failure on an external channel never prevents the Notification row itself from being created and visible in the backoffice unread queue.

7. What the frontend will start doing once this ships

• Repoint AdminOrderWatcherService from polling AdminOrdersLocalGateway to the event stream / GET /api/admin/v2/notifications?unreadOnly=true.
• Build the backoffice Notifications section (unread queue, severity, marketplace/event-type filter) — currently missing from admin nav entirely.
• Wire admin order actions (assign, resend notification, replay sync, cancel/refund, comment, export) to the endpoints in §4.