Initial commit: nick docs

02 - Data Models/User.md

@@ -0,0 +1,137 @@
+---
+title: User
+tags: [data-model, mongoose]
+aliases: [User Model, IUser, Account]
+---
+
+# User
+
+The core identity document for every actor in the marketplace: buyers, sellers, and admins. Stores credentials (password + WebAuthn passkeys), profile/preference data, referral bookkeeping, point balances, and a soft-delete status flag. Almost every other model carries an `ObjectId` reference back to `User`, so this collection is the relational hub of the system.
+
+> [!note] Source
+> `backend/src/models/User.ts:70` — schema definition
+> `backend/src/models/User.ts:257` — model export
+
+## Schema
+
+| Field | Type | Required | Default | Validation | Index | Description |
+| --- | --- | --- | --- | --- | --- | --- |
+| `email` | String | yes | — | lowercase, trim | unique | Primary login identifier. |
+| `password` | String | no | — | minlength 6 | — | Hashed password. Optional to support passkey-only accounts. |
+| `firstName` | String | no | `"کاربر"` | trim | — | Persian default ("user"). |
+| `lastName` | String | no | `"جدید"` | trim | — | Persian default ("new"). |
+| `role` | String | yes | `"buyer"` | enum: `admin` / `buyer` / `seller` | yes | Authorisation tier. |
+| `isEmailVerified` | Boolean | no | `false` | — | — | Set to true after [[TempVerification]] is consumed. |
+| `emailVerificationToken` | String | no | — | — | — | Legacy token-based email verification. |
+| `emailVerificationCode` | String | no | — | — | — | OTP code for email verification. |
+| `emailVerificationCodeExpires` | Date | no | — | — | — | Expiry for `emailVerificationCode`. |
+| `passwordResetToken` | String | no | — | — | — | Token for reset link flow. |
+| `passwordResetExpires` | Date | no | — | — | — | Expiry of `passwordResetToken`. |
+| `passwordResetCode` | String | no | — | — | — | OTP reset code. |
+| `passwordResetCodeExpires` | Date | no | — | — | — | Expiry for OTP reset code. |
+| `passkeys[]` | Subdocument array | no | `[]` | — | — | WebAuthn credentials (see below). |
+| `passkeys[].id` | String | yes | — | — | — | Credential ID. |
+| `passkeys[].publicKey` | String | yes | — | — | — | Stored public key. |
+| `passkeys[].counter` | Number | yes | `0` | — | — | Signature counter. |
+| `passkeys[].deviceType` | String | yes | — | enum: `platform` / `cross-platform` | — | Authenticator class. |
+| `passkeys[].deviceName` | String | no | — | — | — | Optional human label. |
+| `passkeys[].createdAt` | Date | no | `Date.now` | — | — | Registration timestamp. |
+| `profile.avatar` | String | no | — | — | — | Avatar URL. |
+| `profile.photoURL` | String | no | — | — | — | Alternative photo URL. |
+| `profile.phone` | String | no | — | — | — | Contact phone. |
+| `profile.address.street` | String | no | — | — | — | Inline address (separate from [[Address]] book). |
+| `profile.address.city` | String | no | — | — | — | — |
+| `profile.address.state` | String | no | — | — | — | — |
+| `profile.address.zipCode` | String | no | — | — | — | — |
+| `profile.address.country` | String | no | — | — | — | — |
+| `profile.bio` | String | no | — | — | — | Free-form bio. |
+| `profile.website` | String | no | — | — | — | Personal website URL. |
+| `profile.walletAddress` | String | no | — | — | — | On-chain wallet address. |
+| `profile.isPublic` | Boolean | no | `false` | — | — | Whether the profile is publicly visible. |
+| `preferences.language` | String | no | `"en"` | — | — | UI language. |
+| `preferences.currency` | String | no | `"USD"` | — | — | Display currency. |
+| `preferences.notifications.email` | Boolean | no | `true` | — | — | Opt-in for email notifications. |
+| `preferences.notifications.sms` | Boolean | no | `false` | — | — | Opt-in for SMS notifications. |
+| `preferences.notifications.push` | Boolean | no | `true` | — | — | Opt-in for push notifications. |
+| `status` | String | no | `"active"` | enum: `active` / `suspended` / `deleted` | yes | Soft-delete and moderation flag. |
+| `lastLoginAt` | Date | no | — | — | — | Updated by auth middleware. |
+| `refreshTokens[]` | String[] | no | `[]` | — | — | Outstanding JWT refresh tokens. |
+| `referralCode` | String | no | — | — | unique, sparse | Personal invite code. |
+| `referredBy` | ObjectId → User | no | — | — | yes | Who invited this user. |
+| `points.total` | Number | no | `0` | — | — | Lifetime points earned. |
+| `points.available` | Number | no | `0` | — | — | Currently spendable. |
+| `points.used` | Number | no | `0` | — | — | Cumulative spent. |
+| `points.level` | Number | no | `1` | — | yes (`points.level`) | Resolved against [[LevelConfig]]. |
+| `referralStats.totalReferrals` | Number | no | `0` | — | — | Count of invited users. |
+| `referralStats.activeReferrals` | Number | no | `0` | — | — | Subset that became active buyers. |
+| `referralStats.totalEarned` | Number | no | `0` | — | — | Cumulative reward earnings. |
+| `createdAt` | Date | auto | — | — | — | Mongoose timestamp. |
+| `updatedAt` | Date | auto | — | — | — | Mongoose timestamp. |
+
+## Virtuals
+
+| Virtual | Returns | Definition |
+| --- | --- | --- |
+| `fullName` | `${firstName} ${lastName}` | `backend/src/models/User.ts:238` |
+
+## Indexes
+
+Defined explicitly (in addition to the implicit `email` unique index):
+
+- `{ role: 1 }` — `backend/src/models/User.ts:231`
+- `{ status: 1 }` — `backend/src/models/User.ts:232`
+- `{ referralCode: 1 }` — `backend/src/models/User.ts:233`
+- `{ referredBy: 1 }` — `backend/src/models/User.ts:234`
+- `{ 'points.level': 1 }` — `backend/src/models/User.ts:235`
+
+## Pre/Post Hooks
+
+None declared at the schema level.
+
+## Instance Methods
+
+| Signature | Purpose |
+| --- | --- |
+| `toJSON(): object` | Strips `password`, `refreshTokens`, all `emailVerification*` and `passwordReset*` fields before serialisation. Defined at `backend/src/models/User.ts:243`. |
+
+## Static Methods
+
+None defined on the schema.
+
+## Relationships
+
+- **References**: [[User]] (self, via `referredBy`).
+- **Referenced by**: [[PurchaseRequest]] (`buyerId`, `preferredSellerIds`, `deliveryInfo.deliveryCodeUsedBy`, `deliveryInfo.deliveryAttempts[].sellerId`), [[SellerOffer]] (`sellerId`), [[Payment]] (`buyerId`, `sellerId`), [[Chat]] (`participants[].userId`, `messages[].senderId`, `metadata.createdBy`), [[Notification]] (`userId` as string), [[RequestTemplate]] (`sellerId`), [[Dispute]] (`buyerId`, `sellerId`, `adminId`), [[BlogPost]] (`author.id`), [[Address]] (`userId`), [[Review]] (`sellerId`, `reviewerId`), [[PointTransaction]] (`user`, `referredUser`), [[ShopSettings]] (`sellerId`).
+
+## State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> active : signup verified
+    active --> suspended : admin action
+    suspended --> active : admin restore
+    active --> deleted : self-delete
+    suspended --> deleted : admin purge
+    deleted --> [*]
+```
+
+## Common Queries
+
+```ts
+// Find by email (login)
+User.findOne({ email: email.toLowerCase() });
+
+// Active sellers
+User.find({ role: 'seller', status: 'active' });
+
+// Validate referral
+User.findOne({ referralCode: code });
+
+// Leaderboard by points
+User.find({ status: 'active' }).sort({ 'points.total': -1 }).limit(10);
+
+// Promote level
+User.updateOne({ _id: id }, { $set: { 'points.level': newLevel } });
+```
+
+Related: [[TempVerification]], [[LevelConfig]], [[PointTransaction]], [[ShopSettings]].