# Telegram Operations & Auto Trading Bot

App Master 운영 알림·통계 + 코인/주식 가격 알림 + 기술적 분석 자동매매 텔레그램 봇

**Port: 4001**

---

## 환경변수 (.env)

로컬과 배포 서버가 각각 자체 `.env`를 사용한다. 배포 워크플로는 서버의 기존
`.env`를 보존하므로 로컬 `.env`나 커밋으로 운영 비밀값이 전달되지 않는다.

| 변수 | 설명 | 필수 |
|------|------|------|
| `TELEGRAM_BOT_TOKEN` | 텔레그램 봇 토큰 | O |
| `TELEGRAM_CHAT_ID` | 기본 채팅 ID (없으면 첫 명령 채팅방 자동 기억) | X |
| `TELEGRAM_ALLOWED_CHAT_IDS` | 관리 명령 허용 채팅 ID (쉼표 구분) | X |
| `UPBIT_ACCESS_KEY` | 업비트 API Access Key | 자동매매 시 |
| `UPBIT_SECRET_KEY` | 업비트 API Secret Key | 자동매매 시 |
| `AUTH_KEYS` | 외부 API 인증 키 (쉼표 구분) | X |
| `OFFICIAL_MAIL_ADMIN_URL` | 오피셜메일 설정 대행 관리자 화면 주소 | X |
| `OFFICIAL_MAIL_DB_*` | 오피셜메일 DB 접속 정보 | 도메인 설정 대행 알림 사용 시 |
| `PORT` | 서버 포트 (기본: 4001) | X |
| `APP_MASTER_DB_*` | App Master DB 접속 정보 | 운영 통계 사용 시 |
| `APP_MASTER_EVENT_POLL_SECONDS` | 문의·결제 감시 간격 (최소 5초) | X |
| `ALERT_POLL_SECONDS` | 가격 알림 감시 간격 (기본: 10초) | X |
| `TELEGRAM_LONG_POLL_SECONDS` | Telegram 업데이트 장기 폴링 시간 (기본: 30초) | X |
| `TELEGRAM_LONG_POLL_READ_TIMEOUT` | 장기 폴링 읽기 제한 시간 (기본: 폴링 시간 + 15초) | X |
| `TELEGRAM_CONNECT_TIMEOUT` | Telegram 연결 제한 시간 (기본: 10초) | X |
| `APP_MASTER_ADMIN_URL` | 알림의 관리자 화면 링크 | X |

## App Master 운영

| 명령어 | 설명 |
|--------|------|
| `/apps` | 현재 관리 중인 앱 목록과 통계 선택 메뉴 |
| `/stats <앱>` | 앱 이름 또는 키로 요약 통계 바로 조회 |

앱을 선택하면 요약, 사용자, 핵심 활동, 결제, 문의 중 실제 데이터가 있는
항목만 표시됩니다. 신규 문의와 완료 결제는 기본 채팅방으로 자동 전송되며,
체크포인트와 전송 이력을 DB에 저장해 서버 재시작 시 중복이나 누락을 방지합니다.

### 운영 알림 공유

주 계정에서 `/notify_invite`를 실행하면 15분 동안 한 번만 사용할 수 있는 초대
코드가 발급됩니다. 보조 계정은 봇과의 개인 채팅에서 안내된
`/notify_join <초대코드>`를 실행합니다.

| 명령어 | 설명 |
|--------|------|
| `/notify_invite` | 운영 알림 수신 계정 초대 코드 발급 |
| `/notify_list` | 현재 보조 수신 계정 목록 |
| `/notify_remove <chat_id>` | 주 계정에서 보조 수신 계정 제거 |
| `/notify_leave` | 보조 계정에서 운영 알림 구독 해제 |

보조 계정에는 결제 완료, 문의, 도메인 지원 등 운영 알림만 전송됩니다. 트레이딩
명령, 잔고 정보, 거래 및 포지션 알림은 기존 주 계정에만 전송됩니다.

오피셜메일의 도메인 연결 설정 대행 신청도 텔레그램 서버가 DB에서 직접 감지합니다.
오피셜메일 앱에서 텔레그램 서버로 웹훅을 호출하거나 별도 인증 키를 관리하지 않습니다.

감시 대상 결제 데이터는 아가노트 인앱·키즈노트 포토북, 밸런스픽 프리미엄,
탭카운터, 캘모아, 크로마키, 가세로캠입니다.

## 업비트 API 키 발급

