# 🤖 Cloudflare Workers 텔레그램 AI 봇

> **Cloudflare Workers + D1 + OpenAI**를 활용한 서버리스 아키텍처 기반의 지능형 텔레그램 봇입니다.
> 사용자별 프로필을 자동으로 생성하고 기억하며, 예치금 관리 및 도메인 등록 등의 복잡한 작업을 수행할 수 있습니다.

![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)

## 📚 문서 안내

- **[사용자 가이드 (User Guide)](./docs/USER_GUIDE.md)**: 봇 사용법, 명령어, 예치금/도메인 기능 설명
- **[시스템 아키텍처 (Architecture)](./docs/ARCHITECTURE.md)**: 기술 구조, 데이터 흐름, 프로필 시스템 상세
- **[개발자 가이드 (Dev Guide)](./CLAUDE.md)**: 개발 환경 설정, 컨벤션, 트러블슈팅

---

## ✨ 주요 기능

*   🧠 **AI 기반 개인화**: 대화 내용을 분석하여 사용자의 관심사와 맥락을 기억하는 **동적 프로필 시스템**
*   🛠 **Function Calling**: 날씨, 검색, 계산, 시간 등 다양한 도구를 자연어로 호출
*   💰 **예치금 시스템**: 은행 SMS 자동 파싱(AI 폴백 지원) 및 양방향 매칭을 통한 자동 충전
*   🌐 **도메인 관리**: 도메인 검색, 추천(AI), 가격 조회, 등록, DNS 관리 통합
*   ⚡ **서버리스**: Cloudflare Workers 위에서 동작하여 별도의 서버 관리 불필요

### 🚀 성능 최적화

*   **N+1 쿼리 제거**: Cron 작업 99% 쿼리 감소 (100건: 101 → 1 쿼리)
*   **병렬 API 호출**: 도메인 추천 80% 속도 향상
*   **KV 캐싱**: TLD 가격 1시간 캐싱으로 중복 조회 방지
*   **Circuit Breaker**: OpenAI API 장애 시 자동 차단 및 복구
*   **Retry 로직**: 15개 외부 API에 지수 백오프 + 지터 적용

---

## 🚀 빠른 시작 (배포 가이드)

### 1. 환경 설정
```bash
# 의존성 설치
npm install

# Wrangler 로그인
npx wrangler login
```

### 2. 데이터베이스 생성
```bash
npx wrangler d1 create telegram-conversations
npx wrangler d1 execute telegram-conversations --file=schema.sql
```
*생성된 `database_id`를 `wrangler.toml`에 반영해야 합니다.*

### 3. KV Namespace 생성
```bash
# Rate Limiting용 KV Namespace 생성 (필수)
npx wrangler kv:namespace create RATE_LIMIT_KV
# 출력된 id를 wrangler.toml의 [[kv_namespaces]] 섹션에 입력
```

### 4. 환경변수 설정

#### 필수 Secrets

```bash
# Telegram Bot 설정
npx wrangler secret put BOT_TOKEN        # @BotFather에서 발급
npx wrangler secret put WEBHOOK_SECRET   # 임의의 강력한 문자열 (필수!)

# OpenAI API
npx wrangler secret put OPENAI_API_KEY   # OpenAI API 키
```

#### 선택적 Secrets (기능별)

```bash
# 도메인 관련 (도메인 기능 사용 시)
npx wrangler secret put NAMECHEAP_API_KEY          # namecheap-api 래퍼 인증
npx wrangler secret put NAMECHEAP_API_KEY_INTERNAL # Namecheap 실제 API 키

# 검색 (웹 검색 기능 사용 시)
npx wrangler secret put BRAVE_API_KEY    # Brave Search API 키

# 예치금 API (namecheap-api 연동 시)
npx wrangler secret put DEPOSIT_API_SECRET # 외부 서비스 연동용
```

#### 환경별 설정 (선택)

`wrangler.toml`의 환경변수는 기본값이 설정되어 있어 생략 가능합니다.
환경별로 다른 엔드포인트를 사용하려면 override하세요:

```toml
[vars]
OPENAI_API_BASE = "https://your-custom-gateway.com/openai"
NAMECHEAP_API_URL = "https://your-api.example.com"
```

**사용 가능한 환경변수:**
- `OPENAI_API_BASE` - OpenAI API Gateway
- `NAMECHEAP_API_URL` - Namecheap API 래퍼
- `WHOIS_API_URL` - WHOIS 조회 서비스
- `CONTEXT7_API_BASE` - 문서 조회 API
- `BRAVE_API_BASE` - 검색 API
- `WTTR_IN_URL` - 날씨 API
- `HOSTING_SITE_URL` - 공식 웹사이트

### 5. 배포

#### 배포 전 체크리스트

