From 5b665992c6e2802be86193e3c5dd4d35578e5f09 Mon Sep 17 00:00:00 2001
From: zero1177 <younghur07@gmail.com>
Date: Tue, 20 Jan 2026 06:50:36 +0000
Subject: [PATCH] docs(be): add admin notice contestproblem jsdoc

---
 .../src/contest/contest-problem.service.ts    | 29 +++++++++++++++++
 .../apps/admin/src/notice/notice.service.ts   | 31 +++++++++++++++++--
 2 files changed, 58 insertions(+), 2 deletions(-)

diff --git a/apps/backend/apps/admin/src/contest/contest-problem.service.ts b/apps/backend/apps/admin/src/contest/contest-problem.service.ts
index 24dc487fc0..4b9c8f5c38 100644
--- a/apps/backend/apps/admin/src/contest/contest-problem.service.ts
+++ b/apps/backend/apps/admin/src/contest/contest-problem.service.ts
@@ -12,6 +12,12 @@ import type { ProblemScoreInput } from './model/problem-score.input'
 export class ContestProblemService {
   constructor(private readonly prisma: PrismaService) {}
 
+  /**
+   * 특정 대회의 문제 리스트를 조회합니다.
+   *
+   * @param {number} contestId 대회 아이디
+   * @returns {ContestProblem[]} 문제 리스트 반환
+   */
   async getContestProblems(
     contestId: number
   ): Promise<Partial<ContestProblem>[]> {
@@ -30,6 +36,8 @@ export class ContestProblemService {
    *
    * @param {number} contestId 대회 ID
    * @param {ProblemScoreInput[]} problemIdsWithScore 추가할 문제 ID와 배점
+   * @throws {EntityNotExistException} error.code === 'P2003'일때 에러 발생 (FK에 존재하지 않는 부모 엔티티 ID가 있을때)
+   * @throws {UnprocessableDataException} service 레벨에서 처리 불가능한 에러 throw
    * @returns 'ContestProblem' 정보
    */
   async importProblemsToContest(
@@ -105,6 +113,10 @@ export class ContestProblemService {
    *
    * @param {number} contestId 대회 ID
    * @param {number[]} problemIds 제거할 문제 ID 배열
+   * @throws {EntityNotExistException}
+   * 1. ID로 조회시 대회가 존재하지 않을때
+   * 2. 요청한 ConstestProblem 엔티티가 존재하지 않을때
+   * @throws {UnprocessableDataException} service 레벨에서 처리 불가능한 에러 throw
    * @returns 삭제된 `ContestProblem` 정보
    */
   async removeProblemsFromContest(contestId: number, problemIds: number[]) {
@@ -209,6 +221,13 @@ export class ContestProblemService {
     return contestProblems
   }
 
+  /**
+   * 특정 대회에서 문제들의 점수를 업데이트 합니다.
+   *
+   * @param {number} contestId 대회 아이디
+   * @param {ProblemScoreInput[]} problemIdsWithScore 문제별 점수의 배열
+   * @returns {Partial<ContestProblem>[]} 점수가 업데이트 된 문제들의 배열을 반환합니다.
+   */
   async updateContestProblemsScore(
     contestId: number,
     problemIdsWithScore: ProblemScoreInput[]
@@ -233,6 +252,16 @@ export class ContestProblemService {
     return await this.prisma.$transaction(queries)
   }
 
+  /**
+   * 특정 대회의 문제들을 원하는 순서로 정렬(업데이트) 합니다.
+   *
+   * @param {number} contestId 대회 아이디
+   * @param {number[]} orders problemId 배열로 나타낸 순서
+   * @throws {UnprocessableDataException}
+   * 1. orders 배열의 길이가 problem 개수와 일치하지 않을때
+   * 2. orders 배열에 빼먹은 problem이 있을때
+   * @returns {Partial<ContestProblem[]>} 순서가 반영된 대회 문제 배열
+   */
   async updateContestProblemsOrder(
     contestId: number,
     orders: number[]
diff --git a/apps/backend/apps/admin/src/notice/notice.service.ts b/apps/backend/apps/admin/src/notice/notice.service.ts
index 08ef7d45e7..3807be0cd5 100644
--- a/apps/backend/apps/admin/src/notice/notice.service.ts
+++ b/apps/backend/apps/admin/src/notice/notice.service.ts
@@ -1,6 +1,5 @@
-import { Injectable, NotFoundException } from '@nestjs/common'
+import { Injectable } from '@nestjs/common'
 import { EventEmitter2 } from '@nestjs/event-emitter'
-import { EntityNotExistException } from '@libs/exception'
 import { PrismaService } from '@libs/prisma'
 import type { CreateNoticeInput, UpdateNoticeInput } from './model/notice.input'
 
@@ -11,6 +10,12 @@ export class NoticeService {
     private readonly eventEmitter: EventEmitter2
   ) {}
 
+  /**
+   * 새로운 공지를 생성합니다.
+   * @param {number} userId 공지를 생성한 유저 아이디
+   * @param {CreateNoticeInput} createNoticeInput 공지 생성에 필요한 데이터
+   * @returns {Notice} 생성된 notice 객체 반환
+   */
   async createNotice(userId: number, createNoticeInput: CreateNoticeInput) {
     const noticeCreated = await this.prisma.notice.create({
       data: {
@@ -25,6 +30,11 @@ export class NoticeService {
     return noticeCreated
   }
 
+  /**
+   * 공지를 삭제합니다.
+   * @param {number} noticeId 공지 아이디
+   * @returns {Notice} 삭제된 notice 객체 반환
+   */
   async deleteNotice(noticeId: number) {
     return await this.prisma.notice.delete({
       where: {
@@ -33,6 +43,12 @@ export class NoticeService {
     })
   }
 
+  /**
+   * 기존 공지 내용을 업데이트 합니다.
+   * @param {number} noticeId 공지 아이디
+   * @param {UpdateNoticeInput} updateNoticeInput 공지 업데이트에 필요한 데이터
+   * @returns {Notice} 업데이트 된 notice 객체 반환
+   */
   async updateNotice(noticeId: number, updateNoticeInput: UpdateNoticeInput) {
     return await this.prisma.notice.update({
       where: {
@@ -42,6 +58,11 @@ export class NoticeService {
     })
   }
 
+  /**
+   * 공지를 조회합니다.
+   * @param {number} noticeId 공지 아이디
+   * @returns {Notice} 아이디에 해당하는 공지사항 반환
+   */
   async getNotice(noticeId: number) {
     return await this.prisma.notice.findUniqueOrThrow({
       where: {
@@ -50,6 +71,12 @@ export class NoticeService {
     })
   }
 
+  /**
+   * 공지사항들을 페이지 조건에 맞게 조회
+   * @param {number} cursor 다음 페이지 조회를 위한 기준 커서
+   * @param {number} take 한 페이지에 조회할 공지의 개수
+   * @returns {Notice[]} 조회된 공지사항들을 반환
+   */
   async getNotices(cursor: number | null, take: number) {
     const paginator = this.prisma.getPaginator(cursor)
     return await this.prisma.notice.findMany({