feat: 도메인 시스템 개선 + 검색 한글→영문 번역

주요 변경: - Domain Agent 제거, 코드 직접 처리로 전환 - suggest_domains: 등록 가능 도메인만 표시, 10개 미만 시 재시도 - search_web: 한글 검색어 자동 영문 번역 (GPT-4o-mini) - WHOIS: raw 데이터 파싱으로 상세 정보 추출 - 가격 조회: API 필드명 수정 (register_krw → krw) - 동적 도구 로딩 시스템 추가 - 문서 정리 및 업데이트 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-18 11:15:49 +09:00
parent 28ac6737ad
commit 42ab702d1c
7 changed files with 1056 additions and 231 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -181,8 +181,9 @@ Telegram Webhook → Security Validation → Command/Message Router
            Command Handler                                    AI Response Generator
            (commands.ts)                                      (openai-service.ts)
                                                                      ↓
-                                                              Function Calling
-                                                    (weather, search, time, calc, docs)
+                                                              Function Calling (8개)
+                                              (weather, search, time, calc, docs,
+                                               domain, suggest_domains, deposit)
                                                                      ↓
                                                              Profile System
                                                            (summary-service.ts)
@@ -199,15 +200,16 @@ Telegram Webhook → Security Validation → Command/Message Router
 | `commands.ts` | 봇 명령어 | `handleCommand()` |
 | `telegram.ts` | Telegram API | `sendMessage()`, `sendTypingAction()` |

-**Function Calling Tools (7개):**
+**Function Calling Tools (8개):**
 | 도구 | 함수명 | 외부 API | 트리거 키워드 |
 |------|--------|----------|---------------|
 | 날씨 | `get_weather` | wttr.in | 날씨 |
-| 검색 | `web_search` | Brave Search | ~란, ~뭐야 |
+| 검색 | `search_web` | Brave Search | ~란, ~뭐야 (한글→영문 자동 번역) |
 | 시간 | `get_current_time` | 내장 | 몇 시, 시간 |
 | 계산 | `calculate` | 내장 | 계산, +, -, *, / |
 | 문서 | `lookup_docs` | Context7 | 문서, 사용법, API |
-| 도메인 | `manage_domain` | Domain Agent → Namecheap | 도메인, 네임서버, WHOIS |
+| 도메인 | `manage_domain` | 코드 직접 처리 → Namecheap | 도메인, 네임서버, WHOIS |
+| 도메인 추천 | `suggest_domains` | GPT + Namecheap | **도메인 추천, 도메인 제안, 도메인 아이디어** |
 | 예치금 | `manage_deposit` | Deposit Agent → D1 | **입금, 충전, 잔액, 계좌, 송금** |

 **Data Layer (D1 SQLite):**
@@ -219,9 +221,31 @@ Telegram Webhook → Security Validation → Command/Message Router
 | `user_deposits` | 예치금 계정 | user_id, balance |
 | `deposit_transactions` | 거래 내역 | user_id, amount, status |
 | `bank_notifications` | SMS 파싱 | depositor_name, amount, bank |
+| `user_domains` | 도메인 소유권 | user_id, domain, verified (등록 시 자동 추가) |

 **AI Fallback:** OpenAI 미설정 시 Workers AI (Llama 3.1 8B) 자동 전환

+### 동적 도구 로딩
+
+**목적:** 토큰 절약 + AI 선택 정확도 향상
+
+```
+사용자 메시지 → 키워드 패턴 매칭 → 관련 도구만 선택 → AI 호출
+```
+
+**카테고리 분류:**
+| 카테고리 | 도구 | 감지 패턴 |
+|----------|------|-----------|
+| domain | manage_domain, suggest_domains | 도메인, 네임서버, whois, .com |
+| deposit | manage_deposit | 입금, 충전, 잔액, 계좌 |
+| weather | get_weather | 날씨, 기온, 비, 눈 |
+| search | search_web, lookup_docs | 검색, 찾아, 뭐야, 가격 |
+| utility | get_current_time, calculate | (항상 포함) |
+
+**폴백:** 패턴 매칭 없으면 전체 도구 사용
+
+**로그:** `[ToolSelector] 카테고리: domain, utility / 선택된 도구: manage_domain, ...`
+
 ---

 ## Key Patterns
