[BE] Curation v2 시음회·프로그램 장소검색 requestSpec 계약 정렬

[bottlenote-app]

배경

현재 Admin 시음회 form은 requestSpec에 없는 placeName을 FE에서 하드코딩으로 주입하고, 장소검색 UI를 연결한 뒤 submit payload에도 포함하고 있다.

• PROGRAM의 placeName, address는 현재 x-field-style: plain-text이다.
• x-tag 기반 매칭은 없다.
• Admin 주소검색 renderer 계약은 x-field-style: address-search이다.

추가 필드나 임의 payload 허용에 의존하지 않고, requestSpec을 SSoT로 정렬한다.

요구사항

1. WHISKY_TASTING_EVENT requestSpec

placeName을 정식 property 및 required 필드로 추가한다.

• 타입: string
• maxLength: 100
• x-display-name: 장소명
• x-field-style: address-search

2. PROGRAM 주소검색 계약

PROGRAM.address의 x-field-style을 plain-text에서 address-search로 변경한다.

아래 저장 의미를 requestSpec 또는 계약 문서에서 명확히 정의한다.

값	저장 의미
placeName	장소검색 선택 결과의 장소명
선택 주소	장소검색 선택 결과의 실제 주소
상세 위치	건물명·층·호수 등 사용자가 추가 입력하는 세부 위치

3. curation-spec 상세 API 반영 확인

Admin curation-spec 상세 API가 반환하는 실제 requestSpec에도 위 변경이 반영되는지 확인하고, 스키마 정의와 응답 간 불일치가 없게 한다.

4. 호환성·회귀 확인

• 기존 시음회·프로그램 생성/수정 payload의 호환성을 확인한다.
• Product detail/feed에 대한 회귀 여부를 확인한다.

FE 연계 및 후속 작업 범위

현재 Admin renderer는 장소 선택 시 장소명을 자동 동기화하는 로직이 barAddress에만 하드코딩되어 있다. 따라서 PROGRAM.address 또는 시음회 placeName에 address-search만 적용하면 선택 결과가 어느 필드에 저장되는지 불완전할 수 있다.

백엔드 계약에서 선택 결과를 placeName, 실제 주소, 상세 위치에 각각 어떻게 매핑하는지 확정하고, 다음 FE 후속 작업 범위를 명시한다.

• barAddress 전용 자동 동기화 의존을 제거하거나 공통 매핑으로 일반화한다.
• WHISKY_TASTING_EVENT 및 PROGRAM의 주소검색 필드별 선택 결과 저장 대상을 계약에 맞게 연결한다.
• 기존 form 초기값·수정 화면·submit payload가 정식 requestSpec만을 따르도록 정리한다.

완료 기준

• WHISKY_TASTING_EVENT.placeName이 요구한 정식 requestSpec 필드로 제공된다.
• PROGRAM.address가 address-search 계약으로 제공되고 저장 의미가 문서화된다.
• Admin curation-spec 상세 API 응답에서 변경된 requestSpec을 확인한다.
• 기존 생성·수정 payload 호환성 및 Product detail/feed 회귀 확인 결과를 기록한다.
• FE가 적용할 필드 매핑 및 후속 작업 범위가 합의 가능한 형태로 명시된다.

[bottlenote-app]

리포지토리 동기화 근거입니다.

• API-server PR #681는 workspace #344를 명시 참조하지만 base Whale0928/feed-read-path 대상의 Open·미병합 PR입니다. head SHA는 041ae243057216a3f3dee9ab7df2a05823fffbd6입니다.
• 동일 SHA의 CI run 30340541282는 in_progress이며 pull-request CI입니다. 개발·운영 배포 workflow 성공은 확인되지 않았습니다.
• 최신 backend/v1.1.16 릴리즈의 target SHA 2c29c1aa89e956e2195f9971ccac9eff8ef4a3ed는 위 SHA와 다르고, 릴리즈 노트에 workspace [BE] Curation v2 시음회·프로그램 장소검색 requestSpec 계약 정렬 #344 명시 참조가 없습니다.

PR 병합, 개발 배포, 실제 환경 반영/수용 QA가 모두 미확인입니다. 또한 이슈 완료 기준의 required 여부·기존 payload 호환성·상세 API 반영 및 FE 연계 범위는 PR 설명과 이슈 요구사항 사이에 확인이 필요합니다. 따라서 상태: 예정을 유지하며 운영배포 또는 종결 근거는 없습니다.