1. [업비트](https://upbit.com) 로그인
2. [마이페이지 > Open API 관리](https://upbit.com/mypage/open_api_management)
3. **자산조회**, **주문조회**, **주문하기** 권한 체크
4. **허용 IP**에 서버 IP 등록
5. Access Key, Secret Key → `.env`에 입력

---

## 봇 명령어

### 가격 알림

| 명령어 | 예시 |
|--------|------|
| `/price <심볼>` | `/price BTC` `/price 삼성전자` `/price AAPL` |
| `/coins <키워드>` | `/coins 트론` `/coins 비트코인` |
| `/stocks <키워드>` | `/stocks 삼성전자` `/stocks AAPL` `/stocks 005930` |
| `/alert_above <심볼> <가격>` | `/alert_above BTC 100000000` `/alert_above 삼성전자 300000` |
| `/alert_below <심볼> <가격>` | `/alert_below ETH 3000000` `/alert_below AAPL 450000` |
| `/alerts` | 알림 목록 |
| `/remove <번호>` | `/remove 1` |
| `/remove_all` | 전체 해제 |

주식 검색은 한국 상장주(코스피/코스닥)와 미국 주요 종목 티커를 지원합니다.
가격 알림은 기본적으로 원화 기준으로 저장되며, 미국 주식은 Yahoo Finance 시세를
하나은행 고시환율로 환산해 비교합니다.

### 자동매매

| 명령어 | 설명 |
|--------|------|
| `/auto_start <투자금>` | 자동매매 시작 (예: `/auto_start 500000`) |
| `/auto_stop` | 전량 매도 후 중지 |
| `/auto_status` | 현황·포지션·수익률 |
| `/balance` | 업비트 잔고 |

투자금만 설정하면 나머지는 전부 자동:
- 투자금 기반 분산투자 종목 수 자동 계산 (최대 5종목)
- 완성된 15분봉마다 KRW 전체 종목 스캔 (거래대금순 우선 처리)
- 전체 종목 일봉은 1시간 캐시해 API 호출 제한 안에서 운영
- 코인별 변동성(ATR) 기반 목표수익/손절 자동 설정
- 최근 200건 체결과 상위 5호가로 매수·매도 수급 확인
- 수수료(0.05%) 감안한 수익 계산
- 매수 후보가 없을 때는 텔레그램 메시지를 보내지 않음

---

## 자동매매 전략

### 매수

- 개별 코인의 일봉 상승 추세를 필수로 확인
- 메이저는 BTC 일봉 상승장에서만 EMA·MACD·RSI·거래량 회복 신호 사용
- 알트는 BTC 상승 `+2`, 중립 `0`, 하락 `-2`의 시장 위험 점수를 반영
- 알트는 정배열·거래량·직전 고점 돌파가 겹친 강한 신호만 사용
- 일봉과 15분봉 ATR로 저변동·과변동 종목 제외
- 호가 잔량, 실제 체결강도, 상위 10% 대량 체결 방향을 최종 점수에 반영
- 매도 수급 신호가 2개 이상 겹치거나 스프레드가 30bp를 넘으면 매수 차단

호가·체결 수급은 인증이 필요 없는 Upbit 공개 API를 사용한다. 과거 호가 전체
이력은 제공되지 않으므로 기존 백테스트는 캔들 전략을 검증하고, 수급 필터는
실시간 진입 단계에서 추가로 적용한다.

### 매도 (자동)

- ATR 기반 목표수익 도달 (변동성 적응)
- ATR 기반 손절
- RSI > 75 과매수 + 수익 중
- MACD 데드크로스 + 수익 중
- 트레일링 스탑 (고점 대비 ATR 이상 하락 + 수익 중)

### 마켓

업비트 **KRW 마켓** 사용 (수수료 0.05%)

---

## 배포

GitHub Actions → `main` push 시 자동 배포

필수 GitHub Secrets:
- `SERVER_HOST`
- `SERVER_USER`
- `SERVER_SSH_KEY`
- `SERVER_PORT`
- `OFFICIAL_MAIL_DB_HOST`
- `OFFICIAL_MAIL_DB_PORT`
- `OFFICIAL_MAIL_DB_USER`
- `OFFICIAL_MAIL_DB_PASSWORD`
- `OFFICIAL_MAIL_DB_NAME`

텔레그램, 업비트, App Master 설정은 서버의 `.env`에서 직접 관리한다. 배포 시
`.env`가 없거나 비어 있으면 실패하며, 오피셜메일 DB 접속 정보는 GitHub Secret
값으로 갱신한다.