init

README.md

@@ -0,0 +1,152 @@
+# MikoPBX Public SIP Telephony Bot
+
+Telegram-бот для публичной SIP-телефонии на базе MikoPBX.
+
+## Основные возможности
+
+### Для обычных пользователей
+- Регистрация **строго 7-значного** номера
+- **Один номер на одного пользователя** (ограничение)
+- Выбор пароля: сгенерировать или ввести свой
+- Получение **полных параметров подключения** (домен, сервер, порт, транспорт, outbound proxy, STUN и т.д.)
+- Просмотр своих аккаунтов
+
+### Для администраторов
+- Полный список всех аккаунтов
+- Смена номера / пароля
+- Удаление аккаунтов
+- **Привязка уже существующих номеров из MikoPBX** к Telegram ID пользователя
+
+### Синхронизация с MikoPBX
+- Полная двусторонняя синхронизация (создание, изменение номера, изменение пароля, удаление)
+- Возможность привязывать уже существующие в MikoPBX аккаунты
+
+---
+
+## Настройка (.env)
+
+```env
+# MikoPBX
+MIKOPBX_HOST=http://192.168.1.50:8081
+MIKOPBX_ADMIN_LOGIN=admin
+MIKOPBX_ADMIN_PASSWORD=твой_пароль
+
+# Telegram
+TELEGRAM_BOT_TOKEN=твой_токен
+ADMIN_TELEGRAM_IDS=123456789,987654321
+
+# SIP параметры (показываются пользователям)
+DEFAULT_SIP_SERVER=sip.tvoyserver.ru
+DEFAULT_SIP_PORT=5060
+DEFAULT_SIP_DOMAIN=sip.tvoyserver.ru
+DEFAULT_SIP_TRANSPORT=UDP
+DEFAULT_SIP_OUTBOUND_PROXY=
+DEFAULT_SIP_STUN=stun.l.google.com:19302
+```
+
+**Все параметры подключения настраиваются в `.env`** и автоматически подставляются в сообщение пользователю.
+
+---
+
+## Как работает регистрация номера
+
+1. Пользователь нажимает **"Register new number"**
+2. Вводит **ровно 7 цифр**
+3. Вводит имя (опционально)
+4. Выбирает способ получения пароля:
+   - Сгенерировать случайный
+   - Ввести свой пароль
+5. Бот создаёт аккаунт в **MikoPBX** с указанным паролем
+6. Выдаёт **полные параметры подключения**
+
+**Ограничения:**
+- Номер строго 7 цифр
+- У одного Telegram-пользователя может быть только **один** номер
+
+---
+
+## Привязка существующих номеров MikoPBX (Админ)
+
+Это одна из ключевых фич:
+
+1. Админ → **Admin panel** → **Link existing MikoPBX number**
+2. Вводит существующий 7-значный номер из MikoPBX
+3. Вводит Telegram ID пользователя
+4. Номер привязывается к пользователю
+
+После этого пользователь может:
+- Видеть свой номер в разделе "My accounts"
+- Получать параметры подключения (если пароль был заранее известен)
+
+**Полезно**, когда номера уже созданы в MikoPBX вручную.
+
+---
+
+## Полный список кнопок и команд
+
+### Главное меню (для всех)
+- `Register new number` — регистрация нового номера
+- `My accounts` — мои аккаунты
+- `Admin panel` — только для администраторов
+
+### Админ-панель
+- `All registered accounts` — список всех аккаунтов
+- `Link existing MikoPBX number` — привязка существующего номера
+- При просмотре аккаунта:
+  - `Change number`
+  - `Change password`
+  - `Delete account`
+
+### Команды
+- `/start` — главное меню
+- `/cancel` — отмена текущего действия
+
+---
+
+## Пример сообщения с параметрами подключения
+
+```
+Your SIP account has been created!
+
+Number: 1001001
+Secret (password): MySuperPass2025
+
+--- Full connection parameters ---
+Domain: sip.tvoyserver.ru
+Server / Outbound Proxy: sip.tvoyserver.ru
+Port: 5060
+Transport: UDP
+Username / Auth ID: 1001001
+Password: MySuperPass2025
+Outbound Proxy: 
+STUN Server: stun.l.google.com:19302
+
+Recommended clients: Zoiper, MicroSIP, Linphone, Bria
+Use these credentials in your SIP client.
+```
+
+---
+
+## Запуск и обновление
+
+```bash
+# Первый запуск
+docker compose up -d --build
+
+# Просмотр логов
+docker compose logs -f mikopbx-bot
+
+# Пересборка после изменений
+docker compose up -d --build
+```
+
+---
+
+## Важные замечания
+
+- Номера строго 7 цифр (валидация на стороне бота)
+- Один Telegram ID = один номер
+- Все изменения (номер/пароль/удаление) выполняются и в MikoPBX, и в локальной БД
+- Привязка существующих номеров позволяет работать с уже созданными в MikoPBX аккаунтами без пересоздания
+
+Бот полностью готов к эксплуатации.