菜单
AIUsage 사용자에게 RP/코인을 서버에서 지급(보상)하는 절차 — 버그 보상, 이벤트 보상, 개별/대량 지급. "보상 지급", "RP 지급", "코인 지급", "버그 보상", "reward grant", "compensation", "RP 뿌려", "이벤트 보상" 요청 시 사용. 서버 배포/마이그레이션은 supabase-ranking, 클라 릴리스는 release-app skill.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | reward-grants |
| description | AIUsage 사용자에게 RP/코인을 서버에서 지급(보상)하는 절차 — 버그 보상, 이벤트 보상, 개별/대량 지급. "보상 지급", "RP 지급", "코인 지급", "버그 보상", "reward grant", "compensation", "RP 뿌려", "이벤트 보상" 요청 시 사용. 서버 배포/마이그레이션은 supabase-ranking, 클라 릴리스는 release-app skill. |
RP·코인을 특정 사용자(들)에게 서버에서 지급하는 운영 절차. RP가 대량 보상의 기본 경로다.
환경변수·curl·service_role 규약은 [[supabase-ranking]] 전제(source scripts/ranking.env).
RP·코인 총 잔액은 각 기기의 로컬 원장(RankPointLedger / CoinLedger)에 있다. 서버 테이블은
"아직 안 받은 보상"을 담아둘 뿐이다. 지급 흐름:
pendingRpReward/pendingReward로 그 행을 받음(가장 오래된 1건).*_claimed_at 세팅). dedup은 클라의
claimedRpRewards/claimedPodiumPeriods가 담당.함의(반드시 인지):
/usr/bin/curl(keychain CA)로. anaconda/homebrew python·curl은
CERTIFICATE_VERIFY_FAILED. (supabase-ranking 참조)rp_rewardsper-device 원장이라 인원 무제한·금액 자유. 월간 RP는 조용히 적립(알림 없음).
행 스펙: { period, period_type, device_id, rank, rp_amount }, claimed_at=NULL.
period_type: CHECK ('monthly','weekly','guild-monthly'). 'monthly' 사용(silent). ⚠️
'guild-monthly'는 클라가 "우리 길드 N등" 알림을 띄운다 — 보상용으론 쓰지 말 것.period: claim 정규식 ^\d{4}-(\d{2}|W\d{2})$ 통과 필요. 실제 정산과 충돌 안 하는 sentinel을
쓴다(실제 월간=진짜 YYYY-MM, 주간=YYYY-Www). 월 00은 실존 안 함 → '2026-00' 형태.
UNIQUE (period_type, period, device_id)라 같은 사람에게 다시 주려면 다른 period — 캠페인마다
새 sentinel(예: 1차 2026-00, 2차 2027-00).rank: RP는 ≥1. 표시 안 되니 1 고정.rp_amount: 지급액.지급(활성 사용자 중 일부 제외, 대량):
source scripts/ranking.env
H=(-H "apikey: ${SUPABASE_SERVICE_ROLE_KEY}" -H "Authorization: Bearer ${SUPABASE_SERVICE_ROLE_KEY}")
EXCLUDE="<제외할 device_id>" # 없으면 빈 문자열
# 1) 대상 조회 → 페이로드 생성 (python은 로컬 파싱만, fetch/POST는 /usr/bin/curl)
/usr/bin/curl -s "${SUPABASE_URL}/rest/v1/users?select=device_id,nickname&status=eq.active" "${H[@]}" > /tmp/u.json
python3 - /tmp/u.json "$EXCLUDE" /tmp/rows.json <<'PY'
import sys, json
users=json.load(open(sys.argv[1])); ex=sys.argv[2].lower()
t=[u for u in users if u["device_id"].lower()!=ex]
json.dump([{"period":"2026-00","period_type":"monthly","device_id":u["device_id"],"rank":1,"rp_amount":500} for u in t], open(sys.argv[3],"w"))
print(f"대상 {len(t)}명:", ", ".join(sorted(u["nickname"] for u in t)))
PY
# 2) 벌크 INSERT
/usr/bin/curl -s -w '\nHTTP %{http_code}\n' -X POST "${SUPABASE_URL}/rest/v1/rp_rewards" "${H[@]}" \
-H "Content-Type: application/json" -H "Prefer: return=representation" --data-binary @/tmp/rows.json
# 3) 검증 — 미수령 행수
/usr/bin/curl -s "${SUPABASE_URL}/rest/v1/rp_rewards?select=device_id&period=eq.2026-00&claimed_at=is.null" "${H[@]}" -H "Prefer: count=exact" -I 2>/dev/null | grep -i content-range
개별 지급은 /tmp/rows.json을 한 사람짜리 배열로 만들면 된다.
reward_grants 테이블 하나로 RP·코인 어느 통화든 per-device 지급한다. rp_rewards의 깔끔한 흐름을
코인까지 확장한 것 — podium/정산/메달과 완전히 분리돼 부작용 없음(가짜 "명예의 전당 N등" 알림 X,
평생 메달 오염 X, previousMonth 화면 오염 X). 클라는 🎁 보상 도착 알림만 띄운다.
⚠️ 클라 버전 요건:
pendingGrant를 이해하는 v0.16.4+ 클라만 수령 가능. 그 이전 버전 유저에겐 행이 미수령으로 남아있다가 업데이트 후 적립된다. 구버전 유저 코인 즉시 지급이 꼭 필요하면 §2 podium.
행 스펙: { device_id, currency, amount, grant_key, reason }, claimed_at=NULL.
currency: 'rp'(→RankPointLedger) | 'coin'(→CoinLedger). CHECK 강제.amount: 지급액(>0).grant_key: dedup 키(캠페인/사유 슬러그). ^[A-Za-z0-9._-]{1,64}$. UNIQUE (device_id, grant_key) —
같은 사람 재지급은 새 grant_key. 클라 claim 서명의 period 슬롯에 실려오므로 서명-safe 문자만.reason: 운영 메모(표시 안 함, 감사용).지급(개별/대량 공용 — currency만 바꾸면 됨):
source scripts/ranking.env
H=(-H "apikey: ${SUPABASE_SERVICE_ROLE_KEY}" -H "Authorization: Bearer ${SUPABASE_SERVICE_ROLE_KEY}")
/usr/bin/curl -s -w '\nHTTP %{http_code}\n' -X POST "${SUPABASE_URL}/rest/v1/reward_grants" "${H[@]}" \
-H "Content-Type: application/json" -H "Prefer: return=representation" -d '[
{"device_id":"<uuid>","currency":"coin","amount":3000,"grant_key":"guild-loss-2026-07","reason":"길드 소실 보상"}
]'
# 검증 — 미수령 행수
/usr/bin/curl -s "${SUPABASE_URL}/rest/v1/reward_grants?select=device_id&grant_key=eq.guild-loss-2026-07&claimed_at=is.null" "${H[@]}" -H "Prefer: count=exact" -I 2>/dev/null | grep -i content-range
대량은 -d에 배열로 여러 행. 전달은 §0과 동일(다음 폴링, ≤5분). 취소는 §3(미수령 DELETE).
monthly_winners (podium 전용, 대량 부적합)v0.16.4+에선 §1.5 reward_grants가 권장. 아래는 구버전 유저에게 코인을 즉시 줘야 할 때만. podium 경로는 가짜 달 "명예의 전당 N등" 알림 +
device_medals금/은/동 오염 + previousMonth 표시 오염이 따라온다(§1.5가 이걸 없애려 만들어짐).
코인은 로컬 사용량 경제라 서버→클라 지급 경로가 podium 하나뿐이다. 제약이 크다:
(period, rank) + rank ∈ {1,2,3} → 한 period에 최대 3명. 대량이면 sentinel period를
돌려써야 함(비추천).^\d{4}-\d{2}$(월간만, 주간 불가).reward_claimed_at. 조회 필드 reward_coins.final_score, nickname_snapshot, reward_coins(+ rank CHECK 1..3). profile_json_snapshot은 nullable.소수(≤3) 지급 예:
/usr/bin/curl -s -w '\nHTTP %{http_code}\n' -X POST "${SUPABASE_URL}/rest/v1/monthly_winners" "${H[@]}" \
-H "Content-Type: application/json" -H "Prefer: return=representation" -d '[
{"period":"2026-00","device_id":"<uuid>","rank":1,"final_score":0,"nickname_snapshot":"grant","reward_coins":500}
]'
대량 코인 보상이 필요하면 재고: (a) RP로 대체(권장), (b) 클라측 일회성 코인 지급 마이그레이션 (
Settings.applyOnceMigration, CLAUDE.md 참조)로 릴리스에 실어 배포. 서버 podium 우회는 지양.
DELETE .../rp_rewards?period=eq.2026-00&claimed_at=is.null길드 무경쟁 무임 지급 버그로 1명(Joripje)이 500 RP를 이미 수령(회수 불가). 형평을 위해 활성
13명(그 1명 제외)에게 500 RP를 위 §1 방식(period='2026-00', monthly, silent)으로 지급. 공지엔
RP 언급 생략(조용히 적립). 정산 버그 자체는 서버 마이그레이션으로 수정(supabase-ranking).
grant_key UNIQUE(device당) — 재지급이면 새 grant_key. §1 RP면 sentinel period 규칙/usr/bin/curl + service_role로 INSERT, 미수령 행수 검증