[Whale0928]

백엔드 구현했습니다. PR: bottle-note/bottle-note-api-server#681

완료 기준 대응

• WHISKY_TASTING_EVENT.placeName이 정식 requestSpec 필드로 제공된다
• PROGRAM.address가 address-search 계약으로 제공되고 저장 의미가 문서화된다
• Admin curation-spec 상세 API 응답에서 변경된 requestSpec을 확인
• 기존 생성·수정 payload 호환성 및 Product detail/feed 회귀 확인
• FE가 적용할 필드 매핑 및 후속 작업 범위 명시

필드 매핑 (계약 확정)

장소검색 선택 결과	WHISKY_TASTING_EVENT	PROGRAM
장소명	placeName	placeName
우편번호	zipCode	zipCode
선택 주소	barAddress	address
상세 위치(사용자 입력)	detailAddress	detailLocation

barAddress와 detailAddress는 이름·의미 모두 현행 유지했습니다. 이슈 표의 "선택 주소"가 barAddress, "상세 위치"가 detailAddress에 대응합니다.

이슈 범위에서 조정한 것

1. placeName·zipCode를 required가 아닌 optional로 넣었습니다.

이슈는 placeName을 required로 요구했으나, 개발 DB 실측 결과 시음회 14건 중 2건에 placeName이 없고 zipCode는 15건 전부에 없습니다. required로 올리면 해당 건이 어드민에서 저장할 때 CURATION_PAYLOAD_INVALID로 실패합니다. FE가 장소검색을 연결해 데이터가 채워진 뒤 required 승격을 후속으로 제안합니다.

2. PROGRAM.placeName도 address-search로 바꿨습니다.

이슈는 address만 언급했으나 한쪽만 바꾸면 시음회와 계약이 어긋나 FE가 필드별로 다르게 처리해야 합니다.

3. 우편번호 필드를 추가했습니다.

이슈 표의 "선택 주소"에 우편번호가 포함되지 않아 별도 필드로 분리했습니다. 프로젝트 관례를 따라 zipCode입니다 (선례: review의 LocationInfo, DB zip_code varchar(5)).

확인된 현재 상태

• FE가 주입한 placeName은 curation_extension.payload에 실제로 저장되고 있습니다 (시음회 14건 중 12건). CurationPayloadValidator가 미정의 property를 차단하지 않기 때문입니다
• 상세 API는 원본 payload를 그대로 내보내므로 placeName이 이미 응답에 나옵니다. 반면 피드 API에는 없었습니다 — responseSpec에 없어 x-feed 투영에서 빠졌습니다. 이번에 responseSpec에 추가하고 x-feed를 켜서 피드에도 노출됩니다
• PROGRAM은 placeName이 이미 x-feed로 노출되고 있었습니다. 시음회를 맞춘 것이 일관성 회복입니다

알아두실 점

CurationPayloadValidator는 pattern을 검증하지 않습니다. 지원 제약은 type·required·nullable·enum·maxLength·minLength·maximum·minimum·maxItems·minItems뿐입니다. 그래서 zipCode에 minLength: 5 + maxLength: 5를 함께 걸어 길이는 서버가 강제하고, pattern: ^\d{5}$는 숫자 제약을 FE·문서용으로 남겼습니다. 검증기의 pattern 지원은 후속 과제입니다.

배포 순서

PR #681은 bottle-note/bottle-note-api-server#680 위에 쌓여 있습니다. #680 → #681 순서로 머지해야 합니다.

배포 시 responseSpec이 바뀌므로 #680의 재생성 로직이 자동 실행되어 시음회 14건 + 프로그램 1건의 feed_payload에 placeName이 채워집니다. 별도 backfill 작업은 필요 없습니다.

FE 후속 작업

• barAddress 전용 자동 동기화 의존 제거 또는 공통 매핑으로 일반화
• 위 매핑표대로 선택 결과를 각 필드에 연결 (우편번호 포함)
• form 초기값·수정 화면·submit payload가 정식 requestSpec만 따르도록 정리

[bottlenote-app]

리포지토리 동기화 근거입니다.

