telegram-bot-workers/docs/plans/2026-02-05-agent-refactoring-design.md

# 도메인/예치금 에이전트 리팩토링 설계

> 작성일: 2026-02-05
> 상태: 설계 완료, 구현 대기

## 개요

기존 직접 코드 처리 방식의 `domain-tool.ts`와 `deposit-agent.ts`를 `server-agent.ts` 패턴의 세션 기반 AI 에이전트로 리팩토링한다.

## 요구사항

| 항목 | 도메인 에이전트 | 예치금 에이전트 |
|------|----------------|----------------|
| **트리거** | 모든 도메인 요청 | 모든 예치금 요청 |
| **의도 파악** | AI가 판단 | AI가 판단 |
| **세션** | 작업 단위 (추천/등록/NS변경) | 입금 신고만 |
| **즉시 응답** | 가격, WHOIS, 목록 조회 | 잔액, 내역 조회 |
| **리팩토링** | domain-tool.ts 통합 | deposit-agent.ts 통합 |

## 아키텍처

```
메인 AI (openai-service.ts)
    │
    ├─ 도메인 키워드 감지 → Domain Agent (domain-agent.ts)
    │   ├─ 세션 있음? → 세션 컨텍스트로 처리
    │   ├─ 세션 필요? → 세션 생성 후 상담
    │   └─ 즉시 응답 가능? → 바로 실행
    │
    └─ 예치금 키워드 감지 → Deposit Agent (deposit-agent.ts)
        ├─ 세션 있음? → 입금 신고 흐름 계속
        ├─ 입금 신고? → 세션 생성 후 정보 수집
        └─ 조회 요청? → 바로 실행

__PASSTHROUGH__: 무관한 메시지는 메인 AI로 반환
```

## 도메인 에이전트 상세

### 세션 상태
```typescript
type DomainSessionStatus =
  | 'gathering'    // 정보 수집 중 (추천용 키워드, 용도)
  | 'suggesting'   // 추천 결과 표시 중
  | 'confirming'   // 등록 확인 대기
  | 'setting_ns'   // 네임서버 변경 확인 대기
  | 'completed';   // 완료
```

### 작업별 흐름

| 작업 | 세션 | 흐름 |
|------|------|------|
| **추천** | ✅ | gathering → suggesting → confirming → completed |
| **등록** | ✅ | confirming → completed (잔액 확인 → 결제) |
| **NS 변경** | ✅ | setting_ns → completed (위험 작업이라 확인) |
| **가격 조회** | ❌ | 즉시 응답 |
| **WHOIS** | ❌ | 즉시 응답 |
| **내 도메인 목록** | ❌ | 즉시 응답 |
| **도메인 정보** | ❌ | 즉시 응답 |

### AI 페르소나
```
"10년 경력의 도메인 컨설턴트. 브랜딩, SEO, 가격 대비 가치를 고려한 조언 제공.
불필요한 프리미엄 도메인 추천 자제, 실용적인 선택 유도."
```

### 전용 도구
- `check_domain`: 가용성 + 가격 확인
- `search_suggestions`: 키워드 기반 도메인 추천
- `get_whois`: WHOIS 조회
- `get_price`: TLD별 가격 조회
- `register_domain`: 도메인 등록 (잔액 차감)
- `set_nameservers`: 네임서버 변경

## 예치금 에이전트 상세

### 세션 상태
```typescript
type DepositSessionStatus =
  | 'collecting_amount'    // 금액 수집 중
  | 'collecting_name'      // 입금자명 수집 중
  | 'confirming'           // 입금 신고 확인 대기
  | 'completed';           // 완료
```

### 작업별 흐름

| 작업 | 세션 | 흐름 |
|------|------|------|
| **입금 신고** | ✅ | collecting_amount → collecting_name → confirming → completed |
| **잔액 조회** | ❌ | 즉시 응답 |
| **계좌 안내** | ❌ | 즉시 응답 |
| **거래 내역** | ❌ | 즉시 응답 |
| **거래 취소** | ❌ | 즉시 응답 (본인 pending만) |
| **관리자 기능** | ❌ | 즉시 응답 (pending/confirm/reject) |

### 스마트 파싱
```
"홍길동 5만원 입금" → 금액 + 입금자명 한번에 파싱 → confirming 직행
"충전할게" → "얼마를 충전하시겠어요?" → collecting_amount
"3만원" → "입금자명을 알려주세요" → collecting_name
"홍길동" → confirming → 자동매칭 시도
```

