feat: implement processDomainConsultation main handler

- Add full conversation flow with session management - Handle tool call execution - Support __PASSTHROUGH__ and __SESSION_END__ markers - Add hasDomainSession helper for routing - Export executeDomainAction from domain-tool.ts Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-05 09:57:32 +09:00
parent 160569bf8c
commit f9f577f25c
4 changed files with 1417 additions and 7 deletions
--- a/docs/plans/2026-02-05-agent-refactoring-design.md
+++ b/docs/plans/2026-02-05-agent-refactoring-design.md
@@ -0,0 +1,234 @@
+# 도메인/예치금 에이전트 리팩토링 설계
+
+> 작성일: 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__` 폴백, 명확한 시스템 프롬프트 |
+| 마이그레이션 실패 | 로컬 테스트 후 프로덕션 적용 |