# CLAUDE.md - telegram-ai-support

Telegram AI 고객 지원 봇. Cloudflare Workers + Hono + D1 + KV + R2 + Workers AI.

## Commands

```bash
npm run typecheck     # TypeScript 타입 체크
npm test              # Vitest 테스트 실행
npx wrangler deploy   # Workers 배포
npx wrangler d1 execute telegram-ai-support-db --file=schema.sql  # D1 스키마 적용
```

## Architecture

```
src/
├── index.ts                    # Hono 앱 + cron scheduled handler
├── types.ts                    # 모든 타입 정의 (Env, Telegram, OpenAI, DB 모델)
├── telegram.ts                 # Telegram Bot API 래퍼
├── security.ts                 # webhook 인증, rate limit, admin 체크
├── agents/                     # AI 에이전트 시스템
│   ├── base-agent.ts           # 추상 기반 (세션, AI 호출 루프, 마커 처리)
│   ├── agent-registry.ts       # 우선순위 기반 에이전트 라우팅
│   ├── onboarding-agent.ts     # 신규 고객 안내 (multi-round)
│   ├── troubleshoot-agent.ts   # 장애/문제 해결 (multi-round, 에스컬레이션)
│   ├── asset-agent.ts          # 자산 조회 (single-shot)
│   └── billing-agent.ts        # 결제/충전 (single-shot, optimistic lock)
├── tools/                      # OpenAI Function Calling 도구
│   ├── index.ts                # Zod 검증 + 도구 레지스트리 + 동적 선택
│   ├── domain-tool.ts          # 도메인 WHOIS/등록/관리
│   ├── wallet-tool.ts          # 지갑/충전/거래내역
│   ├── server-tool.ts          # 서버 관리 (시작/중지/재부팅)
│   ├── service-tool.ts         # DDoS/VPN 서비스 상태
│   ├── d2-tool.ts              # D2 다이어그램 렌더링 (Incus jp1 + R2 캐시)
│   ├── admin-tool.ts           # 관리자 기능 (차단, 입금 확인 등)
│   └── knowledge-tool.ts       # 지식베이스 검색
├── services/                   # 비즈니스 로직 서비스
│   ├── audit.ts                # 감사 로그
│   ├── feedback.ts             # 피드백 수집/통계
│   ├── human-handoff.ts        # 관리자 에스컬레이션
│   ├── notification.ts         # 관리자 알림
│   ├── pending-actions.ts      # 인프라 변경 승인 워크플로우
│   ├── kv-cache.ts             # KV 캐시 추상화
│   └── cron-jobs.ts            # 크론 작업 (만료 알림, 아카이빙, 모니터링)
├── routes/                     # HTTP 라우팅
│   ├── webhook.ts              # Telegram webhook (인증 미들웨어)
│   ├── api.ts                  # 관리자 API
│   ├── health.ts               # 헬스 체크
│   └── handlers/
│       ├── message-handler.ts  # 메시지 처리 파이프라인
│       └── callback-handler.ts # 인라인 키보드 콜백
├── constants/agent-config.ts   # 에이전트별 설정 (TTL, 토큰, 온도)
├── i18n/                       # 다국어 (ko, en)
└── utils/                      # 유틸리티
    ├── logger.ts               # 구조화 JSON 로깅 + PII 마스킹
    ├── patterns.ts             # 의도 감지 정규식 패턴
    ├── session-manager.ts      # 제네릭 D1 세션 CRUD + TTL
    ├── circuit-breaker.ts      # 서킷 브레이커 패턴
    ├── retry.ts                # 지수 백오프 재시도
    ├── optimistic-lock.ts      # 낙관적 잠금 (금융 데이터)
    ├── metrics.ts              # 메트릭 수집기
    ├── env-validation.ts       # Zod 환경 변수 검증
    └── api-urls.ts             # OpenAI/D2 API URL 헬퍼
```

## Key Patterns

- **BaseAgent**: multi-round (도구 실행 -> AI 재호출) vs single-shot (도구 호출 반환 -> 외부 실행)
- **Agent Registry**: 우선순위 순 활성 세션 확인. `__PASSTHROUGH__` → 다음 에이전트로 이관
- **Session markers**: `__SESSION_END__`, `[세션 종료]`, `__ESCALATE__`, `__PASSTHROUGH__`
- **Tool selection**: 메시지 패턴 → 카테고리 → 필요한 도구만 OpenAI에 전달 (토큰 절약)
- **Pending actions**: 위험한 인프라 변경은 `pending_actions` 테이블에 저장 → 사용자/관리자 승인 후 실행
- **AI fallback**: OpenAI 실패 시 Workers AI (llama-3.1-8b-instruct-fp8)

## Bindings (wrangler.toml)

- `DB`: D1 데이터베이스
- `AI`: Workers AI
- `RATE_LIMIT_KV`, `SESSION_KV`, `CACHE_KV`: KV 네임스페이스
- `ASSETS_BUCKET`: R2 버킷
- `BOT_TOKEN`, `WEBHOOK_SECRET`, `OPENAI_API_KEY`: 시크릿
- `ADMIN_TELEGRAM_IDS`: 쉼표 구분 관리자 ID
- `CLOUD_ORCHESTRATOR`: 서비스 바인딩

## Testing

Vitest + Miniflare. 테스트 setup에서 D1 스키마 자동 초기화.

```bash
npm test                          # 전체 실행
npx vitest run tests/security.test.ts  # 단일 파일
```