e610a45fcf
- Backend: FastAPI + Telethon v2 WebSocket server - Frontend: React + TypeScript + Vite + Zustand - Features: Phone auth, 2FA, real-time bot chat - Fix: Use chats= instead of from_users= to sync messages from all devices - Config: BOT_USERNAME=AnvilForgeBot Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
103 lines
4.1 KiB
Markdown
103 lines
4.1 KiB
Markdown
# Telegram Web Client Design
|
|
|
|
## Overview
|
|
|
|
웹소켓을 이용해 Telegram 봇(telegram-bot-workers)과 대화하는 웹 앱
|
|
|
|
## Stack
|
|
|
|
- **Infrastructure**: Incus 컨테이너 (Debian 13) on jp1/kr1
|
|
- **Backend**: Python + Telethon v2 + FastAPI WebSocket
|
|
- **Frontend**: React + TypeScript + Vite
|
|
- **State Management**: Zustand
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────┐ WebSocket ┌─────────────────────────────┐
|
|
│ React Frontend │◄──────────────────►│ FastAPI Backend (Debian) │
|
|
│ (브라우저) │ │ │
|
|
└─────────────────┘ │ ┌─────────────────────┐ │
|
|
│ │ Telethon v2 Client │ │
|
|
│ │ (MTProto) │ │
|
|
│ └──────────┬──────────┘ │
|
|
└─────────────┼───────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────┐
|
|
│ Telegram API (MTProto) │
|
|
│ ↔ telegram-bot-workers 봇 │
|
|
└─────────────────────────────┘
|
|
```
|
|
|
|
## Backend Structure
|
|
|
|
```
|
|
backend/
|
|
├── main.py # FastAPI 앱 진입점
|
|
├── config.py # 설정 (API_ID, API_HASH, BOT_USERNAME)
|
|
├── auth/
|
|
│ ├── telegram_auth.py # Telethon 인증 로직
|
|
│ └── session_manager.py # 세션 저장/복원
|
|
├── websocket/
|
|
│ ├── handler.py # WebSocket 연결 관리
|
|
│ └── events.py # 메시지 송수신 이벤트
|
|
├── telegram/
|
|
│ ├── client.py # Telethon 클라이언트 래퍼
|
|
│ └── bot_chat.py # 봇과의 대화 전용 로직
|
|
└── models/
|
|
└── schemas.py # Pydantic 모델
|
|
```
|
|
|
|
## Frontend Structure
|
|
|
|
```
|
|
frontend/
|
|
├── src/
|
|
│ ├── App.tsx
|
|
│ ├── main.tsx
|
|
│ ├── components/
|
|
│ │ ├── Auth/
|
|
│ │ │ ├── PhoneInput.tsx # 전화번호 입력
|
|
│ │ │ └── CodeInput.tsx # 인증 코드 입력
|
|
│ │ └── Chat/
|
|
│ │ ├── ChatContainer.tsx # 채팅 메인
|
|
│ │ ├── MessageList.tsx # 메시지 목록
|
|
│ │ └── MessageInput.tsx # 메시지 입력
|
|
│ ├── hooks/
|
|
│ │ └── useWebSocket.ts # WebSocket 연결 훅
|
|
│ ├── stores/
|
|
│ │ └── chatStore.ts # Zustand 상태 관리
|
|
│ └── types/
|
|
│ └── index.ts
|
|
├── package.json
|
|
└── vite.config.ts
|
|
```
|
|
|
|
## Features
|
|
|
|
- **Authentication**: Telegram 로그인 (전화번호 + 인증 코드)
|
|
- **Session Management**: 로그인 후 세션 파일 저장, 재접속 시 자동 복원
|
|
- **Real-time Chat**: WebSocket으로 실시간 메시지 송수신
|
|
- **Bot Filter**: 특정 봇(telegram-bot-workers)과의 대화만 처리
|
|
|
|
## User Flow
|
|
|
|
1. 사용자가 웹에서 전화번호 입력
|
|
2. 백엔드가 Telethon으로 Telegram에 인증 코드 요청
|
|
3. 사용자가 코드 입력 → 세션 생성
|
|
4. WebSocket 연결 유지, 봇과 실시간 대화
|
|
|
|
## Configuration
|
|
|
|
환경 변수:
|
|
- `TELEGRAM_API_ID`: Telegram API ID
|
|
- `TELEGRAM_API_HASH`: Telegram API Hash
|
|
- `BOT_USERNAME`: 대화할 봇 username (예: @telegram_summary_bot)
|
|
|
|
## Deployment
|
|
|
|
- Incus 컨테이너: Debian 13
|
|
- systemd 서비스로 백엔드 실행
|
|
- Caddy/Nginx로 리버스 프록시 + SSL
|