telegram-bot-workers/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

npm run dev           # 로컬 개발 (wrangler dev)
npm run deploy        # Cloudflare Workers 배포
npm run db:init       # D1 스키마 초기화 (production)
npm run db:init:local # D1 스키마 초기화 (local)
npm run tail          # Workers 로그 스트리밍

Secrets 설정:

wrangler secret put BOT_TOKEN        # Telegram Bot Token
wrangler secret put WEBHOOK_SECRET   # Webhook 검증용
wrangler secret put OPENAI_API_KEY   # OpenAI API 키

Architecture

Message Flow:

Telegram Webhook → Security Validation → Command/Message Router
                                              ↓
                   ┌──────────────────────────┴──────────────────────────┐
                   ↓                                                      ↓
            Command Handler                                    AI Response Generator
            (commands.ts)                                      (openai-service.ts)
                                                                      ↓
                                                              Function Calling
                                                    (weather, search, time, calc, docs)
                                                                      ↓
                                                              Profile System
                                                            (summary-service.ts)

Core Services:

• openai-service.ts - GPT-4o-mini + Function Calling (7개 도구: weather, search, time, calculate, lookup_docs, manage_domain, manage_deposit)
• summary-service.ts - 메시지 버퍼링 + 20개마다 프로필 추출 (슬라이딩 윈도우 3개)
• security.ts - Webhook 검증 (timing-safe comparison, timestamp validation, rate limiting 30req/min)
• commands.ts - 봇 명령어 핸들러 (/start, /help, /profile, /reset, /context, /stats, /debug)
• index.ts - Email Worker 핸들러 (SMS → 메일 파싱, 은행 알림 자동 매칭)

Data Layer (D1 SQLite):

• users - telegram_id 기반 사용자
• message_buffer - 롤링 대화 기록
• summaries - 프로필 버전 관리 (generation 추적)
• user_deposits - 예치금 계정 (잔액 관리)
• deposit_transactions - 예치금 거래 내역 (pending/confirmed/rejected)
• bank_notifications - 은행 SMS 파싱 결과 (자동 매칭용)

AI Fallback: OpenAI 미설정 시 Workers AI (Llama 3.1 8B) 자동 전환

Key Patterns

Function Calling: openai-service.ts의 tools 배열에 JSON Schema 정의, executeFunctionCall()에서 실행

Profile System: 매 20개 메시지마다 사용자 발언 분석 → 관심사/목표/맥락 추출 → summaries 테이블에 generation 증가하며 저장

Context Enrichment: getConversationContext()로 이전 프로필 + 최근 10개 메시지 조합하여 AI 프롬프트에 포함

Configuration

wrangler.toml 환경변수:

• SUMMARY_THRESHOLD: 프로필 업데이트 주기 (기본 20)
• MAX_SUMMARIES_PER_USER: 유지할 프로필 버전 수 (기본 3)
• DOMAIN_AGENT_ID: OpenAI Assistant ID (도메인 관리 에이전트)
• DOMAIN_OWNER_ID: 도메인 관리 권한 Telegram ID (소유권 검증용)
• DEPOSIT_ADMIN_ID: 예치금 관리 권한 Telegram ID (입금 확인/거절)

External Integrations

• Context7 API: lookup_docs 함수로 라이브러리 문서 조회
• Domain Agent: manage_domain 함수 → OpenAI Assistants API (asst_MzPFKoqt7V4w6bc0UwcXU4ob)
• Namecheap API: https://namecheap-api.anvil.it.com (도메인 목록, 가격, 네임서버)
• RDAP API: 공개 WHOIS 조회 (com/net/org/io/me/info/biz TLD 지원)
• wttr.in: 날씨 API
• DuckDuckGo: 웹 검색 API
• Vault: vault.anvil.it.com에서 API 키 중앙 관리
• Email Workers: SMS → 메일 수신 → 은행 알림 파싱 (하나/KB/신한 지원)

Deposit System

예치금 자동 매칭 흐름:

[사용자 신고] "홍길동 50000원 입금"
     ↓
bank_notifications 테이블 검색 (입금자명 + 금액 매칭)
     ↓
매칭 성공 → confirmed | 매칭 실패 → pending 대기

[은행 SMS 수신] Email Worker
     ↓
SMS 파싱 → bank_notifications 저장
     ↓
deposit_transactions 검색 (pending 상태 + 입금자명 + 금액)
     ↓
매칭 성공 → confirmed + 잔액 증가 | 매칭 실패 → 알림만 저장

입금 계좌: 하나은행 427-910018-27104 (주식회사 아이언클래드)

• Vault 경로: secret/companies/ironclad-corp

Domain System

Domain Agent 도구 (OpenAI Assistant):

• list_domains - 소유 도메인 목록 (권한 필요)
• get_domain_info - 도메인 상세 정보 (권한 필요)
• get_nameservers - 네임서버 조회 (누구나)
• set_nameservers - 네임서버 변경 (권한 필요)
• get_price - TLD/ccSLD 가격 조회 (누구나, 원화 표시)
• check_domains - 도메인 가용성 확인 (누구나)
• whois_lookup - 공개 WHOIS/RDAP 조회 (누구나)

가격 정책: Namecheap 원가 + 13%, 매일 환율 업데이트 (USD→KRW)

권한 체크: user_domains 테이블에서 verified=1인 도메인만 관리 가능