kaffa/telegram-bot-workers
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(phase-5-3): Logger, Metrics, 알림 시스템 통합

Browse Source 
Phase 5-3 모니터링 강화 작업의 통합을 완료했습니다.

변경사항:
- Logger 통합: console.log를 구조화된 로깅으로 전환 (9개 파일)
  - JSON 기반 로그, 환경별 자동 전환 (개발/프로덕션)
  - 타입 안전성 보장, 성능 측정 타이머 내장

- Metrics 통합: 실시간 성능 모니터링 시스템 연결 (3개 파일)
  - Circuit Breaker 상태 추적 (api_call_count, error_count, state)
  - Retry 재시도 횟수 추적 (retry_count)
  - OpenAI API 응답 시간 측정 (api_call_duration)

- 알림 통합: 장애 자동 알림 시스템 구현 (2개 파일)
  - Circuit Breaker OPEN 상태 → 관리자 Telegram 알림
  - 재시도 실패 → 관리자 Telegram 알림
  - Rate Limiting 적용 (1시간에 1회)

- 문서 업데이트:
  - CLAUDE.md: coder 에이전트 설명 강화 (20년+ 시니어 전문가)
  - README.md, docs/: 아키텍처 문서 추가

영향받은 파일: 16개 (수정 14개, 신규 2개)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
kappa
2026-01-19 21:23:38 +09:00
parent 410676e322
commit eee934391a
16 changed files with 675 additions and 777 deletions
Download Patch File Download Diff File Expand all files Collapse all files

728
README.md
View File

