Guide
전체 기능 가이드 & 주의사항
봇의 모든 시스템과 규칙, 한도, 주의사항을 정리했습니다. 명령어별 자세한 시그니처는커맨드 페이지에서 확인할 수 있어요.
DoubleJ 계정 연결
디스코드 사용자와 사이트(이랑위키) 계정을 1:1로 매핑합니다. 연결되지 않으면 일부 기능이 제한됩니다.
| 연결 명령 | /연결 — 본인만 보이는 응답으로 연결 링크 발송 |
| 토큰 유효시간 | 15분 (만료되면 다시 /연결) |
| 연결 페이지 | rangu-fam.com/connect/discord — DoubleJ 로그인 후 자동 매핑 |
| 1:1 제약 | 한 디스코드 ID는 한 위키 계정에만 연결 가능 (충돌 시 거부) |
- ❗ **버그 제보**, **오늘의 발언 자동화 채널 등록**은 연결 필수입니다.
- ❗ 다른 사용자에게 이미 매핑된 Discord ID는 새로 연결할 수 없습니다.
- ✅ 연결 후 `/내코인`에 사이트 username과 역할(admin/editor 등)이 함께 표시됩니다.
R코인 시스템
Rangu.fam · DoubleJ · 이랑위키 통합 코인. 봇과 사이트가 동일한 잔액·트랜잭션 원장을 공유합니다.
| 저장소 | Cloud SQL Postgres — user_coins + coin_transactions |
| 단위 | R (정수). 디스코드 표시는 n,nnn R 포맷 |
| 지급 사유 | 출석·도박·주식·버그제보·거래소·관리자 부여 |
| 차감 사유 | 상점 구매·도박 패배·주식 매수·거래소 베팅·관리자 회수 |
- 🌱 → 🪙 → 💰 → 💎 → 🏆: 잔액에 따라 `/내코인` rank emoji 동적 변경
- ❗ 모든 거래는 `coin_transactions` 에 영구 기록되어 감사 가능
- ⚠️ **보유 500경(5×10¹⁸) 초과 시 거래소·도박 보상 미지급** — 인플레이션 캡
출석체크
매일 한 번씩 R코인을 받아갈 수 있어요. 연속할수록 보너스가 커집니다.
| 기본 보상 | 50 R |
| 연속 보너스 | +10 R/일 (2일째 +10, 3일째 +20, ... 14일째 +130) |
| 최대 보너스 | 14일 연속 시 +130 R 추가 (총 180 R/일) |
| 쿨다운 | 마지막 출석으로부터 24시간 (KST 자정 아님) |
| 끊김 조건 | 마지막 출석이 어제(KST)가 아니면 streak 1로 리셋 |
- 🔥 진행바로 현재 streak 시각화 — `[▰▰▰▰▱▱▱▱▱▱▱▱▱▱] 4/14`
- ⏳ 쿨다운 중에는 남은 시간 임베드로 표시 + 연속 끊기지 않게 안내
- ✅ 명령은 채널 공개로 게시됨 (자랑하기 좋게)
도박 (슬롯 머신)
가중치 기반 6가지 결과. 7️⃣ 잭팟은 약 1/125,000 확률, 트리플은 약 5%. EV는 약 -5~-10% (사용자 친화적).
| 베팅 한도 | 최소 10 R · 최대 100,000 R |
| 🎰 JACKPOT (7️⃣7️⃣7️⃣) | ×25 — 가장 희귀 |
| ✨ TRIPLE | 심볼별: 💎 ×10 / 🔔 ×6 / 🍇 ×4 / 🍋 ×3 / 🍒 ×2.5 |
| 🌈 SEQUENCE (🍒🍋🍇 등) | ×1.8 — 과일 시퀀스 보너스 |
| 🎯 PAIR (위치 무관) | 심볼별: 7️⃣ ×4 / 💎 ×3 / 🔔 ×2 / 🍇 ×1.7 / 🍋 ×1.4 / 🍒 ×1.2 |
| 💸 LOSS (모두 다름) | 베팅액 100% 소멸 |
| 🔥 연승 보너스 | 5연승부터 +5%, 매 1승마다 +5%, 최대 +30% |
- 심볼 가중치: 🍒(30) > 🍋(25) > 🍇(20) > 🔔(15) > 💎(8) > 7️⃣(2)
- 결과는 미리 결정 후 3단계 reveal 애니메이션으로 표시 (700ms 간격)
- 버튼: [다시 N] [두 배] [반] — 잔액 부족하면 자동 disabled
- ⚠️ 봇 재시작 시 연승 카운터 리셋 (in-memory)
주식 시장
일반 종목 4개 + 인물 코인 (자동 등록). 가격 엔진은 사이트 측에서 lazy compute로 동작합니다.
| 일반 종목 | RNGU(랑우홀딩스) · DBLJ(DoubleJ) · WIKI(이랑위키) · CARD(카드드랍) |
| 변동 주기 | 분 단위 random walk + 평균 회귀 (호출 시 lazy compute) |
| 기본 변동성 | 각 종목별 vol: 15~30% (×100 정수 저장) |
| 인물 코인 등록 | 오늘의 발언 등록 시 발언자 자동 인물 코인 생성 |
| 발언자 가격 변동 | +5~15% 점프 (랜덤) |
| 본문 등장 인물 | +1~5% 점프 (이름 또는 alias 매칭) |
| 차트 | 최근 30 tick ASCII 차트 — /주식 차트 시장 티커 |
- 💼 일반 종목은 시장 전체에 영향, 누구나 매매 가능
- 👤 인물 코인은 발언이 활발할수록 변동 큼 (mention_count 누적)
- 📊 모든 가격 변동은 `stock_ticks` 테이블에 영구 기록
- ⚠️ 거래 중 잔액/수량 부족은 ephemeral 에러 메시지로만 표시
코인 거래소
10분 라운드로 매수/매도 중 한 쪽에 베팅 → 마감 시 실현된 쪽이 배수 보상, 반대편은 베팅액 소멸.
| 라운드 길이 | 10분 (자동 마감) |
| 라운드 break | 마감 후 1분 대기 → 새 라운드 자동 개장 |
| 라운드 코드 | MMDDhhmm (KST 기준) — 예: #05051752 |
| 베팅 한도 | 보유 R코인의 70%까지 |
| 베팅 횟수 | 1라운드 1베팅 (중복 불가) |
| 최소 베팅 | 100 R |
| 배수 | 매번 ×1.5 ~ ×4.0 사이 랜덤 (양쪽 따로) |
| 실현 결정 | 라운드 마감 시 50/50 확률로 매수 또는 매도 |
- 🚫 보유 코인 **500경(垓) 초과** 시 보상 미지급
- ⚠️ 거래 진행 중 다른 명령을 실행하면 코인이 손실될 수 있어요
- ❗ 거래 전 봇 관리 서버에 거래소가 운영 중인지 확인
- 📌 거래소 임베드는 매 30초마다 갱신 — 참여 인원 실시간 반영
- 🏆 라운드 종료 시 상위 5명 수령자가 임베드에 표시됨
오늘의 발언 자동화
디스코드 자동화 채널의 양식 메시지 ↔ 사이트 작업공작소 양방향 동기화. 인물 코인 가격까지 자동 변동.
| 채널 매핑 | 관리자가 /자동화설정 종류:발언 채널:#xxx 으로 등록 |
| 단일 양식 | 발언자: + 발언: 두 줄 |
| 다이얼로그 양식 | 빈 줄로 화자 분리, 이름(별명) + 다음 줄 "발언" |
| 자격 | /연결 완료된 사용자만 등록 가능 |
| 작성자 처리 | 자동 — 메시지 보낸 디스코드 사용자의 연결 계정 |
| 처리 흐름 | 양식 감지 → 사이트 등록 → 원본 메시지 삭제 → 봇이 임베드 재게시 |
| 양방향 동기화 | 사이트에서 등록 시 봇이 자동화 채널에 임베드 게시 |
- 🚫 미연결자는 메시지 삭제 + DM/임시 메시지로 `/연결` 안내
- ❌ 양식 불일치 시 메시지 삭제 + 안내 (hint 있을 때만)
- ✅ 첫 화자가 main speaker로 사이트 등록, 본문 통째로 보존
- 📈 발언자 인물 코인 +5~15%, 본문 등장 인물 +1~5% 자동 점프
- ❗ Discord MessageContent intent 활성화 필수 (Developer Portal)
위키 수정/요청 알람
이랑위키에서 발생한 수정·삭제·요청을 디스코드 채널에서 즉시 받습니다.
| 설정 명령 | /알람설정 종류:<수정|삭제|요청> 채널:#xxx [활성:true] |
| 관리자 권한 | Discord Administrator 또는 사이트 admin 역할 필요 |
| 알람 종류 | 수정 (즉시 반영) / 삭제 (페이지 삭제) / 요청 (승인 대기) |
| 트리거 | 사이트 wikiSubmissions / wikiPages 변경 시 자동 |
- 🔵 요청: 일반 사용자가 위키 편집 요청 (관리자 검토 대기)
- 🟡 수정: 운영자급이 즉시 반영한 편집
- 🔴 삭제: 페이지 isDeleted=true 변경
- ⚙️ 환경변수 `BOT_DEFAULT_GUILD_ID` 가 설정된 길드로만 발송
버그 제보 + BUG HUNTER 칭호
사이트/위키 버그를 제보하고 채택되면 코인과 영구 칭호를 받습니다.
| 제보 명령 | /버그제보 (모달로 제목/본문/재현 URL/심각도 입력) |
| 자격 | /연결 완료된 사용자만 가능 |
| 심각도 | low / normal / high / critical (자유 입력) |
| 초기 상태 | pending — 관리자 검토 대기 |
| 채택 보상 | +200 R + 🐛 BUG HUNTER 칭호 (사이트·위키 프로필 영구 표시) |
- 📩 채택 시 봇이 DM으로 보상/칭호 통지
- 🚫 같은 칭호는 1회만 부여 (중복 방지)
- 📜 `bug_reports` 테이블에 모든 제보 영구 기록
공지사항 통합 발행
관리자 한 명령으로 사이트·위키·디스코드 채널에 동시 공지 발행.
| 조회 | /공지사항 조회 — 최근 5개 공지 채널 공개 |
| 게시 (관리자) | /공지사항 게시 제목 본문 [심각도] [채널] [고정] |
| 심각도 | info(파랑) / notice(주황) / warning(주황) / critical(빨강) |
| 발행 채널 | site_notices DB + (선택) 디스코드 채널 임베드 + 위키 페이지 |
- 📌 `고정:true` 옵션으로 상단 고정 표시
- 🔁 동일 공지가 사이트·위키·디스코드 동기화되어 단일 source of truth 유지
- ⏰ 게시 시 publishedAt 자동 기록, 향후 expiresAt 설정 가능
자동 백그라운드 기능
명령어 없이 봇이 자동으로 동작하는 기능들. Cloud Run에서 봇 단일 인스턴스(`min=1`)로 안전하게 동작.
| 시세 ticker 채널 | 환경변수 STOCK_TICKER_CHANNEL_ID — 1분마다 시세 임베드 갱신 |
| 거래소 채널 | 환경변수 EXCHANGE_CHANNEL_ID — 30초마다 라운드 매니저 tick |
| 오늘의 발언 채널 | 관리자가 /자동화설정 으로 매핑 — 메시지 감지 → 사이트 동기화 |
| 위키 webhook | 사이트 → 봇 HTTP /hooks/wiki-alarm — 알람 채널 매핑 lookup 후 발송 |
- 🔄 모든 자동 기능은 Cloud Run revision rotation에 강함 (재시작 시 자연 복구)
- ⏱️ 30~60초 단위 폴링 — Discord rate limit (5초 5회) 안전 범위
- 🛡️ 봇 HTTP 서버는 `BOT_SERVICE_TOKEN` 으로 인증된 요청만 수락
칭호 시스템
보유한 칭호는 1개만 부착해서 버프를 받을 수 있어요. 일부 칭호는 상점에서 구매, 일부는 자동 부여 (BUG_HUNTER 등).
| 💰 금전애호 도박러 | /코인받기 기본 ×2 + 명예/인기도 추가 지급 |
| 🎲 확률조작 도박러 | /베팅 성공 확률 지수 +8 (50→58) |
| 📦 상자해체 도박러 | /상자 100% 보상 + 보상량 증가 |
| 🌟 랑구 서포터 | 모든 칭호 효과 적용 + 추가 특전 (개발자 후원자 전용) |
| 🐛 BUG HUNTER | 버그 제보 채택 시 자동 부여 |
| 🩸 FIRST BLOOD | 인물 코인 시장 첫 거래자 |
| 👑 STOCK KING | 인물 주식 누적 수익 1위 |
| 📜 WORKSHOP LEGEND | 오늘의 발언 100회 등록 |
| 부착 | /칭호 키:GOLD_BETTOR 또는 (해제) 선택 |
- 🚫 칭호는 계정당 1개만 부착 가능. 마지막 부착 칭호가 활성.
- 💎 도박러 3종은 상점에서 토큰으로 구매 (각 50 토큰).
- 🌟 랑구 서포터는 개발자 직접 부여만 가능 (`/칭호부여` 관리자 명령).
송금 · 저금
다른 유저에게 코인을 보내거나, 안전하게 저금해두세요.
| 송금 명령 | /송금 유저:@xxx 개수:N |
| 송금 최소 | 100 R 이상 |
| 수수료 | 5% 소실 (예: 1,000 R 보내면 950 R 도착) |
| 보너스 | 양쪽 인기도 +1 |
| 비공개 모드 | 받는 유저가 비공개면 송금 불가 |
| 저금 명령 | /저금 동작:입금|출금 개수:N |
| 저금 보호 | 저금된 코인은 도박/베팅에 영향 없음 |
- 🔒 비공개 모드 (`/내설정 모드:상메 내용:-비공개...`)는 송금/프로필 열람 모두 차단
- 💼 저금 시 잔액에서 차감 → 저금에 추가. 도박/거래소가 저금에 영향 없음
랭킹
지표별 TOP 10을 즉시 확인합니다.
| 명령 | /순위 [지표:코인|명예|인기도|토큰|전리품|레벨] |
| 코인 | 보유 잔액 기준 |
| 명예 | 상점 인벤 확장 등 결제용 통화 |
| 인기도 | 송금/상자 등 활동으로 누적 |
| 토큰 | 기프티콘 결제 통화 |
| 전리품 | 🏆 패스권 등 결제용 |
| 레벨 | 강화로 올린 플레이어 레벨 |
- 🔒 비공개 모드 사용자는 _비공개_ 로 가려짐
- 🥇🥈🥉 상위 3명은 메달 표시
관리자 명령
Discord Administrator 권한 또는 사이트 admin 역할 보유자만 실행 가능.
| /상자추가 | /상자추가 등급:일반|고급|스페셜 유저:@xxx 개수:N — 직접 지급 |
| /주주추가 | /주주추가 티커:RNGU 유저:@xxx 개수:N — 주식 직접 추가 |
| /초기화 | /초기화 선택:상자|코인|토큰|주식|전체 유저:@xxx |
| /칭호부여 | /칭호부여 유저:@xxx 키:GOLD_BETTOR 사유: — 칭호 직접 부여 |
| /공지사항 게시 | 사이트·위키·디스코드 동시 발행 |
| /알람설정 | 위키 수정/삭제/요청 알람 채널 매핑 |
| /자동화설정 | 오늘의 발언 자동화 채널 매핑 |
- 🛡️ 모든 관리자 명령은 ephemeral 응답 (다른 사람에게 안 보임)
- 📜 모든 관리자 액션은 `coin_transactions` 또는 ref 테이블에 영구 기록
- ⚠️ `/초기화 선택:전체` 는 모든 자원 reset — 신중히 사용
광고 보상 (보류)
현재는 보류 — 추후 외부 광고 네트워크 연동 후 활성화 예정.
| 현재 상태 | ❌ 비활성 (AD_SIGNING_SECRET env 미설정) |
| 활성화 조건 | AD_REWARD_URL + AD_SIGNING_SECRET env 설정 |
| 예정 보상 | 1회 시청당 20 R, 30분 쿨다운 |
| 예정 네트워크 | AdGate Media (리워드 비디오) + CPX Research (설문) |
- 🚫 디스코드 메시지에 광고 직접 삽입 불가 (Discord ToS) — 외부 페이지 경유
- 🚫 AdSense / AdMob 사용 금지 (인센티브 트래픽 정책 위반)
- 🔐 HMAC 서명된 1회용 토큰 + nonce 일회성 처리로 어뷰징 방지
- 💡 현재는 `/r코인얻기` 의 광고 시청 버튼이 자동 disabled 상태
자동 기능
명령어 없이 백그라운드에서 동작하는 기능들. 모두 Cloud Run의 단일 봇 인스턴스에서 실행되며 재시작에 강합니다.
시세 자동 게시
지정 채널에 1분마다 일반 종목 + 인물 코인 시세 임베드를 자동 갱신
같은 메시지를 edit해서 채널 노이즈 최소화. 메시지가 사라지면 자동으로 새로 게시. 변동 큰 인물 코인 12개를 우선 표시.
코인 거래소 자동 매니저
10분마다 라운드 자동 개장/마감 + 실현 측 결정 + 결과 발표
라운드 코드는 KST 기준 MMDDhhmm. 마감 후 1분 break, 다음 라운드 자동 개장. 매 30초마다 임베드 갱신.
오늘의 발언 양방향 동기화
디스코드 자동화 채널 ↔ 사이트 작업공작소 자동 등록
디스코드 → 사이트: 양식 또는 다이얼로그 메시지 감지 → 사이트 등록 → 임베드 재게시. 사이트 → 디스코드: 작업공작소에서 등록 시 자동화 채널에 임베드.
위키 수정/요청 알람
사이트 위키에 수정 요청이 들어오면 등록한 디스코드 채널에 즉시 알람
wikiSubmissions 테이블에 새 row 추가 시 사이트가 봇 webhook을 호출, 봇이 alarm 채널 매핑 lookup 후 임베드 발송.
인물 코인 자동 가격 변동
오늘의 발언 등록 시 발언자 자동 등록 + 가격 점프
발언자: +5~15%. 본문에 등장한 다른 등록 인물: +1~5%. 모든 변동은 stock_ticks 에 기록되어 차트로 확인 가능.
버그 채택 자동 보상
관리자가 사이트에서 버그 제보를 채택하면 +200 R + BUG HUNTER 칭호 자동 부여
사이트 → 봇 webhook → 코인 적립 + userTitles 추가 + 사용자에게 DM 통지. 칭호는 사이트 프로필에서도 표시.
더 자세한 슬래시 커맨드 시그니처는
전체 커맨드 보기 →