Initial commit: nick docs

02 - Data Models/LevelConfig.md

@@ -0,0 +1,90 @@
+---
+title: LevelConfig
+tags: [data-model, mongoose]
+aliases: [Level, Loyalty Tier, ILevelConfig]
+---
+
+# LevelConfig
+
+Admin-managed configuration of loyalty tiers. Each row defines one level (`level`, `name`, `nameEn`, point window via `minPoints` / `maxPoints`), the perks unlocked (`benefits.*`), and presentation details (`icon`, `color`, `order`). The `User.points.level` field is resolved against this collection.
+
+> [!note] Source
+> `backend/src/models/LevelConfig.ts:24` — schema definition
+> `backend/src/models/LevelConfig.ts:93` — model export
+
+## Schema
+
+| Field | Type | Required | Default | Validation | Index | Description |
+| --- | --- | --- | --- | --- | --- | --- |
+| `level` | Number | yes | — | — | unique | Numeric level (1, 2, 3, ...). |
+| `name` | String | yes | — | — | — | Local language name. |
+| `nameEn` | String | yes | — | — | — | English name. |
+| `minPoints` | Number | yes | `0` | — | yes | Inclusive lower bound. |
+| `maxPoints` | Number | no | — | — | — | Inclusive upper bound (open if omitted). |
+| `benefits.discountPercent` | Number | no | `0` | — | — | Percentage discount unlocked. |
+| `benefits.freeShipping` | Boolean | no | `false` | — | — | Free shipping perk. |
+| `benefits.prioritySupport` | Boolean | no | `false` | — | — | Priority support perk. |
+| `benefits.specialOffers` | Boolean | no | `false` | — | — | Exclusive offers perk. |
+| `icon` | String | no | `solar:medal-star-bold` | — | — | Icon identifier. |
+| `color` | String | no | `#94a3b8` | — | — | Display color. |
+| `order` | Number | yes | — | — | yes | Display order. |
+| `isActive` | Boolean | no | `true` | — | yes | Active flag. |
+| `createdAt` | Date | auto | — | — | — | Mongoose timestamp. |
+| `updatedAt` | Date | auto | — | — | — | Mongoose timestamp. |
+
+## Virtuals
+
+None defined.
+
+## Indexes
+
+Defined at `backend/src/models/LevelConfig.ts:89-91`. Plus the implicit unique index on `level`:
+
+- `{ minPoints: 1 }`
+- `{ order: 1 }`
+- `{ isActive: 1 }`
+
+## Pre/Post Hooks
+
+None declared.
+
+## Instance Methods
+
+None defined.
+
+## Static Methods
+
+None defined.
+
+## Relationships
+
+- **References**: none.
+- **Referenced by**: indirectly by [[User]] (`points.level`) and [[PointTransaction]] (`metadata.levelBefore` / `metadata.levelAfter`).
+
+## State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> active
+    active --> inactive : admin disables
+    inactive --> active : admin re-enables
+```
+
+## Common Queries
+
+```ts
+// All active levels (ordered)
+LevelConfig.find({ isActive: true }).sort({ order: 1 });
+
+// Resolve a point total to a level
+LevelConfig.findOne({
+  isActive: true,
+  minPoints: { $lte: points },
+  $or: [{ maxPoints: { $gte: points } }, { maxPoints: { $exists: false } }],
+}).sort({ minPoints: -1 });
+
+// Fetch by level number
+LevelConfig.findOne({ level });
+```
+
+Related: [[User]], [[PointTransaction]].