From dde677b45f23c23050d41624ff7a105fb120e585 Mon Sep 17 00:00:00 2001
From: sweetRainShin <servdb99@gmail.com>
Date: Sun, 17 May 2026 23:21:10 +0900
Subject: [PATCH 1/2] =?UTF-8?q?docs:=20adoc=20template=20=EC=9E=91?=
 =?UTF-8?q?=EC=84=B1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/docs/asciidoc/program-api.adoc | 417 +++++++++++++++++++++++++++++
 1 file changed, 417 insertions(+)
 create mode 100644 src/docs/asciidoc/program-api.adoc

diff --git a/src/docs/asciidoc/program-api.adoc b/src/docs/asciidoc/program-api.adoc
new file mode 100644
index 0000000..840db17
--- /dev/null
+++ b/src/docs/asciidoc/program-api.adoc
@@ -0,0 +1,417 @@
+= Program Service API 문서
+:doctype: book
+:icons: font
+:source-highlighter: highlightjs
+:toc: left
+:toc-title: 목차
+:toclevels: 3
+:sectlinks:
+:snippets: ../../../build/generated-snippets
+
+== 프로그램 (Program)
+
+=== 프로그램 등록
+
+`POST /api/v1/programs`
+
+HOST 또는 ADMIN 역할만 요청할 수 있습니다.
+등록 시 초기 상태는 항상 `DRAFT`입니다.
+
+==== 요청 헤더
+include::{snippets}/program/create/request-headers.adoc[]
+
+==== 요청 본문
+include::{snippets}/program/create/request-fields.adoc[]
+
+==== 요청 예시
+include::{snippets}/program/create/http-request.adoc[]
+
+==== 응답 필드
+include::{snippets}/program/create/response-fields.adoc[]
+
+==== 응답 예시
+include::{snippets}/program/create/http-response.adoc[]
+
+==== 오류 — 입력값 유효성 오류 (400)
+include::{snippets}/program/create-400/http-request.adoc[]
+include::{snippets}/program/create-400/http-response.adoc[]
+
+==== 오류 — 권한 없음 (403)
+include::{snippets}/program/create-403/http-request.adoc[]
+include::{snippets}/program/create-403/http-response.adoc[]
+
+'''
+
+=== 프로그램 목록 조회
+
+`GET /api/v1/programs`
+
+모든 역할이 요청할 수 있습니다.
+카테고리·키워드·지역·날짜 필터와 정렬을 지원합니다.
+
+==== 요청 파라미터
+include::{snippets}/program/search/query-parameters.adoc[]
+
+==== 요청 예시
+include::{snippets}/program/search/http-request.adoc[]
+
+==== 응답 필드
+include::{snippets}/program/search/response-fields.adoc[]
+
+==== 응답 예시
+include::{snippets}/program/search/http-response.adoc[]
+
+'''
+
+=== 프로그램 상세 조회
+
+`GET /api/v1/programs/{programId}`
+
+모든 역할이 요청할 수 있습니다.
+스케줄·잔여 좌석 수를 포함하여 반환합니다.
+
+==== 경로 파라미터
+include::{snippets}/program/get/path-parameters.adoc[]
+
+==== 요청 예시
+include::{snippets}/program/get/http-request.adoc[]
+
+==== 응답 필드
+include::{snippets}/program/get/response-fields.adoc[]
+
+==== 응답 예시
+include::{snippets}/program/get/http-response.adoc[]
+
+==== 오류 — 프로그램 없음 (404)
+include::{snippets}/program/get-404/http-request.adoc[]
+include::{snippets}/program/get-404/http-response.adoc[]
+
+'''
+
+=== 프로그램 수정
+
+`PATCH /api/v1/programs/{programId}`
+
+HOST 또는 ADMIN 역할만 요청할 수 있습니다.
+null 필드는 기존 값을 유지합니다.
+
+[NOTE]
+====
+* `DRAFT` 상태: title·category·theme·posterUrl·description 모두 수정 가능
+* `ON_SALE` 상태: posterUrl·description만 수정 가능 (title·category·theme 수정 불가)
+* `CANCELLED` / `CLOSED` 상태: 수정 불가
+====
+
+==== 요청 헤더
+include::{snippets}/program/update-draft/request-headers.adoc[]
+
+==== 경로 파라미터
+include::{snippets}/program/update-draft/path-parameters.adoc[]
+
+==== 요청 본문
+include::{snippets}/program/update-draft/request-fields.adoc[]
+
+==== DRAFT 상태 수정
+
+===== 요청 예시
+include::{snippets}/program/update-draft/http-request.adoc[]
+
+===== 응답 예시
+include::{snippets}/program/update-draft/http-response.adoc[]
+
+==== 오류 — ON_SALE 상태에서 title 수정 시도 (422)
+include::{snippets}/program/update-422-on-sale/http-request.adoc[]
+include::{snippets}/program/update-422-on-sale/http-response.adoc[]
+
+==== 오류 — CANCELLED 상태 수정 시도 (422)
+include::{snippets}/program/update-422-cancelled/http-request.adoc[]
+include::{snippets}/program/update-422-cancelled/http-response.adoc[]
+
+'''
+
+=== 프로그램 삭제
+
+`DELETE /api/v1/programs/{programId}`
+
+HOST 또는 ADMIN 역할만 요청할 수 있습니다.
+`DRAFT` 상태에서만 삭제할 수 있습니다.
+
+==== 요청 헤더
+include::{snippets}/program/delete/request-headers.adoc[]
+
+==== 경로 파라미터
+include::{snippets}/program/delete/path-parameters.adoc[]
+
+==== 요청 예시
+include::{snippets}/program/delete/http-request.adoc[]
+
+==== 응답 예시
+include::{snippets}/program/delete/http-response.adoc[]
+
+==== 오류 — DRAFT 아닌 상태 삭제 시도 (422)
+include::{snippets}/program/delete-422/http-request.adoc[]
+include::{snippets}/program/delete-422/http-response.adoc[]
+
+'''
+
+== 상태 전이 (Status Transition)
+
+프로그램 상태 전이 규칙은 다음과 같습니다.
+
+[source]
+----
+DRAFT ──publish──▶ ON_SALE ──cancel──▶ CANCELLED
+                         └──close───▶ CLOSED
+SOLD_OUT ──────────close──▶ CLOSED
+----
+
+NOTE: `DRAFT → CANCELLED` 직접 전이는 허용되지 않습니다.
+
+=== 판매 시작 (DRAFT → ON_SALE)
+
+`PATCH /api/v1/programs/{programId}/publish`
+
+스케줄과 가격등급이 모두 등록된 경우에만 전이할 수 있습니다.
+
+==== 요청 헤더
+include::{snippets}/program/publish/request-headers.adoc[]
+
+==== 경로 파라미터
+include::{snippets}/program/publish/path-parameters.adoc[]
+
+==== 요청 예시
+include::{snippets}/program/publish/http-request.adoc[]
+
+==== 응답 필드
+include::{snippets}/program/publish/response-fields.adoc[]
+
+==== 응답 예시
+include::{snippets}/program/publish/http-response.adoc[]
+
+==== 오류 — 잘못된 상태 전이 (422)
+include::{snippets}/program/publish-422/http-request.adoc[]
+include::{snippets}/program/publish-422/http-response.adoc[]
+
+'''
+
+=== 프로그램 취소 (→ CANCELLED)
+
+`PATCH /api/v1/programs/{programId}/cancel`
+
+==== 경로 파라미터
+include::{snippets}/program/cancel/path-parameters.adoc[]
+
+==== 요청 예시
+include::{snippets}/program/cancel/http-request.adoc[]
+
+==== 응답 필드
+include::{snippets}/program/cancel/response-fields.adoc[]
+
+==== 응답 예시
+include::{snippets}/program/cancel/http-response.adoc[]
+
+'''
+
+=== 프로그램 종료 (→ CLOSED)
+
+`PATCH /api/v1/programs/{programId}/close`
+
+모든 스케줄의 공연이 종료된 이후에만 전이할 수 있습니다.
+
+==== 경로 파라미터
+include::{snippets}/program/close/path-parameters.adoc[]
+
+==== 요청 예시
+include::{snippets}/program/close/http-request.adoc[]
+
+==== 응답 필드
+include::{snippets}/program/close/response-fields.adoc[]
+
+==== 응답 예시
+include::{snippets}/program/close/http-response.adoc[]
+
+'''
+
+== 스케줄 (Schedule)
+
+=== 스케줄 등록
+
+`POST /api/v1/programs/{programId}/schedules`
+
+HOST 또는 ADMIN 역할만 요청할 수 있습니다.
+동일 공연장의 시간이 겹치는 스케줄은 등록할 수 없습니다 (V-04).
+
+==== 요청 헤더
+include::{snippets}/program/schedule/create/request-headers.adoc[]
+
+==== 경로 파라미터
+include::{snippets}/program/schedule/create/path-parameters.adoc[]
+
+==== 요청 본문
+include::{snippets}/program/schedule/create/request-fields.adoc[]
+
+==== 요청 예시
+include::{snippets}/program/schedule/create/http-request.adoc[]
+
+==== 응답 예시
+include::{snippets}/program/schedule/create/http-response.adoc[]
+
+==== 오류 — venueId 누락 (400)
+include::{snippets}/program/schedule/create-400/http-request.adoc[]
+include::{snippets}/program/schedule/create-400/http-response.adoc[]
+
+==== 오류 — 공연장 시간 겹침 (409)
+include::{snippets}/program/schedule/create-409/http-request.adoc[]
+include::{snippets}/program/schedule/create-409/http-response.adoc[]
+
+'''
+
+=== 스케줄 목록 조회
+
+`GET /api/v1/programs/{programId}/schedules`
+
+모든 역할이 요청할 수 있습니다.
+
+==== 경로 파라미터
+include::{snippets}/program/schedule/list/path-parameters.adoc[]
+
+==== 요청 예시
+include::{snippets}/program/schedule/list/http-request.adoc[]
+
+==== 응답 예시
+include::{snippets}/program/schedule/list/http-response.adoc[]
+
+'''
+
+=== 스케줄 상세 조회
+
+`GET /api/v1/programs/{programId}/schedules/{scheduleId}`
+
+모든 역할이 요청할 수 있습니다.
+
+==== 경로 파라미터
+include::{snippets}/program/schedule/get/path-parameters.adoc[]
+
+==== 요청 예시
+include::{snippets}/program/schedule/get/http-request.adoc[]
+
+==== 응답 필드
+include::{snippets}/program/schedule/get/response-fields.adoc[]
+
+==== 응답 예시
+include::{snippets}/program/schedule/get/http-response.adoc[]
+
+==== 오류 — 스케줄 없음 (404)
+include::{snippets}/program/schedule/get-404/http-request.adoc[]
+include::{snippets}/program/schedule/get-404/http-response.adoc[]
+
+'''
+
+=== 스케줄 수정
+
+`PATCH /api/v1/programs/{programId}/schedules/{scheduleId}`
+
+HOST 또는 ADMIN 역할만 요청할 수 있습니다.
+null 필드는 기존 값을 유지합니다.
+
+==== 경로 파라미터
+include::{snippets}/program/schedule/update/path-parameters.adoc[]
+
+==== 요청 본문
+include::{snippets}/program/schedule/update/request-fields.adoc[]
+
+==== 요청 예시
+include::{snippets}/program/schedule/update/http-request.adoc[]
+
+==== 응답 예시
+include::{snippets}/program/schedule/update/http-response.adoc[]
+
+'''
+
+=== 스케줄 삭제
+
+`DELETE /api/v1/programs/{programId}/schedules/{scheduleId}`
+
+HOST 또는 ADMIN 역할만 요청할 수 있습니다.
+`DRAFT` 상태의 프로그램 스케줄만 삭제할 수 있습니다.
+
+==== 경로 파라미터
+include::{snippets}/program/schedule/delete/path-parameters.adoc[]
+
+==== 요청 예시
+include::{snippets}/program/schedule/delete/http-request.adoc[]
+
+==== 응답 예시
+include::{snippets}/program/schedule/delete/http-response.adoc[]
+
+'''
+
+== 가격 등급 (PriceGrade)
+
+=== 가격 등급 추가
+
+`POST /api/v1/programs/{programId}/schedules/{scheduleId}/price-grades`
+
+HOST 또는 ADMIN 역할만 요청할 수 있습니다.
+
+[NOTE]
+====
+* `SEATED` / `STANDING` 타입: `sectionId` 필수
+* `FREE` 타입: `sectionId` null 허용
+====
+
+==== 요청 헤더
+include::{snippets}/program/price-grade/add/request-headers.adoc[]
+
+==== 경로 파라미터
+include::{snippets}/program/price-grade/add/path-parameters.adoc[]
+
+==== 요청 본문
+include::{snippets}/program/price-grade/add/request-fields.adoc[]
+
+==== 요청 예시
+include::{snippets}/program/price-grade/add/http-request.adoc[]
+
+==== 응답 예시
+include::{snippets}/program/price-grade/add/http-response.adoc[]
+
+==== 오류 — 등급명 누락 (400)
+include::{snippets}/program/price-grade/add-400/http-request.adoc[]
+include::{snippets}/program/price-grade/add-400/http-response.adoc[]
+
+'''
+
+=== 가격 등급 목록 조회
+
+`GET /api/v1/programs/{programId}/schedules/{scheduleId}/price-grades`
+
+모든 역할이 요청할 수 있습니다.
+
+==== 경로 파라미터
+include::{snippets}/program/price-grade/list/path-parameters.adoc[]
+
+==== 요청 예시
+include::{snippets}/program/price-grade/list/http-request.adoc[]
+
+==== 응답 필드
+include::{snippets}/program/price-grade/list/response-fields.adoc[]
+
+==== 응답 예시
+include::{snippets}/program/price-grade/list/http-response.adoc[]
+
+'''
+
+=== 가격 등급 삭제
+
+`DELETE /api/v1/programs/{programId}/schedules/{scheduleId}/price-grades/{gradeLabel}`
+
+HOST 또는 ADMIN 역할만 요청할 수 있습니다.
+
+==== 경로 파라미터
+include::{snippets}/program/price-grade/delete/path-parameters.adoc[]
+
+==== 요청 예시
+include::{snippets}/program/price-grade/delete/http-request.adoc[]
+
+==== 응답 예시
+include::{snippets}/program/price-grade/delete/http-response.adoc[]

From ca7494c6d9b20bc384d2bcf15132ea6ec4d2b5ea Mon Sep 17 00:00:00 2001
From: sweetRainShin <servdb99@gmail.com>
Date: Mon, 18 May 2026 18:18:21 +0900
Subject: [PATCH 2/2] =?UTF-8?q?refactor:=20todo=20=EC=A3=BC=EC=84=9D=20?=
 =?UTF-8?q?=EC=A0=9C=EA=B1=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../java/com/firstticket/programservice/domain/Program.java  | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/src/main/java/com/firstticket/programservice/domain/Program.java b/src/main/java/com/firstticket/programservice/domain/Program.java
index 61277dc..3916dfa 100644
--- a/src/main/java/com/firstticket/programservice/domain/Program.java
+++ b/src/main/java/com/firstticket/programservice/domain/Program.java
@@ -102,9 +102,6 @@ public static Program create(String title, String category, String theme,
 
     // -----------schedule 관련 -------------------------------------------
 
-    //TODO: 개별 Schedule 취소 기능 추가 시 ScheduleStatus 도입 여부 고려
-    //      → 기본 기능 구현 후 고도화 시 feature/schedule-status 브랜치에서 작업
-
     /**
      * 스케줄 추가는 반드시 Program을 통해서만 가능
      * SOLD_OUT 상태라도 새 회차를 추가하면 다시 판매가 가능해지므로, 스케줄 추가가 가능합니다.
@@ -183,8 +180,6 @@ public void publish() {
      * 공연을 취소(CANCELLED) 상태로 전환합니다.
      * 취소 후 Kafka ProgramCancelledEvent 발행은
      * Application 계층에서 처리
-     * TODO: Program 취소 시 하위 Schedule도 함께 CANCELLED 처리 예정
-     *       → feature/schedule-status 브랜치에서 작업
      */
     public void cancel() {
         status.validateTransition(ProgramStatus.CANCELLED);