MINE-Discord-Bot

KO | EN

gitlite — search

#typescript #go #golang #machine-learning #rust #linux #docker #macos #cli #kubernetes #vue #pytorch #security #ios

MINE-Discord-Bot

(★ 112)

Discord Music & Utility Bot

MINE-Discord-Bot Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 마인 Discord 봇

**MINE봇**은 개인 서버에서 쓰기 좋게 만든 음악·코인 경제 디스코드 봇입니다.

전용 노래 채널인 **Soundroom**을 중심으로 음악을 재생하고, 서버 안에서 사용할 수 있는 가상 코인 경제 기능을 함께 제공합니다.

![Soundroom 미리보기](https://raw.githubusercontent.com/adgjmptw2/MINE-Discord-Bot/main/docs/readme-soundroom-panel.png)

### 주요 기능

🎵 **음악 / Soundroom**

- `/세팅`으로 노래 전용 채널과 컨트롤 패널을 만듭니다.
- 전용 노래 채널 기반 음악 재생
- 플레이리스트 기능
- 인기차트 관리 기능

![음악 기능 미리보기](https://raw.githubusercontent.com/adgjmptw2/MINE-Discord-Bot/main/docs/readme-player-and-queue.png)

🪙 **코인 경제**

- `/출석`, `/알바`, `/낚시`로 코인 획득
- `/자산`, `/프로필`, `/랭킹`으로 내 상태 확인
- `/미션`, `/업적`으로 활동 보상 획득

![주식·자산 미리보기](https://raw.githubusercontent.com/adgjmptw2/MINE-Discord-Bot/main/docs/readme-mock-investment-stocks.png)

📈 **주식 모의투자**

- 코인으로 국내 인기 종목을 매수·매도
- 시세는 설정한 Provider(예: yahoo, mock 등)에서 가져옵니다.
- `/주식목록`, `/시세`, `/매수`, `/매도`, `/주식자산`
- 실제 투자용이 아닌 서버 내 모의투자 게임입니다.
- 매수·매도 시간을 KST 평일 창으로 제한할 수 있습니다(`.env`).

🎮 **미니게임 / 상점**

- `/가위바위보`로 코인 게임
- `/상점`, `/구매`, `/내아이템`
- 칭호 구매·장착, 프로필·랭킹 표시

🏆 **시즌 / 관리자 기능**

- 서버 코인 랭킹 시즌 관리
- 코인 지급·차감, 유저 초기화, 서버 초기화
- `/상태`, `/도움말`로 운영 상태와 명령어 확인

🔮 **오늘의 운세**

- `/오늘운세`로 저장형(프로필 저장) 또는 일회용 재미용 운세를 확인합니다.
- 오늘의 흐름·대인운·코인운·게임운 등과 행운 키워드·색·숫자를 보여 줍니다.
- 저장형을 쓰려면 봇 호스트가 `FORTUNE_PROFILE_ENCRYPTION_KEY_BASE64`를 설정해야 합니다(`.env.example` 참고).

![오늘의 운세 미리보기](https://raw.githubusercontent.com/adgjmptw2/MINE-Discord-Bot/main/docs/readme-fortune-panel.png)

운세 프로필(저장형)이 어떤 데이터를 다루는지는 **[개인정보 안내](docs/PRIVACY.md)** 를 참고하세요.

MINE의 코인, 주식, 게임 기능은 모두 **서버 내 가상 기능**이며 실제 돈, 환전, 현물 보상과는 관련이 없습니다.

문서: [배포 가이드](docs/deployment.md) · [웹 대시보드 배포](docs/WEB_DASHBOARD_DEPLOYMENT.md) · [베타 운영 체크리스트](docs/beta-ops-checklist.md) · [개인정보 안내](docs/PRIVACY.md)

## 주식 모의투자 게임

서버별 가상 화폐로 국내 인기 주식 5개를 사고파는 모의투자 게임입니다.

실제 돈·환전·현물 보상은 없습니다.

실제 투자 판단에 사용할 수 없습니다.

시세·평가는 지연되거나 부정확할 수 있습니다.

가격 소스는 StockQuoteProvider 구현을 바꿉니다.

mock / yahoo / twelvedata 등으로 교체할 수 있습니다.

**거래 시간·수수료:** `STOCK_TRADING_HOURS_ENABLED=true`이면 **KST 평일**에만 `/매수`·`/매도`가 가능하고, 기본 창은 **09:00 이상 15:30 미만**(15:30 정각은 제외)입니다. 토·일은 거래 불가이며 **공휴일·임시 휴장은 반영하지 않습니다.** 매수·매도 수수료와 매도 거래세는 `.env`의 `STOCK_BUY_FEE_RATE`, `STOCK_SELL_FEE_RATE`, `STOCK_SELL_TAX_RATE`로 정하며, 실제 증권사와 동일하지 않을 수 있습니다. `/주식목록`, `/시세`, `/주식자산` 등 조회는 시간 제한 없습니다.

### 지원 종목

| 종목 | 종목코드 |
| --- | --- |
| 삼성전자 | 005930 |
| SK하이닉스 | 000660 |
| NAVER | 035420 |
| 카카오 | 035720 |
| 현대차 | 005380 |

### 슬래시 명령어

| 명령어 | 설명 |
| --- | --- |
| /도움말 | 봇의 주요 명령어와 사용법을 확인합니다 |
| /상태 | 봇의 주요 운영 상태를 확인합니다 |
| /오늘운세 | 저장형 또는 일회용으로 재미용 오늘의 운세를 확인합니다 |
| /세팅 | Soundroom 전용 음악 채널과 컨트롤 패널을 생성합니다 |
| /출석 | 하루 1회 가상 화폐를 받습니다 |
| /알바 | 일정 시간마다 알바를 해서 코인을 법니다 |
| /낚시 | 일정 시간마다 낚시를 해서 코인을 법니다 |
| /미션 | 오늘의 코인 미션 진행도를 확인합니다 |
| /상점 | 코인으로 구매할 수 있는 아이템을 확인합니다 |
| /구매 | 상점 아이템을 구매합니다 |
| /내아이템 | 보유 아이템과 장착 상태를 확인합니다 |
| /칭호장착 | 구매한 칭호를 장착합니다 |
| /칭호해제 | 장착 중인 칭호를 해제합니다 |
| /프로필 | 유저의 코인 프로필을 확인합니다 |
| /업적 | 업적 진행도와 보상을 확인합니다 |
| /자산 | 내 총 잔액을 공개 메시지로 확인합니다 |
| /주식자산 | 내 주식 보유 현황을 본인만 자세히 확인합니다 |
| /주식목록 | 지원 종목·시세를 ANSI 블록으로 확인합니다 (공개 메시지) |
| /시세 | 특정 종목의 모의투자 시세를 확인합니다 |
| /매수 | 가상 화폐로 주식을 매수합니다 |
| /매도 | 보유 주식을 매도합니다 |
| /랭킹 | 서버 코인 랭킹을 확인합니다 (표시는 `<@userId>` 형태이나 응답에 `allowedMentions`로 알림 없음) |
| /코인지급 | 관리자가 유저에게 코인을 지급합니다 |
| /코인차감 | 관리자가 유저의 코인을 차감합니다 |
| /유저초기화 | 관리자가 특정 유저의 코인/주식 데이터를 초기화합니다 |
| /서버초기화 | 관리자가 이 서버의 코인/주식 데이터를 전체 초기화합니다 |
| /시즌시작 | 관리자가 서버 코인 랭킹 시즌을 시작합니다 |
| /시즌종료 | 현재 시즌을 종료하고 랭킹 결과를 저장합니다 |
| /시즌정보 | 현재 시즌과 최근 종료 시즌 정보를 확인합니다 |
| /가위바위보 | 코인을 걸고 봇과 가위바위보를 합니다 |
| /게임기록 | 최근 코인 미니게임 기록을 확인합니다 |
| /코인설정 | 서버 코인 경제 설정을 확인하거나 변경합니다 |

`<@id>`는 클라이언트에서 멘션처럼 보이지만, 응답 옵션으로 자동 멘션·알림을 끕니다.

### 환경 변수

| 변수 | 설명 |
| --- | --- |
| FORTUNE_PROFILE_ENCRYPTION_KEY_BASE64 | 저장형 `/오늘운세` 프로필 암호화(AES-256-GCM). 32바이트를 Base64로 인코딩한 값. 비우면 일회용만 가능 |
| STOCK_PRICE_PROVIDER | mock, yahoo, twelvedata 중 하나 |
| STOCK_PRICE_REFRESH_INTERVAL_MS | 기본 300000ms, 5분 (`interval` 모드에서 사용) |
| STOCK_PRICE_REFRESH_MODE | `interval`(기본) 또는 `scheduled-close` |
| STOCK_SCHEDULED_CLOSE_REFRESH_TIMES_KST | `scheduled-close`일 때만 사용. 쉼표로 구분한 KST `HH:mm` 목록 |
| STOCK_TRADING_HOURS_ENABLED | `true`면 평일 KST 지정 시간에만 `/매수`·`/매도` (기본 `false`) |
| STOCK_TRADING_START_KST | 거래 시작 `HH:mm` (기본 `09:00`) |
| STOCK_TRADING_END_KST | 거래 종료 `HH:mm`, **미포함** 상한 (기본 `15:30`) |
| STOCK_BUY_FEE_RATE | 매수 수수료율 (기본 `0.00015`) |
| STOCK_SELL_FEE_RATE | 매도 수수료율 (기본 `0.00015`) |
| STOCK_SELL_TAX_RATE | 매도 거래세율 (기본 `0.002`) |
| TWELVE_DATA_API_KEY | twelvedata 사용 시 필요 |

### 개발·테스트 순서

1. .env에서 STOCK_PRICE_PROVIDER=mock 설정
2. npm run check
3. npm run build
4. npm run start:bot
5. Discord 일반 채널에서 /출석
6. /주식목록
7. /시세 종목:삼성전자
8. /매수 종목:삼성전자 금액:5000
9. /자산
10. /주식자산
11. /매도 종목:삼성전자 매도:50%
12. /랭킹

### 시세 갱신 모드

- 기본은 **interval**: `STOCK_PRICE_REFRESH_INTERVAL_MS`마다 메모리 캐시를 갱신한다.

- **scheduled-close**: KST 평일에만, 지정 시각(기본 15:31, 15:35, 15:40, 16:00)마다 갱신을 시도한다.

- 정규장 마감 직후 반영 지연을 고려한 선택 모드이며, 공휴일·임시 휴장은 아직 반영하지 않는다.

- 시세는 demo/delayed 등으로 지연·누락될 수 있으며 실제 투자용이 아니다.

### Provider·시세 구조

- 명령어는 외부 API를 직접 호출하지 않는다.
- StockMarketService가 주기적으로 가격을 캐시한다.
- `/자산`은 총자산(현금+주식 평가)만 공개 메시지로 표시한다.
- `/주식자산`은 상세 보유·수익률을 본인만(ephemeral) 확인한다.
- /시세, /매수, /매도, /랭킹은 캐시 가격만 사용하며, 체결·시세 안내는 채널에 공개 메시지로 표시된다.
- Yahoo provider는 공식 투자용 데이터가 아닌 demo/delayed quote provider다.

### 알려진 한계

- `/매수`·`/매도`는 `.env`의 `STOCK_TRADING_HOURS_ENABLED` 등으로 **평일 KST 지정 시간**에만 제한할 수 있으며, **공휴일·임시 휴장은 반영하지 않는다**(기본은 24시간 주문 가능).
- 시즌은 관리자가 `/시즌시작`·`/시즌종료`로 선택 운영하며, 시즌 종료만으로 유저 지갑·거래 데이터가 자동 초기화되지는 않음
- 예약/지정가 주문 없음
- Yahoo provider는 공식 투자용 데이터가 아님
- 가격 데이터는 지연되거나 누락될 수 있음
- 대규모 서버에서는 랭킹 집계 최적화 필요
- 실제 투자용 아님

### 포트폴리오 관점

- Discord slash command 기반 인터랙션
- SQLite 기반 서버별 지갑, 보유, 거래 기록
- Provider 인터페이스로 가격 데이터 소스 분리
- 캐시 기반 시세 조회
- 트랜잭션 기반 매수/매도 처리
- 서버별 랭킹 계산

상세 설계는 [docs/stock-investing.md](docs/stock-investing.md)를 참고합니다.

수동 테스트는 [docs/stock-manual-test.md](docs/stock-manual-test.md)를 참고합니다.

배포·VM 구성은 [docs/deployment.md](docs/deployment.md)를, 베타 운영 점검은 [docs/beta-ops-checklist.md](docs/beta-ops-checklist.md)를 참고합니다.

### Soundroom 웹 대시보드

브라우저에서 노래채널 상태·재생 조작·검색/추가·대기열 관리를 할 수 있습니다.

| 모드 | 접속 예 | 요약 |
| --- | --- | --- |
| 개발 | `http://localhost:3000/dashboard` | `npm run dashboard:dev` + API `127.0.0.1:3077` |
| 정적 서빙 | `http://127.0.0.1:3077/dashboard` | `npm run build:all` 후 `WEB_DASHBOARD_STATIC_ENABLED=true` |

공개 **랜딩**(`/`)·**웹 리모컨**(`/dashboard`)·**개인정보처리방침**(`/privacy`)·**이용약관**(`/terms`)을 제공합니다. `WEB_DASHBOARD_PUBLIC_URL`을 설정하면 Soundroom 패널에 **🌐 웹 리모컨** 링크가 표시됩니다. Discord Developer Portal 등록 URL은 배포 가이드를 참고하세요.

운영(HTTPS·reverse proxy)·OAuth Redirect·환경 변수는 **[웹 대시보드 배포 가이드](docs/WEB_DASHBOARD_DEPLOYMENT.md)** 를 참고하세요.

```bash
npm run check:all           # typecheck + 대시보드 빌드 검증
npm run build:all           # 봇 dist + dashboard/dist
npm run dashboard:preflight # 운영 전 .env·빌드·보안 설정 점검
npm run dashboard:dev       # 개발 UI만
```

운영 공개 전 권장 순서: `npm run check` → `npm run build` → `npm run dashboard:build` → `npm run dashboard:preflight`

운영 전 최종 점검은 **[웹 대시보드 운영 체크리스트](docs/WEB_DASHBOARD_OPERATIONS_CHECKLIST.md)** 를 참고하세요. 상세 설정: [웹 대시보드 배포 가이드](docs/WEB_DASHBOARD_DEPLOYMENT.md)

## 준비

1. Node.js 20 이상을 설치합니다.

2. Lavalink 서버를 준비합니다.

3. `.env.example`을 복사해서 `.env`를 만들고 값을 채웁니다.

```bash
npm install
npm run start:bot
```

`start:bot`과 `start`는 실행 전에 자동으로 build를 돌립니다.

음악(Lavalink)까지 한 번에 로컬에서 켜려면 `.env`에 **`LAVALINK_JAR_DIR`**(`Lavalink.jar` 가 있는 폴더의 절대 경로)를 넣고 `npm run start:all` 을 사용합니다. Lavalink만 켤 때는 `npm run start:lavalink` 입니다. 원격 Lavalink(`LAVALINK_HOST`가 localhost가 아님)면 `start:all`은 쓸 수 없고, 터미널 두 개로 Lavalink 후 봇 순서를 지키면 됩니다.

`dist`만 갱신하려면 `npm run build`만 실행하면 됩니다.

기본 패키지 매니저는 npm(`package-lock.json`)입니다.

Bun으로도 실행할 수 있어 `bun.lock`도 함께 두었습니다.

```bash
bun install
bun run start:bot:bun
```

MINE-Discord-Bot

MINE-Discord-Bot Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

MINE-Discord-Bot

MINE-Discord-Bot Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README