Документация по особенностям платформы Oopz

Информация о документе

Основная информация

• Класс адаптера: OopzAdapter (entry-point oopz)
• Способ подключения: WebSocket (wss://ws.oopz.cn) + REST-шлюз (https://gateway.oopz.cn), заголовки запросов с RSA-подписью + JWT
• Учётные данные: «либо логин-пароль, либо токен» — password (номер телефона + пароль + приватный ключ клиента, автоматический вход и продление, рекомендуется) или token (набор из четырёх компонентов: uid/JWT/device_id/приватный ключ; запасной вариант только на случай, когда вход по паролю блокируется риск-контролем; при истечении срока JWT требуется ручное повторное извлечение)
• Мультиаккаунтность: поддерживается ([Oopz_Adapter.accounts.<name>]), источник события помечается через self.account_id
• Мягкая зависимость от фреймворка: ErisPulse ≥ 2.7.1

Модель сессий

Соответствие стандарту (0.1.0)

Спецификация кодов ошибок

Структура ответа

Все ответы содержат status / retcode / data / message_id / message / oopz_raw; message_id в ответе на отправку берётся из возвращённого платформой messageId; data.self_info.user_id заполняется в get_self_info.

Полнота полей событий

• Во всех событиях обязательны id / time / type / detail_type / sub_type / platform / self, при этом oopz_raw + oopz_raw_type присутствуют всегда
• События сообщений на верхнем уровне обязательно содержат message_id; строки временных меток в микросекундах нормализуются в секунды
• id события дедуплицируется в рамках аккаунта (<account>:<тип>:<платформенный ID>)
• Неизвестные события преобразуются в type="unknown" + warning и не отбрасываются молча
• Внутренние кадры протокола (рукопожатие/аутентификация/heartbeat/подписка) не порождают платформенных событий

Семантика деградации

• Сегменты отправки voice/audio/video/file → retcode=10002 (платформа поддерживает загрузку только изображений), без выброса исключений
• Цель отправки guild → retcode=10003 (укажите канал)
• Недействительный JWT в режиме token → retcode=34100 с предложением обновить учётные данные; в режиме password автоматически выполняется повторный вход и одна повторная попытка

Поддерживаемые типы отправки сообщений

Стандартные действия API (ApiDSL)

Поддерживаемые стандартные действия

get_self_info, get_user_info, get_friend_list, get_group_info (объединённая информация о канале и его домене), get_group_list (плоский список каналов присоединённых доменов), get_guild_info, get_guild_list, get_channel_list, get_guild_members, delete_message (требуется контекст channel_id или user_id), get_file (URL вложения → base64), leave_guild, get_status, get_version, get_supported_actions

Неподдерживаемые стандартные действия (retcode=10002)

send_message (используется Send DSL), upload_file, get_latest_events, set_group_name, set_group_admin, set_group_leave, set_group_card, leave_group, leave_channel

Расширенные действия платформы (oopz.*)

Обработка заявок в друзья

• Событие: request/friend, request_id — составной stateless-ключ <target>:<friendRequestId>
• event.approve() / event.reject() → POST /client/v1/friendship/v1/response
• Единый гомогенный эндпоинт, таблица хранения контекста типа запроса не требуется

Возвращаемое значение методов отправки

{
  "status": "ok",
  "retcode": 0,
  "data": {"message_id": "14283..."},
  "message_id": "14283...",
  "message": "",
  "oopz_raw": {"messageId": "14283...", "timestamp": "..."}
}

Специфические типы событий

• Дополнительные поля событий сообщений: oopz_area_id, guild_id (сообщения каналов); oopz_reference_message_id (ответы)
• Расширения уведомлений: oopz_edited_text, oopz_emoji, oopz_reaction_type, oopz_persons, oopz_from_channel, oopz_channel_name, oopz_channel_type, oopz_area_name, oopz_role_id, oopz_role_name, oopz_ban_until, oopz_login_state
• Удобные методы EventMixin: get_raw_event(), get_area_id(), get_edited_text(), get_emoji(), get_reaction_type(), get_voice_persons()