Day97

Wed, 20 May 2026 12:26:16 GMT

기준일: 2026-05-20
범위: 캐릭터 도메인, 공유 도메인, 관련 user/item 도메인 연동 지점

1. 현재 정리된 방향

1.1 공유 카드 생성

현재 공유 카드 생성은 프론트엔드가 이미지를 먼저 생성하고 업로드한 뒤, 공개 이미지 URL을 백엔드에 전달하는 방식이다.

컴포넌트 렌더링
-> 이미지 캡처
-> GET /api/share/v1/presigned-url
-> presignedUrl로 R2/S3 직접 PUT 업로드
-> POST /api/share/v1/share-cards { characterId, imageUrl }
-> POST /api/share/v1/share-events

POST /api/share/v1/share-cards 요청에는 현재 headline을 포함하지 않는다.

{
  "characterId": 10,
  "imageUrl": "https://cdn.polaris.app/share-cards/UUID.png"
}

1.2 공유 보상

공유 보상은 API 명세 기준 하루 1회, 10 별조각이다.

{
  "rewardPaid": true,
  "rewardStarPiece": 10
}

1.3 공유 headline

현재 백엔드 구현은 사용자 입력 headline을 받지 않고, 서버 고정 문구를 내려준다.

private static final String PLACEHOLDER_HEADLINE = "Today, I shone a little.";

단기적으로는 서버 기본 문구를 유지할 수 있다. 다만 공유 카드가 반복 노출되는 기능이므로, 추후에는 headline 후보 문구를 테이블로 관리하고 공유 카드 생성 시 하나를 선택해 저장하는 구조가 적합하다.

2. P0: 바로 해결해야 할 문제

2.1 공유 보상 wallet 적립 연동

상태: 일부 수정완료

현재 ShareService#createShareEvent는 rewardPaid와 rewardStarPiece를 계산하고 share_logs에 저장하지만, 실제 wallet 적립을 호출하지 않는다.

완료된 부분:

user 도메인 WalletService#earnStarPiece 메서드는 존재한다.
proto/src/main/proto/user/v1/wallet_service.proto에 EarnStarPiece RPC가 추가되어 있다.
WalletGrpcController#earnStarPiece가 구현되어 있다.

남은 문제:

character 도메인 ShareService에 wallet 연동 TODO가 남아 있다.
ShareService#createShareEvent에서 아직 user wallet gRPC를 호출하지 않는다.
공유 보상이 실제 wallet에 적립되지 않는다.
ShareEventResult.walletStarPiece는 여전히 0을 반환한다.

남은 작업:

character/share 도메인에서 user wallet gRPC client 연결
공유 보상 지급 시 EarnStarPiece 호출
reason=SHARE_REWARD, refType=SHARE, refId=shareLogId 또는 shareCardId, idempotencyKey 전달
응답의 wallet.starPiece에 최신 잔액 반영
wallet 적립 실패 시 share_logs 저장과 보상 지급 상태를 어떻게 맞출지 정책 결정

2.2 공유 보상 일일 1회 멱등성 강화

상태: 개선 필요

현재 공유 이벤트는 클라이언트가 body로 전달한 idempotencyKey를 그대로 사용한다.

문제:

클라이언트가 매번 다른 idempotencyKey를 보내면 같은 날 중복 요청을 완전히 막기 어렵다.
existsByUserIdAndShareDateAndRewardPaidTrue 확인 후 저장하는 방식만으로는 race condition 방어가 부족하다.

권장 방향:

보상 지급용 멱등키는 서버가 생성한다.

SHARE_REWARD:{userId}:{yyyy-MM-dd}

클라이언트 body의 idempotencyKey는 공유 이벤트 요청 재시도 식별용으로만 쓸지, 아예 서버 생성 키로 통일할지 정책을 정한다.
DB 레벨에서 일일 보상 중복 지급을 막는다.

가능한 DB 방어:

-- reward_paid=true인 공유 보상은 유저/날짜당 1개만 허용
CREATE UNIQUE INDEX uq_share_logs_daily_reward
ON share_logs (user_id, share_date)
WHERE reward_paid = TRUE;

완료된 부분:

보상 지급용 멱등키를 서버에서 생성하는 로직이 추가되었다.

SHARE_REWARD:{userId}:{yyyy-MM-dd}

share_logs에 일일 보상 중복 방지용 partial unique index가 추가되었다.

CREATE UNIQUE INDEX IF NOT EXISTS uq_share_logs_daily_reward_paid
ON share_logs (user_id, share_date)
WHERE reward_paid = TRUE;

남은 개선점:

