[RELEASE] Alpha Web v0.1.0: Полная реализация и деплой Web-клиента

[xlabtg]

Priority: Critical
Type: Release / Implementation
Labels: release, alpha, web, tdlib, teleton-agent, ai-solvable
Assignee: hive-mind
Parent: #1

---

🎯 Цель

Создать, реализовать, протестировать и опубликовать первую рабочую Alpha Web-версию Teleton-Client в директории web/. Приложение должно позволять авторизоваться по номеру телефона, читать/отправлять сообщения, настраивать прокси и опционально подключать teleton-agent для TON-операций и ИИ-автономии.

---

🏗️ Архитектура (фиксированная спецификация)

Уровни взаимодействия

[UI / React Components] 
       ↓ (Zustand Store + Hooks)
[Services Layer]
  ├── tdlib.service.ts   # WASM TDLib (MTProto, auth, messages)
  ├── agent.service.ts   # WebSocket JSON-RPC к teleton-agent
  ├── proxy.service.ts   # Валидация, сохранение, применение прокси
  └── crypto.service.ts  # AES-256-GCM шифрование сессии/настроек
       ↓
[External]
  ├── Telegram Backend (через tdweb)
  ├── Teleton Agent (localhost:PORT)
  └── LocalStorage / IndexedDB (зашифрованное хранилище)

Поток данных (Data Flow)

• Авторизация: Ввод номера → tdlib.authPhone() → ввод кода → tdlib.authCode() → сессия хранится в памяти (sessionStorage), опционально в IndexedDB с AES-шифрованием.
• Сообщения: TDLib генерирует события → useTelegram() хук подписывается → обновление Zustand → рендер UI.
• ИИ-Агент: При включении → WebSocket connect → отправка session_id → агент получает доступ к аккаунту (userbot-mode) или обрабатывает входящие через хуки клиента.
• TON-операции: UI → agent.getTonBalance() → WebSocket → Teleton Agent → TON RPC → возврат баланса в UI. Транзакции требуют подтверждения в UI.

Управление состоянием

• zustand для глобального стейта: auth, chats, settings, agentStatus, ui.
• Сессию не сохранять в localStorage по умолчанию. Сохранение только по явному согласию пользователя + шифрование.
• Настройки прокси/агента: localStorage → шифруются перед записью.

Ожидаемая структура web/

web/
├── src/
│   ├── app/          # Роутинг, провайдеры, глобальные стили
│   ├── features/     # Auth, Chat, Settings, Agent, TON
│   ├── services/     # tdlib, agent, proxy, crypto
│   ├── shared/       # UI-kit, hooks, utils, types, constants
│   └── widgets/      # ChatList, MessageWindow, InputBar
├── public/           # tdweb.wasm, worker.js, manifest.json
├── tests/            # Unit (vitest), E2E (playwright)
├── .env.example
├── vite.config.ts
└── README.md

Контракт интеграции с Teleton Agent

• Агент работает как отдельный процесс (node teleton-agent).
• Клиент подключается через ws://localhost:${PORT} (порт из env).
• Протокол: JSON-RPC 2.0 поверх WebSocket.
• Базовые методы:
  • agent.enable({ session, userId }) → { success: boolean }
  • agent.disable() → { success: boolean }
  • ton.getBalance({ address }) → { balance: string, currency: "TON" }
  • ton.sendTx({ to, amount, comment }) → { txHash: string }
• Безопасность: валидация Origin, проверка session перед активацией, таймауты 10с на RPC.

📦 Контекст и стек

• Репозиторий: xlabtg/Teleton-Client
• Фреймворк: React 18 + Vite + TypeScript
• Telegram Core: tdweb (официальный WASM-билд TDLib для браузера)
• Стили: TailwindCSS + zustand для состояния
• Интеграция: teleton-agent (уже готов, подключается через WebSocket/HTTP Management API)
• Деплой: Vercel / Cloudflare Pages (скрипт deploy.sh)

---