@@ -246,41 +270,74 @@ case 'new_tool':
  return await executeNewTool(args);
 ```

-### 프로필 시스템 흐름
+### 프로필 시스템 흐름 (3개 요약 통합 방식)
 ```
 메시지 수신 → message_buffer 저장 (최대 19개)
                    ↓ 20개 도달
-            사용자 발언만 추출 → OpenAI 분석
-                    ↓
-            summaries 테이블 저장 (generation++)
-                    ↓
-            구버전 삭제 (최근 3개만 유지)
+     ┌──────────────┴──────────────┐
+     ↓                              ↓
+기존 요약 3개 조회            사용자 발언만 추출
+     ↓                              ↓
+     └──────────→ OpenAI 통합 분석 ←┘
+                        ↓
+              summaries 테이블 저장 (generation++)
+                        ↓
+              구버전 삭제 (최근 3개만 유지)
 ```

+**통합 분석 방식:**
+- 기존: 최신 요약 1개만 참조하여 업데이트
+- 변경: **모든 요약 (최대 3개) + 새 메시지 → AI가 통합 분석**
+
 ### Context Enrichment
 ```typescript
 // getConversationContext() 반환값 구조
 {
-  profile: "이전 프로필 요약",
-  recentMessages: [ /* 최근 10개 */ ]
+  previousSummary: Summary | null,  // 최신 요약 (호환성)
+  summaries: Summary[],             // 전체 요약 (최대 3개, 최신순)
+  recentMessages: BufferedMessage[],
+  totalMessages: number,
 }
-// → AI 프롬프트의 system 메시지에 포함
+```
+
+**시스템 프롬프트에 통합:**
+```
+## 사용자 프로필 (3개 버전 통합)
+[v1] 초기 프로필 내용...
+[v2] 업데이트된 프로필...
+[v3] 최신 프로필...
+
+최신 버전을 우선시하되, 이전 버전 맥락도 고려
 ```

 ### AI 시스템 프롬프트 (`summary-service.ts`)
 ```
- 날씨, 시간, 계산, 검색 등의 요청은 제공된 도구를 사용하세요.
+- 날씨, 시간, 계산 요청은 제공된 도구를 사용하세요.
+- 최신 정보, 실시간 데이터, 현재 가격, 뉴스 등은 search_web 도구로 검색하세요.
 - 예치금, 입금, 충전, 잔액, 계좌 관련 요청은 반드시 manage_deposit 도구를 사용하세요.
-  금액 제한이나 규칙을 직접 판단하지 마세요.
- 도메인 관련 요청은 반드시 manage_domain 도구를 사용하세요.
- manage_deposit, manage_domain 도구 결과는 그대로 전달하세요.
-  추가 질문이나 "도움이 필요하시면~" 같은 멘트를 붙이지 마세요.
+- 도메인 추천, 도메인 제안, 도메인 아이디어 요청은 반드시 suggest_domains 도구를 사용하세요.
+- 기타 도메인 관련 요청(조회, 등록, 네임서버 등)은 manage_domain 도구를 사용하세요.
+- manage_deposit, manage_domain, suggest_domains 도구 결과는 그대로 전달하세요.
 ```

 **중요:** 메인 AI가 도구를 호출하지 않고 직접 답변하는 경우:
 1. 시스템 프롬프트에 해당 키워드 추가 (`summary-service.ts:252-254`)
 2. 도구 description에 키워드 명시 (`openai-service.ts` tools 배열)

+### 검색 한글→영문 자동 번역
+
+```
+"판골린 VPN" → GPT-4o-mini 번역 → "Pangolin VPN" → Brave Search
+```
+
+**동작:**
+- 한글 포함 검색어 감지 (`/[가-힣]/`)
+- GPT-4o-mini로 영문 번역 (외래어/기술용어 원어 복원)
+- 번역된 쿼리로 검색
+- 결과에 원본+번역 표시: `검색 결과: 판골린 VPN (→ Pangolin VPN)`
+
+**로그:** `[search_web] 번역: "판골린 VPN" → "Pangolin VPN"`
+
 ### Deposit Agent 프롬프트 수정 방법
 ```bash
 # Vault에서 API 키 조회