• API-server PR #681은 workspace #344를 명시 참조하며 base Whale0928/feed-read-path에 병합된 SHA는 de9396f224f99405e3e5506e9639115c3fc1421d입니다. 동일 SHA의 CI run 30342154409은 completed/success이나 pull-request CI입니다. 해당 SHA의 성공한 개발 배포 workflow는 확인되지 않았습니다.
• 최신 backend/v1.1.16 릴리즈의 target SHA는 2c29c1aa89e956e2195f9971ccac9eff8ef4a3ed로 위 SHA와 다르고, 릴리즈 노트에 workspace [BE] Curation v2 시음회·프로그램 장소검색 requestSpec 계약 정렬 #344 명시 참조가 없습니다.

상태: 예정을 유지합니다. 개발 배포·실제 환경 반영·수용 QA가 미확인이고, 이슈의 placeName required 요구와 PR의 optional 구현 차이, FE 연계 완료 여부도 확인이 필요하므로 운영배포 또는 종결 근거가 없습니다.

[Whale0928]

후속 커밋 2건을 main에 반영했습니다. 개발 배포 완료.

1. 스펙 version 승격 (2.0.0 → 3.0.0)

Admin FE가 스펙 스키마를 specId + version으로 캐시해서(#321), 버전을 안 올리면 이미 캐시한 어드민에게 새 필드가 안 보입니다. 두 스펙 모두 DB version이 3으로 올라갔으니 캐시가 갱신됩니다.

2. zipCode 형식 검증 시작

이제 zipCode는 숫자 5자리가 아니면 400입니다. 이전에는 pattern이 검증되지 않아 아무 값이나 통과했습니다.

FE 연결 작업은 별도 이슈로 분리했습니다: #348

[bottlenote-app]

리포지토리 동기화 근거입니다.

• API-server PR #681은 workspace #344를 본문에서 명시 참조하며, Whale0928/feed-read-path 병합 SHA는 de9396f224f99405e3e5506e9639115c3fc1421d입니다. 해당 SHA의 CI run 30342154409은 completed/success입니다.
• PR #680의 main 병합 SHA 28976f65f2b66488e76bba75ce75297685e0cad3에 대한 개발 배포 run 30342688307은 completed/success이나, 이 SHA는 PR #681의 병합 SHA와 다릅니다.
• 최신 backend/v1.1.16 릴리즈의 target SHA 2c29c1aa89e956e2195f9971ccac9eff8ef4a3ed는 위 변경 SHA들과 다르고, 릴리즈 노트에 workspace [BE] Curation v2 시음회·프로그램 장소검색 requestSpec 계약 정렬 #344 명시 참조가 없습니다.

현재 상태: 개발배포 라벨은 변경하지 않았습니다. PR #681의 정확한 병합 SHA에 대응하는 성공한 개발 배포 workflow, 실제 환경 수용 QA, 이슈 본문의 placeName required 요구와 optional 구현의 합의, FE 연계 완료 여부가 미확인입니다. 따라서 운영배포 또는 종결 근거는 없습니다.

[bottlenote-app]

리포지토리 동기화 근거입니다.

• API-server PR #681은 workspace #344를 본문에서 명시 참조하며 병합 SHA는 de9396f224f99405e3e5506e9639115c3fc1421d입니다. 같은 SHA의 CI run 30342154409은 completed/success이나 pull-request CI입니다.
• PR #680의 main 병합 SHA 28976f65f2b66488e76bba75ce75297685e0cad3에 대한 개발 배포 run 30342688307은 성공했지만 #681의 병합 SHA와 일치하지 않습니다. #681 SHA의 성공한 개발 배포 workflow는 확인되지 않았습니다.
• 최신 backend/v1.1.16 릴리즈의 target SHA는 2c29c1aa89e956e2195f9971ccac9eff8ef4a3ed이고, 릴리즈 노트에 workspace [BE] Curation v2 시음회·프로그램 장소검색 requestSpec 계약 정렬 #344 명시 참조가 없습니다.

현재 상태: 개발배포는 변경하지 않습니다. 실제 개발 환경 수용 QA, 이슈 본문의 placeName required 요구와 optional 구현의 합의, FE 연계 완료 여부 및 운영 릴리즈·배포/QA가 미확인이므로 상태: 운영배포 또는 종결 근거가 없습니다.