@@ -1,715 +1,79 @@
# Cloudflare Workers 텔레그램 봇
# 🤖 Cloudflare Workers 텔레그램 AI 봇
> Cloudflare Workers + D1 + OpenAI를 활용한 사용자 프로필 기반 텔레그램 봇
> **Cloudflare Workers + D1 + OpenAI**를 활용한 서버리스 아키텍처 기반의 지능형 텔레그램 봇입니다.
> 사용자별 프로필을 자동으로 생성하고 기억하며, 예치금 관리 및 도메인 등록 등의 복잡한 작업을 수행할 수 있습니다.
**📖 이 문서**: 기능 소개, 배포 가이드, 사용법 (사용자/운영자용)
**🔧 [CLAUDE.md](./CLAUDE.md)**: 기술 상세, 코드 패턴, 트러블슈팅 (개발자용)
![License](https://img.shields.io/badge/license-MIT-blue.svg)
![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)
![Cloudflare Workers](https://img.shields.io/badge/Cloudflare-Workers-orange)
## 목차
## 📚 문서 안내
1. [개요](#개요)
2. [아키텍처](#아키텍처)
3. [Function Calling](#function-calling)
4. [예치금 시스템](#예치금-시스템)
5. [도메인 관리](#도메인-관리)
6. [프로젝트 구조](#프로젝트-구조)
7. [배포 가이드](#배포-가이드)
8. [보안 설정](#보안-설정)
9. [봇 명령어](#봇-명령어)
- **[사용자 가이드 (User Guide)](./docs/USER_GUIDE.md)**: 봇 사용법, 명령어, 예치금/도메인 기능 설명
- **[시스템 아키텍처 (Architecture)](./docs/ARCHITECTURE.md)**: 기술 구조, 데이터 흐름, 프로필 시스템 상세
- **[개발자 가이드 (Dev Guide)](./CLAUDE.md)**: 개발 환경 설정, 컨벤션, 트러블슈팅
---
## 개요
## ✨ 주요 기능
### 주요 기능
- **OpenAI GPT-4o-mini**: 고품질 AI 응답 및 Function Calling 지원
- **사용자 프로필**: 대화에서 사용자의 관심사, 목표, 맥락을 추출하여 프로필 구축
- **Function Calling (8개)**: 날씨, 검색, 시간, 계산, 문서 조회, 도메인 관리, **도메인 추천**, 예치금 관리
- **Context7 연동**: 프로그래밍 라이브러리 공식 문서 실시간 조회
- **동적 도구 로딩**: 메시지 키워드 기반으로 필요한 도구만 선택하여 토큰 절약
- **도메인 추천**: GPT가 창의적 도메인 생성 → 가용성 자동 확인 → 가격과 함께 제안
- **예치금 시스템**: 코드 직접 처리, 은행 입금 자동 감지(SMS/AI 파싱) + 사용자 신고 매칭으로 자동 충전
- **Email Worker**: SMS → 메일 → 자동 파싱(Regex + AI 폴백)으로 입금 알림 처리
- **무한 컨텍스트**: 슬라이딩 윈도우(3개)로 프로필 유지, 무제한 대화 기억
- **개인화 응답**: 프로필 기반으로 맞춤형 AI 응답 제공
- **폴백 지원**: OpenAI 미설정 시 Workers AI(Llama)로 자동 전환
### 기술 스택
| 서비스 | 용도 |
|--------|------|
| **Workers** | 서버리스 런타임 |
| **D1** | SQLite 데이터베이스 |
| **OpenAI** | GPT-4o-mini + Function Calling |
| **Context7** | 라이브러리 문서 조회 API |
| **도메인 관리** | 코드 직접 처리 → Namecheap API |
| **도메인 추천** | GPT + Namecheap API (코드 레벨) |
| **예치금 관리** | 코드 직접 처리 → D1 |
| **Namecheap API** | 도메인 조회/가용성/가격 백엔드 |
| **Email Workers** | SMS → 메일 파싱 (입금 알림) |
| **Workers AI** | 폴백용 (Llama 3.1 8B) |
* 🧠 **AI 기반 개인화**: 대화 내용을 분석하여 사용자의 관심사와 맥락을 기억하는 **동적 프로필 시스템**
* 🛠 **Function Calling**: 날씨, 검색, 계산, 시간 등 다양한 도구를 자연어로 호출
* 💰 **예치금 시스템**: 은행 SMS 자동 파싱(AI 폴백 지원) 및 양방향 매칭을 통한 자동 충전
* 🌐 **도메인 관리**: 도메인 검색, 추천(AI), 가격 조회, 등록, DNS 관리 통합
* ⚡ **서버리스**: Cloudflare Workers 위에서 동작하여 별도의 서버 관리 불필요
---
## 아키텍처
### 메시지 처리 흐름
```
[사용자 메시지]
│
▼
┌──────────────────┐
│ Cloudflare │
│ Worker │
└──────────────────┘
│
▼
┌──────────────────┐
│ OpenAI API │ ← GPT-4o-mini
│ (Function Call) │ 도구 호출 자동 판단
└──────────────────┘
│
┌───┴───┬───────┬───────┬───────┬───────┬───────┬───────┐
▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼
[날씨] [검색] [시간] [계산] [문서] [도메인] [도메인 [예치금]
│ │ │ │ │ │ 추천] │
│ │ │ │ │ │ │ └── Deposit Agent
│ │ │ │ │ │ └── GPT + Namecheap API
│ │ │ │ │ └── 코드 직접 처리 → Namecheap API
│ │ │ │ └── Context7
└───┬───┴───────┴───────┴───────┴───────────────────────────┘
▼
┌──────────────────┐
│ 최종 응답 생성 │
└──────────────────┘
│
▼
[D1 저장] → [Telegram 응답]
```
### 사용자 프로필 시스템
```
[사용자 메시지]
│
▼
┌──────────────────┐
│ message_buffer │ ← 최대 19개 (20개 되면 프로필 업데이트)
└──────────────────┘
│ 20개 도달
▼
┌──────────────────────────────────────────┐
│ 통합 프로필 분석 │
│ ┌─────────────────┐ ┌───────────────┐ │
│ │ 기존 요약 3개 │ │ 새 메시지 20개 │ │
│ │ [v1][v2][v3] │ │ (사용자 발언) │ │
│ └────────┬────────┘ └───────┬───────┘ │
│ └──────────┬────────┘ │
│ ↓ │
│ OpenAI 통합 분석 │
└──────────────────────────────────────────┘
│
▼
┌──────────────────┐
│ summaries │ ← 최근 3개만 유지 (슬라이딩 윈도우)
│ [v1] [v2] [v3] │ 새 v4 저장, v1 삭제
└──────────────────┘
```
**3개 요약 통합 방식:**
- 프로필 업데이트 시 기존 요약 3개 + 새 메시지를 함께 AI에 전달
- AI가 모든 버전을 종합 분석하여 새로운 통합 프로필 생성
- 응답 생성 시에도 3개 요약 모두 컨텍스트로 제공 (최신 버전 우선)
### 프로필 분석 내용
| 추출 정보 | 설명 |
|-----------|------|
| **관심사** | 사용자가 자주 언급하는 주제 |
| **목표** | 해결하려는 문제, 달성하려는 것 |
| **맥락** | 직업, 상황, 배경 정보 |
| **선호도** | 좋아하는 것, 싫어하는 것 |
| **질문 패턴** | 무엇에 대해 알고 싶어하는지 |
---
## Function Calling
OpenAI Function Calling을 통해 AI가 자동으로 필요한 도구를 호출합니다.
### 지원 기능
| 기능 | 예시 질문 | API |
|------|-----------|-----|
| **날씨** | "서울 날씨", "도쿄 날씨 알려줘" | wttr.in |
| **검색** | "파이썬이 뭐야", "클라우드플레어란" | Brave Search |
| **시간** | "지금 몇 시야", "뉴욕 시간" | 내장 |
| **계산** | "123 * 456", "100의 20%" | 내장 |
| **문서** | "React hooks 사용법", "OpenAI API 예제" | Context7 |
| **도메인** | "도메인 목록", "anvil.it.com 네임서버", ".com 가격", "google.com whois" | 코드 직접 처리 + WHOIS API |
| **도메인 추천** | "커피숍 도메인 추천해줘", "스타트업 도메인 아이디어" | GPT + Namecheap |
| **예치금** | "잔액 확인", "충전하고 싶어", "10000원 입금했어" | 코드 직접 처리 |
### 동작 방식
```
사용자: "서울 날씨 어때?"
│
▼
OpenAI: "get_weather 함수를 호출해야겠다"
│
▼
Worker: wttr.in API 호출 → 날씨 데이터 수신
│
▼
OpenAI: 날씨 데이터를 자연어로 응답 생성
│
▼
응답: "🌤 서울 날씨\n온도: 5°C\n습도: 45%..."
```
### 동적 도구 로딩
메시지 키워드를 분석하여 필요한 도구만 선택적으로 로딩합니다. (토큰 40% 절약)
| 카테고리 | 도구 | 감지 패턴 |
|----------|------|-----------|
| domain | manage_domain, suggest_domains | 도메인, 네임서버, whois, .com |
| deposit | manage_deposit | 입금, 충전, 잔액, 계좌 |
| weather | get_weather | 날씨, 기온, 비, 눈 |
| search | search_web, lookup_docs | 검색, 찾아, 뭐야, 가격 |
| utility | get_current_time, calculate | (항상 포함) |
패턴 매칭 없으면 전체 도구 사용 (폴백)
### AI Gateway
OpenAI API 호출을 Cloudflare AI Gateway를 통해 프록시하여 지역 제한을 우회합니다.
```
Gateway ID: telegram-bot
URL: gateway.ai.cloudflare.com/v1/{account_id}/telegram-bot/openai/...
```
**대시보드**: Cloudflare Dashboard → AI → AI Gateway → telegram-bot
---
## 예치금 시스템
은행 계좌 입금 기반 예치금 충전 시스템입니다. 사용자 신고와 은행 SMS 알림을 양방향으로 자동 매칭합니다.
### 입금 계좌
| 은행 | 계좌번호 | 예금주 |
|------|----------|--------|
| 하나은행 | 427-910018-27104 | 주식회사 아이언클래드 |
> **Vault 경로**: `secret/companies/ironclad-corp` @ `vault.anvil.it.com`
### 자동 매칭 흐름
```
[시나리오 1: 사용자가 먼저 신고]
사용자: "홍길동 50000원 입금했어"
│
▼
┌──────────────────┐
│ bank_notifications│ ← 기존 은행 알림 확인
└──────────────────┘
│
├── 매칭 발견 → 즉시 confirmed + 잔액 증가 (대화 중 응답)
│
└── 매칭 없음 → pending 상태로 대기 (SMS 도착 시 자동 매칭 + 알림)
```
```
[시나리오 2: 은행 SMS가 먼저 도착]
은행 SMS → 메일 전달 → Cloudflare Email Routing → Worker (email handler)
│
▼
┌──────────────────┐
│ SMS 파싱 │ ← 입금자명, 금액, 은행 추출 (AI 폴백 지원)
│ (하나/KB/신한) │
└──────────────────┘
│
▼
┌──────────────────┐
│ deposit_transactions│ ← 대기중 입금 확인
└──────────────────┘
│
├── 매칭 발견 → confirmed + 잔액 증가 + 사용자에게 Telegram 알림 🎉
│ + 관리자에게 Telegram 알림
│
└── 매칭 없음 → bank_notifications에 저장 + 관리자에게 알림 (대기)
```
### 지원 기능
| 기능 | 설명 | 권한 |
|------|------|------|
| `잔액 조회` | 현재 예치금 잔액 확인 | 모든 사용자 |
| `계좌 안내` | 입금 계좌 정보 표시 | 모든 사용자 |
| `입금 신고` | 입금자명 + 금액으로 충전 요청 | 모든 사용자 |
| `거래 내역` | 최근 거래 내역 조회 | 모든 사용자 |
| `입금 취소` | 대기중 입금 취소 (번호 없으면 최근 pending 자동 선택) | 모든 사용자 |
| `대기 목록` | 미처리 입금 목록 조회 | 관리자 전용 |
| `수동 확인` | 입금 수동 확정 처리 | 관리자 전용 |
| `입금 거절` | 입금 요청 거절 | 관리자 전용 |
### 사용법 예시
```
# 잔액 확인
"잔액" → "현재 잔액: 10,000원"
# 계좌 안내
"입금할게요" → 계좌 정보 안내
# 입금 신고 (자연어 금액 인식 지원)
"홍길동 50000원 입금했어" → 즉시 처리
"홍길동 만원 입금" → 10,000원으로 인식
"홍길동 5천원" → 5,000원으로 인식
# 거래 내역
"거래 내역" → "#5: 입금 10원 ✓ (01/17)"
# 간편 취소
"취소해줘" → 가장 최근 pending 자동 취소
```
**특징:**
- 🔍 **AI 파싱**: 정형화되지 않은 은행 문자도 AI가 자동 분석하여 처리
- 🔢 **자연어 금액**: "만원", "5천원", "삼만오천원" 등 자동 변환
- ⚡ **즉시 실행**: 입금자명+금액 있으면 확인 없이 바로 처리
- 📋 **동시 요청**: 기존 pending 있어도 새 입금 신고 가능
- 🗑️ **간편 취소**: 거래번호 없이 "취소해줘"만으로 최근 pending 취소
### 자동 알림 시스템
자동 매칭 성공 시 **사용자와 관리자 모두에게 Telegram 알림**이 전송됩니다.
| 이벤트 | 사용자 알림 | 관리자 알림 |
|--------|-------------|-------------|
| 자동 매칭 성공 | ✅ 입금액 + 현재 잔액 | ✅ 입금 정보 + 매칭 완료 |
| 매칭 대기 (SMS만) | - | ⏳ 입금 정보 + 대기 상태 |
**사용자가 받는 메시지 예시:**
```
✅ 입금 확인 완료!
입금액: 7원
현재 잔액: 7원
감사합니다! 🎉
```
### Cloudflare Email Routing
SMS를 메일로 전달받아 Worker에서 직접 처리합니다.
**흐름:**
```
은행 SMS → 메일 전달 → Cloudflare Email Routing → Worker (email handler)
↓
SMS 파싱 → DB 저장 → 자동 매칭
↓
매칭 성공 → 사용자/관리자 Telegram 알림
```
**설정 방법:**
1. Cloudflare Dashboard → Email → Email Routing → Routes
2. 수신 주소 설정 (예: `deposit@your-domain.com`)
3. Worker로 라우팅: `telegram-summary-bot`
**지원 은행 SMS 패턴:**
- 하나은행 (Web발신): `[Web발신] 하나,01/16, 23:30 427******27104 입금5원 황병하`
- 하나은행 (기존): `[하나은행] 01/16 14:30 입금 50,000원 홍길동 잔액 1,234,567원`
- KB국민: `[KB] 입금 50,000원 01/16 14:30 홍길동`
- 신한: `[신한] 01/16 입금 50,000원 홍길동`
- **AI 자동 인식**: 패턴 미일치 시 AI가 내용 분석하여 자동 추출
---
## 도메인 관리
코드 직접 처리 방식의 도메인 관리 기능입니다. 메인 AI가 action 파라미터로 작업을 지정하고, 코드에서 Namecheap API를 호출합니다.
### 지원 기능
| 기능 | 설명 | 권한 |
|------|------|------|
| `도메인 목록` | 내 도메인 목록 조회 | 소유자 |
| `도메인 정보` | 도메인 상세 정보 (내 도메인 아니면 WHOIS 자동 조회) | 누구나 |
| `네임서버 조회` | 현재 네임서버 확인 | 누구나 |
| `네임서버 변경` | 네임서버 설정 변경 | 소유자 |
| `가격 조회` | TLD/ccSLD 등록 가격 (원화) | 누구나 |
| `WHOIS 조회` | 공개 WHOIS 정보 (RDAP) | 누구나 |
| `가용성 확인` | 도메인 등록 가능 여부 | 누구나 |
| `도메인 등록` | 새 도메인 등록 (예치금 차감) | 사용자 |
### 가격 조회
Namecheap 가격 + 13% 마진, 매일 환율 업데이트
```
사용자: ".com 가격"
봇: ".com 도메인 등록 가격은 20,000원입니다."
사용자: "it.com 가격"
봇: "it.com 도메인 등록 가격은 55,000원입니다."
```
지원 TLD: com, net, org, io, me, info, biz, it.com, uk.com 등
### WHOIS 조회
자체 WHOIS API 서버(Vercel)를 통해 TCP 43 포트로 직접 쿼리
```
사용자: "google.com whois" 또는 "google.com 정보"
봇: 등록일, 만료일, 네임서버, 등록기관 정보 표시
```
- **WHOIS API**: `https://whois-api-eight.vercel.app`
- **지원 TLD**: com, net, org, io, co, me, kr, jp, cn, uk, de, fr 등 40+ TLD
- **ccSLD 미지원**: it.com, uk.com, us.com 등 사설 레지스트리는 WHOIS 비공개
### 도메인 등록
예치금에서 자동 차감되는 도메인 등록 기능입니다.
```
[잔액 충분한 경우]
사용자: "example123.com 등록해줘"
봇: 📋 도메인 등록 확인
• 도메인: example123.com
• 가격: 15,000원 (예치금에서 차감)
• 현재 잔액: 50,000원 ✓
• 등록 기간: 1년
📌 등록자 정보
서비스 기본 정보로 등록됩니다.
(WHOIS Guard가 적용되어 개인정보는 비공개)
⚠️ 주의사항
도메인 등록 후에는 취소 및 환불이 불가능합니다.
등록을 진행하시려면 '확인'이라고 입력해주세요.
사용자: "확인"
봇: ✅ example123.com 등록이 완료되었습니다!
예치금 15,000원 차감, 현재 잔액: 35,000원
```
```
[잔액 부족한 경우]
사용자: "premium-domain.io 등록해줘"
봇: 📋 도메인 등록 확인
• 도메인: premium-domain.io
• 가격: 45,000원
• 현재 잔액: 10,000원 ⚠️ 부족
• 부족 금액: 35,000원
💳 입금 계좌
하나은행 427-910018-27104 (주식회사 아이언클래드)
입금 후 '홍길동 35000원 입금' 형식으로 알려주세요.
```
**특징:**
- 🔍 가용성 자동 확인 후 가격 안내
- 💰 **현재 잔액 실시간 표시**
- ⚠️ 등록 전 취소/환불 불가 안내
- 💳 **잔액 부족 시 입금 계좌 자동 안내**
- 📝 등록 즉시 소유 도메인으로 자동 등록
- 🔒 WHOIS Guard 자동 적용 (개인정보 보호)
**등록자 정보:**
- 현재: 서비스 기본 정보로 등록 (WHOIS Guard 적용)
- 추후: 사용자 본인 정보로 등록 옵션 추가 예정
### 도메인 추천
AI가 키워드를 기반으로 창의적인 도메인 이름을 생성하고, 가용성을 자동 확인하여 등록 가능한 도메인만 제안합니다.
```
사용자: "커피숍 도메인 추천해줘"
봇: 🎯 커피숍 관련 도메인:
✅ 등록 가능:
1. coffeenest.com - 15,000원/년
2. brewlab.io - 45,000원/년
3. beanspot.co - 32,000원/년
4. roasthub.net - 18,000원/년
❌ 이미 등록됨:
- coffee.com
- brew.io
- bean.com
💎 프리미엄 도메인:
- coffeehouse.com (별도 문의)
등록하시려면 번호나 도메인명을 말씀해주세요.
```
**특징:**
- 🎨 **창의적 이름**: 트렌디한 접미사 (hub, lab, spot, nest, base, cloud, stack, flow)
- 🔍 **자동 가용성 확인**: 15개 아이디어 생성 후 일괄 확인
- 💰 **가격 표시**: 등록 가능한 도메인만 원화 가격 안내
- 💎 **프리미엄 분류**: 일반/프리미엄 도메인 구분 표시
---
## 프로젝트 구조
```
telegram-bot-workers/
├── src/
│ ├── index.ts # 메인 Worker
│ ├── types.ts # 타입 정의
│ ├── security.ts # Webhook 보안 검증
│ ├── telegram.ts # Telegram API 유틸
│ ├── summary-service.ts # 프로필 분석 서비스
│ ├── openai-service.ts # OpenAI + Function Calling
│ ├── deposit-agent.ts # 예치금 에이전트 (Assistants API)
│ ├── n8n-service.ts # n8n 연동 (선택)
│ └── commands.ts # 봇 명령어 핸들러
├── src/services/
│ ├── bank-sms-parser.ts # SMS 파싱 로직 (Regex + AI)
│ ├── user-service.ts # 사용자 관리
│ └── conversation-service.ts # 대화 로직
├── schema.sql # D1 스키마
├── wrangler.toml # Wrangler 설정
├── n8n-workflow-example.json # n8n 워크플로우 예시
├── package.json
├── tsconfig.json
└── README.md
```
---
## 배포 가이드
### 1. 프로젝트 설정
## 🚀 빠른 시작 (배포 가이드)
### 1. 환경 설정
```bash
cd telegram-bot-workers
# 의존성 설치
npm install
# Wrangler 로그인
npx wrangler login
```
### 2. D1 데이터베이스
현재 설정:
```toml
[[d1_databases]]
binding = "DB"
database_name = "telegram-conversations"
database_id = "c285bb5b-888b-405d-b36f-475ae5aed20e"
```
스키마:
- `users` - 사용자 정보
- `message_buffer` - 메시지 임시 저장
- `summaries` - 프로필 저장
- `user_deposits` - 예치금 계정
- `deposit_transactions` - 예치금 거래 내역
- `bank_notifications` - 은행 입금 알림 (SMS 파싱)
### 3. Secrets 설정
### 2. 데이터베이스 생성
```bash
# Bot Token (BotFather에서 발급)
wrangler secret put BOT_TOKEN
# Webhook Secret
wrangler secret put WEBHOOK_SECRET
# OpenAI API Key (필수)
wrangler secret put OPENAI_API_KEY
# Brave Search API Key
wrangler secret put BRAVE_API_KEY
# Deposit API Secret (namecheap-api 연동용)
wrangler secret put DEPOSIT_API_SECRET
# namecheap-api 래퍼 인증 키 (도메인 추천용)
wrangler secret put NAMECHEAP_API_KEY
npx wrangler d1 create telegram-conversations
npx wrangler d1 execute telegram-conversations --file=schema.sql
```
*생성된 `database_id`를 `wrangler.toml`에 반영해야 합니다.*
### Vault 연동 (선택)
API 키는 HashiCorp Vault에서 중앙 관리됩니다.
### 3. 비밀키 설정 (Secrets)
```bash
# Vault에서 OpenAI API 키 조회
vault kv get secret/openai
# 저장된 정보
# - api_key: OpenAI API 키
# - email: kappa.inouter@gmail.com (계정 관리용)
# Vault에서 키 가져와서 Worker에 설정
OPENAI_KEY=$(vault kv get -field=api_key secret/openai)
echo $OPENAI_KEY | wrangler secret put OPENAI_API_KEY
npx wrangler secret put BOT_TOKEN # Telegram Bot Token
npx wrangler secret put OPENAI_API_KEY # OpenAI API Key
npx wrangler secret put WEBHOOK_SECRET # Webhook 검증용 Secret
```
> **참고**: Vault 서버: `https://vault.anvil.it.com`
### 4. 배포
### 4. 배포 및 웹훅 연결
```bash
wrangler deploy
```
# 배포
npx wrangler deploy
### 5. Webhook 설정
```bash
curl https://telegram-summary-bot.kappa-d8e.workers.dev/setup-webhook
curl https://telegram-summary-bot.kappa-d8e.workers.dev/webhook-info
```
### 6. CLI 테스트 (선택)
```bash
# .env 파일 생성 (최초 1회)
echo 'WEBHOOK_SECRET=...' > .env # Vault: secret/telegram-bot
# 대화형 모드
npm run chat
# 단일 메시지 모드
npm run chat "안녕"
# 웹훅 설정 (배포된 URL 사용)
curl https://<YOUR_WORKER_URL>/setup-webhook
```
---
## 보안 설정
## 🛠 기술 스택
### Webhook 보안 검증
| 검증 항목 | 설명 |
|-----------|------|
| **Secret Token** | `X-Telegram-Bot-Api-Secret-Token` 헤더 검증 |
| **Timing-safe 비교** | 타이밍 공격 방지 |
| **Timestamp** | 60초 이내 메시지만 처리 |
| **Rate Limiting** | 30req/분/사용자 |
### API 키 관리
| 키 | 저장 위치 | 비고 |
|----|-----------|------|
| `BOT_TOKEN` | Wrangler Secret | BotFather 발급 |
| `WEBHOOK_SECRET` | Wrangler Secret | 자동 생성 |
| `OPENAI_API_KEY` | Wrangler Secret + Vault | kappa.inouter@gmail.com |
**Vault 경로**: `secret/openai` @ `vault.anvil.it.com`
| 분류 | 기술 | 비고 |
|------|------|------|
| **Runtime** | Cloudflare Workers | Serverless |
| **DB** | Cloudflare D1 | SQLite |
| **Cache** | Cloudflare KV | Rate Limiting |
| **AI** | OpenAI GPT-4o-mini | Logic & Tools |
| **Fallback** | Workers AI (Llama 3) | Backup AI |
---
## 봇 명령어
## 🤝 기여 및 문의
### 사용자 명령어
| 명령어 | 설명 |
|--------|------|
| `/start` | 봇 시작, 기능 소개 |
| `/help` | 도움말 |
| `/profile` | 내 프로필 보기 |
| `/reset` | 대화 초기화 (확인 필요) |
| `/reset-confirm` | 초기화 확인 (실제 삭제) |
### 개발자 명령어 (숨김)
| 명령어 | 설명 |
|--------|------|
| `/context` | 현재 컨텍스트 상태 (버퍼 수, 프로필 버전) |
| `/stats` | 대화 통계 |
| `/debug` | 디버그 정보 |
---
## 설정값
`wrangler.toml`:
```toml
name = "telegram-summary-bot"
main = "src/index.ts"
compatibility_date = "2024-01-01"
[ai]
binding = "AI"
[vars]
SUMMARY_THRESHOLD = "20"
MAX_SUMMARIES_PER_USER = "3"
N8N_WEBHOOK_URL = "https://n8n.anvil.it.com"
DOMAIN_OWNER_ID = "821596605"
DEPOSIT_AGENT_ID = "asst_XMoVGU7ZwRpUPI6PHGvRNm8E"
DEPOSIT_ADMIN_ID = "821596605"
[[d1_databases]]
binding = "DB"
database_name = "telegram-conversations"
database_id = "c285bb5b-888b-405d-b36f-475ae5aed20e"
```
---
## 비용 예측
### 월간 예상 비용
| 사용량 | D1 | OpenAI | Workers | 총 |
|--------|-----|--------|---------|-----|
| 1만 메시지 | $0 | ~$0.20 | $0 | **~$0.20** |
| 10만 메시지 | $0 | ~$2.00 | $0 | **~$2.00** |
| 100만 메시지 | $0 | ~$20.00 | ~$0.30 | **~$20.30** |
> GPT-4o-mini: 입력 $0.15/1M, 출력 $0.60/1M 토큰
---
## API 엔드포인트
| 경로 | 메서드 | 설명 |
|------|--------|------|
| `/` | GET | 서비스 정보 |
| `/health` | GET | 헬스 체크 |
| `/webhook-info` | GET | Webhook 상태 |
| `/setup-webhook` | GET | Webhook 설정 |
| `/webhook` | POST | Telegram Webhook |
| `/api/bank-notification` | POST | 입금 알림 API (레거시, Email Routing으로 대체) |
| `/api/deposit/balance` | GET | 예치금 잔액 조회 (namecheap-api용) |
| `/api/deposit/deduct` | POST | 예치금 차감 (namecheap-api용) |
---
## 참고
- [OpenAI API](https://platform.openai.com/docs)
- [Cloudflare D1](https://developers.cloudflare.com/d1/)
- [Cloudflare Workers](https://developers.cloudflare.com/workers/)
- [Telegram Bot API](https://core.telegram.org/bots/api)
- [Context7 API](https://context7.com/docs/api-guide)
---
## 소스 코드
**Gitea**: https://gitea.anvil.it.com/kaffa/telegram-bot-workers
```
버그 신고나 기능 제안은 Issue를 등록해주세요.
소스 코드는 **[Gitea](https://gitea.anvil.it.com/kaffa/telegram-bot-workers)**에서 관리됩니다.