동시 요청에서 unique index 충돌이 발생했을 때 예외를 잡아 기존 보상 로그를 조회하고 동일 응답으로 replay하는 처리가 필요하다.
클라이언트가 보낸 idempotencyKey를 보상용 키와 이벤트 기록용 키 중 어떤 의미로 유지할지 정책을 더 명확히 해야 한다.
wallet 적립 연동 후에는 wallet transaction의 idempotencyKey도 SHARE_REWARD:{userId}:{yyyy-MM-dd}와 일관되게 맞춰야 한다.

2.3 공유 이벤트 소유자 검증

상태: 수정됨

현재 createShareEvent(userId, shareCardId, ...)는 shareCardId로 카드를 조회하지만, 해당 카드가 요청 사용자 소유인지 확인하지 않는다.

필요 작업:

ShareCard card 조회 후 card.getUserId().equals(userId) 검증
불일치 시 NOT_SHARE_CARD_OWNER 또는 적절한 권한 에러 반환

이 검증이 없으면 다른 사용자의 shareCardId로 내 공유 보상을 받을 수 있다.

2.4 오늘 공유 보상 상태 조회 API 구현

상태: 수정됨

API 명세에는 아래 endpoint가 있다.

GET /api/share/v1/share-events/today

하지만 현재 gateway ShareController에는 해당 endpoint가 없다.

필요 작업:

character proto에 today status RPC 추가
character ShareService에 오늘 보상 수령 여부 조회 구현
gateway ShareController에 endpoint 추가

응답 예시:

{
  "rewardClaimed": true,
  "lastSharedAt": "2026-05-19T09:22:24.400Z"
}

2.5 공유 링크 OG HTML 라우트 구현

상태: 개선 필요

현재 구현된 공개 공유 링크 API는 JSON이다.

GET /api/share/v1/share-links/{shareId}

하지만 카카오톡, 디스코드, X 등 외부 서비스의 미리보기는 JS를 실행하지 않고 HTML 의 OG 태그를 읽는다.

필요 작업:

/share/{shareId} HTML 라우트 제공
서버에서 동적으로 OG 태그 렌더링
gateway 모듈에 공유 링크 전용 HTML 컨트롤러를 추가하는 방식을 우선 검토한다.

현재 gateway는 spring-boot-starter-web만 사용하고 Thymeleaf 의존성이 없다. 따라서 MVP에서는 별도 템플릿 엔진을 추가하지 않고, @Controller 또는 @RestController에서 text/html 응답을 직접 반환하는 경량 구현이 적합하다.

예상 흐름:

GET /share/{shareId}
-> gateway ShareHtmlController
-> ShareGatewayService#getShareLink(shareId)
-> character/share 도메인에서 imageUrl, headline, characterName, signupUrl 조회
-> gateway가 OG meta tag 포함 HTML 반환

필수 OG 태그:

주의:

og:image는 반드시 https://... 절대 URL이어야 한다.
권장 이미지 크기는 1200 x 630px이다.
프론트 SPA에서 동적으로 meta tag를 바꾸는 방식은 메신저 미리보기를 보장하지 못한다.

권장 구현 형태:

@Controller
@RequiredArgsConstructor
public class ShareHtmlController {

    private final ShareGatewayService shareGatewayService;

    @GetMapping(value = "/share/{shareId}", produces = MediaType.TEXT_HTML_VALUE)
    @ResponseBody
    public String getShareHtmlPage(@PathVariable String shareId) {
        var shareLink = shareGatewayService.getShareLink(shareId);
        // HTML escape, URL validation 후 HTML 문자열 반환
    }
}

구현 시 필수 보완:

characterName, headline, imageUrl, signupUrl 등 HTML에 삽입되는 값은 반드시 escape한다.
og:image와 redirect URL은 https://... 절대 URL인지 검증한다.
imageUrl이 비어 있거나 올바르지 않으면 기본 공유 이미지로 fallback한다.
og:url의 base URL은 코드에 고정하지 말고 설정값으로 분리한다. 예: app.public-base-url=https://polaris.app
없는 shareId는 JSON 에러가 아니라 404 HTML 또는 기본 OG HTML로 응답할지 정책을 정한다.
실제 사용자를 위해 JavaScript redirect만 두지 말고 body에 기본 링크와

rxg_1211.log

Day97

Character / Share Backend TODO

1. 현재 정리된 방향

1.1 공유 카드 생성

1.2 공유 보상

1.3 공유 headline

2. P0: 바로 해결해야 할 문제

2.1 공유 보상 wallet 적립 연동

2.2 공유 보상 일일 1회 멱등성 강화

2.3 공유 이벤트 소유자 검증

2.4 오늘 공유 보상 상태 조회 API 구현

2.5 공유 링크 OG HTML 라우트 구현