Files

kappa eee934391a 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>

2026-01-19 21:23:38 +09:00

4.4 KiB

Raw Permalink Blame History

🏗 시스템 아키텍처

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

📋 목차

전체 아키텍처
메시지 처리 흐름
사용자 프로필 시스템
예치금 시스템 로직
프로젝트 구조
보안

전체 아키텍처

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(이메일) 수신 및 파싱

메시지 처리 흐름

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

검증: X-Telegram-Bot-Api-Secret-Token을 통한 요청 인증
버퍼링: 사용자 메시지를 D1 message_buffer 테이블에 임시 저장
AI 처리: 컨텍스트와 함께 OpenAI 호출. 필요 시 도구(날씨, 도메인 등) 실행
요약: 메시지가 일정 수(예: 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: 사용자별 잔액

매칭 프로세스

사용자 신고 시: bank_notifications에서 동일 금액/입금자명의 미처리 건 검색 → 있으면 즉시 승인
SMS 수신 시: deposit_transactions에서 pending 상태의 요청 검색 → 있으면 즉시 승인
매칭 실패 시: 각각 대기 상태로 저장되어, 추후 상대방 데이터가 들어오면 매칭됨

프로젝트 구조

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 등)

보안

Webhook Secret: 타이밍 공격 방지 비교(Timing-safe comparison) 적용
Rate Limiting: KV를 사용하여 사용자별 분당 요청 수 제한
API Key 관리: 모든 키는 wrangler secret 또는 Vault를 통해 관리되며 코드에 노출되지 않음
SQL Injection 방지: D1의 PreparedStatement (bind) 사용

4.4 KiB Raw Permalink Blame History