MandarinGuy · YeaChan05 · Sep 8, 2025 · Sep 4, 2025 · Sep 4, 2025 · Sep 5, 2025
diff --git a/.github/workflows/gradle.yml b/.github/workflows/gradle.yml
@@ -31,10 +31,10 @@ jobs:
           distribution: "temurin"
 
       - name: Build (no tests)
-        run: ./gradlew clean build -x test -x spotbugsMain -x spotbugsTest -Dspring.profiles.active=test
+        run: ./gradlew clean build -x test -Dspring.profiles.active=test
 
       - name: Test
-        run: ./gradlew test -Dspring.profiles.active=local
+        run: ./gradlew test -Dspring.profiles.active=test
 
       - name: Publish Test Report
         uses: dorny/test-reporter@v1

diff --git a/.gitignore b/.gitignore
@@ -3,3 +3,4 @@
 /build
 .idea
 .aiassistant/rules/AGENTS.md
+/src/docs/
diff --git a/build.gradle b/build.gradle
@@ -2,12 +2,17 @@ plugins {
 	id 'java'
 	id 'org.springframework.boot' version '3.5.4'
 	id 'io.spring.dependency-management' version '1.1.7'
-	id 'com.github.spotbugs' version '6.2.4'
+    id 'com.epages.restdocs-api-spec' version '0.18.2'
+    id 'org.asciidoctor.jvm.convert' version '3.3.2'
 }
 
 group = 'org.mandarin'
 version = '0.0.1-SNAPSHOT'
 
