feat(phase-5-3): Logger, Metrics, 알림 시스템 통합
Phase 5-3 모니터링 강화 작업의 통합을 완료했습니다. 변경사항: - Logger 통합: console.log를 구조화된 로깅으로 전환 (9개 파일) - JSON 기반 로그, 환경별 자동 전환 (개발/프로덕션) - 타입 안전성 보장, 성능 측정 타이머 내장 - Metrics 통합: 실시간 성능 모니터링 시스템 연결 (3개 파일) - Circuit Breaker 상태 추적 (api_call_count, error_count, state) - Retry 재시도 횟수 추적 (retry_count) - OpenAI API 응답 시간 측정 (api_call_duration) - 알림 통합: 장애 자동 알림 시스템 구현 (2개 파일) - Circuit Breaker OPEN 상태 → 관리자 Telegram 알림 - 재시도 실패 → 관리자 Telegram 알림 - Rate Limiting 적용 (1시간에 1회) - 문서 업데이트: - CLAUDE.md: coder 에이전트 설명 강화 (20년+ 시니어 전문가) - README.md, docs/: 아키텍처 문서 추가 영향받은 파일: 16개 (수정 14개, 신규 2개) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
kappa
118
docs/ARCHITECTURE.md
Normal file
118
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# 🏗 시스템 아키텍처
|
||||
|
||||
이 문서는 프로젝트의 기술적 구조, 데이터 흐름, 핵심 로직을 설명합니다.
|
||||
|
||||
## 📋 목차
|
||||
1. [전체 아키텍처](#전체-아키텍처)
|
||||
2. [메시지 처리 흐름](#메시지-처리-흐름)
|
||||
3. [사용자 프로필 시스템](#사용자-프로필-시스템)
|
||||
4. [예치금 시스템 로직](#예치금-시스템-로직)
|
||||
5. [프로젝트 구조](#프로젝트-구조)
|
||||
6. [보안](#보안)
|
||||
|
||||
---
|
||||
|
||||
## 전체 아키텍처
|
||||
|
||||
Cloudflare 에코시스템을 기반으로 한 서버리스 구조입니다.
|
||||
|
||||
| 컴포넌트 | 기술 스택 | 역할 |
|
||||
|----------|-----------|------|
|
||||
| **Runtime** | Cloudflare Workers | 메인 로직 실행, 웹훅 처리 |
|
||||
| **Database** | Cloudflare D1 (SQLite) | 사용자, 대화 요약, 예치금 데이터 저장 |
|
||||
| **Cache/RateLimit** | Cloudflare KV | API 요청 제한, 단기 데이터 캐싱 |
|
||||
| **AI** | OpenAI API (GPT-4o-mini) | 자연어 처리, 도구 호출(Function Calling) |
|
||||
| **Email** | Cloudflare Email Workers | 은행 SMS(이메일) 수신 및 파싱 |
|
||||
|
||||
---
|
||||
|
||||
## 메시지 처리 흐름
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
User[사용자] -->|Message| Telegram
|
||||
Telegram -->|Webhook| Worker[Cloudflare Worker]
|
||||
Worker -->|1. Validate| Security[Security Check]
|
||||
Worker -->|2. Buffer| D1[Message Buffer]
|
||||
Worker -->|3. AI Request| OpenAI[OpenAI API]
|
||||
OpenAI -->|Function Call?| Tools[Tool Execution]
|
||||
Tools -->|Result| OpenAI
|
||||
OpenAI -->|Response| Worker
|
||||
Worker -->|Reply| Telegram
|
||||
Worker -->|4. Profile Update?| SummaryService
|
||||
```
|
||||
|
||||
1. **검증**: `X-Telegram-Bot-Api-Secret-Token`을 통한 요청 인증
|
||||
2. **버퍼링**: 사용자 메시지를 D1 `message_buffer` 테이블에 임시 저장
|
||||
3. **AI 처리**: 컨텍스트와 함께 OpenAI 호출. 필요 시 도구(날씨, 도메인 등) 실행
|
||||
4. **요약**: 메시지가 일정 수(예: 20개) 쌓이면 백그라운드에서 프로필 요약 실행
|
||||
|
||||
---
|
||||
|
||||
## 사용자 프로필 시스템 (Rolling Summary)
|
||||
|
||||
토큰 비용을 절약하면서 무한한 대화 맥락을 유지하기 위해 **슬라이딩 윈도우** 방식을 사용합니다.
|
||||
|
||||
```
|
||||
[메시지 버퍼] (0~19개)
|
||||
│
|
||||
▼ 20개 도달 시
|
||||
[통합 분석 실행]
|
||||
│ ← 기존 요약본 3개 + 새 메시지 20개
|
||||
▼
|
||||
[새로운 요약 생성]
|
||||
│
|
||||
▼
|
||||
[Summaries 테이블] (최신 3개만 유지)
|
||||
[v4 (New)] [v3] [v2] ... (v1 삭제)
|
||||
```
|
||||
|
||||
이 방식은 단순히 대화를 요약하는 것을 넘어, 사용자의 **관심사, 말투, 주요 정보**를 추출하여 프로필화합니다.
|
||||
|
||||
---
|
||||
|
||||
## 예치금 시스템 로직
|
||||
|
||||
사용자 신고와 은행 알림(SMS)을 양방향으로 매칭하여 누락 없는 입금 처리를 보장합니다.
|
||||
|
||||
### 데이터 모델
|
||||
- **`bank_notifications`**: 은행 SMS 파싱 데이터 (Raw Data)
|
||||
- **`deposit_transactions`**: 사용자 입금 요청 (Pending/Confirmed)
|
||||
- **`user_deposits`**: 사용자별 잔액
|
||||
|
||||
### 매칭 프로세스
|
||||
1. **사용자 신고 시**: `bank_notifications`에서 동일 금액/입금자명의 미처리 건 검색 → 있으면 즉시 승인
|
||||
2. **SMS 수신 시**: `deposit_transactions`에서 `pending` 상태의 요청 검색 → 있으면 즉시 승인
|
||||
3. **매칭 실패 시**: 각각 대기 상태로 저장되어, 추후 상대방 데이터가 들어오면 매칭됨
|
||||
|
||||
---
|
||||
|
||||
## 프로젝트 구조
|
||||
|
||||
```
|
||||
src/
|
||||
├── index.ts # 엔트리포인트 (Router)
|
||||
├── security.ts # 보안 (Webhook 검증, Rate Limit)
|
||||
├── commands.ts # 명령어 핸들러 (/start, /reset 등)
|
||||
├── routes/ # 라우트 핸들러 (Webhook, API)
|
||||
├── services/ # 비즈니스 로직
|
||||
│ ├── conversation-service.ts # 대화 및 AI 처리
|
||||
│ ├── user-service.ts # 사용자 관리
|
||||
│ ├── summary-service.ts # 프로필 요약
|
||||
│ ├── bank-sms-parser.ts # SMS 파싱 (Regex + AI)
|
||||
│ └── ...
|
||||
├── tools/ # Function Calling 도구들
|
||||
│ ├── domain-tool.ts
|
||||
│ ├── deposit-tool.ts
|
||||
│ └── ...
|
||||
└── utils/ # 유틸리티 (Logger, Retry 등)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 보안
|
||||
|
||||
1. **Webhook Secret**: 타이밍 공격 방지 비교(Timing-safe comparison) 적용
|
||||
2. **Rate Limiting**: KV를 사용하여 사용자별 분당 요청 수 제한
|
||||
3. **API Key 관리**: 모든 키는 `wrangler secret` 또는 Vault를 통해 관리되며 코드에 노출되지 않음
|
||||
4. **SQL Injection 방지**: D1의 PreparedStatement (`bind`) 사용
|
||||
105
docs/USER_GUIDE.md
Normal file
105
docs/USER_GUIDE.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# 🤖 텔레그램 봇 사용자 가이드
|
||||
|
||||
이 문서는 봇의 주요 기능과 사용법, 명령어에 대해 설명합니다.
|
||||
|
||||
## 📋 목차
|
||||
1. [기본 사용법](#기본-사용법)
|
||||
2. [기능 상세](#기능-상세)
|
||||
3. [예치금 시스템](#예치금-시스템)
|
||||
4. [도메인 관리](#도메인-관리)
|
||||
|
||||
---
|
||||
|
||||
## 기본 사용법
|
||||
|
||||
### 봇 명령어
|
||||
| 명령어 | 설명 |
|
||||
|--------|------|
|
||||
| `/start` | 봇 시작 및 기능 소개 |
|
||||
| `/help` | 도움말 확인 |
|
||||
| `/profile` | 내 프로필(AI가 분석한 정보) 보기 |
|
||||
| `/reset` | 대화 내용 초기화 (새로운 주제로 시작하고 싶을 때) |
|
||||
|
||||
### AI와의 대화
|
||||
이 봇은 GPT-4o-mini를 기반으로 동작하며, 대화 맥락을 기억합니다.
|
||||
- 궁금한 점을 자연스럽게 물어보세요.
|
||||
- 날씨, 시간, 계산, 검색 등의 기능은 대화 중에 자동으로 실행됩니다.
|
||||
|
||||
---
|
||||
|
||||
## 기능 상세
|
||||
|
||||
봇은 대화 내용을 분석하여 다음과 같은 도구를 자동으로 호출합니다.
|
||||
|
||||
| 기능 | 예시 질문 |
|
||||
|------|-----------|
|
||||
| **날씨** | "오늘 서울 날씨 어때?", "비 오나?" |
|
||||
| **검색** | "최신 아이폰 가격 검색해줘", "파이썬이 뭐야?" |
|
||||
| **시간** | "지금 뉴욕 몇 시야?" |
|
||||
| **계산** | "123 * 456은?", "5만원의 10%는?" |
|
||||
| **문서** | "React hooks 사용법 알려줘" (개발자용) |
|
||||
|
||||
---
|
||||
|
||||
## 예치금 시스템
|
||||
|
||||
도메인 등록 등에 사용되는 예치금을 충전하고 관리합니다.
|
||||
|
||||
### 1. 입금 계좌 정보
|
||||
> **하나은행 427-910018-27104 (주식회사 아이언클래드)**
|
||||
|
||||
"입금 계좌 알려줘" 또는 "충전할래"라고 말하면 언제든 확인할 수 있습니다.
|
||||
|
||||
### 2. 입금 및 충전 방법
|
||||
두 가지 방법으로 충전이 가능합니다.
|
||||
|
||||
**방법 A: 입금 후 봇에게 말하기 (가장 빠름)**
|
||||
입금자명과 금액을 봇에게 말하면 즉시 처리됩니다.
|
||||
```
|
||||
사용자: "홍길동 5만원 입금했어"
|
||||
봇: "✅ 입금 확인 완료! 현재 잔액: 50,000원"
|
||||
```
|
||||
|
||||
**방법 B: 은행 SMS 자동 인식**
|
||||
은행 입금 문자가 수신되면(관리자), 자동으로 매칭되어 알림이 옵니다.
|
||||
별도로 봇에게 말하지 않아도 됩니다.
|
||||
|
||||
### 3. 기타 기능
|
||||
- **잔액 조회**: "잔액", "내 돈 얼마 있어?"
|
||||
- **거래 내역**: "거래 내역 보여줘"
|
||||
- **취소**: 잘못 말했을 경우 "취소해줘"라고 하면 최근 대기 건이 취소됩니다.
|
||||
|
||||
---
|
||||
|
||||
## 도메인 관리
|
||||
|
||||
도메인을 검색하고, 등록하고, 관리할 수 있습니다.
|
||||
|
||||
### 1. 도메인 검색 및 추천
|
||||
원하는 도메인이 있는지 확인하거나, 아이디어를 얻으세요.
|
||||
|
||||
- **가용성 확인**: "example.com 등록 가능한가요?"
|
||||
- **가격 조회**: ".com 가격 얼마야?", "가장 싼 도메인 보여줘"
|
||||
- **도메인 추천**: "커피숍 도메인 추천해줘" (AI가 창의적인 이름을 제안합니다)
|
||||
|
||||
### 2. 도메인 정보 조회 (WHOIS)
|
||||
도메인의 상세 정보를 조회합니다. 내 도메인이 아니어도 조회 가능합니다.
|
||||
|
||||
- "naver.com 정보"
|
||||
- "google.com whois"
|
||||
|
||||
### 3. 도메인 등록
|
||||
**주의:** 등록 시 예치금이 차감되며, 등록 후에는 취소가 불가능합니다.
|
||||
|
||||
```
|
||||
사용자: "my-startup.com 등록해줘"
|
||||
봇: (가격과 잔액 확인 후 등록 버튼 표시)
|
||||
사용자: [등록하기] 버튼 클릭
|
||||
봇: "✅ 등록 완료!"
|
||||
```
|
||||
|
||||
### 4. 내 도메인 관리
|
||||
등록한 도메인을 관리합니다.
|
||||
|
||||
- **목록**: "내 도메인 목록"
|
||||
- **네임서버 변경**: "example.com 네임서버를 ns1.example.com으로 바꿔줘"
|
||||
Reference in New Issue
Block a user