[WTH-468] 백엔드 패널티 관리 UI 변경에 따른 수정사항 반영

.claude/rules/transaction-concurrency.md

@@ -4,7 +4,7 @@ Use the `concurrency-safety` skill when changing transaction boundaries, lock be
 
 ## Transaction Placement
 
-- `@Transactional` goes on **UseCase** methods only — Command: `@Transactional`, Query: `@Transactional(readOnly = true)`
+- `@Transactional` goes on **UseCase** only — Command UseCase: `@Transactional` on each method; Query Service: `@Transactional(readOnly = true)` at the **class level** (not method level)
 - Domain Services must NOT have `@Transactional`; UseCase owns transaction boundaries
 - Keep transactions short — no external I/O (S3, HTTP) inside transactions
 

.gitignore

@@ -47,6 +47,7 @@ src/main/resources/*.p8
 src/test/resources/*.env
 .env.local
 .env.*.local
+.env
 
 ### Claude Code ###
 # 로컬 평가 텔레메트리 — 분석은 로컬에서, 결론만 docs/plan에 반영

src/main/kotlin/com/weeth/domain/club/application/dto/response/ClubMemberResponse.kt

@@ -37,8 +37,10 @@ data class ClubMemberResponse(
     val absenceCount: Int,
     @field:Schema(description = "출석률 (%)", example = "83")
     val attendanceRate: Int,
-    @field:Schema(description = "패널티 횟수", example = "1")
+    @field:Schema(description = "페널티 횟수", example = "1")
     val penaltyCount: Int,
+    @field:Schema(description = "최근 페널티 일시 (없으면 null)", nullable = true)
+    val lastPenaltyAt: LocalDateTime? = null,
     @field:Schema(description = "프로필 이미지 URL", example = "https://cdn.weeth.com/profile/1.png", nullable = true)
     val profileImageUrl: String? = null,
     @field:Schema(description = "자기소개", example = "안녕하세요", nullable = true)

src/main/kotlin/com/weeth/domain/club/application/mapper/ClubMapper.kt

@@ -66,6 +66,7 @@ class ClubMapper(
     fun toMemberResponse(
         member: ClubMember,
         cardinals: List<ClubMemberCardinal>,
+        lastPenaltyAt: java.time.LocalDateTime? = null,
     ) = ClubMemberResponse(
         userId = member.user.id,
         clubMemberId = member.id,
@@ -82,6 +83,7 @@ class ClubMapper(
         absenceCount = member.attendanceStats.absenceCount,
         attendanceRate = member.attendanceStats.attendanceRate,
         penaltyCount = member.penaltyCount,
+        lastPenaltyAt = lastPenaltyAt,
         profileImageUrl = resolveMemberProfileImage(member),
         bio = resolveMemberBio(member),
         joinedAt = member.createdAt,

src/main/kotlin/com/weeth/domain/club/application/usecase/query/GetClubMemberQueryService.kt

@@ -12,6 +12,7 @@ import com.weeth.domain.club.domain.repository.ClubMemberCardinalReader
 import com.weeth.domain.club.domain.repository.ClubMemberReader
 import com.weeth.domain.club.domain.service.ClubMemberPolicy
 import com.weeth.domain.club.domain.service.ClubPermissionPolicy
+import com.weeth.domain.penalty.domain.repository.PenaltyReader
 import com.weeth.domain.user.domain.repository.UserReader
 import com.weeth.global.common.response.PageResponse
 import org.springframework.data.domain.PageRequest
@@ -27,6 +28,7 @@ class GetClubMemberQueryService(
     private val clubPermissionPolicy: ClubPermissionPolicy,
     private val clubMapper: ClubMapper,
     private val userReader: UserReader,
+    private val penaltyReader: PenaltyReader,
 ) {
     fun findClubMembersForAdmin(
         clubId: Long,
@@ -49,17 +51,31 @@ class GetClubMemberQueryService(
                 pageable = pageable,
             )
 
-        // 기수는 조회된 페이지의 멤버에 대해서만 일괄 조회해 N+1을 피한다.
+        // 기수와 최근 페널티는 조회된 페이지의 멤버에 대해서만 일괄 조회해 N+1을 피한다.
+        val clubMemberIds = members.content.map { it.id }
         val cardinalsByMemberId =
             if (members.isEmpty) {
                 emptyMap()
             } else {
                 clubMemberCardinalReader.findAllByClubMembers(members.content).groupBy { it.clubMember.id }
             }
+        val lastPenaltyAtByMemberId =
+            if (clubMemberIds.isEmpty()) {
+                emptyMap()
+            } else {
+                penaltyReader
+                    .findByClubMemberIds(clubMemberIds)
+                    .groupBy { it.clubMember.id }
+                    .mapValues { (_, penalties) -> penalties.first().createdAt }
+            }
 
         return PageResponse.from(
             members.map { member ->
-                clubMapper.toMemberResponse(member, cardinalsByMemberId[member.id] ?: emptyList())
+                clubMapper.toMemberResponse(
+                    member,
+                    cardinalsByMemberId[member.id] ?: emptyList(),
+                    lastPenaltyAtByMemberId[member.id],
+                )
             },
         )
     }
@@ -113,7 +129,24 @@ class GetClubMemberQueryService(
         return clubMapper.toMemberSummaryResponse(member, cardinals)
     }
 
+    fun searchClubMembers(
+        clubId: Long,
+        userId: Long,
+        keyword: String,
+        cardinalNumber: Int?,
+    ): List<ClubMemberResponse> =
+        findClubMembersForAdmin(
+            clubId = clubId,
+            userId = userId,
+            page = 0,
+            size = MAX_SEARCH_SIZE,
+            keyword = keyword,
+            cardinalNumber = cardinalNumber,
+            sort = ClubMemberSort.CARDINAL_DESC, // 검색은 기수 내림차순 고정
+        ).content
+
     companion object {
         private const val MAX_PAGE_SIZE = 100
+        private const val MAX_SEARCH_SIZE = 50
     }
 }

src/main/kotlin/com/weeth/domain/club/domain/entity/Club.kt

@@ -66,6 +66,14 @@ class Club(
     var backgroundImageStorageKey: String? = backgroundImageStorageKey
         private set
 
+    @Column(nullable = false)
+    var warningEnabled: Boolean = false
+        private set
+
+    @Column(length = 500, nullable = true)
+    var penaltyRule: String? = null
+        private set
+
     // todo: 동아리 삭제 지원
 
     fun update(
@@ -119,6 +127,21 @@ class Club(
         }
     }
 
+    fun updatePenaltyRule(rule: String?) {
+        rule?.let {
+            require(it.length <= MAX_PENALTY_RULE_LENGTH) { "패널티 규정은 ${MAX_PENALTY_RULE_LENGTH}자 이하여야 합니다." }
+        }
+        this.penaltyRule = rule?.takeIf { it.isNotBlank() }
+    }
+
+    fun enableWarning() {
+        warningEnabled = true
+    }
+
+    fun disableWarning() {
+        warningEnabled = false
+    }
+
     fun regenerateCode(newCode: String) {
         require(newCode.isNotBlank()) { "초대 코드는 비어 있을 수 없습니다." }
         this.code = newCode
@@ -141,6 +164,7 @@ class Club(
 
     companion object {
         private const val MAX_DESCRIPTION_LENGTH = 30
+        private const val MAX_PENALTY_RULE_LENGTH = 500
 
         fun create(
             name: String,

src/main/kotlin/com/weeth/domain/club/domain/entity/ClubMember.kt

@@ -65,6 +65,10 @@ class ClubMember(
     var penaltyCount: Int = 0
         private set
 
+    @Column(nullable = false)
+    var warningCount: Int = 0
+        private set
+
     @Column(length = 500)
     var profileImageStorageKey: String? = null
         private set
@@ -158,16 +162,25 @@ class ClubMember(
         attendanceStats.recalculate(attendCount, absentCount)
     }
 
-    fun incrementPenaltyCount() {
-        penaltyCount++
+    fun incrementPenaltyCount(score: Int = 1) {
+        require(score > 0) { "페널티 점수는 1 이상이어야 합니다." }
+        penaltyCount += score
+    }
+
+    fun adjustPenaltyCount(delta: Int) {
+        penaltyCount = (penaltyCount + delta).coerceAtLeast(0)
+    }
+
+    fun adjustWarningCount(delta: Int) {
+        warningCount = (warningCount + delta).coerceAtLeast(0)
     }
 
     fun resetPenaltyCount() {
         penaltyCount = 0
     }
 
     fun recalculatePenaltyCount(count: Int) {
-        require(count >= 0) { "패널티 수는 0 이상이어야 합니다." }
+        require(count >= 0) { "페널티 수는 0 이상이어야 합니다." }
         penaltyCount = count
     }
 
@@ -198,6 +211,17 @@ class ClubMember(
         }
     }
 
+    fun incrementWarningCount(score: Int = 1) {
+        require(score > 0) { "경고 점수는 1 이상이어야 합니다." }
+        warningCount += score
+    }
+
+    fun decrementWarningCount() {
+        if (warningCount > 0) {
+            warningCount--
+        }
+    }
+
     companion object {
         private const val RETENTION_DAYS = 30L
 

src/main/kotlin/com/weeth/domain/club/presentation/ClubAdminController.kt

@@ -126,6 +126,34 @@ class ClubAdminController(
         return CommonResponse.success(ClubResponseCode.MEMBER_FIND_ALL_SUCCESS, members)
     }
 
+    @GetMapping("/members/search")
+    @Operation(
+        summary = "동아리 멤버 이름 검색",
+        description = """
+            멤버 이름으로 검색합니다. 가입 대기·추방·탈퇴 멤버도 포함됩니다.
+
+            사용 예시:
+            - 전체 멤버 검색: GET /api/v4/admin/clubs/xxx/members/search?keyword=김
+            - 5기만 검색: GET /api/v4/admin/clubs/xxx/members/search?keyword=김&cardinalNumber=5
+        """,
+    )
+    fun searchClubMembers(
+        @Parameter(hidden = true) @CurrentUser userId: Long,
+        @TsidParam
+        @TsidPathVariable clubId: Long,
+        @RequestParam keyword: String,
+        @RequestParam(required = false) cardinalNumber: Int?,
+    ): CommonResponse<List<ClubMemberResponse>> {
+        val members =
+            getClubMemberQueryService.searchClubMembers(
+                clubId = clubId,
+                userId = userId,
+                keyword = keyword,
+                cardinalNumber = cardinalNumber,
+            )
+        return CommonResponse.success(ClubResponseCode.MEMBER_FIND_ALL_SUCCESS, members)
+    }
+
     @GetMapping("/members/{clubMemberId}")
     @Operation(summary = "동아리 멤버 상세 조회", description = "가입 대기·추방·탈퇴 멤버도 조회할 수 있습니다.")
     fun getClubMemberDetail(

src/main/kotlin/com/weeth/domain/penalty/application/dto/request/SavePenaltyRequest.kt

@@ -1,10 +1,23 @@
 package com.weeth.domain.penalty.application.dto.request
 
+import com.weeth.domain.penalty.domain.enums.PenaltyType
 import io.swagger.v3.oas.annotations.media.Schema
+import jakarta.validation.constraints.NotBlank
+import jakarta.validation.constraints.NotEmpty
+import jakarta.validation.constraints.Positive
+import jakarta.validation.constraints.Size
 
 data class SavePenaltyRequest(
-    @field:Schema(description = "패널티 대상 사용자 ID", example = "1")
-    val userId: Long,
-    @field:Schema(description = "패널티 사유", example = "정기모임 무단 불참")
-    val penaltyDescription: String?,
+    @field:Schema(description = "페널티 대상 사용자 ID 목록", example = "[1, 2, 3]")
+    @field:NotEmpty
+    val userIds: List<Long>,
+    @field:Schema(description = "페널티 점수", example = "1")
+    @field:Positive
+    val score: Int = 1,
+    @field:Schema(description = "페널티 사유", example = "정기모임 무단 불참")
+    @field:NotBlank
+    @field:Size(max = 20)
+    val penaltyDescription: String,
+    @field:Schema(description = "페널티 타입 (기본값: PENALTY)", example = "PENALTY", allowableValues = ["PENALTY", "WARNING"])
+    val penaltyType: PenaltyType = PenaltyType.PENALTY,
 )

src/main/kotlin/com/weeth/domain/penalty/application/dto/request/SavePenaltyRuleRequest.kt

@@ -0,0 +1,10 @@
+package com.weeth.domain.penalty.application.dto.request
+
+import io.swagger.v3.oas.annotations.media.Schema
+import jakarta.validation.constraints.Size
+
+data class SavePenaltyRuleRequest(
+    @field:Schema(description = "패널티 규정 내용 (null 또는 빈 값이면 삭제)", example = "정기 모임에 출석을 하지 않았을때 (=결석)", nullable = true)
+    @field:Size(max = 500)
+    val content: String?,
+)

src/main/kotlin/com/weeth/domain/penalty/application/dto/request/UpdatePenaltyRequest.kt

@@ -1,10 +1,16 @@
 package com.weeth.domain.penalty.application.dto.request
 
 import io.swagger.v3.oas.annotations.media.Schema
+import jakarta.validation.constraints.Positive
+import jakarta.validation.constraints.Size
 
 data class UpdatePenaltyRequest(
-    @field:Schema(description = "수정할 패널티 ID", example = "1")
+    @field:Schema(description = "수정할 페널티 ID", example = "1")
     val penaltyId: Long,
-    @field:Schema(description = "수정할 패널티 사유", example = "정기모임 무단 불참 (수정)")
+    @field:Schema(description = "수정할 페널티 사유 (null=변경 안 함)", example = "정기모임 무단 불참 (수정)", nullable = true)
+    @field:Size(max = 20)
     val penaltyDescription: String?,
+    @field:Schema(description = "수정할 페널티 점수 (null=변경 안 함)", example = "2", nullable = true)
+    @field:Positive
+    val score: Int?,
 )

src/main/kotlin/com/weeth/domain/penalty/application/dto/response/MemberPenaltyDetailResponse.kt

@@ -0,0 +1,19 @@
+package com.weeth.domain.penalty.application.dto.response
+
+import com.weeth.domain.club.domain.enums.MemberStatus
+import io.swagger.v3.oas.annotations.media.Schema
+
+data class MemberPenaltyDetailResponse(
+    @field:Schema(description = "프로필 이미지 URL", nullable = true)
+    val profileImageUrl: String?,
+    @field:Schema(description = "이름", example = "홍길동")
+    val name: String,
+    @field:Schema(description = "소속 기수 목록", example = "[6, 7]")
+    val cardinals: List<Int>,
+    @field:Schema(description = "멤버 상태", example = "ACTIVE")
+    val memberStatus: MemberStatus,
+    @field:Schema(description = "자기소개", nullable = true)
+    val bio: String?,
+    @field:Schema(description = "페널티 목록")
+    val penalties: List<PenaltyDetailResponse>,
+)

src/main/kotlin/com/weeth/domain/penalty/application/dto/response/PenaltyByCardinalResponse.kt

@@ -5,6 +5,6 @@ import io.swagger.v3.oas.annotations.media.Schema
 data class PenaltyByCardinalResponse(
     @field:Schema(description = "기수 번호", example = "4")
     val cardinal: Int?,
-    @field:Schema(description = "해당 기수의 유저별 패널티 목록")
+    @field:Schema(description = "해당 기수의 유저별 페널티 목록")
     val responses: List<PenaltyResponse>,
 )

src/main/kotlin/com/weeth/domain/penalty/application/dto/response/PenaltyDetailResponse.kt

@@ -4,12 +4,14 @@ import io.swagger.v3.oas.annotations.media.Schema
 import java.time.LocalDateTime
 
 data class PenaltyDetailResponse(
-    @field:Schema(description = "패널티 ID", example = "1")
+    @field:Schema(description = "페널티 ID", example = "1")
     val penaltyId: Long,
     @field:Schema(description = "기수 번호", example = "4")
     val cardinal: Int?,
-    @field:Schema(description = "패널티 사유", example = "정기모임 무단 불참")
+    @field:Schema(description = "페널티 사유", example = "정기모임 무단 불참")
     val penaltyDescription: String,
-    @field:Schema(description = "최종 수정 시간", example = "2026-02-19T01:00:00")
+    @field:Schema(description = "페널티 점수", example = "1")
+    val score: Int,
+    @field:Schema(description = "페널티 부여 일시", example = "2026-02-19T01:00:00")
     val time: LocalDateTime,
 )

src/main/kotlin/com/weeth/domain/penalty/application/dto/response/PenaltyResponse.kt

@@ -10,10 +10,10 @@ data class PenaltyResponse(
     val name: String,
     @field:Schema(description = "동아리 멤버 상태", example = "ACTIVE")
     val memberStatus: MemberStatus,
-    @field:Schema(description = "패널티 횟수", example = "2")
+    @field:Schema(description = "페널티 횟수", example = "2")
     val penaltyCount: Int,
     @field:Schema(description = "소속 기수 목록", example = "[3, 4]")
     val cardinals: List<Int>,
-    @field:Schema(description = "패널티 상세 목록")
+    @field:Schema(description = "페널티 상세 목록")
     val penalties: List<PenaltyDetailResponse>,
 )

src/main/kotlin/com/weeth/domain/penalty/application/dto/response/PenaltyRuleResponse.kt

@@ -0,0 +1,8 @@
+package com.weeth.domain.penalty.application.dto.response
+
+import io.swagger.v3.oas.annotations.media.Schema
+
+data class PenaltyRuleResponse(
+    @field:Schema(description = "패널티 규정 내용 (미설정 시 null)", nullable = true)
+    val content: String?,
+)