CareNest Bot

CareNest Bot — небольшой Telegram-бот о заботе и тёплых моментах. Он хранит список желаний, проводит квиз, присылает случайную тёплую фотографию и умеет отправлять утренние сообщения по расписанию.

Статус

Версия 1.2.2 сохраняет стабильную основу и добавляет необязательные комплименты по расписанию, безопасную подготовку фотографий и память о недавно показанных кадрах. Репозиторий публикуется как нейтральная витрина кода; сам бот рассчитан на один доверенный круг Telegram ID.

Возможности

• /start — главное меню;
• /quiz — запуск или безопасный перезапуск квиза с прогрессом и необязательными фотографиями;
• /mood — случайный тёплый момент из пула без немедленного повтора или текстовый fallback;
• /favorite — любимое фото из отдельного пула любимых фотографий с собственным shuffle bag;
• /wish — добавление желания длиной до 200 символов;
• /wishlist — просмотр общего списка по стабильным ID и удаление с подтверждением;
• /cancel — отмена ожидаемого ввода желания;
• /help — краткая справка по реальным функциям;
• /about — назначение и текущая версия проекта;
• утренние сообщения в заданном часовом поясе IANA;
• необязательные комплименты через OpenAI-совместимый API (шлюз AI Prime Tech, группа моделей Codex) раз в заданное число локальных дней;
• тихое отклонение запросов от пользователей вне ALLOWED_IDS.

Те же действия доступны через русские кнопки главного меню.

Требования и установка

Нужен Python 3.11 или новее. Данные хранятся в SQLite; отдельный сервер базы данных не нужен.

git clone https://github.com/CodeVinci8/carenest-bot.git
cd carenest-bot
python -m venv .venv

Активация окружения:

# Windows PowerShell
.venv\Scripts\Activate.ps1

# Linux и macOS
source .venv/bin/activate

Установка приложения и инструментов проверки:

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Для обычного запуска без инструментов разработки достаточно python -m pip install -r requirements.txt.

Переменные окружения

Скопируйте пример и замените заполнители:

# Windows PowerShell
Copy-Item .env.example .env

# Linux и macOS
cp .env.example .env

Обязательные значения:

• TELEGRAM_TOKEN — токен от BotFather;
• ALLOWED_IDS — один или несколько разрешённых Telegram ID через запятую.

RECIPIENT_ID нужен только для включённых утренних сообщений. Старый HER_ID временно поддерживается как fallback, если RECIPIENT_ID не задан; при запуске появится предупреждение. Токены и ID нельзя добавлять в JSON или коммитить.

Для AI-комплиментов используются AIPRIMETECH_API_KEY, AIPRIMETECH_BASE_URL и AIPRIMETECH_MODEL. Шлюз AI Prime Tech работает по OpenAI-совместимому протоколу (/v1/chat/completions); ключ относится к группе моделей Codex (gpt-5.6-luna, gpt-5.6-sol, gpt-5.6-terra), а не к моделям Claude. Ключ обязателен только при compliments.enabled=true и не выводится в журнал. При любой ошибке провайдера (таймаут, аутентификация, лимит запросов, некорректный или пустой ответ) используется локальный fallback без сбоя.

Необязательные CARENEST_CONFIG и CARENEST_DATA_DIR задают путь к персонализации и каталогу локальных данных. Относительные пути всегда считаются от корня проекта, а не от текущей папки оболочки.

Персонализация

Создайте приватный файл из нейтрального примера:

Copy-Item config/personalization.example.json config/personalization.json

cp config/personalization.example.json config/personalization.json

Файл config/personalization.json игнорируется Git. В нём настраиваются:

• recipient_name;
• final_quiz_message и code_word (в финальном тексте доступны {recipient_name} и {code_word});
• morning_messages;
• scheduler.enabled, hour, minute и IANA-зона timezone;
• пути к базе и каталогам медиа;
• compliments: интервал, локальное время, IANA-зона, разрешённый обезличенный safe_context, необязательный обезличенный профиль compliment_profile и локальные fallback-тексты;
• quiz.questions.

Каждый вопрос содержит question длиной до 800 символов, минимум два значения в options, индекс верного ответа correct начиная с нуля и необязательный photo. Текст каждого варианта ограничен 64 символами, чтобы корректно помещаться на кнопке Telegram. Фотографии квиза кладутся в media/quiz, любимые фотографии — в media/favorites, случайные воспоминания — в media/memories. Для вопроса без фотографии укажите "photo": null. Отсутствующее медиа не останавливает бота: он отправляет текстовый вариант.

Старый приватный quiz_data.py поддерживается без импорта и выполнения Python-кода: если в JSON нет quiz.questions, CareNest Bot безопасно читает литеральный список QUESTIONS. Новый формат JSON рекомендуется для дальнейших изменений.

Проверка и запуск

Проверить committed-пример без токена и соединения с Telegram:

python main.py --check-config --example
python -m carenest --check-config --example

Проверить рабочие .env, JSON, пути и ссылки на медиа:

python main.py --check-config
python -m carenest --check-config

Ошибки дают код завершения 2, предупреждения о необязательном медиа не мешают запуску. Обычный запуск:

python main.py
# или
python -m carenest

Локальные данные и совместимость

По умолчанию новая база находится в data/wishlist.db. Если там ещё нет базы, но в корне проекта уже лежит старая wishlist.db, бот продолжит использовать её на месте и не будет переносить или перезаписывать файл. Таблица items(id, name) сохраняется без изменения.

Старые каталоги photos/ и cute_photos/ также используются автоматически, если новые media/quiz и media/support отсутствуют. Все эти каталоги, .env, приватный JSON, quiz_data.py и SQLite-файлы исключены из Git.

Регулярно копируйте wishlist.db в безопасное место, предварительно остановив бота. Проект не делает облачных резервных копий и не синхронизирует локальные данные.

Безопасность и ограничения

• Не публикуйте .env, приватный JSON, фотографии и базу данных.
• runtime/, базы, журналы и медиа исключены из Git.
• Провайдер получает только строки из compliments.safe_context и compliments.compliment_profile: имена, ID, фотографии, ответы квиза, желания и история Telegram не передаются.
• Первый запуск только фиксирует стартовую локальную дату. Успех сохраняется после подтверждения Telegram; простои не создают серию догоняющих сообщений.
• При утечке токена отзовите его через BotFather.
• Доступ проверяется по Telegram ID; отклонённому пользователю бот не показывает его ID и причину.
• Состояние ввода и текущая сессия квиза хранятся только в памяти и сбрасываются при перезапуске процесса; ответы квиза не сохраняются как аналитика.
• У списка нет категорий, цен, ссылок, аккаунтов или облачной синхронизации.
• SQLite подходит для небольшого личного бота, но не для нескольких одновременно работающих экземпляров.
• Доставка сообщений зависит от Telegram и доступности сети; реальный чат не эмулируется тестами.

Структура

carenest/                         пакет приложения и обработчики Telegram
  compliments.py                 адаптер провайдера и безопасная доставка
  media_tools.py                 проверка ZIP, оптимизация и удаление EXIF
config/personalization.example.json
tests/                            проверки конфигурации и локальной логики
main.py                           совместимый вход python main.py
pyproject.toml                    зависимости и настройки инструментов
.github/workflows/quality.yml     проверки pull request и веток

Проверки разработки

python -m pytest
python -m ruff check .
python -m ruff format --check .
git diff --check

Проект восстановлен в аккуратном виде при участии CodeVinci.