Puzzle Rating and Review System

src/puzzles/controllers/puzzle-rating.controller.ts

@@ -0,0 +1,27 @@
+import { Controller, Post, Body, Param, UseGuards, Request, Get } from '@nestjs/common';
+import { ThrottlerGuard } from '@nestjs/throttler';
+import { PuzzleRatingService } from '../services/puzzle-rating.service';
+import { CreateRatingDto } from '../dto/create-rating.dto';
+import { JwtAuthGuard } from '../../auth/guards/jwt-auth.guard';
+import { PuzzleRating } from '../entities/puzzle-rating.entity';
+import { PuzzleRatingAggregate } from '../entities/puzzle-rating-aggregate.entity';
+
+@Controller('api/puzzles')
+export class PuzzleRatingController {
+  constructor(private readonly ratingService: PuzzleRatingService) {}
+
+  @Post(':id/ratings')
+  @UseGuards(JwtAuthGuard, ThrottlerGuard)
+  async submitRating(
+    @Param('id') puzzleId: string,
+    @Body() createRatingDto: CreateRatingDto,
+    @Request() req,
+  ): Promise<PuzzleRating> {
+    return this.ratingService.submitRating(req.user.id, puzzleId, createRatingDto);
+  }
+
+  @Get(':id/ratings/aggregate')
+  async getAggregate(@Param('id') puzzleId: string): Promise<PuzzleRatingAggregate> {
+    return this.ratingService.getPuzzleAggregate(puzzleId);
+  }
+}

src/puzzles/controllers/puzzle-review.controller.ts

@@ -0,0 +1,70 @@
+import { Controller, Post, Put, Delete, Body, Param, UseGuards, Request, Get, Query } from '@nestjs/common';
+import { ThrottlerGuard } from '@nestjs/throttler';
+import { PuzzleReviewService } from '../services/puzzle-review.service';
+import { CreateReviewDto } from '../dto/create-review.dto';
+import { UpdateReviewDto } from '../dto/update-review.dto';
+import { VoteReviewDto } from '../dto/vote-review.dto';
+import { FlagReviewDto } from '../dto/flag-review.dto';
+import { JwtAuthGuard } from '../../auth/guards/jwt-auth.guard';
+import { PuzzleReview } from '../entities/puzzle-review.entity';
+
+@Controller('api')
+export class PuzzleReviewController {
+  constructor(private readonly reviewService: PuzzleReviewService) {}
+
+  @Post('puzzles/:id/reviews')
+  @UseGuards(JwtAuthGuard)
+  async submitReview(
+    @Param('id') puzzleId: string,
+    @Body() createReviewDto: CreateReviewDto,
+    @Request() req,
+  ): Promise<PuzzleReview> {
+    return this.reviewService.submitReview(req.user.id, puzzleId, createReviewDto);
+  }
+
+  @Put('reviews/:id')
+  @UseGuards(JwtAuthGuard)
+  async updateReview(
+    @Param('id') reviewId: string,
+    @Body() updateReviewDto: UpdateReviewDto,
+    @Request() req,
+  ): Promise<PuzzleReview> {
+    return this.reviewService.updateReview(req.user.id, reviewId, updateReviewDto);
+  }
+
+  @Delete('reviews/:id')
+  @UseGuards(JwtAuthGuard)
+  async deleteReview(@Param('id') reviewId: string, @Request() req): Promise<void> {
+    return this.reviewService.deleteReview(req.user.id, reviewId);
+  }
+
+  @Post('reviews/:id/vote')
+  @UseGuards(JwtAuthGuard, ThrottlerGuard)
+  async voteReview(
+    @Param('id') reviewId: string,
+    @Body() voteDto: VoteReviewDto,
+    @Request() req,
+  ): Promise<void> {
+    return this.reviewService.voteReview(req.user.id, reviewId, voteDto);
+  }
+
+  @Post('reviews/:id/flag')
+  @UseGuards(JwtAuthGuard, ThrottlerGuard)
+  async flagReview(
+    @Param('id') reviewId: string,
+    @Body() flagDto: FlagReviewDto,
+    @Request() req,
+  ): Promise<void> {
+    return this.reviewService.flagReview(req.user.id, reviewId, flagDto);
+  }
+
+  @Get('puzzles/:id/reviews')
+  async getReviews(
+    @Param('id') puzzleId: string,
+    @Query('page') page: number = 1,
+    @Query('limit') limit: number = 20,
+    @Query('sort') sort: 'recency' | 'helpful' = 'recency',
+  ): Promise<{ reviews: PuzzleReview[], total: number }> {
+    return this.reviewService.getPuzzleReviews(puzzleId, page, limit, sort);
+  }
+}

