Initial commit: nick docs

02 - Data Models/SellerOffer.md

@@ -0,0 +1,96 @@
+---
+title: SellerOffer
+tags: [data-model, mongoose]
+aliases: [Seller Offer, Bid, ISellerOffer]
+---
+
+# SellerOffer
+
+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` — schema definition
+> `backend/src/models/SellerOffer.ts:100` — model export
+
+## Schema
+
+| 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` / `USDT` / `USDC` | — | Quote currency. |
+| `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` | yes | Offer status. |
+| `attachments[]` | String[] | no | — | — | — | URLs of supporting files. |
+| `notes` | String | no | — | trim | — | Internal/private notes. |
+| `validUntil` | Date | no | — | — | — | Expiration. |
+| `createdAt` | Date | auto | — | — | yes (desc) | Mongoose timestamp. |
+| `updatedAt` | Date | auto | — | — | — | Mongoose timestamp. |
+
+## Virtuals
+
+None defined.
+
+## Indexes
+
+Defined at `backend/src/models/SellerOffer.ts:95-98`:
+
+- `{ sellerId: 1 }`
+- `{ purchaseRequestId: 1 }`
+- `{ status: 1 }`
+- `{ createdAt: -1 }`
+
+## Pre/Post Hooks
+
+None declared.
+
+## Instance Methods
+
+None defined.
+
+## Static Methods
+
+None defined.
+
+## Relationships
+
+- **References**: [[User]] (`sellerId`), [[PurchaseRequest]] (`purchaseRequestId`).
+- **Referenced by**: [[PurchaseRequest]] (`offers[]`, `selectedOfferId`), [[Payment]] (`sellerOfferId`), [[Chat]] (`relatedTo.id` when `relatedTo.type === 'SellerOffer'`).
+
+## State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> pending
+    pending --> accepted : buyer accepts
+    pending --> rejected : buyer rejects
+    pending --> withdrawn : seller cancels
+    accepted --> [*]
+    rejected --> [*]
+    withdrawn --> [*]
+```
+
+## Common Queries
+
+```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' });
+```
+
+Related: [[PurchaseRequest]], [[Payment]], [[User]].