[WTH-364] weeth server 0.1.0 릴리즈

.claude/hooks/ktlint-format.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# PostToolUse hook: .kt 파일 수정 시 ktlint 자동 포맷
+
+FILE_PATH=$(cat | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# .kt 파일만 처리
+if [[ "$FILE_PATH" != *.kt ]]; then
+  exit 0
+fi
+
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+./gradlew ktlintFormat 2>&1 >&2

.claude/rules/api-design.md

@@ -17,6 +17,15 @@ class UserController(
 }
 ```
 
+## Club-scoped API
+
+Club resources use `/api/v4/clubs/{clubId}/...`. `clubId` is Base62 TSID — use two annotations together:
+
+```kotlin
+@TsidParam        // Swagger (type: string)
+@TsidPathVariable clubId: Long  // decodes Base62 → Long at runtime
+```
+
 ## Required Annotations
 
 | Annotation | Purpose |
@@ -61,9 +70,9 @@ enum class UserResponseCode(
     override val status: HttpStatus,
     override val message: String
 ) : ResponseCodeInterface {
-    GET_MY_INFO(1100, HttpStatus.OK, "내 정보 조회에 성공했습니다."),
-    GET_USER_INFO(1101, HttpStatus.OK, "다른 사용자 정보 조회에 성공했습니다."),
-    UPDATE_PROFILE_IMAGE(1102, HttpStatus.OK, "프로필 이미지 수정에 성공했습니다.")
+    USER_FIND_ALL_SUCCESS(10900, HttpStatus.OK, "모든 회원 정보를 성공적으로 조회했습니다."),
+    USER_FIND_BY_ID_SUCCESS(10907, HttpStatus.OK, "회원 정보가 성공적으로 조회되었습니다."),
+    USER_UPDATE_SUCCESS(10908, HttpStatus.OK, "회원 정보가 성공적으로 수정되었습니다."),
 }
 ```
 
@@ -72,44 +81,70 @@ enum class UserResponseCode(
   - `CommonResponse.success(USER_FIND_BY_ID_SUCCESS, data)`
   - `CommonResponse.success(USER_UPDATE_SUCCESS)`
 
-## Domain Success Codes
+## Code Format
+
+|   | Mean            | Value                                                                      |
+|---|-----------------|----------------------------------------------------------------------------|
+| X | Category        | 1=Success, 2=Domain Error, 3=Infra/Server Error, 4=Client/Validation Error |
+| DD | Domain ID       | 01~99                                                                      |
+| NN | In Domain Count | 00~99                                                                      |
+
+## Domain ID
+
+| DD | Domain     | Success Range | Domain Error Range | Infra Error Range |
+|----|------------|---------------|--------------------|-------------------|
+| 01 | account    | 10100~        | 20100~             | —                 |
+| 02 | attendance | 10200~        | 20200~             | —                 |
+| 03 | session    | 10300~        | 20300~             | —                 |
+| 04 | board      | 10400~        | 20400~             | —                 |
+| 05 | comment    | 10500~        | 20500~             | —                 |
+| 06 | file       | 10600~        | 20600~             | 30600~            |
+| 07 | penalty    | 10700~        | 20700~             | —                 |
+| 08 | schedule   | 10800~        | 20800~             | —                 |
+| 09 | user       | 10900~        | 20900~             | —                 |
+| 10 | cardinal   | 11000~        | 21000~             | —                 |
+| 11 | club       | 11100~        | 21100~             | —                 |
+| 12 | dashboard  | 11200~        | 21200~             | —                 |
+| 13 | university | 11300~        | —                  | 31300~            |
+| 90 | jwt/auth   | —             | 29000~             | —                 |
+| 99 | common     | —             | —                  | 39900~            |
 
-Current project uses domain-specific success enums under `src/main/java/com/weeth/domain/*/presentation/*ResponseCode.java`.
+## Domain Success Codes
 
 | Domain | ResponseCode Enum | Code Range | Location |
 |--------|------------------|------------|----------|
-| Account | `AccountResponseCode` | `11xx` | `domain/account/presentation/` |
-| Attendance | `AttendanceResponseCode` | `12xx` | `domain/attendance/presentation/` |
-| Board | `BoardResponseCode` | `13xx` | `domain/board/presentation/` |
-| Comment | `CommentResponseCode` | `140xx` | `domain/comment/presentation/` |
-| File | `FileResponseCode` | `15xx` | `domain/file/presentation/` |
-| Penalty | `PenaltyResponseCode` | `160xx` | `domain/penalty/presentation/` |
-| Schedule | `ScheduleResponseCode` | `17xx` | `domain/schedule/presentation/` |
-| User | `UserResponseCode` | `18xx` | `domain/user/presentation/` |
+| Account | `AccountResponseCode` | `101xx` | `domain/account/presentation/` |
+| Attendance | `AttendanceResponseCode` | `102xx` | `domain/attendance/presentation/` |
+| Session | `SessionResponseCode` | `103xx` | `domain/session/presentation/` |
+| Board | `BoardResponseCode` | `104xx` | `domain/board/presentation/` |
+| Comment | `CommentResponseCode` | `105xx` | `domain/comment/presentation/` |
+| File | `FileResponseCode` | `106xx` | `domain/file/presentation/` |
+| Penalty | `PenaltyResponseCode` | `107xx` | `domain/penalty/presentation/` |
+| Schedule | `ScheduleResponseCode` | `108xx` | `domain/schedule/presentation/` |
+| User | `UserResponseCode` | `109xx` | `domain/user/presentation/` |
+| Cardinal | `CardinalResponseCode` | `110xx` | `domain/cardinal/presentation/` |
+| Club | `ClubResponseCode` | `111xx` | `domain/club/presentation/` |
+| Dashboard | `DashboardResponseCode` | `112xx` | `domain/dashboard/presentation/` |
+| University | `UniversityResponseCode` | `113xx` | `domain/university/presentation/` |
 
 ## Domain Error Codes
 
-Domain-specific error enums under `src/main/java/com/weeth/domain/*/application/exception/*ErrorCode.java`.
-
 | Domain | ErrorCode Enum | Code Range | Location |
 |--------|---------------|------------|----------|
-| Account | `AccountErrorCode` | `21xx` | `domain/account/application/exception/` |
-| Attendance | `AttendanceErrorCode` | `22xx` | `domain/attendance/application/exception/` |
-| Board | `BoardErrorCode`, `NoticeErrorCode`, `PostErrorCode` | `23xx` | `domain/board/application/exception/` |
-| Comment | `CommentErrorCode` | `240x` | `domain/comment/application/exception/` |
-| Penalty | `PenaltyErrorCode` | `260x` | `domain/penalty/application/exception/` |
-| Schedule | `EventErrorCode`, `MeetingErrorCode` | `27xx` | `domain/schedule/application/exception/` |
-| User | `UserErrorCode` | `28xx` | `domain/user/application/exception/` |
-| JWT (Global) | `JwtErrorCode` | `29xx` | `global/auth/jwt/exception/` |
-
-## Code Numbering
-
-| Range | Category |
-|-------|----------|
-| 1XXX | Success responses |
-| 2XXX | Domain-specific errors |
-| 3XXX | Server errors |
-| 4XXX | Client errors |
+| Account | `AccountErrorCode` | `201xx` | `domain/account/application/exception/` |
+| Attendance | `AttendanceErrorCode` | `202xx` | `domain/attendance/application/exception/` |
+| Session | `SessionErrorCode` | `203xx` | `domain/session/application/exception/` |
+| Board | `BoardErrorCode` | `204xx` | `domain/board/application/exception/` |
+| Comment | `CommentErrorCode` | `205xx` | `domain/comment/application/exception/` |
+| File | `FileErrorCode` | `206xx` (domain), `306xx` (infra) | `domain/file/application/exception/` |
+| Penalty | `PenaltyErrorCode` | `207xx` | `domain/penalty/application/exception/` |
+| Schedule | `EventErrorCode` | `208xx` | `domain/schedule/application/exception/` |
+| User | `UserErrorCode` | `209xx` | `domain/user/application/exception/` |
+| Cardinal | `CardinalErrorCode` | `210xx` | `domain/cardinal/application/exception/` |
+| Club | `ClubErrorCode` | `211xx` | `domain/club/application/exception/` |
+| Dashboard | `DashboardErrorCode` | `212xx` | `domain/dashboard/application/exception/` |
+| University | `UniversityErrorCode` | `313xx` (infra) | `domain/university/application/exception/` |
+| JWT (Global) | `JwtErrorCode` | `290xx` | `global/auth/jwt/application/exception/` |
 
 ## HTTP Methods
 
@@ -132,6 +167,17 @@ DELETE /users/{userId}           # Delete user
 POST   /users/{userId}/activate  # Action on resource
 ```
 
+### Admin Endpoints
+
+`admin` prefix comes **before** `clubs/{clubId}`: `/api/v4/admin/clubs/{clubId}/{resource}`
+
+```
+/api/v4/clubs/{clubId}/boards          # user-facing
+/api/v4/admin/clubs/{clubId}/boards    # admin
+```
+
+Enables a single SecurityConfig rule: `.requestMatchers("/api/v4/admin/**").hasRole("ADMIN")`
+
 ## Query & Path Parameters
 
 - Query params for filtering: `?page=0&size=10&status=ACTIVE`

.claude/rules/architecture.md

@@ -3,7 +3,7 @@
 ## Package Structure
 
 ```text
-src/main/kotlin/weeth/
+src/main/kotlin/com/weeth/
 ├── domain/{domain-name}/
 │   ├── application/
 │   │   ├── dto/request/, dto/response/
@@ -26,7 +26,8 @@ src/main/kotlin/weeth/
 └── global/
     ├── auth/
     ├── config/
-    └── common/
+    ├── common/
+    └── logging/
 ```
 
 ## Layer Dependencies
@@ -79,11 +80,50 @@ presentation → application → domain (owns Port)
 
 ## Entity (Rich Domain Model)
 
-- **Factory method**: `companion object` with `create()` / `of()` including validation
 - **State changes**: named methods (`publish()`, `softDelete()`) — no public setters
 - **Validation**: `require` for argument checks, `check` for state preconditions
 - **Business decisions**: `isEditableBy()`, `canPublish()` belong to Entity
 
+### Constructor Pattern
+
+Primary constructor takes **business creation params only** (non-property) — JPA-managed fields (`id`, `isDeleted`) belong in the body with `private set` and default values.
+
+```kotlin
+@Entity
+class Post(
+    title: String,
+    content: String,
+    user: User,
+    board: Board,
+) : BaseEntity() {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    var id: Long = 0L
+        private set
+
+    var title: String = title
+        private set
+    // ...
+
+    companion object {
+        fun create(title: String, content: String, user: User, board: Board): Post {
+            require(title.isNotBlank()) { "제목은 비어 있을 수 없습니다" }
+            return Post(title = title, content = content, user = user, board = board)
+        }
+    }
+}
+```
+
+| Concern | Location |
+|---------|----------|
+| JPA-managed fields (`id`, `isDeleted`) | Body, `private set`, default value |
+| Business creation params | Primary constructor (non-property) |
+| Validation | `create()` / named mutation methods — not constructor |
+
+- **Factory method** (`companion object`): use when the entity has creation logic or validation. Expresses domain intent.
+- **Simple entities** (e.g., `Board`): public constructor is fine; no factory method needed if creation is trivial.
+
 ## Value Object (VO)
 
 - **Location**: `domain/vo/`
@@ -154,8 +194,8 @@ class User(
 
 ## Port-Adapter Pattern
 
-- **Port** (`domain/port/`): interface in domain language, no tech names → `FileStorage`, `PushNotificationSender`
-- **Adapter** (`infrastructure/`): implementation with tech prefix → `S3FileStorage`, `FcmPushNotificationSender`
+- **Port** (`domain/port/`): interface in domain language → `FileStoragePort`, `PushNotificationSenderPort`
+- **Adapter** (`infrastructure/`): implementation with tech prefix → `S3FileStorageAdapter`, `FcmPushNotificationSenderAdapter`
 - UseCase depends on Port interface only → swappable, testable
 
 ## Core Principles
@@ -164,4 +204,4 @@ class User(
 2. **UseCase = orchestration**: coordinates flow; "how" is decided by Entity
 3. **No meaningless services**: Repository wrappers are eliminated; Domain Service only for multi-entity logic
 4. **Port-Adapter**: domain owns Port interfaces; infrastructure implements them
-5. **Incremental migration**: migrate Java → Kotlin preserving existing structure
+5. **Kotlin-first**: Java → Kotlin migration complete; all new code in Kotlin

.claude/rules/code-style.md

@@ -67,6 +67,17 @@ companion object {
 }
 ```
 
+## Comments
+
+- Do NOT comment on self-explanatory code
+- Add comments in these cases:
+  - **Core business logic**: Domain rules, policy decisions — explain "why", not "what"
+  - **Collaboration aid**: Intent or background that other developers need to understand the code
+  - **Non-obvious implementation**: Performance optimizations, workarounds, external system constraints
+  - **Architecture decisions**: Reason for choosing a specific pattern or structure (e.g., `// NOTE: Kept in Java for Lombok @SuperBuilder compatibility`)
+- Use KDoc (`/** */`) for public APIs, Port interfaces, and external contracts
+- Use inline comments (`//`) for implementation intent within methods
+
 ## Null Handling
 
 ```kotlin

.claude/rules/exception-handling.md

@@ -6,7 +6,7 @@
 RuntimeException
     └── BaseException (abstract)
             ├── UserNotFoundException
-            ├── OrderNotFoundException
+            ├── BoardNotFoundException
             └── ... (domain-specific exceptions)
 ```
 
@@ -40,31 +40,33 @@ enum class UserErrorCode(
     override val message: String
 ) : ErrorCodeInterface {
     @ExplainError("사용자 ID로 조회했으나 해당 사용자가 존재하지 않을 때 발생합니다.")
-    USER_NOT_FOUND(2100, HttpStatus.NOT_FOUND, "존재하지 않는 사용자입니다."),
-    
-    @ExplainError("사용자 설정을 조회했으나 설정 정보가 존재하지 않을 때 발생합니다.")
-    USER_SETTING_NOT_FOUND(2101, HttpStatus.NOT_FOUND, "존재하지 않는 사용자 설정입니다."),
-    
-    @ExplainError("이미 탈퇴 처리된 사용자 계정에 접근을 시도할 때 발생합니다.")
-    USER_ALREADY_LEAVE(2102, HttpStatus.BAD_REQUEST, "이미 탈퇴한 사용자입니다."),
+    USER_NOT_FOUND(20900, HttpStatus.NOT_FOUND, "존재하지 않는 유저입니다."),
+
+    @ExplainError("가입 승인 대기 중인 사용자가 접근을 시도할 때 발생합니다.")
+    USER_INACTIVE(20901, HttpStatus.FORBIDDEN, "가입 승인이 허가되지 않은 계정입니다."),
+
+    @ExplainError("이미 가입된 이메일로 회원가입을 시도할 때 발생합니다.")
+    USER_EXISTS(20902, HttpStatus.BAD_REQUEST, "이미 가입된 사용자입니다."),
 }
 ```
 
-## Common Error Codes
+## Common Error Codes (pattern example, not yet implemented)
+
+Follow the pattern below when introducing a common error code enum. Currently, `CommonExceptionHandler` uses `CommonResponse.createFailure()` directly.
 
 ```kotlin
 enum class CommonErrorCode(
     override val code: Int,
     override val status: HttpStatus,
     override val message: String
 ) : ErrorCodeInterface {
-    // 3XXX: Server errors
-    INTERNAL_SERVER_ERROR(3001, HttpStatus.INTERNAL_SERVER_ERROR, "Internal server error"),
-    JSON_PROCESSING_ERROR(3002, HttpStatus.INTERNAL_SERVER_ERROR, "JSON processing error"),
+    // 3DDNN: Infra/Server errors (DD=99 for common)
+    INTERNAL_SERVER_ERROR(39901, HttpStatus.INTERNAL_SERVER_ERROR, "Internal server error"),
+    JSON_PROCESSING_ERROR(39902, HttpStatus.INTERNAL_SERVER_ERROR, "JSON processing error"),
 
-    // 4XXX: Client errors
-    INVALID_ARGUMENT(4001, HttpStatus.BAD_REQUEST, "Invalid argument"),
-    RESOURCE_NOT_FOUND(4003, HttpStatus.NOT_FOUND, "Resource not found"),
+    // 4DDNN: Client/Validation errors (DD=99 for common)
+    INVALID_ARGUMENT(49901, HttpStatus.BAD_REQUEST, "Invalid argument"),
+    RESOURCE_NOT_FOUND(49903, HttpStatus.NOT_FOUND, "Resource not found"),
 }
 ```
 
@@ -115,8 +117,8 @@ enum class UserErrorCode(
     override val status: HttpStatus,
     override val message: String
 ) : ErrorCodeInterface {
-    @ExplainError("Raised when no user exists for the given user ID.")
-    USER_NOT_FOUND(2100, HttpStatus.NOT_FOUND, "존재하지 않는 사용자입니다."),
+    @ExplainError("사용자 ID로 조회했으나 해당 사용자가 존재하지 않을 때 발생합니다.")
+    USER_NOT_FOUND(20900, HttpStatus.NOT_FOUND, "존재하지 않는 유저입니다."),
 }
 ```
 

.claude/rules/mapper-dto.md

@@ -2,18 +2,15 @@
 
 ## Mapper Pattern
 
-AS-IS (Java): MapStruct 사용 → TO-BE (Kotlin): 수동 Mapper 패턴으로 마이그레이션
+Manual `@Component` Mapper pattern (no MapStruct).
 
 ```kotlin
 @Component
-class UserMapper(
-    private val profileMapper: ProfileMapper
-) {
+class UserMapper {
     fun toResponse(user: User) = UserResponse(
         id = user.id,
         name = user.name,
         email = user.email,
-        profile = profileMapper.toResponse(user.profile)
     )
 
     fun toEntity(request: CreateUserRequest) = User(
@@ -82,7 +79,9 @@ data class UserResponse(
 - Use non-nullable types for required fields
 - Use nullable types with default `null` for optional fields
 
-## List Response with Pagination
+## List Response with Pagination (pattern example)
+
+Follow the pattern below when introducing a pagination response DTO.
 
 ```kotlin
 data class UserListResponse(
@@ -114,12 +113,11 @@ data class PageResponse(
 
 ## Mapper Dependencies
 
-Mappers can inject other mappers:
+Mappers can inject other mappers when needed:
 
 ```kotlin
 @Component
-class UserMapper(
-    private val profileMapper: ProfileMapper,
-    private val addressMapper: AddressMapper
+class PostMapper(
+    private val commentMapper: CommentMapper
 )
 ```