src/puzzles/dto/create-rating.dto.ts

@@ -0,0 +1,17 @@
+import { IsInt, IsNotEmpty, Min, Max, IsOptional, IsString } from 'class-validator';
+
+export class CreateRatingDto {
+  @IsInt()
+  @Min(1)
+  @Max(5)
+  @IsNotEmpty()
+  rating: number;
+
+  @IsOptional()
+  @IsString()
+  difficultyVote?: 'easy' | 'medium' | 'hard' | 'expert';
+
+  @IsOptional()
+  @IsString({ each: true })
+  tags?: string[];
+}

src/puzzles/dto/create-review.dto.ts

@@ -0,0 +1,8 @@
+import { IsString, IsNotEmpty, Length } from 'class-validator';
+
+export class CreateReviewDto {
+  @IsString()
+  @IsNotEmpty()
+  @Length(50, 1000)
+  reviewText: string;
+}

src/puzzles/dto/flag-review.dto.ts

@@ -0,0 +1,7 @@
+import { IsString, IsNotEmpty } from 'class-validator';
+
+export class FlagReviewDto {
+  @IsString()
+  @IsNotEmpty()
+  reason: string;
+}

src/puzzles/dto/search-puzzle.dto.ts

@@ -7,6 +7,7 @@ export enum SortBy {
   TITLE = 'title',
   DIFFICULTY = 'difficulty',
   RATING = 'rating',
+  REVIEWS = 'reviews',
   PLAYS = 'totalPlays',
   COMPLETION_RATE = 'completionRate'
 }

src/puzzles/dto/update-review.dto.ts

@@ -0,0 +1,8 @@
+import { IsString, IsNotEmpty, Length } from 'class-validator';
+
+export class UpdateReviewDto {
+  @IsString()
+  @IsNotEmpty()
+  @Length(50, 1000)
+  reviewText: string;
+}

src/puzzles/dto/vote-review.dto.ts

@@ -0,0 +1,12 @@
+import { IsEnum, IsNotEmpty } from 'class-validator';
+
+export enum VoteType {
+  HELPFUL = 'helpful',
+  UNHELPFUL = 'unhelpful',
+}
+
+export class VoteReviewDto {
+  @IsEnum(VoteType)
+  @IsNotEmpty()
+  voteType: VoteType;
+}

src/puzzles/entities/puzzle-rating-aggregate.entity.ts

@@ -0,0 +1,46 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  UpdateDateColumn,
+  OneToOne,
+  JoinColumn,
+  Index,
+} from 'typeorm';
+import { Puzzle } from './puzzle.entity';
+
+@Entity('puzzle_rating_aggregates')
+export class PuzzleRatingAggregate {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ type: 'uuid' })
+  @Index({ unique: true })
+  puzzleId: string;
+
+  @Column({ type: 'decimal', precision: 3, scale: 2, default: 0 })
+  averageRating: number;
+
+  @Column({ type: 'int', default: 0 })
+  totalRatings: number;
+
+  @Column({ type: 'int', default: 0 })
+  totalReviews: number;
+
+  // Rating distribution for histogram
+  @Column({ type: 'jsonb', default: { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 } })
+  ratingDistribution: {
+    1: number;
+    2: number;
+    3: number;
+    4: number;
+    5: number;
+  };
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+
+  @OneToOne(() => Puzzle, { onDelete: 'CASCADE' })
+  @JoinColumn({ name: 'puzzleId' })
+  puzzle: Puzzle;
+}

src/puzzles/entities/puzzle-review.entity.ts

