feat: help content api/#713

[chaeyn]

변경사항

• 클라이언트에 하드코딩되어 있던 도움말/툴팁 내용을 서버에서 관리할 수 있도록 HelpContent 도메인과 저장소를 추가했습니다.
• GET /api/help-contents/{key}는 UTF-8 텍스트와 ETag를 반환하며, 동일한 If-None-Match 요청에는 Spring의 조건부 요청 처리로 304 Not Modified를 응답합니다.
• POST /api/admin/help-contents로 관리자가 새 도움말 키와 전체 텍스트를 생성할 수 있습니다. 중복 키는 409 Conflict로 거부합니다.
• PUT /api/admin/help-contents/{key}로 기존 전체 텍스트를 수정할 수 있으며, JPA 낙관적 락으로 동시 수정에 따른 Lost Update를 방지합니다.
• Flyway 마이그레이션으로 EXP, 쿠키, 티어 보상 등 현재 앱에서 사용하는 7개 툴팁의 초기 내용을 등록했습니다.

변경 이유

클라이언트 릴리즈 이후 도움말 문구나 보상 기준이 실제 서버 정책과 달라질 경우, 사용자가 잘못된 안내를 보거나 문의를 남길 수 있습니다.

서버를 운영 원본으로 두고 ETag로 변경된 내용만 내려받을 수 있게 해, 클라이언트 재배포 없이 기존 안내를 수정하거나 새 안내를 추가할 수 있습니다. 클라이언트는 마지막으로 받은 내용을 로컬에 보관해 서버 연결이 불안정한 상황에서도 기존 안내를 계속 표시할 수 있습니다.

API 동작

• 새 안내 생성: POST /api/admin/help-contents → 201 Created, JPA가 초기 version 0 부여
• 최초 또는 변경된 문서 조회: 200 OK + 텍스트 본문 + ETag
• 동일 버전 재조회: 304 Not Modified
• 기존 안내 수정: PUT /api/admin/help-contents/{key} → JPA가 version 증가 및 동시 수정 검증

관련 이슈

Closes #713

검증

• ./gradlew test --tests '*HelpContent*'
• ./gradlew test
• ./gradlew clean build

[gemini-code-assist]

Code Review

This pull request introduces a new feature for managing and retrieving help content (tooltips) with ETag-based caching. It adds the necessary domain entities, JPA persistence layers, application services, and REST controllers for both public retrieval and admin updates, along with OpenAPI documentation, security configurations, database migrations, and unit tests. The code review feedback highlights three key improvement opportunities: removing the produces attribute from the public GET endpoint to avoid 406 errors during exception handling, utilizing Spring's built-in WebRequest.checkNotModified to simplify ETag validation, and applying JPA's @Version annotation to the entity's version field to prevent lost updates via optimistic locking.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Finefinee]

코드 본문에 있는 리뷰 외에도 AI 리뷰를 한 결과
현재 API로는 일반적인 Lost Update를 막지 못합니다.
UpdateHelpContentDto.java의 PUT 요청에는 클라이언트가 읽었던 버전이 없습니다.

동시에 같은 키를 생성하면 409가 아닌 500이 될 수 있습니다.

와 같은 문제가 있었으나 API 특성상 큰 문제는 아닌 것 같아 코드 본문에는 리뷰 달지 않고 여기 짧게 남기겠습니다.

수고하셨습니다.