docs(notice): v2 최근 공지 계약과 클라이언트 연동을 정의한다

2026-10-28 16:20:06 +09:00
parent 58f3286380
commit b9cccda1a9
3 changed files with 135 additions and 0 deletions
@@ -0,0 +1,22 @@
+# 클라이언트 전달용 프롬프트
+
+아래 내용을 클라이언트 작업자에게 전달한다. 서버 코드 구현·로컬 검증과 실제 배포는 별개다.
+
+```text
+기존 공지 UI, 레이아웃, 스타일, 진입점, 상세 이동과 내비게이션을 유지하면서 최근 공지 데이터만 아래 새 계약으로 연결해 주세요. UI 재설계나 캐러셀 추가는 하지 마세요.
+
+API: 익명 GET /api/v2/notices/latest
+요청 body/query와 인증 필수 요구는 없습니다.
+응답: ApiResponse<List<NoticeItem>>
+NoticeItem: id(number), title(string), content(string), date(string, yyyy-MM-dd).
+data는 활성 공지 중 id 내림차순 최대 3개입니다. 순서를 다시 정렬하지 말고 서버 순서를 사용하세요. date는 이미 기존 UTC→Asia/Seoul 규칙으로 포맷된 문자열이므로 다시 timezone 변환하지 마세요. title/content는 전체 문자열을 유지하세요.
+활성 공지가 없으면 data:[]이며 null이 아닙니다. 1/2개면 해당 개수만 표시하고 3개를 채우려고 중복하지 마세요. 기존 단일 공지 v1과 홈 응답 스키마는 변경되지 않습니다.
+
+서버 배포가 확인되기 전에는 개발 환경의 명시적 mock 모드로만 작업하세요. 이 서버 작업은 운영 배포를 수행하지 않습니다. 실제 404/오류를 mock이나 v1로 자동 fallback하지 말고, 배포 후 명시적으로 API 연결을 전환하세요. production mock은 금지합니다.
+
+공통 envelope의 success를 HTTP 상태와 함께 검사하세요. 성공 응답에는 message:null과 errorProperty:null이 생략 없이 포함됩니다(실제 HTTP 검증 완료). 기존 정책상 HTTP 200에도 success:false가 올 수 있습니다. 조회 실패를 정상 빈 목록으로 숨기지 말고 기존 화면의 오류 처리와 로딩 상태를 유지하세요. 보안/HTTP 오류가 모두 동일한 envelope라고 가정하지 마세요.
+
+0/1/2/3개 fixture를 각각 테스트하세요. 0개일 때 기존 빈 상태, 1/2개일 때 중복 없음, 3개일 때 id 역순 유지, 상세 이동 시 동일 id/전체 본문 보존을 확인하세요. 긴 제목·여러 줄 본문·KST 날짜 경계도 기존 UI 안에서 확인하세요.
+범위 밖: 캐러셀, 자동 fallback, 캐싱, 페이지네이션, 홈 응답 변경, 기존 내비게이션 변경.
+계약: docs/20261028_최근공지사항_v2/api-contract.md
+```