```bash
# 1. 로컬 테스트
npm run dev

# 2. TypeScript 컴파일 확인
npx tsc --noEmit

# 3. 환경변수 확인
npx wrangler secret list

# 4. KV Namespace 확인
npx wrangler kv:namespace list
```

#### 배포 실행

```bash
npm run deploy
```

#### 배포 후 확인

```bash
# Health check
curl https://telegram-summary-bot.kappa-d8e.workers.dev/health

# Webhook 상태
curl https://telegram-summary-bot.kappa-d8e.workers.dev/webhook-info

# 실시간 로그
npm run tail
```

### 6. Webhook 연결

```bash
# 웹훅 설정 (배포된 URL 사용)
curl https://<YOUR_WORKER_URL>/setup-webhook
```

#### ⚠️ 주의사항

- **WEBHOOK_SECRET 필수**: 미설정 시 모든 webhook 요청이 거부됩니다.
- **KV Namespace 필수**: 미생성 시 Rate Limiting이 비활성화되어 DoS 공격에 취약합니다.
- **환경변수 기본값**: 대부분의 외부 API URL은 기본값이 설정되어 있습니다. 프로덕션 환경에서는 기본값을 그대로 사용하거나, 필요시에만 override하세요.

---

## 📡 API Documentation

본 프로젝트는 외부 서비스 연동을 위한 REST API를 제공합니다.

**완전한 OpenAPI 문서**: [`openapi.yaml`](./openapi.yaml)

### 주요 엔드포인트

| 엔드포인트 | 메서드 | 인증 | 용도 |
|-----------|--------|------|------|
| `/health` | GET | None | Health check |
| `/api/contact` | POST | CORS | 웹사이트 문의 폼 |
| `/api/deposit/balance` | GET | API Key | 잔액 조회 (Internal) |
| `/api/deposit/deduct` | POST | API Key | 잔액 차감 (Internal) |
| `/api/metrics` | GET | Bearer | 시스템 모니터링 |

### 인증 방식

- **API Key**: `X-API-Key` 헤더 (Deposit API)
- **Bearer Token**: `Authorization: Bearer {token}` (Metrics API)
- **CORS**: `hosting.anvil.it.com`만 허용 (Contact Form)

### 문서 보기

```bash
# Swagger UI (로컬)
npx swagger-ui-watcher openapi.yaml

# HTML 문서 생성
npx redoc-cli bundle openapi.yaml -o docs/api.html

# 스펙 검증
npx @apidevtools/swagger-cli validate openapi.yaml
```

### External Consumers

- **namecheap-api**: 도메인 등록 시 예치금 조회/차감
- **hosting.anvil.it.com**: 웹사이트 문의 폼 제출
- **Monitoring Tools**: Circuit Breaker 상태 조회

자세한 내용은 [OpenAPI Specification](./openapi.yaml)을 참조하세요.

---

## 🧪 테스트

### 자동화된 단위 테스트

프로젝트는 **Vitest**와 **Miniflare**를 사용하여 Cloudflare Workers 환경에서 단위 테스트를 실행합니다.

#### 테스트 실행

```bash
# 의존성 설치
npm install

# 모든 테스트 실행
npm test

# Watch 모드 (개발 중)
npm run test:watch

# 커버리지 리포트
npm run test:coverage
```

#### 테스트 범위

**deposit-agent.ts** (예치금 시스템):
- ✅ 음수/0원 금액 거부
- ✅ 동시성 처리 안전성
- ✅ Batch 부분 실패 처리
- ✅ 입금자명 7글자 매칭 로직
- ✅ 관리자 권한 검증
- ✅ 거래 상태 검증

**테스트 파일 위치**:
- `tests/deposit-agent.test.ts` - 예치금 시스템 테스트 (50+ test cases)
- `vitest.config.ts` - Vitest 설정 (Miniflare 환경)
- `tests/setup.ts` - D1 Database 초기화 및 헬퍼 함수

#### 테스트 아키텍처

- **환경**: Miniflare (in-memory SQLite)
- **모킹**: D1 Database, KV Namespace, 환경 변수
- **커버리지**: V8 Coverage Provider
- **실행 시간**: <10초 (전체 테스트 스위트)

#### 수동 테스트

자동화되지 않은 기능의 수동 테스트 예제:
- `src/services/__test__/notification.test.ts` - 관리자 알림 시스템
- `src/utils/__test__/logger.test.ts` - 구조화된 로깅

---

## 🛠 기술 스택

| 분류 | 기술 | 비고 |
|------|------|------|
| **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 |
| **Testing** | Vitest + Miniflare | Unit Tests |

---

## 🤝 기여 및 문의

버그 신고나 기능 제안은 Issue를 등록해주세요.
소스 코드는 **[Gitea](https://gitea.anvil.it.com/kaffa/telegram-bot-workers)**에서 관리됩니다.