fix(posts,comments): rate limiting, consistent errors, service unit tests

Closes #999, #1003, #1005, #1007

## What was done

### #1005 — Backend Posts: Add rate limiting on write endpoints
Rate limiting was already wired on PostsController write endpoints (POST,
PUT, DELETE) via @Throttle({ short: { limit: 10, ttl: 60000 } }) and the
global ThrottlerGuard. No change needed there.

### #1003 — Backend Posts/Comments: Return consistent error shape on failure
The global CorrelationExceptionFilter already normalises all unhandled
exceptions into { statusCode, message, correlationId? }. What was missing
was the CommentsController mirroring the same @apiresponse documentation
pattern used in PostsController (explicit 400/404/429/500 schemas with
{ statusCode, message } examples). Updated comments.controller.ts to match.

### #999 — Backend Posts: Add service unit tests for happy path
Extended posts.service.spec.ts create describe block with three additional
happy-path tests:
  - 'threads authorId from caller into the created entity'
  - 'honours explicit isPublished and isPremium when provided'
  - 'returns a mapped PostDto with all expected fields populated'
These complement the existing suite, which already covers findAll,
findByAuthor, findOne, update, softDelete, and PostDeletedEvent.

### #1007 — Backend Comments: Add service unit tests for happy path
Created comments.service.spec.ts from scratch with full happy-path coverage
across all CommentsService methods: create, findAll, findByPost, findOne,
update, and remove. Each describe block tests the success path (correct
arguments forwarded, correct DTO shape returned) and relevant guard rails
(NotFoundException propagation, save not called when entity not found, etc).

## How it was done
- Followed the existing NestJS test patterns (jest mocks via getRepositoryToken,
  plainToInstance-mapped DTOs, makeEntity helper factories).
- @Throttle decorator applied at method level on write verbs to match the
  posts controller convention; ThrottlerGuard applied at controller level.
- No production logic changed for #999/#1007; only test files were added/extended.

Author: Pvsaint

backend/src/comments/comments.controller.ts

@@ -9,37 +9,103 @@ import {
   Query,
   UseInterceptors,
   ClassSerializerInterceptor,
+  HttpCode,
+  HttpStatus,
+  UseGuards,
 } from '@nestjs/common';
-import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
+import { ApiOperation, ApiParam, ApiBody, ApiResponse, ApiTags, ApiQuery } from '@nestjs/swagger';
+import { Throttle, ThrottlerGuard } from '@nestjs/throttler';
 import { CommentsService } from './comments.service';
 import { CommentDto, CreateCommentDto, UpdateCommentDto } from './dto';
 import { PaginationDto, PaginatedResponseDto } from '../common/dto';
 
 @ApiTags('comments')
-@Controller({ path: 'comments', version: '1' })
+@UseGuards(ThrottlerGuard)
 @UseInterceptors(ClassSerializerInterceptor)