### AI 페르소나
```
"친절한 금융 상담사. 입금 절차를 명확하게 안내하고,
자동 매칭 결과를 즉시 알려줌. 오입금 방지를 위해 확인 절차 진행."
```

### 전용 도구
- `get_balance`: 잔액 조회
- `get_account_info`: 계좌 안내
- `request_deposit`: 입금 신고 및 자동 매칭
- `get_transactions`: 거래 내역
- `cancel_transaction`: 대기 중 거래 취소

## 데이터베이스 스키마

### domain_sessions
```sql
CREATE TABLE domain_sessions (
  user_id TEXT PRIMARY KEY,
  status TEXT NOT NULL,
  collected_info TEXT,
  target_domain TEXT,
  messages TEXT,
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL,
  expires_at INTEGER NOT NULL
);

CREATE INDEX idx_domain_sessions_expires ON domain_sessions(expires_at);
```

### deposit_sessions
```sql
CREATE TABLE deposit_sessions (
  user_id TEXT PRIMARY KEY,
  status TEXT NOT NULL,
  collected_info TEXT,
  messages TEXT,
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL,
  expires_at INTEGER NOT NULL
);

CREATE INDEX idx_deposit_sessions_expires ON deposit_sessions(expires_at);
```

## 파일 구조 변경

### Before
```
src/
├── openai-service.ts
├── deposit-agent.ts
├── server-agent.ts
├── tools/
│   ├── domain-tool.ts
│   ├── deposit-tool.ts
│   ├── server-tool.ts
│   └── ...
```

### After
```
src/
├── openai-service.ts
├── agents/
│   ├── domain-agent.ts
│   ├── deposit-agent.ts
│   └── server-agent.ts
├── tools/
│   ├── search-tool.ts
│   ├── weather-tool.ts
│   └── utility-tools.ts
```

## 구현 순서

### Phase 1: 기반 작업
1. `migrations/006_add_agent_sessions.sql` 작성
2. `src/agents/` 디렉토리 생성
3. `server-agent.ts` → `src/agents/`로 이동
4. 타입 정의 (`types.ts`에 세션 타입 추가)

### Phase 2: 도메인 에이전트
1. `src/agents/domain-agent.ts` 생성
2. 기존 `domain-tool.ts` 로직 통합
3. `openai-service.ts` 수정
4. `tools/domain-tool.ts` 삭제

### Phase 3: 예치금 에이전트
1. `src/agents/deposit-agent.ts` 리팩토링
2. `openai-service.ts` 수정
3. `tools/deposit-tool.ts` 삭제

### Phase 4: 정리
1. `tools/server-tool.ts` → `agents/` 통합
2. import 경로 정리
3. 테스트 및 문서 업데이트

## 테스트 계획

### 도메인 에이전트
| 시나리오 | 예상 결과 |
|----------|----------|
| "도메인 추천해줘" | 세션 시작 → 용도 질문 |
| "커피숍 도메인" | 키워드 수집 → 추천 결과 |
| "1번 등록" | 잔액 확인 → 등록 확인 |
| ".com 가격" | 즉시 응답 (세션 없음) |
| "example.com WHOIS" | 즉시 응답 (세션 없음) |
| 세션 중 "날씨 알려줘" | `__PASSTHROUGH__` → 메인 AI |

### 예치금 에이전트
| 시나리오 | 예상 결과 |
|----------|----------|
| "충전할게" | 세션 시작 → 금액 질문 |
| "5만원" | 입금자명 질문 |
| "홍길동" | 확인 → 자동매칭 시도 |
| "홍길동 5만원 입금" | 한번에 파싱 → 바로 확인 |
| "잔액" | 즉시 응답 (세션 없음) |
| "내역" | 즉시 응답 (세션 없음) |

## 위험 요소 및 대응

| 위험 | 대응 |
|------|------|
| 기존 기능 회귀 | 기존 테스트 유지 + 세션 테스트 추가 |
| 세션 충돌 | user_id 기반 단일 세션 보장 |
| AI 오판단 | `__PASSTHROUGH__` 폴백, 명확한 시스템 프롬프트 |
| 마이그레이션 실패 | 로컬 테스트 후 프로덕션 적용 |