Initial commit: Telegram Web Client with bot chat sync

- 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>
2026-02-05 13:55:22 +09:00
commit e610a45fcf
34 changed files with 1898 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,142 @@
+# Telegram Web Client
+
+웹소켓을 이용해 Telegram 봇(telegram-bot-workers)과 대화하는 웹 앱
+
+## Stack
+
+- **Backend**: Python + Telethon v2 + FastAPI WebSocket
+- **Frontend**: React + TypeScript + Vite + Zustand
+- **Infrastructure**: Incus 컨테이너 (Debian 13) on jp1
+
+## Setup
+
+### 1. Telegram API 자격증명 획득
+
+1. https://my.telegram.org 접속
+2. "API development tools" 클릭
+3. `API_ID`와 `API_HASH` 복사
+
+### 2. 환경 변수 설정
+
+```bash
+# 컨테이너에 접속
+incus exec jp1:telegram-web-client -- bash
+
+# .env 파일 생성
+cd /opt/telegram-web-client/backend
+cp .env.example .env
+
+# 편집
+vi .env
+# TELEGRAM_API_ID=your_api_id
+# TELEGRAM_API_HASH=your_api_hash
+# BOT_USERNAME=telegram_summary_bot
+```
+
+### 3. 서비스 시작
+
+```bash
+# systemd 서비스 등록
+incus file push telegram-web-client.service jp1:telegram-web-client/etc/systemd/system/
+
+# 서비스 활성화 및 시작
+incus exec jp1:telegram-web-client -- systemctl daemon-reload
+incus exec jp1:telegram-web-client -- systemctl enable telegram-web-client
+incus exec jp1:telegram-web-client -- systemctl start telegram-web-client
+
+# 상태 확인
+incus exec jp1:telegram-web-client -- systemctl status telegram-web-client
+```
+
+### 4. 프론트엔드 빌드
+
+```bash
+# 컨테이너 내에서
+cd /opt/telegram-web-client/frontend
+npm install
+npm run build
+```
+
+## Development
+
+### 로컬 개발 (macOS)
+
+```bash
+# Backend
+cd backend
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+# Edit .env with your credentials
+uvicorn main:app --reload --port 8000
+
+# Frontend (별도 터미널)
+cd frontend
+npm install
+npm run dev
+```
+
+### 컨테이너 접속
+
+```bash
+incus exec jp1:telegram-web-client -- bash
+```
+
+### 로그 확인
+
+```bash
+incus exec jp1:telegram-web-client -- journalctl -u telegram-web-client -f
+```
+
+## Architecture
+
+```
+┌─────────────────┐     WebSocket      ┌─────────────────────────────┐
+│  React Frontend │◄──────────────────►│  FastAPI Backend (Debian)   │
+│  (브라우저)      │                    │                             │
+└─────────────────┘                    │  ┌─────────────────────┐    │
+                                       │  │ Telethon v2 Client  │    │
+                                       │  │ (MTProto)           │    │
+                                       │  └──────────┬──────────┘    │
+                                       └─────────────┼───────────────┘
+                                                     │
+                                                     ▼
+                                       ┌─────────────────────────────┐
+                                       │  Telegram API (MTProto)     │
+                                       │  ↔ telegram-bot-workers 봇  │
+                                       └─────────────────────────────┘
+```
+
+## WebSocket Messages
+
+### Client → Server
+
+| Type | Data | Description |
+|------|------|-------------|
+| `check_auth` | `{}` | 인증 상태 확인 |
+| `send_code` | `{phone}` | 인증 코드 전송 요청 |
+| `verify_code` | `{phone, code, phone_code_hash}` | 코드 검증 |
+| `verify_password` | `{password}` | 2FA 비밀번호 검증 |
+| `send_message` | `{text}` | 메시지 전송 |
+| `get_history` | `{}` | 채팅 기록 조회 |
+
+### Server → Client
+
+| Type | Data | Description |
+|------|------|-------------|
+| `connected` | `{session_id}` | 연결 완료 |
+| `auth_status` | `{authenticated, user_id, ...}` | 인증 상태 |
+| `code_sent` | `{phone, phone_code_hash}` | 코드 전송됨 |
+| `need_password` | `{message}` | 2FA 필요 |
+| `auth_success` | `{user_id, username, ...}` | 인증 성공 |
+| `auth_error` | `{message}` | 인증 실패 |
+| `history` | `{messages}` | 채팅 기록 |
+| `message_sent` | `{id, text, date, ...}` | 메시지 전송됨 |
+| `new_message` | `{id, text, date, ...}` | 새 메시지 수신 |
+
+## Container Info
+
+- **Name**: `jp1:telegram-web-client`
+- **IP**: `incus exec jp1:telegram-web-client -- ip a`
+- **Port**: 8000 (Backend API/WebSocket)