Skip to content

feat: 어드민 학기 생성 API 구현 #2324

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Soundbar91 wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

feat: 어드민 학기 생성 API 구현 #2324

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ba852bc
feat: 시간표 학기 생성 로직 추가
Soundbar91 Aug 6, 2026
9d32376
feat: 시간표 학기 생성 어드민 API 추가
Soundbar91 Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions src/main/java/in/koreatech/koin/admin/history/enums/DomainType.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ public enum DomainType {

LANDS("복덕방"),
LECTURES("강의"),
SEMESTER("학기"),
COOP_SHOPS("생협 매장"),

USERS("회원"),
Expand Down
24 changes: 24 additions & 0 deletions src/main/java/in/koreatech/koin/admin/semester/controller/AdminSemesterApi.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package in.koreatech.koin.admin.semester.controller;

import static in.koreatech.koin.admin.history.enums.DomainType.COOP_SEMESTER;
import static in.koreatech.koin.admin.history.enums.DomainType.SEMESTER;
import static in.koreatech.koin.domain.user.model.UserType.ADMIN;
import static in.koreatech.koin.global.code.ApiResponseCode.*;

Expand All @@ -14,15 +15,38 @@
import in.koreatech.koin.admin.history.aop.AdminActivityLogging;
import in.koreatech.koin.admin.semester.dto.AdminSemesterCreateRequest;
import in.koreatech.koin.admin.semester.dto.AdminSemesterResponse;
import in.koreatech.koin.admin.semester.dto.AdminTimetableSemesterCreateRequest;
import in.koreatech.koin.global.auth.Auth;
import in.koreatech.koin.global.code.ApiResponseCodes;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;

@Tag(name = "(ADMIN) Semester : 학기", description = "관리자 권한으로 학기 정보를 관리한다")
public interface AdminSemesterApi {

@ApiResponseCodes({
OK,
INVALID_REQUEST_BODY,
UNAUTHORIZED_USER,
FORBIDDEN_ADMIN,
NOT_READABLE_HTTP_MESSAGE,
DUPLICATE_SEMESTER
})
@Operation(summary = "(ADMIN) 시간표 학기 생성", description = """
- `year`와 `term`을 사용해 시간표 학기를 생성합니다.
- `term`은 `FIRST`, `SECOND`, `SUMMER`, `WINTER` 중 하나입니다.
- 이미 같은 연도와 학기가 존재하면 생성하지 않습니다.
""")
@SecurityRequirement(name = "Jwt Authentication")
@AdminActivityLogging(domain = SEMESTER)
@PostMapping("/admin/semesters")
ResponseEntity<Void> createSemester(
@Valid @RequestBody AdminTimetableSemesterCreateRequest request,
@Auth(permit = {ADMIN}) Integer adminId
);

@ApiResponseCodes({
OK,
INVALID_SEMESTER_FORMAT,
Expand Down
14 changes: 14 additions & 0 deletions src/main/java/in/koreatech/koin/admin/semester/controller/AdminSemesterController.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package in.koreatech.koin.admin.semester.controller;

import static in.koreatech.koin.admin.history.enums.DomainType.COOP_SEMESTER;
import static in.koreatech.koin.admin.history.enums.DomainType.SEMESTER;
import static in.koreatech.koin.domain.user.model.UserType.ADMIN;

import java.util.List;
Expand All @@ -14,7 +15,9 @@
import in.koreatech.koin.admin.history.aop.AdminActivityLogging;
import in.koreatech.koin.admin.semester.dto.AdminSemesterCreateRequest;
import in.koreatech.koin.admin.semester.dto.AdminSemesterResponse;
import in.koreatech.koin.admin.semester.dto.AdminTimetableSemesterCreateRequest;
import in.koreatech.koin.admin.semester.service.AdminCoopShopSemesterService;
import in.koreatech.koin.admin.semester.service.AdminTimetableSemesterService;
import in.koreatech.koin.global.auth.Auth;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
Expand All @@ -24,6 +27,17 @@
public class AdminSemesterController implements AdminSemesterApi {

private final AdminCoopShopSemesterService adminCoopShopSemesterService;
private final AdminTimetableSemesterService adminTimetableSemesterService;

@AdminActivityLogging(domain = SEMESTER)
@PostMapping("/admin/semesters")
public ResponseEntity<Void> createSemester(
@Valid @RequestBody AdminTimetableSemesterCreateRequest request,
@Auth(permit = {ADMIN}) Integer adminId
) {
adminTimetableSemesterService.createSemester(request);
return ResponseEntity.ok().build();
}

@AdminActivityLogging(domain = COOP_SEMESTER)
@PostMapping("/admin/coopshop/semesters")
Expand Down
25 changes: 25 additions & 0 deletions src/main/java/in/koreatech/koin/admin/semester/dto/AdminTimetableSemesterCreateRequest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
package in.koreatech.koin.admin.semester.dto;

import static com.fasterxml.jackson.databind.PropertyNamingStrategies.SnakeCaseStrategy;
import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED;

import com.fasterxml.jackson.databind.annotation.JsonNaming;

import in.koreatech.koin.domain.timetableV3.model.Term;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Positive;

@JsonNaming(SnakeCaseStrategy.class)
public record AdminTimetableSemesterCreateRequest(
@Schema(description = "연도", example = "2026", requiredMode = REQUIRED)
@NotNull(message = "연도는 필수입니다.")
@Positive(message = "연도는 양수여야 합니다.")
Integer year,
Comment on lines +10 to +18

@coderabbitai coderabbitai Bot Aug 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== candidate files =="
fd -a 'AdminTimetableSemesterCreateRequest.java|Semester.java|.*Semester.*Request.*|.*Semester.*' . | sed 's#^\./##' | head -100

echo
echo "== search relevant symbols =="
rg -n "AdminTimetableSemesterCreateRequest|record AdminTimetableSemester|class AdminTimetableSemester|Semester\.of|`@Size`|max = 10|YEAR|SUMMER|WINTER|semester" src/main/java/in/koreatech/koin -g '*.java' | head -200

echo
echo "== inspect request file =="
F=$(fd -a 'AdminTimetableSemesterCreateRequest.java' . | head -1)
if [ -n "${F:-}" ]; then
  cat -n "$F"
fi

echo
echo "== inspect Semester model =="
S=$(fd -a 'Semester.java' . | rg '/domain/timetable/model/Semester.java$' | head -1)
if [ -n "${S:-}" ]; then
  cat -n "$S"
fi

echo
echo "== inspect validator/service/controller references =="
rg -n "AdminTimetableSemesterCreateRequest|AdminTimetableSemester|semester|create.*semester|timetable.*semester" src/main/java src/test/java -g '*.java' | head -250

Repository: BCSDLab/KOIN_API_V2

Length of output: 50375

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== admin semester service =="
F=$(fd -a 'AdminTimetableSemesterService.java' . | head -1)
if [ -n "${F:-}" ]; then
  cat -n "$F"
fi

echo
echo "== admin semester controller relevant lines =="
F=$(fd -a 'AdminSemesterController.java' . | head -1)
if [ -n "${F:-}" ]; then
  cat -н "$F" | sed -n '20,90p' | cat -n
fi

echo
echo "== exact tests for admin semester create path =="
rg -n "POST .*/admin/semesters|semesters|AdminTimetableSemesterCreateRequest|AdminSemester.*Test|semester.*year|createSemester|`@Valid`|ConstraintViolation|400" src/test/in/koreatech/koin src/test/java/in/koreatech/koin -g '*.java' | head -300

echo
echo "== deterministic generated label lengths for edge cases =="
python3 - <<'PY'
samples = [1, 9, 10, 99, 100, 999, 1000, 9999, 10000, 9_999_999, 10_000_000]
for year in samples:
    for korean in ["여름", "겨울", "1", "2"]:
        sem = f"{year}-{korean}" if korean in {"여름", "겨울"} else f"{year}{korean}"
        print(f"year={year} term={korean} -> {sem!r} char={len(sem)}", end=" | ")
    print()
PY

echo
echo "== repository save method =="
F=$(fd -a 'AdminTimetableSemesterRepository.java' . | head -1)
if [ -n "${F:-}" ]; then
  cat -n "$F"
fi

Repository: BCSDLab/KOIN_API_V2

Length of output: 1855

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== admin semester controller relevant lines =="
F=$(fd -a 'AdminSemesterController.java' . | head -1)
if [ -n "${F:-}" ]; then
  awk 'NR>=20 && NR<=90 { printf "%4d  %s\n", NR, $0 }' "$F"
fi

echo
echo "== exact tests for admin semester create path =="
rg -n "POST .*/admin/semesters|semesters|AdminTimetableSemesterCreateRequest|AdminSemester.*Test|semester.*year|createSemester|`@Valid`|ConstraintViolation|400|AdminSemester" src/test -g '*.java' | head -300 || true

echo
echo "== deterministic generated label lengths for edge cases =="
python3 - <<'PY'
samples = [1, 9, 10, 99, 100, 999, 1000, 9999, 10000, 1_000_000, 9_999_999, 10_000_000]
for year in samples:
    sems = {
        "FIRST": f"{year}1",
        "SECOND": f"{year}2",
        "SUMMER": f"{year}-여름",
        "WINTER": f"{year}-겨울",
    }
    max_len = max(len(s) for s in sems.values())
    print(f"year={year} lengths={s for s in sems.values() if len(s)==max_len} max_len={max_len}")
PY

echo
echo "== repository save method =="
F=$(fd -a 'AdminTimetableSemesterRepository.java' . | head -1)
if [ -n "${F:-}" ]; then
  cat -n "$F"
fi

Repository: BCSDLab/KOIN_API_V2

Length of output: 12855

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== generated label lengths for summer/winter edge cases =="
python3 - <<'PY'
samples = [10_000_000, 9_999_999, 1_000_000]
for year in samples:
    for term in ["SUMMER", "WINTER", "FIRST", "SECOND"]:
        if term in {"SUMMER", "WINTER"}:
            label = f"{year}-여름" if term == "SUMMER" else f"{year}-겨울"
        else:
            label = f"{year}{term[0]}"
        ok = len(label) <= 10
        print(f"{term:8} year={year:>9} label={label:<15} length={len(label)} ok={ok}")
PY

echo
echo "== focused tests around /admin/semesters create =="
rg -n '"/admin/semesters"|AdminSemesterCreateRequest|AdminSemesterController|/admin/semesters|admin/semesters|POST.*semesters|semesters"' src/test/java src/main/java -g '*.java' | head -200 || true

Repository: BCSDLab/KOIN_API_V2

Length of output: 4197

Limit year so generated semester labels fit the 10-character field

@Positive accepts 10_000_000, and Semester.of then stores 10000000-여름 / 10000000-겨울, whose length is 11. Store the same created label back into Semester, so validation on the DTO is the user-visible failure point.

Proposed fix 
+import jakarta.validation.constraints.Max;
 import jakarta.validation.constraints.NotNull;
 import jakarta.validation.constraints.Positive;

     `@NotNull`(message = "연도는 필수입니다.")
     `@Positive`(message = "연도는 양수여야 합니다.")
+    `@Max`(value = 9_999_999, message = "연도는 9999999 이하여야 합니다.")
     Integer year,
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Positive;
@JsonNaming(SnakeCaseStrategy.class)
public record AdminTimetableSemesterCreateRequest(
@Schema(description = "연도", example = "2026", requiredMode = REQUIRED)
@NotNull(message = "연도는 필수입니다.")
@Positive(message = "연도는 양수여야 합니다.")
Integer year,
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Positive;
`@JsonNaming`(SnakeCaseStrategy.class)
public record AdminTimetableSemesterCreateRequest(
`@Schema`(description = "연도", example = "2026", requiredMode = REQUIRED)
`@NotNull`(message = "연도는 필수입니다.")
`@Positive`(message = "연도는 양수여야 합니다.")
`@Max`(value = 9_999_999, message = "연도는 9999999 이하여야 합니다.")
Integer year,
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@src/main/java/in/koreatech/koin/admin/semester/dto/AdminTimetableSemesterCreateRequest.java`
around lines 10 - 18, Update the year validation in
AdminTimetableSemesterCreateRequest to reject values whose generated semester
labels exceed the 10-character field, including 10,000,000; use the existing
validation mechanism and ensure the created label is stored back into Semester
so DTO validation remains the user-visible failure point.


@Schema(description = "학기", example = "FIRST", requiredMode = REQUIRED)
@NotNull(message = "학기는 필수입니다.")
Term term
) {

}
13 changes: 13 additions & 0 deletions ...in/java/in/koreatech/koin/admin/semester/repository/AdminTimetableSemesterRepository.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
package in.koreatech.koin.admin.semester.repository;

import org.springframework.data.repository.Repository;

import in.koreatech.koin.domain.timetable.model.Semester;
import in.koreatech.koin.domain.timetableV3.model.Term;

public interface AdminTimetableSemesterRepository extends Repository<Semester, Integer> {

boolean existsBySemesterOrYearAndTerm(String semester, Integer year, Term term);

Semester save(Semester semester);
}
34 changes: 34 additions & 0 deletions src/main/java/in/koreatech/koin/admin/semester/service/AdminTimetableSemesterService.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
package in.koreatech.koin.admin.semester.service;

import static in.koreatech.koin.global.code.ApiResponseCode.DUPLICATE_SEMESTER;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import in.koreatech.koin.admin.semester.dto.AdminTimetableSemesterCreateRequest;
import in.koreatech.koin.admin.semester.repository.AdminTimetableSemesterRepository;
import in.koreatech.koin.domain.timetable.model.Semester;
import in.koreatech.koin.global.exception.CustomException;
import lombok.RequiredArgsConstructor;

@Service
@RequiredArgsConstructor
public class AdminTimetableSemesterService {

private final AdminTimetableSemesterRepository adminTimetableSemesterRepository;

@Transactional
public void createSemester(AdminTimetableSemesterCreateRequest request) {
Semester semester = Semester.of(request.year(), request.term());
validateDuplicateSemester(semester);
adminTimetableSemesterRepository.save(semester);
}

private void validateDuplicateSemester(Semester semester) {
if (adminTimetableSemesterRepository.existsBySemesterOrYearAndTerm(
semester.getSemester(), semester.getYear(), semester.getTerm()
)) {
throw CustomException.of(DUPLICATE_SEMESTER);
Comment on lines +20 to +31

@coderabbitai coderabbitai Bot Aug 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect existing exception translation for database uniqueness failures.
rg -n -C 3 -g '*.java' \
  'DataIntegrityViolationException|ConstraintViolationException|DUPLICATE_SEMESTER|`@ExceptionHandler`' \
  src/main/java

# Inspect schema definitions that create the semester uniqueness constraint.
rg -n -C 3 -g '*.sql' -g '*.xml' -g '*.yml' -g '*.yaml' \
  'semester|unique' .

Repository: BCSDLab/KOIN_API_V2

Length of output: 34901

Map the duplicate semester constraint failure to DUPLICATE_SEMESTER.

existsBySemesterOrYearAndTerm(...) and save(...) are not atomic. Concurrent requests for the same semester can both pass validation; the later transaction then fails at commit on UNIQUE KEY semester_UNIQUE instead of returning the declared DUPLICATE_SEMESTER response. Add an integration test that exercises the concurrent create race.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@src/main/java/in/koreatech/koin/admin/semester/service/AdminTimetableSemesterService.java`
around lines 20 - 31, Update createSemester and its transaction handling to
catch the database unique-constraint failure for semester_UNIQUE during
save/commit and translate it to DUPLICATE_SEMESTER, while preserving the
existing pre-check. Add an integration test that runs concurrent identical
create requests and verifies the losing request returns the declared
duplicate-semester response.

}
}
}
10 changes: 10 additions & 0 deletions src/main/java/in/koreatech/koin/domain/timetable/model/Semester.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,4 +50,14 @@ public Semester(String semester, Integer year, Term term) {
this.year = year;
this.term = term;
}

public static Semester of(Integer year, Term term) {
String semester = switch (term) {
case FIRST -> year + "1";
case SECOND -> year + "2";
case SUMMER -> year + "-여름";
case WINTER -> year + "-겨울";
};
return new Semester(semester, year, term);
}
}
Loading