eee934391a
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>
119 lines
4.4 KiB
Markdown
119 lines
4.4 KiB
Markdown
# 🏗 시스템 아키텍처
|
|
|
|
이 문서는 프로젝트의 기술적 구조, 데이터 흐름, 핵심 로직을 설명합니다.
|
|
|
|
## 📋 목차
|
|
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`) 사용
|