@@ -302,12 +359,12 @@ curl -X POST 'https://api.openai.com/v1/assistants/asst_XMoVGU7ZwRpUPI6PHGvRNm8E
 |------|--------|------|
 | `SUMMARY_THRESHOLD` | 20 | 프로필 업데이트 주기 (메시지 수) |
 | `MAX_SUMMARIES_PER_USER` | 3 | 유지할 프로필 버전 수 |
-| `DOMAIN_AGENT_ID` | - | 도메인 관리 Assistant ID |
 | `DOMAIN_OWNER_ID` | - | 도메인 관리 권한 Telegram ID |
 | `DEPOSIT_AGENT_ID` | - | 예치금 관리 Assistant ID |
 | `DEPOSIT_ADMIN_ID` | - | 예치금 관리 권한 Telegram ID |
 | `BANK_API_SECRET` | - | 입금 알림 API 인증 키 (wrangler secret) |
 | `BRAVE_API_KEY` | - | Brave Search API 키 (wrangler secret) |
+| `DEPOSIT_API_SECRET` | - | Deposit API 인증 키 (namecheap-api용, wrangler secret) |

 ---

@@ -316,7 +373,6 @@ curl -X POST 'https://api.openai.com/v1/assistants/asst_XMoVGU7ZwRpUPI6PHGvRNm8E
 | 서비스 | 용도 | 엔드포인트 | 주의사항 |
 |--------|------|-----------|----------|
 | Context7 | 문서 조회 | context7.com API | - |
-| Domain Agent | 도메인 관리 | OpenAI Assistants | `asst_MzPFKoqt7V4w6bc0UwcXU4ob` |
 | Deposit Agent | 예치금 관리 | OpenAI Assistants | `asst_XMoVGU7ZwRpUPI6PHGvRNm8E` |
 | Namecheap API | 도메인 백엔드 | namecheap-api.anvil.it.com | 날짜: MM/DD/YYYY → ISO 변환 |
 | WHOIS API | WHOIS 조회 | whois-api-eight.vercel.app | ccSLD 미지원 |
@@ -411,17 +467,102 @@ Content-Type: application/json

 ## Domain System

-**도구 목록:**
-| 도구 | 권한 | 설명 |
-|------|------|------|
-| `list_domains` | 소유자 | 도메인 목록 |
-| `get_domain_info` | 소유자 | 상세 정보 (만료일 등) |
-| `get_nameservers` | 공개 | 네임서버 조회 |
-| `set_nameservers` | 소유자 | 네임서버 변경 |
-| `get_price` | 공개 | TLD 가격 (원화) |
-| `check_domains` | 공개 | 가용성 확인 |
-| `whois_lookup` | 공개 | WHOIS 조회 |
+**아키텍처 변경 (2025-01):** Agent 기반 → 코드 직접 처리

-**가격 정책:** Namecheap 원가 + 13%, 매일 환율 업데이트
+| 구분 | 이전 (Agent) | 현재 (코드) |
+|------|-------------|-------------|
+| 의도 파악 | Domain Agent | 메인 AI (action 파라미터) |
+| API 호출 | Agent Function Calling | `executeDomainAction()` |
+| 응답 형식 | Agent 생성 (불안정) | 코드 고정 (100% 일관성) |
+| 비용 | Agent 호출당 ~$0.01 | 없음 |

