telegram-bot-workers/telegram-cli/README.md

# Telegram Bot Web Chat UI

Cloudflare Worker로 변환된 웹 채팅 인터페이스 및 API 엔드포인트

## 기능

- **웹 채팅 UI** (GET /): 브라우저에서 봇과 대화
- **JSON API** (POST /api/chat): Claude나 curl로 사용 가능
- **Health Check** (GET /health): 상태 확인

## 배포 방법

### 1. 의존성 설치

```bash
cd telegram-cli
npm install
```

### 2. Secrets 설정

```bash
# BOT_TOKEN 설정 (실제로는 사용하지 않지만 필수 변수)
wrangler secret put BOT_TOKEN

# WEBHOOK_SECRET 설정 (Bot Worker /api/test 인증용)
wrangler secret put WEBHOOK_SECRET
```

**Vault에서 가져오기:**
```bash
vault kv get secret/telegram-bot
```

### 3. 로컬 테스트

```bash
npm run dev
```

브라우저에서 http://localhost:8787 접속

### 4. 배포

```bash
npm run deploy
```

배포 후 URL: https://telegram-cli-web.your-subdomain.workers.dev

## 엔드포인트

### GET /

웹 채팅 UI (HTML/CSS/JS 인라인)

**특징:**
- 다크 테마
- 실시간 응답 시간 표시
- 로딩 상태 표시
- Enter로 메시지 전송
- 자동 스크롤

**사용법:**
1. 브라우저에서 Worker URL 접속
2. 메시지 입력창에 텍스트 입력
3. Enter 키 또는 "전송" 버튼 클릭
4. 봇 응답 대기 (응답 시간 표시됨)

### POST /api/chat

JSON API 엔드포인트

**Request:**
```json
{
  "message": "서버 추천해줘"
}
```

**Response:**
```json
{
  "response": "봇 응답 내용...",
  "time_ms": 1234
}
```

**curl 예시:**
```bash
curl -X POST https://telegram-cli-web.your-subdomain.workers.dev/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "서버 추천해줘"}'
```

**Claude가 사용하는 경우:**
```bash
# Claude는 이 API를 호출하여 봇과 대화할 수 있습니다
curl -X POST https://telegram-cli-web.your-subdomain.workers.dev/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "날씨 알려줘"}'
```

### GET /health

Health check 엔드포인트

**Response:**
```json
{
  "status": "ok",
  "timestamp": "2026-01-26T00:00:00.000Z"
}
```

## 환경변수

### Secrets (wrangler secret put)

| 변수 | 설명 | 필수 |
|------|------|------|
| `BOT_TOKEN` | Telegram Bot Token (실제로는 미사용) | ✅ |
| `WEBHOOK_SECRET` | Bot Worker /api/test 인증용 | ✅ |

### Variables (wrangler.toml)

| 변수 | 기본값 | 설명 |
|------|--------|------|
| `CHAT_ID` | `821596605` | Telegram Chat ID |
| `BOT_WORKER_URL` | `https://telegram-summary-bot...` | Bot Worker URL |

**변경 방법:**
```toml
# wrangler.toml
[vars]
CHAT_ID = "YOUR_TELEGRAM_ID"
BOT_WORKER_URL = "https://your-bot-worker.workers.dev"
```

## 아키텍처

```
브라우저 (Web UI)
      ↓
GET / → HTML/CSS/JS 반환
      ↓
POST /api/chat → telegram-cli-web Worker
                        ↓
                 Bot Worker (/api/test)
                   - message
                   - chat_id
                   - user_id
                   - username: 'web-tester'
                        ↓
                   Bot 응답 처리
                   - DB 작업
                   - AI 응답 생성
                   - Function Calling
                        ↓
                 Web UI로 응답 반환
                   { response, time_ms }
```

## 테스트 시나리오

### 1. 웹 UI 테스트

브라우저에서 접속 후:

```
# 기본 대화
"안녕하세요"
"날씨 알려줘"

# Function Calling 도구
"서울 날씨"
"ChatGPT 가격 검색"
"123 * 456"
"현재 시간"

# 도메인
"example.com 조회"
"도메인 추천해줘: 커피숍"

# 예치금
"잔액 조회"
"홍길동 5000원 입금"
```

### 2. API 테스트 (curl)

```bash
# 기본 대화
curl -X POST https://your-worker.workers.dev/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "안녕하세요"}'

# 잔액 조회
curl -X POST https://your-worker.workers.dev/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "/deposit"}'

# 도메인 조회
curl -X POST https://your-worker.workers.dev/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "example.com 조회"}'
```

### 3. Claude 사용 예시

Claude가 이 API를 사용하여 봇과 대화:

```bash
# Claude는 이 엔드포인트를 호출하여 봇의 기능을 테스트할 수 있습니다
curl -X POST https://telegram-cli-web.workers.dev/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "날씨 알려줘"}'
```

## 로그 확인

```bash
npm run tail
```

실시간 로그 스트리밍으로 요청/응답 확인 가능

## 개발 모드

```bash
npm run dev
```

로컬에서 http://localhost:8787 접속하여 테스트

**로컬 개발 시 주의사항:**
- Secrets는 `.dev.vars` 파일에 설정
- 또는 `wrangler dev --remote`로 프로덕션 Secrets 사용

## 기술 스택

- **Runtime**: Cloudflare Workers (V8 Isolate)
- **Language**: TypeScript
- **Frontend**: Vanilla JavaScript (인라인 HTML)
- **CSS**: 다크 테마, 애니메이션, 반응형

## 보안

- ✅ CORS 설정 완료 (모든 Origin 허용)
- ✅ Bot Worker의 /api/test 엔드포인트는 Bearer 토큰으로 인증
- ✅ Secrets는 Workers 환경변수로 안전하게 관리
- ⚠️ 웹 UI는 공개 접근 가능 (인증 없음)

## 문제 해결

### Secrets 미설정 오류

**증상:**
```
Bot Worker error: 401 - Unauthorized
```

**해결:**
```bash
wrangler secret put WEBHOOK_SECRET
# Vault에서 가져온 값 입력
```

### Bot Worker URL 변경

`wrangler.toml` 수정:

```toml
[vars]
BOT_WORKER_URL = "https://new-worker.workers.dev"
```

### CHAT_ID 변경

`wrangler.toml` 수정:

```toml
[vars]
CHAT_ID = "123456789"
```

### 로컬 테스트 시 Secrets 설정

`.dev.vars` 파일 생성:

```env
BOT_TOKEN=1234567890:ABC...
WEBHOOK_SECRET=your-webhook-secret
```

## 성능

- **응답 시간**: 평균 200-500ms (Bot Worker 처리 시간 포함)
- **Cold Start**: ~100ms (Workers 특성상 매우 빠름)
- **동시 요청**: 무제한 (Workers 스케일링)

## 라이센스

MIT

## 관련 파일

| 파일 | 역할 |
|------|------|
| `src/index.ts` | Worker 메인 로직 |
| `wrangler.toml` | Workers 설정 |
| `package.json` | 의존성 및 스크립트 |
| `../src/routes/api.ts` | Bot Worker /api/test 엔드포인트 |
| `../openapi.yaml` | API 문서 |

## 참고 자료

- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)
- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)
- [Telegram Bot API](https://core.telegram.org/bots/api)