docs: sync from backend 8fc2309 — M43/M44 missing FKs + H37 dispute enums
This commit is contained in:
Siavash Sameni
@@ -1,58 +1,29 @@
|
||||
---
|
||||
title: SellerOffer
|
||||
tags: [data-model, mongoose, postgres]
|
||||
tags: [data-model, postgres]
|
||||
aliases: [Seller Offer, Bid, ISellerOffer]
|
||||
---
|
||||
|
||||
# SellerOffer
|
||||
|
||||
> **Last updated:** 2026-06-03 — added Postgres/Drizzle table definition and migration status.
|
||||
> **Last updated:** 2026-06-06 — MongoDB/Mongoose fully removed; PostgreSQL + Drizzle is now the only database layer.
|
||||
|
||||
A seller's bid against a [[PurchaseRequest]]. Stores the proposed price, the delivery time commitment, optional notes/attachments, and a small status machine (`pending` / `accepted` / `rejected` / `withdrawn`). The parent `PurchaseRequest` keeps the array of offer ids in `offers[]` and the chosen one in `selectedOfferId`.
|
||||
|
||||
> [!note] Source
|
||||
> `backend/src/models/SellerOffer.ts:24` — Mongoose schema definition
|
||||
> `backend/src/models/SellerOffer.ts:100` — Mongoose model export
|
||||
> `backend/src/db/schema/sellerOffer.ts` — Drizzle/Postgres table definition
|
||||
|
||||
## Migration Status
|
||||
|
||||
**DUAL-WRITE** — part of `DualWriteMarketplaceRepo`. Writes go to both MongoDB and Postgres; reads still come from MongoDB.
|
||||
> `backend/src/db/schema/sellerOffer.ts` — PostgreSQL schema (Drizzle) definition
|
||||
|
||||
## Schema
|
||||
|
||||
### Mongoose (MongoDB)
|
||||
|
||||
| Field | Type | Required | Default | Validation | Index | Description |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| `sellerId` | ObjectId → [[User]] | yes | — | — | yes | Seller submitting the bid. |
|
||||
| `purchaseRequestId` | ObjectId → [[PurchaseRequest]] | yes | — | — | yes | Parent request. |
|
||||
| `title` | String | yes | — | trim, maxlength 200 | — | Offer headline. |
|
||||
| `description` | String | yes | — | trim, maxlength 1000 | — | Pitch and details. |
|
||||
| `price.amount` | Number | yes | — | min 0 | — | Quoted amount. |
|
||||
| `price.currency` | String | yes | `USDT` | enum: `USD` / `EUR` / `IRR` / `TRY` / `USDT` / `USDC` | — | Quote currency. `TRY` is supported by the oracle/depeg path through the off-chain FX provider. |
|
||||
| `deliveryTime.amount` | Number | yes | — | min 1 | — | Numeric ETA. |
|
||||
| `deliveryTime.unit` | String | yes | — | enum: `hours` / `days` / `weeks` | — | ETA unit. |
|
||||
| `status` | String | no | `pending` | enum: `pending` / `accepted` / `rejected` / `withdrawn` / `active` | yes | Offer status. |
|
||||
| `attachments[]` | String[] | no | — | — | — | URLs of supporting files. |
|
||||
| `notes` | String | no | — | trim | — | Internal/private notes. |
|
||||
| `validUntil` | Date | no | — | — | — | Expiration. |
|
||||
| `requireAmlCheck` | Boolean | no | — | — | — | If true, AML screening must pass before the offer is presented to the buyer. |
|
||||
| `amlBlockOnFailure` | Boolean | no | — | — | — | If true and AML screening fails, the offer is blocked. Otherwise it is flagged for manual review. |
|
||||
| `createdAt` | Date | auto | — | — | yes (desc) | Mongoose timestamp. |
|
||||
| `updatedAt` | Date | auto | — | — | — | Mongoose timestamp. |
|
||||
|
||||
> **Status enum note:** `active` is accepted by the current backend schema for marketplace/listing flows, in addition to the negotiation statuses `pending | accepted | rejected | withdrawn`.
|
||||
|
||||
### Postgres (Drizzle) — `seller_offers`
|
||||
### PostgreSQL schema (Drizzle) — `seller_offers`
|
||||
|
||||
Table: `seller_offers` | Schema file: `backend/src/db/schema/sellerOffer.ts`
|
||||
|
||||
| PG Column | Drizzle Type | Nullable | Default | Notes |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `id` | `uuid` PK | no | `gen_random_uuid()` | PG primary key |
|
||||
| `legacy_object_id` | `text` | yes | — | Mongo ObjectId bridge; partial-unique WHERE NOT NULL |
|
||||
| `seller_id` | `uuid` FK → `users` CASCADE | no | — | Maps from `sellerId` |
|
||||
| `id` | `uuid` PK | no | `gen_random_uuid()` | Primary key (UUID string) |
|
||||
| `legacy_object_id` | `text` | yes | — | Former Mongo ObjectId; partial-unique WHERE NOT NULL |
|
||||
| `seller_id` | `uuid` FK → `users` CASCADE | no | — | Maps from `sellerId` (uses user.pgId) |
|
||||
| `purchase_request_id` | `uuid` FK → `purchase_requests` CASCADE | no | — | Maps from `purchaseRequestId` |
|
||||
| `title` | `varchar(200)` | no | — | |
|
||||
| `description` | `varchar(1000)` | no | — | |
|
||||
@@ -84,6 +55,8 @@ Table: `seller_offers` | Schema file: `backend/src/db/schema/sellerOffer.ts`
|
||||
|
||||
**Money precision note:** `price_amount` uses `numeric(18,8)` — differs from the `numeric(38,18)` used by `payments` and `funds_ledger_entries`. This matches the Migration Guide specification for offer amounts.
|
||||
|
||||
**ID note:** The primary key is `id` (UUID string), not `_id`. `legacy_object_id` retains the former MongoDB ObjectId for backfill/bridging purposes only and is not used by any runtime query.
|
||||
|
||||
#### Postgres Indexes
|
||||
|
||||
| Index | Type | Notes |
|
||||
@@ -95,22 +68,43 @@ Table: `seller_offers` | Schema file: `backend/src/db/schema/sellerOffer.ts`
|
||||
| `(purchase_request_id, seller_id)` | btree | composite |
|
||||
| `legacy_object_id` | partial-unique | WHERE NOT NULL; idempotent backfill upserts |
|
||||
|
||||
## Domain Fields (TypeScript)
|
||||
|
||||
| Field | Type | Required | Default | Notes |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `id` | `string` (UUID) | yes | auto | PG primary key; replaces former `_id` ObjectId |
|
||||
| `sellerId` | `string` (UUID) | yes | — | user.pgId of the submitting seller |
|
||||
| `purchaseRequestId` | `string` (UUID) | yes | — | Parent request |
|
||||
| `title` | `string` | yes | — | Offer headline (max 200) |
|
||||
| `description` | `string` | yes | — | Pitch and details (max 1000) |
|
||||
| `price.amount` | `number` | yes | — | Quoted amount (min 0) |
|
||||
| `price.currency` | `string` | yes | `USDT` | `USD` / `EUR` / `IRR` / `TRY` / `USDT` / `USDC` |
|
||||
| `deliveryTime.amount` | `number` | yes | — | Numeric ETA (min 1) |
|
||||
| `deliveryTime.unit` | `string` | yes | — | `hours` / `days` / `weeks` |
|
||||
| `status` | `string` | no | `pending` | `pending` / `accepted` / `rejected` / `withdrawn` / `active` |
|
||||
| `attachments[]` | `string[]` | no | — | URLs of supporting files |
|
||||
| `notes` | `string` | no | — | Internal/private notes |
|
||||
| `validUntil` | `Date` | no | — | Expiration |
|
||||
| `requireAmlCheck` | `boolean` | no | — | AML screening required before presenting to buyer |
|
||||
| `amlBlockOnFailure` | `boolean` | no | — | Block offer on AML failure (vs. flag for review) |
|
||||
| `createdAt` | `Date` | auto | — | |
|
||||
| `updatedAt` | `Date` | auto | — | |
|
||||
|
||||
> **Status enum note:** `active` is accepted by the current backend schema for marketplace/listing flows, in addition to the negotiation statuses `pending | accepted | rejected | withdrawn`.
|
||||
|
||||
> **Currency note:** `TRY` is supported by the oracle/depeg path through the off-chain FX provider.
|
||||
|
||||
## UpdateSellerOfferInput
|
||||
|
||||
`UpdateSellerOfferInput` does **not** include an `updatedAt` field — the column is managed automatically by the database (`now()` default; updated by the repo layer on write).
|
||||
|
||||
## Virtuals
|
||||
|
||||
None defined.
|
||||
|
||||
## Mongoose Indexes
|
||||
|
||||
Defined at `backend/src/models/SellerOffer.ts:95-98`:
|
||||
|
||||
- `{ sellerId: 1 }`
|
||||
- `{ purchaseRequestId: 1 }`
|
||||
- `{ status: 1 }`
|
||||
- `{ createdAt: -1 }`
|
||||
|
||||
## Pre/Post Hooks
|
||||
|
||||
None declared.
|
||||
None declared (Drizzle ORM does not use Mongoose-style lifecycle hooks).
|
||||
|
||||
## Instance Methods
|
||||
|
||||
@@ -136,7 +130,7 @@ The frontend exposes this via the `withdrawOffer(offerId)` action in `src/action
|
||||
|
||||
## Relationships
|
||||
|
||||
- **References**: [[User]] (`sellerId`), [[PurchaseRequest]] (`purchaseRequestId`).
|
||||
- **References**: [[User]] (`sellerId` = user.pgId), [[PurchaseRequest]] (`purchaseRequestId`).
|
||||
- **Referenced by**: [[PurchaseRequest]] (`offers[]`, `selectedOfferId`), [[Payment]] (`sellerOfferId`), [[Chat]] (`relatedTo.id` when `relatedTo.type === 'SellerOffer'`).
|
||||
- **PG FKs**: `seller_offers.seller_id → users.id CASCADE`, `seller_offers.purchase_request_id → purchase_requests.id CASCADE`.
|
||||
- **Referenced by (PG)**: `payments.seller_offer_id` (polymorphic triple), `payment_quotes` (via payment join).
|
||||
@@ -156,25 +150,6 @@ stateDiagram-v2
|
||||
|
||||
## Common Queries
|
||||
|
||||
### MongoDB
|
||||
|
||||
```ts
|
||||
// Offers for a request
|
||||
SellerOffer.find({ purchaseRequestId }).sort({ createdAt: -1 });
|
||||
|
||||
// Seller's active offers
|
||||
SellerOffer.find({ sellerId, status: 'pending' });
|
||||
|
||||
// Reject siblings on accept
|
||||
SellerOffer.updateMany(
|
||||
{ purchaseRequestId, _id: { $ne: acceptedId }, status: 'pending' },
|
||||
{ status: 'rejected' }
|
||||
);
|
||||
|
||||
// Cleanup expired offers
|
||||
SellerOffer.find({ validUntil: { $lt: new Date() }, status: 'pending' });
|
||||
```
|
||||
|
||||
### Postgres (Drizzle)
|
||||
|
||||
```ts
|
||||
|
||||
Reference in New Issue
Block a user