-**권한 체크:** `user_domains` 테이블 `verified=1`
+**manage_domain 도구 파라미터:**
+```typescript
+{
+  action: 'register' | 'check' | 'whois' | 'list' | 'info' | 'get_ns' | 'set_ns' | 'price',
+  domain?: string,      // 대상 도메인
+  nameservers?: string[], // set_ns용
+  tld?: string           // price용
+}
+```
+
+**action별 처리:**
+| action | 설명 | 권한 |
+|--------|------|------|
+| `list` | 내 도메인 목록 | 소유자 |
+| `info` | 도메인 상세정보 | 소유자 |
+| `get_ns` | 네임서버 조회 | 공개 |
+| `set_ns` | 네임서버 변경 | 소유자 |
+| `check` | 가용성 확인 + 가격 | 공개 |
+| `whois` | WHOIS 조회 | 공개 |
+| `price` | TLD 가격 | 공개 |
+| `register` | 등록 확인 페이지 | 사용자 |
+
+### 도메인 등록 흐름
+
+```
+사용자: "example.com 등록해줘"
+       ↓
+메인 AI: manage_domain(action="register", domain="example.com")
+       ↓
+executeDomainAction():
+  1. check_domains API → 가용성 확인
+  2. get_price API → 가격 조회
+  3. DB 조회 → 현재 잔액 확인
+  4. 고정 형식 응답 생성
+       ↓
+┌─────────────────────┬─────────────────────┐
+│    잔액 충분 시      │    잔액 부족 시      │
+├─────────────────────┼─────────────────────┤
+│ 📋 도메인 등록 확인   │ 📋 도메인 등록 확인   │
+│ • 도메인: example.com│ • 도메인: example.com│
+│ • 가격: 15,000원     │ • 가격: 15,000원     │
+│ • 현재 잔액: ✓       │ • 현재 잔액: ⚠️ 부족 │
+│ • 등록 기간: 1년     │ • 부족 금액: X원     │
+│ 📌 등록자 정보       │                     │
+│ ⚠️ 취소/환불 불가    │ 💳 입금 계좌        │
+│                     │ 하나은행 427-...    │
+│ '확인' 입력 요청     │ 입금 안내           │
+└─────────────────────┴─────────────────────┘
+```
+
+### 도메인 추천 기능 (`suggest_domains`)
+
+**별도 구현된 코드 레벨 도구**
+
+```
+사용자: "커피숍 도메인 추천해줘"
+       ↓
+1. GPT-4o-mini: 키워드 기반 창의적 도메인 15개 생성
+       ↓
+2. Namecheap API: check_domains로 가용성 일괄 확인
+       ↓
+3. 등록 가능 도메인 < 10개? → 1-2 반복 (최대 3회)
+       ↓
+4. Namecheap API: TLD별 가격 조회
+       ↓
+5. 결과 포맷팅 (등록 가능한 것만 표시, 10개 목표)
+```
+
+**특징:**
+- 등록 가능 도메인만 표시 (이미 등록된 도메인 미표시)
+- 10개 미만 시 자동 재시도 (최대 3회)
+- 이전에 체크한 도메인은 제외하고 새로 생성
+
+**Namecheap API:**
+- 엔드포인트: `namecheap-api.anvil.it.com`
+- 가격 정책: Namecheap 원가 + 13%, 매일 환율 업데이트
+- 권한 체크: `user_domains` 테이블 `verified=1`
+
+**등록자 정보:**
+- 현재: 서비스 기본 정보만 지원 (일본 주소)
+- WHOIS Guard 자동 적용 (개인정보 비공개)
+- 추후: 사용자 본인 정보로 등록 옵션 추가 예정
+
+**Deposit API (namecheap-api용):**
+```
+GET  /api/deposit/balance?telegram_id=xxx    # 잔액 조회
+POST /api/deposit/deduct                      # 잔액 차감
+     { telegram_id, amount, reason }
+Header: X-API-Key: DEPOSIT_API_SECRET
+```