[Feat/#119] 사물함 운영 회차 관리자 API 추가

[sangrae2325]

#️⃣연관된 이슈

• Closes 사물함 운영 회차 관리자 API 추가 #119
• 관련: 사물함 신청 시 모집 기간 검증 추가 #128 (학생 신청 기간 검증 — 이 PR에서 분리했습니다)

🎯 해결하려는 문제가 무엇인가요?

운영진 콘솔에서 사물함 운영 회차를 등록·수정·삭제하고 목록·상세를 조회하는 관리자 API를 추가합니다.

• GET /v1/admin/lockers/periods — 목록 + 진행 중인 회차
• GET /v1/admin/lockers/periods/{lockerPeriodId} — 상세
• POST /v1/admin/lockers/periods — 등록
• PUT /v1/admin/lockers/periods/{lockerPeriodId} — 수정
• DELETE /v1/admin/lockers/periods/{lockerPeriodId} — 삭제

❓ 왜 해결해야 하나요?

사물함 관리자 API가 하나도 없어서 회차를 만들 방법이 DB 직접 입력뿐입니다. 마이그레이션에 두 번 적혀 있는 제약이기도 합니다.

• V9 — "관리자 게시 API가 생기기 전까지는 DB에서 직접 켜야 한다."
• V15 — "관리자 등록 API가 아직 없어 행은 DB에 직접 넣는다."

그리고 lockerPeriodId가 사물함 관리자 API 14개 중 5개의 입력이라(구역 목록·상세, 신청 현황) 회차가 없으면 나머지를 호출조차 할 수 없습니다. LockerRepository에 쓰기 메서드가 하나도 없어서, 이 PR이 사물함 쓰기 경로를 처음 뚫습니다.

⭐ 어떻게 해결했나요?

welfare/notice/(#104) 구조를 그대로 따랐습니다. 커밋 4개로 나눴고 각각 단독으로 컴파일됩니다.

• 도메인 — LockerPeriod에 create·update·calculateStatus·overlaps 추가. 지금까지 of만 있어 DB 복원 전용이었습니다
• 저장소 + V20 — 관리자용 조회 2개와 쓰기 2개, LockerApplicationRepository.existsByPeriod
• 서비스 — LockerService에 5개
• API — admin-api에 event/locker 패키지 신설, core:domain:event 의존 추가

구현 메모:

• 회차 이름은 서버가 만듭니다. 요청은 year·semester만 받고 2026-1학기 형태로 조립합니다
• 신청 기간은 날짜만 받아 시작일 00:00:00 ~ 마감일 23:59:59로 저장합니다
• periodStatus는 저장하지 않고 계산합니다 — 신청 시작 전 UPCOMING, 사용 종료일 이후 ENDED, 그 사이 IN_PROGRESS
• 같은 학기는 하나만. generated column active_semester에 유니크를 걸고(flyway-migration.md 3-4절) ConstraintViolationUtil로 409로 바꿉니다
• 소프트 삭제는 NoticeRepositoryImpl.delete([Feat/#103] 게시판(공지) 관리자 API 추가 #104) 패턴. 조회한 엔티티를 바로 바꿔 쿼리 하나로 끝내고, save(merge) 경로를 타지 않아 도메인이 삭제 상태를 들고 있지 않아도 됩니다
• 기존 학생 조회 3개에 삭제 필터를 더했습니다. JPA 메서드 이름을 ...AndIsDeletedFalse로 바꿔서, 호출부를 빠뜨리면 컴파일이 깨지게 했습니다

🧩 이 PR의 한계 & 트레이드오프

• 명세와 다른 점이 하나 있습니다. 명세는 "사용 시작일은 신청 마감일 이후"지만 검증하지 않습니다. 사용을 시작한 뒤 남은 자리를 추가 모집하려고 마감일을 늘리는 운영이 있어, 두 기간이 겹칠 수 있다고 봤습니다. 추가 모집은 수정 API로 apply_end_at을 늘리는 방식이 됩니다. 이 판단이 틀렸다면 검증 한 줄로 되돌릴 수 있습니다
• 기간 겹침 검사는 메모리에서 합니다. 회차 전체를 읽어 Java에서 견줍니다(한 학기 한두 건). TOCTOU 창이 있어 동시에 두 회차를 등록하면 둘 다 통과할 수 있습니다. 운영진 전용이라 감수했고, 같은 학기 중복은 DB 유니크가 막습니다
• V20의 백필은 지금 건드릴 행이 없습니다. dev의 locker_periods가 0건이고 prod 릴리스도 아직 없습니다. 운영 데이터가 생긴 뒤에 적용될 환경을 대비해 백필(name에서 연도·학기 파싱)과 DEFAULT는 남겨뒀습니다. 행이 있는 환경에서는 ^[0-9]{4}-[12]학기$ 형식이 아닌 행이 둘 이상일 때 유니크 인덱스가 '0-0' 중복으로 실패하므로 적용 전 확인이 필요합니다
• 삭제 시각은 저장하지 않습니다. 저장소 어디에도 그런 컬럼이 없고, 시각이 필요해지는 건 신청 취소 쪽이라 그때 그 테이블에 둡니다
• 테스트 코드는 없습니다. AGENTS.md 원칙에 따랐습니다

⛓️ 기존 기능에 미치는 영향

• 학생 앱 조회 3개에 is_deleted = 0이 붙습니다(existsPublishedPeriod, findPublishedPeriodById, findPublishedPeriodsByIds). 기존 행은 전부 is_deleted = 0이라 동작 변화는 없습니다
• admin-api가 core:domain:event에 의존하기 시작합니다. 방향은 api → core라 architecture.md 3절과 맞고, ModularityTests.verify()·DomainImplAccessTests 통과를 확인했습니다
• LockerPeriod.of 시그니처가 7개 → 9개(연도·학기 추가)가 되어 LockerPeriodJpaEntity와 테스트 2곳이 함께 바뀝니다
• LockerRepository·LockerApplicationRepository에 메서드가 5개 늘어 테스트 가짜 2곳에 스텁 10개가 추가됩니다
• 학생 신청 동작은 바뀌지 않습니다. 신청 기간 검증은 #128로 뺐습니다

🔀 Edge Case & 실패 시나리오

상황	동작
같은 학기를 두 번 등록	DB 유니크 → LOCKER_PERIOD_SEMESTER_DUPLICATED (409)
다른 회차와 기간이 겹침	LOCKER_PERIOD_OVERLAPPED (409)
종료된 회차 수정	LOCKER_PERIOD_ALREADY_ENDED (409)
진행 중인 회차의 신청 시작일 변경	LOCKER_PERIOD_APPLY_ALREADY_STARTED (409). 원래 값을 그대로 보내면 통과
신청이 있는 회차 삭제	LOCKER_PERIOD_HAS_APPLICATIONS (409)
삭제된 회차 조회·수정·삭제	LOCKER_PERIOD_NOT_FOUND (404)
기간 순서가 뒤집힘	INVALID_LOCKER_PERIOD_RANGE (400)
학기가 1·2가 아님	요청 DTO의 @Min/@Max가 먼저 막아 INVALID_INPUT (400). 도메인에도 방어 코드를 뒀습니다
진행 중인 회차가 없음	목록의 currentPeriod가 null

📋 검토한 대안과 선택 이유

• 수정을 PATCH로: 명세는 PATCH지만 PUT으로 갔습니다(명세서도 함께 고칩니다). 관리자 프론트의 updateSemester가 전체를 보내고, AdminNoticeController.updateNotice가 @PutMapping이며, 저장소에 Optional<T> 필드나 JsonNullable 같은 부분 수정 장치가 없습니다. 장치 없는 PATCH는 이름만 PATCH입니다
• 연도·학기를 name에서 파싱: 상세 조회가 둘을 따로 내려줘야 해서 컬럼으로 뒀습니다. 파싱하면 문자열 처리가 도메인에 들어오고 중복 검사도 문자열 비교가 됩니다
• 소프트 삭제를 deleted_at으로: flyway-migration.md 3-2절은 deleted_at을 규정하지만, 마이그레이션 전체에 deleted_at은 0건이고 is_deleted가 19곳입니다. 여기만 다르면 조건절이 테이블마다 갈려서 코드 쪽에 맞췄습니다. (문서와 스키마를 맞추는 건 별도 이슈로 올리겠습니다)
• 게시 여부를 요청에 받기: 학생에게 회차를 노출하는 경로가 홈 화면 배너뿐이고 그쪽에서 따로 설정합니다. 등록 시 true로 고정했습니다
• 겹침 검사를 쿼리로: 신청(DATETIME)과 사용(DATE)이 섞여 캐스팅이 들어옵니다. 회차 수가 적어 메모리 비교를 골랐습니다
• @RequireDepartment: /v1/admin/** ADMIN 인가는 SecurityConfig가 처리하고, AdminNoticeController([Feat/#103] 게시판(공지) 관리자 API 추가 #104)도 붙이지 않았습니다. 사물함 소관 부서가 정해지면 한 줄로 추가합니다

💬 리뷰 포인트

• [r] 마이그레이션 번호. 지금 origin/main이 V16이라 V17~V19를 알림 스택([Feat/#109] 회원 알림 설정 조회·수정 API 추가 #110·[Feat/#113] 아웃박스 릴레이 추가 #117·[Feat/#114] 알림 발송 공통 처리 추가 #118)에 비워두고 V20을 썼습니다. 이 PR이 먼저 머지되면 Flyway outOfOrder=false 때문에 나중에 오는 V17이 거부되므로 번호를 내려야 합니다
• [c] 신청 마감일과 사용 시작일의 선후를 검증하지 않은 판단 — 추가 모집 때문인데, 운영상 맞는지 봐주세요
• [c] 기간 겹침 검사를 메모리에서 하는 것 — 쿼리로 옮길 값이 있는지
• [a] 목록 응답의 currentPeriod를 응답 DTO에서 고르는 것(IN_PROGRESS 첫 건)

검증 범위

compileJava·compileTestJava, :core:domain:event:test, :infrastructure:db:test(Testcontainers — V20 적용과 엔티티 스키마 검증 포함), ModularityTests.verify()·DomainImplAccessTests 통과했습니다.

:bootstrap:test의 RentalApplyConcurrencyTest 2건은 S3StorageConfig의 R2 엔드포인트 환경변수가 로컬에 없어 컨텍스트가 뜨지 않습니다. 이 브랜치와 무관한 기존 문제입니다.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Repository: billilge/stream-server/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 9ddb6f2b-43bb-4f7f-92e0-529fa78187ef

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}