Alphea App

Phase 4 구현 완료¶

commit:server|de617cf

적용된 변경¶

DB 스키마 v14 (clean rewrite)

• friends: inviter_id/invitee_id (BIGINT) → inviter_user_id/invitee_user_id (UUID). UNIQUE(inviter_user_id, invitee_user_id) + 2개 인덱스
• referral_claims: account_id → user_id (UUID) + 인덱스 (user_id, claimed_at DESC)
• rewards_log: account_id → user_id (UUID) + 인덱스
• accounts.referral_code UNIQUE 유지 — referral code 발급 주체는 여전히 account

Store

• store/friends.go 전체 재작성. 모든 helper 가 user_id 인자로 교체:
  • GetFriendCount(userID), GetActiveFriendCount(userID), GetNetworkFriendsCount(userID)
  • GetInviterUserID(userID), GetInvitees(userID), GetInviterChain(userID, maxDepth)
  • CreateFriendship(inviterUserID, inviteeUserID) — ON CONFLICT DO NOTHING
  • GetClaimedRewards(userID), HasClaimed(userID, type, amount), CreateReferralClaim(userID, type, amount)
  • DeleteFriendsByInviter(inviterUserID) (이전 nodes.go 의 중복 제거)
• CreditAccountByUserID(userID, delta, reason, refCode) 신규 helper (Phase 2 의 ledger 경로 그대로 타고도록 경로 축소)
• RecordReferralEarning 을 user_id 인자 도입으로 확장: aggregated_earnings.user_id 추가 (Phase 2 에서 변경된 스키마와 일치)

Proto

• FriendsSummaryResponse.inviter_address → inviter_user_id + inviter_display_name
• FriendInfo.wallet_address → user_id
• EngageResponse.inviter_address → inviter_user_id
• GetReferralCodeResponse.wallet_address → user_id
• Phase 2의 DiscardUnknown 덕분에 이전 wallet_address 기반 클라이언트가 계속 동작

Handler

• handler/friends.go:
  • requireWallet(ctx) → requireUser(ctx). AuthContext로부터 user_id 추출, 계정이 없으면 EnsureAccountForUser 로 자동 materialize
  • 7개 RPC(GetSummary / ListFriends / GetReferralCode / Engage / GetRewards / ClaimReward / ClaimCompletionBonus) 모두 caller user_id 로 동작
  • Reward claim 은 CreditAccountByUserID 로 wallet_adjustments 에 기록
  • usernameOrDefault 에 display_name > username > email 우선순위 추가
• handler/pool.go::SeedFriends: 데모 친구도 이제 합성 user_id 할당 후 friends 관계 생성. 이랇에 초대자 계정이 user_id 미연결 이면 FailedPrecondition
• handler/stubs.go::UserService.GetUser: account.UserID 로 friend_count 조회 (넘어우면 0)
• handler/friends_halving_test.go: ctxWithUser + seedUserWithWallet + UpdateLastActiveByUser 패턴으로 재작성

검증¶

• go build ./... PASS
• go vet ./... PASS
• go test ./... PASS (handler/store/sdk/admin 전부, integration 테스트는 TEST_DATABASE_URL 미설정으로 skip)

DoD 체크¶

• make build, make test 통과
• FriendsService 7개 RPC 가 GoTrue user JWT 없으면 Unauthenticated 거부
• 친구 관계 + 리퍼럴 리워드 + completion bonus 모두 user_id 키로 적립 / 조회
• 각 reward claim 이 wallet_adjustments ledger 에 기록 (Phase 2 경로 재사용)

후속 (추후 이슈)¶

• nodes.owner_wallet_address 컬럼 제거
• virtual_node_assignments / virtual_node_credits / virtual_node_packages 스키마 user_id 직접 전환