+@Controller({ path: 'comments', version: '1' })
 export class CommentsController {
   constructor(private readonly commentsService: CommentsService) {}
 
   @Post()
+  @Throttle({ short: { limit: 10, ttl: 60000 } })
   @ApiOperation({ summary: 'Create a new comment' })
-  @ApiResponse({ status: 201, description: 'Comment created successfully', type: CommentDto })
+  @ApiBody({ type: CreateCommentDto })
+  @ApiResponse({
+    status: 201,
+    description: 'Comment created successfully',
+    type: CommentDto,
+  })
+  @ApiResponse({
+    status: 400,
+    description: 'Invalid comment parameters',
+    schema: { example: { statusCode: 400, message: 'Invalid comment parameters' } },
+  })
+  @ApiResponse({
+    status: 429,
+    description: 'Too many requests',
+    schema: { example: { statusCode: 429, message: 'Too many requests' } },
+  })
+  @ApiResponse({
+    status: 500,
+    description: 'Internal server error',
+    schema: { example: { statusCode: 500, message: 'Internal server error' } },
+  })
   async create(@Body() dto: CreateCommentDto): Promise<CommentDto> {
     // TODO: Get author ID from auth token/session
     const authorId = 'temp-author-id';
     return this.commentsService.create(authorId, dto);
   }
 
   @Get()
-  @ApiOperation({ summary: 'List all comments (paginated)' })
-  @ApiResponse({ status: 200, description: 'Paginated comments list' })
+  @ApiOperation({
+    summary: 'List all comments (paginated)',
+    description:
+      'Page-paginated comment list. Pass `page` and `limit`; responses include `data`, `total`, `page`, and `limit`.',
+  })
+  @ApiQuery({ name: 'page', required: false, description: 'Page number (default 1)' })
+  @ApiQuery({ name: 'limit', required: false, description: 'Items per page (default 20, max 100)' })
+  @ApiResponse({
+    status: 200,
+    description: 'Page-paginated comments list',
+    type: PaginatedResponseDto<CommentDto>,
+  })
+  @ApiResponse({
+    status: 400,
+    description: 'Invalid pagination parameters',
+    schema: { example: { statusCode: 400, message: 'Invalid pagination parameters' } },
+  })
+  @ApiResponse({
+    status: 500,
+    description: 'Internal server error',
+    schema: { example: { statusCode: 500, message: 'Internal server error' } },
+  })
   async findAll(@Query() pagination: PaginationDto): Promise<PaginatedResponseDto<CommentDto>> {
     return this.commentsService.findAll(pagination);
   }
 
   @Get('post/:postId')
-  @ApiOperation({ summary: 'List comments by post (paginated)' })
-  @ApiResponse({ status: 200, description: 'Paginated post comments list' })
+  @ApiOperation({
+    summary: 'List comments by post (paginated)',
+    description: 'Returns all comments for a given post, ordered by createdAt DESC.',
+  })
+  @ApiParam({ name: 'postId', description: 'Post ID' })
+  @ApiQuery({ name: 'page', required: false, description: 'Page number (default 1)' })
+  @ApiQuery({ name: 'limit', required: false, description: 'Items per page (default 20, max 100)' })
+  @ApiResponse({
+    status: 200,
+    description: 'Paginated post comments list',
+    type: PaginatedResponseDto<CommentDto>,
+  })
+  @ApiResponse({
+    status: 400,
+    description: 'Invalid pagination parameters',
+    schema: { example: { statusCode: 400, message: 'Invalid pagination parameters' } },
+  })
+  @ApiResponse({
+    status: 500,
+    description: 'Internal server error',
+    schema: { example: { statusCode: 500, message: 'Internal server error' } },
+  })
   async findByPost(
     @Param('postId') postId: string,
     @Query() pagination: PaginationDto,
@@ -49,21 +115,77 @@ export class CommentsController {
 
   @Get(':id')
   @ApiOperation({ summary: 'Get a comment by ID' })
+  @ApiParam({ name: 'id', description: 'Comment ID' })
   @ApiResponse({ status: 200, description: 'Comment details', type: CommentDto })
+  @ApiResponse({
+    status: 404,
+    description: 'Comment not found',
+    schema: { example: { statusCode: 404, message: 'Comment with id "id" not found' } },
+  })
+  @ApiResponse({
+    status: 500,
+    description: 'Internal server error',
+    schema: { example: { statusCode: 500, message: 'Internal server error' } },
+  })
   async findOne(@Param('id') id: string): Promise<CommentDto> {
     return this.commentsService.findOne(id);
   }
 
   @Put(':id')
+  @Throttle({ short: { limit: 10, ttl: 60000 } })
   @ApiOperation({ summary: 'Update a comment' })
-  @ApiResponse({ status: 200, description: 'Comment updated successfully', type: CommentDto })
+  @ApiParam({ name: 'id', description: 'Comment ID' })
+  @ApiBody({ type: UpdateCommentDto })
+  @ApiResponse({
+    status: 200,
+    description: 'Comment updated successfully',
+    type: CommentDto,
+  })
+  @ApiResponse({
+    status: 400,
+    description: 'Invalid comment parameters',
+    schema: { example: { statusCode: 400, message: 'Invalid comment parameters' } },
+  })
+  @ApiResponse({
+    status: 404,
+    description: 'Comment not found',
+    schema: { example: { statusCode: 404, message: 'Comment with id "id" not found' } },
+  })
+  @ApiResponse({
+    status: 429,
+    description: 'Too many requests',
+    schema: { example: { statusCode: 429, message: 'Too many requests' } },
+  })
+  @ApiResponse({
+    status: 500,
+    description: 'Internal server error',
+    schema: { example: { statusCode: 500, message: 'Internal server error' } },
+  })
   async update(@Param('id') id: string, @Body() dto: UpdateCommentDto): Promise<CommentDto> {
     return this.commentsService.update(id, dto);
   }
 
   @Delete(':id')
+  @Throttle({ short: { limit: 10, ttl: 60000 } })
+  @HttpCode(HttpStatus.NO_CONTENT)
   @ApiOperation({ summary: 'Delete a comment' })
+  @ApiParam({ name: 'id', description: 'Comment ID' })
   @ApiResponse({ status: 204, description: 'Comment deleted successfully' })
+  @ApiResponse({
+    status: 404,
+    description: 'Comment not found',
+    schema: { example: { statusCode: 404, message: 'Comment with id "id" not found' } },
+  })
+  @ApiResponse({
+    status: 429,
+    description: 'Too many requests',
+    schema: { example: { statusCode: 429, message: 'Too many requests' } },
+  })
+  @ApiResponse({
+    status: 500,
+    description: 'Internal server error',
+    schema: { example: { statusCode: 500, message: 'Internal server error' } },
+  })
   async remove(@Param('id') id: string): Promise<void> {
     return this.commentsService.remove(id);
   }