+ext {
+    snippetsDir = file('build/generated-snippets')
+}
+
 java {
 	toolchain {
 		languageVersion = JavaLanguageVersion.of(21)
@@ -20,6 +25,7 @@ repositories {
 
 configurations {
 	byteBuddyAgent
+    asciidoctorExt
 }
 
 dependencies {
@@ -36,6 +42,13 @@ dependencies {
     testRuntimeOnly 'com.h2database:h2'
     implementation 'com.github.gavlyukovskiy:p6spy-spring-boot-starter:1.9.0'
 
+    // ---- Querydsl ----
+    implementation 'com.querydsl:querydsl-jpa:5.1.0:jakarta'
+    annotationProcessor 'com.querydsl:querydsl-apt:5.1.0:jakarta'
+    // Ensure APT has Jakarta APIs (some environments require explicit presence)
+    annotationProcessor 'jakarta.persistence:jakarta.persistence-api:3.1.0'
+    annotationProcessor 'jakarta.annotation:jakarta.annotation-api:2.1.1'
+
     // ---- Security & Auth ----
     implementation 'org.springframework.boot:spring-boot-starter-security'
     implementation 'io.jsonwebtoken:jjwt-api:0.12.6'
@@ -44,14 +57,14 @@ dependencies {
     testImplementation 'io.jsonwebtoken:jjwt-impl:0.12.6'
 
     // ---- Lombok ----
-    implementation 'org.projectlombok:lombok:1.18.36'
+    compileOnly 'org.projectlombok:lombok:1.18.36'
     annotationProcessor 'org.projectlombok:lombok:1.18.36'
+    testCompileOnly 'org.projectlombok:lombok:1.18.36'
+    testAnnotationProcessor 'org.projectlombok:lombok:1.18.36'
 
     // ---- Dev Only ----
     developmentOnly 'org.springframework.boot:spring-boot-docker-compose'
-
-    // ---- Code Quality / Tooling ----
-    spotbugs 'com.github.spotbugs:spotbugs:4.9.3'
+    developmentOnly 'org.springframework.boot:spring-boot-devtools'
 
     // ---- Testing ----
     testImplementation 'org.springframework.boot:spring-boot-starter-test'
@@ -60,11 +73,41 @@ dependencies {
     testImplementation 'com.tngtech.archunit:archunit-junit5:1.3.0'
 	byteBuddyAgent 'net.bytebuddy:byte-buddy-agent:1.17.6'
     testImplementation 'org.mockito:mockito-inline:5.2.0'
+
+    // ---- API Docs (REST Docs + Rest Assured) ----
+    testImplementation 'org.springframework.restdocs:spring-restdocs-restassured'
+
+    asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor:3.1.0'
+
+    // null safety
+    implementation 'org.jspecify:jspecify:1.0.0'
+}
+ext {
+    set('snippetsDir', file('build/generated-snippets'))
 }
 
 tasks.named('test') {
 	useJUnitPlatform()
 	systemProperty 'spring.profiles.active', 'test'
 	// javaagent 선부착 (Mockito self-attach 방지)
 	jvmArgs "-javaagent:${configurations.byteBuddyAgent.singleFile}"
+    outputs.dir snippetsDir
 }
+
+asciidoctor {
+    group = 'documentation'
+    description = 'Converts AsciiDoc files to HTML, including REST Docs snippets.'
+    dependsOn test
+    baseDirFollowsSourceDir()
+    sourceDir = file('src/docs')
+    sources {
+        include '**/*.adoc'
+    }
+    inputs.dir snippetsDir
+    attributes 'snippets': snippetsDir
+    resources {
+        from(snippetsDir) { into 'snippets' }
+    }
+    outputDir = layout.buildDirectory.dir("docs/asciidoc").get().asFile
+}
+
diff --git a/docs/devlog/250908.md b/docs/devlog/250908.md
@@ -0,0 +1,7 @@
+## 예찬
+
+기존의 개발 방식을 고수하면서 이번에는 Aggregate root간의 의존을 최소화 하기 위해 Application Event를 적당히 활용해봤다. 실무에서도 이렇게 잘 쓰이는지는 모르겠다만, 결국 Spring Context에 의해 관리되는 영역인 만큼 그냥 써도 되지 않을까 하는 생각..
+
+그리고 이번에 AR를 적극적으로 활용한 DDD를 하려 하다보니 Entity를 package private로 개발하는 방식을 처음으로 써봤다. 도메인 로직들은 통상 AR를 통해 호출되기 때문에, AR를 제외한 나머지 Entity들은 외부에서 직접 접근할 일이 거의 없다는 점에 착안한 것이다. 물론, 이 방식이 무조건 옳다고 생각하지는 않는다. 다만, 이번 프로젝트에서는 이 방식을 채택함으로써 도메인 모델의 캡슐화가 좀 더 강화된 느낌이다.
+
+마침 AR를 사용한 설계의 장점을 극대화할 겸, 어차피 나중에 한번쯤은 손대려고 했던 모듈을 다음 기능 개발에 도입하려 한다. 이때 AR 기준 접근을 하려 했던 기존의 설계가 빛을 바랄거라고 생각되는데, 이 부분은 다음 개발기를 통해 좀 더 자세히 다뤄보도록 하겠다.
diff --git a/docs/specs/api/show_register.md b/docs/specs/api/show_register.md
@@ -12,31 +12,33 @@
 - 본문
 
     ```json
-
+    {
+        "title": "인셉션",
+        "type": "MUSICAL",
+        "rating": "AGE12",
+        "synopsis": "타인의 꿈속에 진입해 아이디어를 주입하는 특수 임무를 수행하는 이야기.",
+        "posterUrl": "https://example.com/posters/inception.jpg",
+        "performanceStartDate": "2025-10-01",
+        "performanceEndDate": "2025-10-31"
+    }
     ```
 
 
 - curl 명령 예시
 
     ```bash
       curl -i -X POST 'http://localhost:8080/api/show' \
-      -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MTIzNCIsInJvbGVzIjoiUk9MRV9ESVNUUklCVVRPUiIsInVzZXJJZCI6InRlc3QxMjM0Iiwibmlja05hbWUiOiJ0ZXN0IiwiaWF0IjoxNzU2NDM4MjIzLCJleHAiOjE3NTY0Mzg4MjN9.DN0wZb8BdKY-7Grd0KAALXf88KX3iF_tg6UmcfotkFOlbRoRnSuY1nNVUFfZk2TxP0hvju3A8AglK3mt_hnutQ' \
+      -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MTIzNCIsInJvbGVzIjoiUk9MRV9BRE1JTiIsInVzZXJJZCI6InRlc3QxMjM0Iiwibmlja05hbWUiOiJ0ZXN0IiwiaWF0IjoxNzU3MzExNDc5LCJleHAiOjE3NTczMTIwNzl9.xhEkuZEF0gZlvyX_F2kiAMEMGw_C2ZtGL8PmzLxhZQW32A9hmr6M0nauYEejXOFrZAb3nMdU3jFLxuhDWDbE2g' \
       -H 'Content-Type: application/json' \
       -d '{
-        "title": "인셉션",
-        "director": "크리스토퍼 놀란",
-        "runtimeMinutes": 148,
-        "genre": "SF",
-        "releaseDate": "2010-07-21",
-        "rating": "AGE12",
-        "synopsis": "타인의 꿈속에 진입해 아이디어를 주입하는 특수 임무를 수행하는 이야기.",
-        "posterUrl": "https://example.com/posters/inception.jpg",
-        "casts": [
-          "레오나르도 디카프리오",
-          "조셉 고든레빗",
-          "엘렌 페이지"
-        ]
-      }'
+            "title": "인셉션",
+            "type": "MUSICAL",
+            "rating": "AGE12",
+            "synopsis": "타인의 꿈속에 진입해 아이디어를 주입하는 특수 임무를 수행하는 이야기.",
+            "posterUrl": "https://example.com/posters/inception.jpg",
+            "performanceStartDate": "2025-10-01",
+            "performanceEndDate": "2025-10-31"
+          }'
     ```
 
 ### 응답
@@ -50,15 +52,16 @@
         "data": {
             "showId": 1
         },
-        "timestamp": "2024-06-10T12:34:56.789Z"
+        "timestamp": "2025-09-10T12:34:56.789Z"
     }
     ```
 
 ### 테스트
 
 - [x] 올바른 요청을 보내면 status가 SUCCESS이다
-- [ ] 올바른 요청을 보내면 응답 본문에 showId가 존재한다
-- [x] Authorization 헤더에 유효한 accessToken이 없으면 status가 UNAUTHORIZED이다 
+- [x] Authorization 헤더에 유효한 accessToken이 없으면 status가 UNAUTHORIZED이다
 - [x] title, director, runtimeMinutes, genre, releaseDate, rating이 비어있으면 BAD_REQUEST이다
-- [x] runtimeMinutes은 0 미만이면 BAD_REQUEST이다
-- [x] releaseDate는 yyyy-MM-dd 형태를 준수하지 않으면 BAD_REQUEST이다
+- [x] 허용되지 않은 타입이면 BAD_REQUEST이다
+- [x] 올바른 요청을 보내면 응답 본문에 showId가 존재한다
+- [x] 공연 시작일은 공연 종료일 이후면 INTERNAL_SERVER_ERROR이다
+- [x] 중복된 제목의 공연을 등록하면 INTERNAL_SERVER_ERROR가 발생한다
diff --git a/docs/specs/api/show_schedule_register.md b/docs/specs/api/show_schedule_register.md
@@ -0,0 +1,65 @@
+### 요청
+
+- 메서드: `POST`
+- 경로: `/api/show/schedule`
+- 헤더
+
+    ```
+    Content-Type: application/json
+    Authorization: Bearer <accessToken>
+    ```
+
+- 본문 예시
+
+    ```json
+    {
+      "showId": 1,
+      "hallId": 10,
+      "startAt": "2025-10-10T19:00:00",
+      "endAt": "2025-10-10T21:30:00",
+      "runtimeMinutes": 150
+    }
+    ```
+
+- curl 명령 예시
+
+    ```bash
+    curl -i -X POST 'http://localhost:8080/api/show/schedule' \
+    -H 'Content-Type: application/json' \
+    -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MTIzNCIsInJvbGVzIjoiUk9MRV9BRE1JTiIsInVzZXJJZCI6InRlc3QxMjM0Iiwibmlja05hbWUiOiJ0ZXN0IiwiaWF0IjoxNzU3MzExNDc5LCJleHAiOjE3NTczMTIwNzl9.xhEkuZEF0gZlvyX_F2kiAMEMGw_C2ZtGL8PmzLxhZQW32A9hmr6M0nauYEejXOFrZAb3nMdU3jFLxuhDWDbE2g' \
+    -d '{
+      "showId": 1,
+      "hallId": 1,
+      "startAt": "2025-10-10T19:00:00",
+      "endAt": "2025-10-10T21:30:00"
+    }'
+    ```
+
+---
+
+### 응답
+
+- 상태코드: `200 OK`
+- 본문 예시
+
+    ```json
+    {
+      "showId": 1
+    }
+    ```
+
+---
+
+### 테스트
+
+- [x] 올바른 접근 토큰과 유효한 요청을 보내면 SUCCESS 상태코드를 반환한다
+- [x] ADMIN 권한을 가진 사용자가 올바른 요청을 하는 경우 SUCCESS 상태코드를 반환한다
+- [x] 응답 본문에 scheduleId가 포함된다
+- [x] 권한이 없는 사용자 토큰으로 요청하면 FORBIDDEN 상태코드를 반환한다
+- [x] runtimeMinutes가 0 이하일 경우 BAD_REQUEST를 반환한다
+- [x] runtimeMinutes은 startAt과 endAt의 차이만큼이 아니면 BAD_REQUEST를 반환한다
+- [x] startAt이 endAt보다 늦은 경우 BAD_REQUEST를 반환한다
+- [x] 존재하지 않는 showId를 보내면 NOT_FOUND 상태코드를 반환한다
+- [x] 존재하지 않는 hallId를 보내면 NOT_FOUND 상태코드를 반환한다
+- [x] 공연 기간 범위를 벗어나는 startAt 또는 endAt을 보낼 경우 BAD_REQUEST를 반환한다
+- [x] 동일한 hallId와 시간이 겹치는 회차를 등록하려 하면 INTERNAL_SERVER_ERROR를 반환한다
diff --git a/docs/specs/domain.md b/docs/specs/domain.md
@@ -26,12 +26,11 @@ _Aggregate Root_
 - 포스터 URL(posterUrl)
 - 공연 시작일(performanceStartDate, yyyy-MM-dd)
 - 공연 종료일(performanceEndDate, yyyy-MM-dd)
+- 공연 스케줄(schedules: List\<ShowSchedule>)
 
 #### 행위
 - `create(command: ShowCreateCommand)`
-- `addSchedule(hallId, startAt, endAt, runtimeOverride)`
-- `setCasting(scheduleId, roleName, personName)`
-- `changePerformanceWindow(start, end)`
+- `registerSchedule(hallId, startAt, endAt, runtimeOverride)`
 
 #### 관련 타입
 - `ShowCreateCommand`
@@ -73,15 +72,10 @@ _Aggregate Root_
 - 주소(address)
 
 #### 행위
-- `addHall(name)`
-- `addSeat(hallId, rowLabel, number, viewGrade, accessibility)`
-- `defineGrade(hallId, name)`
+
+- `create(show,hallId,command)`
 
 #### 관련 타입
-- `CreateVenueCommand`
-- `AddHallCommand`
-- `AddSeatCommand`
-- `DefineGradeCommand`
 
 ---
 

diff --git a/docs/specs/policy/test.md b/docs/specs/policy/test.md
@@ -72,7 +72,7 @@
 
         // Act & Assert
         var response = testUtils.get("/test/with-auth")
-                .withHeader("Authorization", invalidToken)
+                .withAuthorization(invalidToken)
                 .assertFailure();
         assertThat(response.getStatus()).isEqualTo(UNAUTHORIZED);
         assertThat(response.getData()).isEqualTo("유효한 토큰이 없습니다.");

diff --git a/docs/todo.md b/docs/todo.md
@@ -15,4 +15,17 @@
 - [x] 리펙터링
 
 2025.08.29
-- [ ] `/api/members`와 같이 `/api`로 시작하지만 존재하지 않는 엔드포인트에 대한 처리가 `AuthenticationEntryPoint`에서 처리되고 있음
+
+- [x] `/api/members`와 같이 `/api`로 시작하지만 존재하지 않는 엔드포인트에 대한 처리가 `AuthenticationEntryPoint`에서 처리되고 있음
+
+2025.09.09
+
+- [ ] 모듈화 설계
+    - [ ] public 떡칠하지 말고 기본 접근제어자 적극 활용
+    - [ ] Spring Modulith 사용 가능한지 점검
+
+---
+
+- [ ] venue register
+- [ ] hall register
+- [ ] 누가 AR인가? venue vs hall
diff --git a/src/main/java/org/mandarin/booking/adapter/security/SecurityConfig.java b/src/main/java/org/mandarin/booking/adapter/security/SecurityConfig.java
@@ -6,6 +6,10 @@
 import org.springframework.context.annotation.Configuration;
 import org.springframework.core.annotation.Order;
 import org.springframework.http.HttpMethod;
+import org.springframework.security.access.expression.method.DefaultMethodSecurityExpressionHandler;
+import org.springframework.security.access.expression.method.MethodSecurityExpressionHandler;
+import org.springframework.security.access.hierarchicalroles.RoleHierarchy;
+import org.springframework.security.access.hierarchicalroles.RoleHierarchyImpl;
 import org.springframework.security.authentication.AuthenticationProvider;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
 import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
@@ -29,17 +33,18 @@ public BCryptPasswordEncoder bCryptPasswordEncoder() {
     @Bean
     @Order(1)
     public SecurityFilterChain apiChain(HttpSecurity http,
-                                                   AuthenticationProvider authenticationProvider,
-                                                   AuthenticationEntryPoint authenticationEntryPoint,
-                                                   AccessDeniedHandler accessDeniedHandler)
+                                        AuthenticationProvider authenticationProvider,
+                                        AuthenticationEntryPoint authenticationEntryPoint,
+                                        AccessDeniedHandler accessDeniedHandler)
             throws Exception {
         http
                 .securityMatcher("/api/**")
                 .authorizeHttpRequests(auth -> auth
                         .requestMatchers(HttpMethod.POST, "/api/member").permitAll()
                         .requestMatchers("/api/auth/login").permitAll()
                         .requestMatchers("/api/auth/reissue").permitAll()
-                        .requestMatchers(HttpMethod.POST, "/api/show").hasAuthority("ROLE_DISTRIBUTOR")
+                        .requestMatchers(HttpMethod.POST, "/api/show/schedule").hasAuthority("ROLE_DISTRIBUTOR")
+                        .requestMatchers(HttpMethod.POST, "/api/show").hasAuthority("ROLE_ADMIN")
                         .anyRequest().authenticated()
                 )
                 .formLogin(AbstractHttpConfigurer::disable)
@@ -53,6 +58,21 @@ public SecurityFilterChain apiChain(HttpSecurity http,
         return http.build();
     }
 
+    @Bean
+    static RoleHierarchy roleHierarchy() {
+        return RoleHierarchyImpl.withDefaultRolePrefix()
+                .role("ADMIN").implies("DISTRIBUTOR")
+                .role("DISTRIBUTOR").implies("USER")
+                .build();
+    }
+
+    @Bean
+    static MethodSecurityExpressionHandler methodSecurityExpressionHandler(RoleHierarchy roleHierarchy) {
+        DefaultMethodSecurityExpressionHandler expressionHandler = new DefaultMethodSecurityExpressionHandler();
+        expressionHandler.setRoleHierarchy(roleHierarchy);
+        return expressionHandler;
+    }
+
     @Bean
     @Order(2)
     SecurityFilterChain publicChain(HttpSecurity http) throws Exception {
-Original file line number
+Diff line change
@@ Expand Up / @@ -3,3 +3,4 @@ @@
     /build
     .idea
     .aiassistant/rules/AGENTS.md
+    /src/docs/