@@ -0,0 +1,69 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  UpdateDateColumn,
+  DeleteDateColumn,
+  ManyToOne,
+  OneToMany,
+  Index,
+  JoinColumn,
+} from 'typeorm';
+import { User } from '../../users/entities/user.entity';
+import { Puzzle } from './puzzle.entity';
+import { ReviewVote } from './review-vote.entity';
+
+@Entity('puzzle_reviews')
+@Index(['userId', 'puzzleId'], { unique: true, where: '"deletedAt" IS NULL' })
+export class PuzzleReview {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ type: 'uuid' })
+  @Index()
+  userId: string;
+
+  @Column({ type: 'uuid' })
+  @Index()
+  puzzleId: string;
+
+  @Column({ type: 'text' })
+  reviewText: string;
+
+  @Column({ type: 'enum', enum: ['pending', 'approved', 'rejected', 'flagged'], default: 'pending' })
+  @Index()
+  moderationStatus: 'pending' | 'approved' | 'rejected' | 'flagged';
+
+  @Column({ type: 'int', default: 0 })
+  helpfulVotes: number;
+
+  @Column({ type: 'int', default: 0 })
+  unhelpfulVotes: number;
+
+  @Column({ type: 'boolean', default: false })
+  isFlagged: boolean;
+
+  @Column({ type: 'text', nullable: true })
+  flagReason: string;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+
+  @DeleteDateColumn()
+  deletedAt: Date;
+
+  @ManyToOne(() => User, { onDelete: 'CASCADE' })
+  @JoinColumn({ name: 'userId' })
+  user: User;
+
+  @ManyToOne(() => Puzzle, { onDelete: 'CASCADE' })
+  @JoinColumn({ name: 'puzzleId' })
+  puzzle: Puzzle;
+
+  @OneToMany(() => ReviewVote, (vote) => vote.review)
+  votes: ReviewVote[];
+}

src/puzzles/entities/review-vote.entity.ts

@@ -0,0 +1,41 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  ManyToOne,
+  Index,
+  JoinColumn,
+  Unique,
+} from 'typeorm';
+import { User } from '../../users/entities/user.entity';
+import { PuzzleReview } from './puzzle-review.entity';
+
+@Entity('review_votes')
+@Unique(['userId', 'reviewId'])
+export class ReviewVote {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ type: 'uuid' })
+  @Index()
+  userId: string;
+
+  @Column({ type: 'uuid' })
+  @Index()
+  reviewId: string;
+
+  @Column({ type: 'enum', enum: ['helpful', 'unhelpful'] })
+  voteType: 'helpful' | 'unhelpful';
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @ManyToOne(() => User, { onDelete: 'CASCADE' })
+  @JoinColumn({ name: 'userId' })
+  user: User;
+
+  @ManyToOne(() => PuzzleReview, (review) => review.votes, { onDelete: 'CASCADE' })
+  @JoinColumn({ name: 'reviewId' })
+  review: PuzzleReview;
+}

src/puzzles/puzzles.module.ts

@@ -6,6 +6,13 @@ import { CommunityPuzzlesModule } from './community-puzzles.module';
 import { Puzzle } from './entities/puzzle.entity';
 import { PuzzleProgress } from '../game-logic/entities/puzzle-progress.entity';
 import { PuzzleRating } from './entities/puzzle-rating.entity';
+import { PuzzleReview } from './entities/puzzle-review.entity';
+import { ReviewVote } from './entities/review-vote.entity';
+import { PuzzleRatingAggregate } from './entities/puzzle-rating-aggregate.entity';
+import { PuzzleRatingService } from './services/puzzle-rating.service';
+import { PuzzleReviewService } from './services/puzzle-review.service';
+import { PuzzleRatingController } from './controllers/puzzle-rating.controller';
+import { PuzzleReviewController } from './controllers/puzzle-review.controller';
 
 // Import entities and components for categories, collections, and themes
 import { Category } from './entities/category.entity';
@@ -24,19 +31,26 @@ import { ThemesController } from './theme.controller'; // Import ThemesControlle
       Puzzle,
       PuzzleProgress,
       PuzzleRating,
+      PuzzleReview,
+      ReviewVote,
+      PuzzleRatingAggregate,
       Category,
       Collection,
       Theme // Add Theme entity
     ])
   ],
   controllers: [
     PuzzlesController,
+    PuzzleRatingController,
+    PuzzleReviewController,
     CategoriesController,
     CollectionsController,
     ThemesController // Add ThemesController
   ],
   providers: [
     PuzzlesService,
+    PuzzleRatingService,
+    PuzzleReviewService,
     CategoriesService,
     CollectionsService,
     ThemesService // Add ThemesService