# 🏗 시스템 아키텍처

이 문서는 프로젝트의 기술적 구조, 데이터 흐름, 핵심 로직을 설명합니다.

## 📋 목차
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`) 사용