🔧 Пошаговый план выполнения

1. Инициализация: Создать web/ в корне. npm create vite@latest . -- --template react-ts. Установить: tdweb, @tonconnect/ui-react, zustand, tailwindcss, react-router-dom.
2. TDLib Ядро: Реализовать src/services/tdlib.ts. Методы: init(), authPhone(), authCode(), getChats(), sendMessage(), setProxy(). Использовать import.meta.env.VITE_API_ID и VITE_API_HASH.
3. Мост к Агенту: Реализовать src/services/agent.ts. WebSocket-клиент к ws://localhost:8765 (или из env). Методы: connect(), enable(session), getTonBalance(). Обработка ошибок без падения UI.
4. UI Экраны:
   • AuthScreen: Ввод телефона → Ввод кода → Переход в чат.
   • ChatScreen: Список чатов, окно сообщений, поле ввода.
   • Settings: Переключатель ИИ-агента, форма прокси (MTProto/SOCKS5), отображение баланса TON.
5. Прокси: Форма сохранения настроек прокси. Вызов tdweb.setProxy() при изменении. Валидация полей.
6. Безопасность: Никаких хардкодов. Все секреты только через .env. Сессия в памяти браузера (не localStorage по умолчанию). Шифрование при явном сохранении.
7. Сборка и Деплой: Настроить vite.config.ts для продакшна. Добавить deploy.sh (Vercel/CF). Команда npm run build должна проходить без ошибок. Размер бандла ≤ 5 МБ (без wasm).
8. Документация: Создать web/README.md (запуск, деплой, безопасность). Обновить корневой README.md ссылкой на Web-версию.

---

🚦 Правила для ИИ-исполнителя

• ✅ Не создавать подзадачи. Выполнять всё в рамках этого PR.
• ✅ Коммитить после каждого этапа. Чёткие сообщения: feat(web): этап 1, feat(web): этап 2 и т.д.
• ✅ Итерировать до успеха. Если шаг падает → анализ логов → фикс → повтор.
• ✅ Агент опционален. Приложение должно работать полностью без запущенного teleton-agent.
• ✅ Тестировать локально. Перед финальным коммитом запустить npm run build && npm run preview, проверить авторизацию и отправку сообщения.
• ❌ Не менять корневую структуру репо. Всё размещать строго в web/.
• ❌ Не хардкодить api_id, токены, URL агента. Только .env.example.
• ❌ Не использовать localStorage для сессии без шифрования.

---

✅ Критерии приемки (Definition of Done)

• Директория web/ содержит полный рабочий проект
• npm install && npm run build проходит без ошибок
• Авторизация по телефону работает (тестовый аккаунт или реальный)
• Чаты загружаются, сообщения отправляются
• UI настроек прокси сохраняет данные и применяет их в TDLib
• Переключатель агента пытается подключиться к ws://localhost:8765
• Присутствует .env.example с описанием переменных
• web/README.md позволяет запустить проект с нуля за ≤10 минут
• PR содержит код, базовые тесты (если применимо) и обновлённую документацию

💡 Примечание для hive-mind: У вас есть полный доступ к репозиторию. Действуйте автономно. Создавайте ветку, коммитьте, открывайте черновой PR. Я проверю и влью, когда все критерии выше будут зелёными.

🔗 Справочные материалы и контекст

Для корректной реализации используй следующие источники:

1. Архитектура проекта:
   • docs/architecture.md — общая структура и принципы.
   • docs/backlog.md — детализация задач.
2. Интеграция с ИИ-агентом:
   • xlabtg/teleton-agent — исходный код агента.
   • Важно: Изучи Management API агента. Клиент должен подключаться к агенту локально (ws://localhost:8765 или порт из env) для получения баланса TON и управления автономностью.
3. Telegram Core (Web):
   • tdweb (npm) — официальная библиотека для браузера. Используй её для MTProto-соединения.
4. Best Practices (Hive Mind):
   • Следуй стандартам кода.