7d7df59b43
- Namecheap API가 미국 형식(08/01/2026)을 반환하여 AI가 1월 8일로 오해석 - ISO 형식(2026-08-01)으로 변환하여 명확한 날짜 표시 - list_domains, get_domain_info에 날짜 변환 적용 - 문서에 WHOIS API 서버 정보 및 ccSLD 미지원 안내 추가 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
124 lines
5.6 KiB
Markdown
124 lines
5.6 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
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 설정**:
|
|
```bash
|
|
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` (도메인 목록, 가격, 네임서버)
|
|
- 날짜 형식: MM/DD/YYYY (미국 형식) → ISO (YYYY-MM-DD) 변환 필요
|
|
- **WHOIS API**: `https://whois-api-eight.vercel.app` (공개 WHOIS 조회, TCP 43 직접 쿼리)
|
|
- 지원 TLD: com, net, org, io, co, me, kr, jp 등 40+ TLD
|
|
- ccSLD 미지원: it.com, uk.com, us.com 등 (사설 레지스트리)
|
|
- **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`인 도메인만 관리 가능
|