feat: implement tiered loyalty & rewards program engine #283

src/app.module.ts

@@ -56,6 +56,8 @@ import { ProductImage } from './media/entities/image.entity';
 import { Coupon } from './coupons/entities/coupon.entity';
 import { CouponUsage } from './coupons/entities/coupon-usage.entity';
 import { RewardPoints } from './rewards/entities/reward-points.entity';
+import { LoyaltyTier } from './rewards/entities/loyalty-tier.entity';
+import { UserLoyaltyTier } from './rewards/entities/user-loyalty-tier.entity';
 
 // ── Guards & Middleware ─────────────────────────────────────────────────────
 import { AdminGuard } from './guards/admin.guard';
@@ -99,7 +101,7 @@ import { CorrelationIdMiddleware } from './common/middleware/correlation-id.midd
       migrations: ['dist/migrations/*.js'],
       migrationsRun: false,
     }),
-    TypeOrmModule.forFeature([ProductImage, Coupon, CouponUsage, RewardPoints]),
+    TypeOrmModule.forFeature([ProductImage, Coupon, CouponUsage, RewardPoints, LoyaltyTier, UserLoyaltyTier]),
 
     // ── Queue ─────────────────────────────────────────────────────────────
     BullModule.forRoot({

src/rewards/dto/loyalty-tier.dto.ts

@@ -0,0 +1,149 @@
+import { IsEnum, IsNotEmpty, IsOptional, IsString, IsNumber, IsBoolean, Min, Max, ValidateNested, IsObject } from 'class-validator';
+import { Type } from 'class-transformer';
+import { LoyaltyTierName } from '../entities/loyalty-tier.entity';
+
+export class TierBenefitDto {
+  @IsNumber()
+  @Min(1)
+  pointsMultiplier: number;
+
+  @IsNumber()
+  @Min(0)
+  @Max(100)
+  discountPercentage: number;
+
+  @IsNumber()
+  @Min(0)
+  freeShippingThreshold: number;
+
+  @IsString()
+  @IsOptional()
+  exclusiveAccess?: string[];
+
+  @IsNumber()
+  @Min(0)
+  birthdayBonus: number;
+
+  @IsNumber()
+  @Min(0)
+  anniversaryBonus: number;
+}
+
+export class CreateLoyaltyTierDto {
+  @IsEnum(LoyaltyTierName)
+  tierName: LoyaltyTierName;
+
+  @IsString()
+  @IsNotEmpty()
+  displayName: string;
+
+  @IsString()
+  @IsOptional()
+  description?: string;
+
+  @IsNumber()
+  @Min(0)
+  minPoints: number;
+
+  @IsNumber()
+  @IsOptional()
+  maxPoints?: number;
+
+  @ValidateNested()
+  @Type(() => TierBenefitDto)
+  benefits: TierBenefitDto;
+
+  @IsString()
+  @IsOptional()
+  color?: string;
+
+  @IsString()
+  @IsOptional()
+  icon?: string;
+
+  @IsBoolean()
+  @IsOptional()
+  isActive?: boolean;
+
+  @IsNumber()
+  @Min(0)
+  @IsOptional()
+  sortOrder?: number;
+}
+
+export class UpdateLoyaltyTierDto {
+  @IsString()
+  @IsOptional()
+  displayName?: string;
+
+  @IsString()
+  @IsOptional()
+  description?: string;
+
+  @IsNumber()
+  @IsOptional()
+  minPoints?: number;
+
+  @IsNumber()
+  @IsOptional()
+  maxPoints?: number;
+
+  @ValidateNested()
+  @Type(() => TierBenefitDto)
+  @IsOptional()
+  benefits?: TierBenefitDto;
+
+  @IsString()
+  @IsOptional()
+  color?: string;
+
+  @IsString()
+  @IsOptional()
+  icon?: string;
+
+  @IsBoolean()
+  @IsOptional()
+  isActive?: boolean;
+
+  @IsNumber()
+  @Min(0)
+  @IsOptional()
+  sortOrder?: number;
+}
+
+export class UserLoyaltySummaryDto {
+  @IsString()
+  currentTier: string;
+
+  @IsString()
+  currentTierDisplayName: string;
+
+  @IsNumber()
+  lifetimePoints: number;
+
+  @IsNumber()
+  currentYearPoints: number;
+
+  @IsObject()
+  @IsOptional()
+  tierProgress?: {
+    pointsToNextTier: number;
+    nextTierName: string;
+    progressPercentage: number;
+  };
+
+  @IsObject()
+  @IsOptional()
+  currentBenefits?: {
+    pointsMultiplier: number;
+    discountPercentage: number;
+    freeShippingThreshold: number;
+    exclusiveAccess: string[];
+    birthdayBonus: number;
+    anniversaryBonus: number;
+  };
+
+  @IsNumber()
+  @IsOptional()
+  monthsAtCurrentTier: number;
+}

src/rewards/entities/loyalty-tier.entity.ts

@@ -0,0 +1,95 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  UpdateDateColumn,
+  Index,
+  DeleteDateColumn,
+} from 'typeorm';
+
+export enum LoyaltyTierName {
+  BRONZE = 'bronze',
+  SILVER = 'silver',
+  GOLD = 'gold',
+  PLATINUM = 'platinum',
+  DIAMOND = 'diamond',
+}
+
+export interface TierBenefit {
+  pointsMultiplier: number;
+  discountPercentage: number;
+  freeShippingThreshold: number;
+  exclusiveAccess: string[];
+  birthdayBonus: number;
+  anniversaryBonus: number;
+}
+
+@Entity('loyalty_tiers')
+@Index(['tierName'])
+@Index(['minPoints'])
+export class LoyaltyTier {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({
+    type: 'enum',
+    enum: LoyaltyTierName,
+    unique: true,
+  })
+  tierName: LoyaltyTierName;
+
+  @Column({ type: 'text' })
+  displayName: string;
+
+  @Column({ type: 'text', nullable: true })
+  description?: string;
+
+  @Column({ type: 'int', default: 0, name: 'min_points' })
+  minPoints: number;
+
+  @Column({ type: 'int', nullable: true, name: 'max_points' })
+  maxPoints?: number;
+
+  @Column({ type: 'jsonb' })
+  benefits: TierBenefit;
+
+  @Column({ type: 'varchar', length: 7, default: '#CD7F32' })
+  color: string;
+
+  @Column({ type: 'varchar', length: 100, nullable: true })
+  icon?: string;
+
+  @Column({ default: true })
+  isActive: boolean;
+
+  @Column({ type: 'int', default: 0 })
+  sortOrder: number;
+
+  @CreateDateColumn({ name: 'created_at' })
+  createdAt: Date;
+
+  @UpdateDateColumn({ name: 'updated_at' })
+  updatedAt: Date;
+
+  @DeleteDateColumn({ name: 'deleted_at' })
+  deletedAt?: Date;
+
+  // Helper methods
+  isInRange(userPoints: number): boolean {
+    return userPoints >= this.minPoints && 
+           (!this.maxPoints || userPoints <= this.maxPoints);
+  }
+
+  calculatePointsEarned(basePoints: number): number {
+    return Math.floor(basePoints * this.benefits.pointsMultiplier);
+  }
+
+  calculateDiscount(orderAmount: number): number {
+    return (orderAmount * this.benefits.discountPercentage) / 100;
+  }
+
+  hasFreeShipping(orderAmount: number): boolean {
+    return orderAmount >= this.benefits.freeShippingThreshold;
+  }
+}

src/rewards/entities/user-loyalty-tier.entity.ts

@@ -0,0 +1,106 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  UpdateDateColumn,
+  Index,
+  DeleteDateColumn,
+  ManyToOne,
+  JoinColumn,
+  Unique,
+} from 'typeorm';
+import { User } from '../../entities/user.entity';
+import { LoyaltyTier } from './loyalty-tier.entity';
+
+@Entity('user_loyalty_tiers')
+@Unique(['userId'])
+@Index(['userId'])
+@Index(['currentTierId'])
+export class UserLoyaltyTier {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column('uuid', { name: 'user_id' })
+  userId: string;
+
+  @Column('uuid', { name: 'current_tier_id' })
+  currentTierId: string;
+
+  @Column({ type: 'int', default: 0, name: 'lifetime_points' })
+  lifetimePoints: number;
+
+  @Column({ type: 'int', default: 0, name: 'current_year_points' })
+  currentYearPoints: number;
+
+  @Column({ type: 'date', nullable: true, name: 'tier_upgrade_date' })
+  tierUpgradeDate?: Date;
+
+  @Column({ type: 'int', default: 0, name: 'months_at_current_tier' })
+  monthsAtCurrentTier: number;
+
+  @Column({ type: 'jsonb', nullable: true })
+  tierProgress?: {
+    pointsToNextTier: number;
+    nextTierName: string;
+    progressPercentage: number;
+  };
+
+  @Column({ type: 'jsonb', nullable: true })
+  earnedBenefits?: {
+    totalDiscountsEarned: number;
+    totalFreeShippingEarned: number;
+    totalBonusPointsEarned: number;
+  };
+
+  @Column({ type: 'date', nullable: true, name: 'last_activity_date' })
+  lastActivityDate?: Date;
+
+  @CreateDateColumn({ name: 'created_at' })
+  createdAt: Date;
+
+  @UpdateDateColumn({ name: 'updated_at' })
+  updatedAt: Date;
+
+  @DeleteDateColumn({ name: 'deleted_at' })
+  deletedAt?: Date;
+
+  // Relationships
+  @ManyToOne(() => User, { onDelete: 'CASCADE' })
+  @JoinColumn({ name: 'user_id' })
+  user: User;
+
+  @ManyToOne(() => LoyaltyTier, { onDelete: 'RESTRICT' })
+  @JoinColumn({ name: 'current_tier_id' })
+  currentTier: LoyaltyTier;
+
+  // Helper methods
+  updatePoints(points: number): void {
+    this.lifetimePoints += points;
+    this.currentYearPoints += points;
+    this.lastActivityDate = new Date();
+  }
+
+  calculateProgressToNextTier(nextTier: LoyaltyTier): void {
+    if (!nextTier) {
+      this.tierProgress = null;
+      return;
+    }
+
+    const pointsNeeded = nextTier.minPoints - this.lifetimePoints;
+    const currentTierMinPoints = this.currentTier?.minPoints || 0;
+    const totalPointsNeeded = nextTier.minPoints - currentTierMinPoints;
+    const pointsEarned = this.lifetimePoints - currentTierMinPoints;
+
+    this.tierProgress = {
+      pointsToNextTier: Math.max(0, pointsNeeded),
+      nextTierName: nextTier.displayName,
+      progressPercentage: Math.min(100, (pointsEarned / totalPointsNeeded) * 100),
+    };
+  }
+
+  isEligibleForTierUpgrade(tier: LoyaltyTier): boolean {
+    return this.lifetimePoints >= tier.minPoints && 
+           this.currentTierId !== tier.id;
+  }
+}