admin/cm-over
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Andrewkydev
2026-02-22 19:30:40 +03:00
commit 5b682894ba
6 changed files with 448 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
01-system-overview.md Normal file
View File

@@ -0,0 +1,58 @@
# System Overview
## Назначение проекта
`DuExpBot` — это платформа VK-бота и miniapp-панели для управления чатами и расширениями (аддонами).
Основные направления:
1. чат-менеджмент (модерация, роли, события, таймеры, статистика, правила);
2. модульные команды и утилиты;
3. каталог аддонов с модерацией и установкой в чаты;
4. интеграции с внешними сервисами (whois/ip/minecraft-query/callback).
## Технологический стек
1. Backend: `Go`.
2. База данных: `PostgreSQL`.
3. ORM/миграции: `GORM` + `AutoMigrate`.
4. VK API: `vksdk`.
5. Miniapp frontend: `React + TypeScript + Vite`.
6. Router HTTP: `gorilla/mux`.
## Высокоуровневая архитектура
1. `internal/bootstrap/*`
Сборка и запуск приложения, wiring зависимостей.
2. `internal/modules/*`
Бизнес-модули (chatmanager, addons, manager API, callbacks и т.д.).
3. `internal/modules/cmd/*`
Командные модули бота.
4. `internal/domain/*`
Модели данных (ORM-сущности).
5. `internal/db/*`
Инициализация БД и миграции совместимости.
6. `miniapp/*`
UI-панель для управления.
## Ключевые подсистемы
1. `chatmanager`
Управление поведением бота в чатах, RBAC, санкции, аудит, автоматизация.
2. `addons`
Чатовые аддоны, рантайм исполнения, каталогные установки.
3. `manager`
API для miniapp (чаты, группы, настройки, каталог, модерация).
4. `callbacks`
Webhook/callback-инфраструктура.
5. `query`
Запросы к игровым серверам (Minecraft), обновление статуса.
6. `whois` + `whois-service`
WHOIS/RDAP lookup контур.
## Модель расширяемости
1. Ботовые команды регистрируются модульно.
2. Аддоны могут исполняться в sandbox/изолированном runtime.
3. Каталог аддонов имеет этапы: draft -> pending -> approved/rejected/archived.
4. Уровни аккаунта (`account_type`) применяются для глобальных прав (например, модерация каталога).

50
02-processes-and-services.md Normal file
View File

@@ -0,0 +1,50 @@
# Processes And Services
## Точка входа
`cmd/app/main.go` -> `bootstrap.RunApp()`
## Что запускает `RunApp`
1. загрузку `.env`;
2. startup guard (в prod);
3. загрузку локалей;
4. подключение к PostgreSQL;
5. миграции;
6. запуск API-сервера;
7. запуск VK-бота;
8. автозапуск внутренних сервисов (опционально).
## Основные процессы
1. `api`
Основной HTTP API приложения.
2. `bot`
Longpoll/командный runtime VK-бота.
3. `whois-service`
Отдельный HTTP-сервис whois/rdap.
4. `addons-v8-service`
Сервис изолированного исполнения аддонов (V8 runtime).
## Автостарт дополнительных сервисов
Переменные:
1. `AUTOSTART_WHOIS_SERVICE` (по умолчанию `true`);
2. `AUTOSTART_ADDONS_V8_SERVICE` (по умолчанию `true`).
## Связанные cmd-пакеты
1. `cmd/api` — отдельный запуск API (если нужен отдельно).
2. `cmd/bot` — отдельный запуск бота.
3. `cmd/miniapp-receiver` — сервисный контур для miniapp/webhook.
4. `cmd/whois-service` — standalone whois service.
5. `cmd/addons-v8-service` — standalone addons runtime service.
## Graceful shutdown
При `SIGINT/SIGTERM`:
1. останавливается bot loop;
2. вызывается `Shutdown` у API;
3. вызывается `Shutdown` у `whois-service` и `addons-v8-service` (если запущены).

156
03-bot-commands.md Normal file
View File

@@ -0,0 +1,156 @@
# Bot Commands
Ниже команды по модулям. Описания — на уровне назначения, без внутренней логики.
## Общая регистрация команд
Команды подключаются в `internal/bootstrap/bot_commands.go`.
Основные командные модули:
1. `chatmanager`
2. `addons`
3. `utils`
4. `games`
5. `query` (minecraft)
6. `whois`
7. `screen`
## 1) Addons module
Команды:
1. `/addon` (управление аддоном, подкоманды)
2. `/addons` (список аддонов чата)
Подкоманды `/addon`:
1. `role` — смена роли/приоритета доступа к аддону.
2. `prefix` — префикс вызова аддонов.
3. `sandbox` — статус/вкл/выкл/движок sandbox.
4. `install` — установка аддона из каталога.
5. `enable|disable` — вкл/выкл аддон.
6. `delete` — удалить аддон.
7. `<name> <code>` — создание аддона.
Отдельно:
1. unknown command handler перехватывает префиксные вызовы аддонов.
## 2) Chatmanager module
### 2.1 Moderation
1. `kick`, `multikick`, `kickbots`, `kickdogs`
2. `kickafter`, `kickfrom`, `kickmessages`
3. `inactive`, `kickinactive`, `kickleft`
4. `ban`, `multiban`, `everban`, `multieverban`, `unban`
5. `mute`, `unmute`
6. `warn`, `unwarn`, `warnlist`, `banlist`
7. `selfban`
### 2.2 Roles
1. `role`, `promote`, `demote`
2. `joinrole`
3. `hierarchy`, `tree`, `staff`, `roles`
4. `createrole`, `deleterole`, `rolerename`, `roleemoji`
5. fixed helpers: `membercmd`, `helpercmd`, `modcmd`, `hmodcmd`, `admincmd`, `clearcmd`, `unrole`
### 2.3 Access / Permissions
1. `immunity`, `unimmunity`, `immunities`
2. `perm`, `perms`
### 2.4 Settings
1. `prefix`, `timezone`
2. `quieterrors`, `quieterrorsru`
3. `language`, `chatlang`
4. `autounban`
5. `warnlimit`, `limitwarns`
6. `warntime`, `warnlifetime`
7. `kickrole`, `inviterole`, `titlerole`, `pinrole`, `adminrole`
8. `kickmenu`, `inactivejoin`, `autodelete`
9. `statstype`, `catalog`, `news`, `whitelist`, `chattype`
### 2.5 Service / Runtime / Help
1. `logs`, `chathelp`
2. `resync`
3. `rules`, `setrules`
4. `motd`, `setmotd`
5. `online`, `offline`, `status`, `chatinfo`
6. `announce`
7. notification toggles: `notifybans`, `notifyunbans`, `notifywarns`, `notifyprevents`, `notifyevents`, `togglegroup`, `subscription`
8. `backlog`, `actions`, `captcha`, `write`, `cleanup`
### 2.6 Automation
1. Limits: `limits`, `limit`, `removelimit`
2. Timers: `timers`, `timer`, `remtask`
3. Events/Prevents: `events`, `addevent`, `redevent`, `remrule`, `preevents`, `prevent`, `remprevent`
### 2.7 Stats & Templates
1. `chatstats`, `stata`, `topstats`, `statlist`
2. `setwarn`, `setmute`
### 2.8 Anywhere commands (доступ вне чата)
1. `helpanywhere` / `helpme`
2. `mychats`, `rating`
3. `hidekeyboard`
4. `report`
5. `bind`, `tochat`
6. `donotnotify`, `nomention`
### 2.9 Callback commands
1. `callback`
2. `callbacktest`
3. `callbacksecret`
## 3) Utils module
1. `color` / `colour`
2. `gradient` / `grad`
3. `currency` / `rates` / `convert`
4. `datereg` / `regdate`
5. `ip` / `hostip` / `dns`
6. `ping` / `latency`
7. `password` / `pass` / `pwd`
8. `phar` / `zip` / `convertation` / `pluginconvert`
Примечание:
1. команда `jar` есть в коде как отключенный блок.
## 4) Games module
1. `balance` / `coins` / `wallet`
2. `bonus` / `reward`
3. `coin` / `coinflip`
4. `transfer` / `pay`
## 5) Query module (Minecraft)
1. `mcpe` / `mcbe` / `bedrock`
2. `java` / `mcjava` / `mcpc`
3. `query` / `q` (обертка-подсказка)
Поддерживаются callback-кнопки refresh для обновления статуса.
## 6) Whois module
1. `whois`
2. aliases: `ip`, `ipinfo`
Возвращает сводку по IP/домену через whois/rdap-клиент.
## 7) Screen module
1. `screen` / `screenshot` / `shot`
2. admin: `screen_admin` / `screenctl`
`screen` — скриншот URL; `screen_admin` — управление доступностью/блоклистом.

79
04-manager-api.md Normal file
View File

@@ -0,0 +1,79 @@
# Manager API
Источник маршрутов: `internal/modules/manager/http/module.go`.
## Public
1. `POST /tenant/vk/callback/{path_token}/{tenant_id}/{group_id}`
Callback endpoint для tenant/group.
2. `OPTIONS /tenant/vk/callback/{path_token}/{tenant_id}/{group_id}`
CORS/preflight.
## Private (`/manager/*`)
### Me
1. `GET /manager/me/profile` — профиль менеджера (`account_type`, `account_code`).
2. `GET /manager/me/settings` — пользовательские настройки.
3. `PUT /manager/me/settings` — обновление пользовательских настроек.
### Chats / Workspace
1. `GET /manager/chats` — список доступных чатов.
2. `GET /manager/chats/workspace/{chat_uid}` — агрегированный workspace чата.
3. `POST /manager/chats/workspace/{chat_uid}/events` — создать event rule.
4. `POST /manager/chats/workspace/{chat_uid}/timers` — создать timer.
5. `GET /manager/chats/workspace/{chat_uid}/actions` — список audit-действий.
6. `GET /manager/chats/workspace/{chat_uid}/stats` — статистика чата.
### Chat addons
1. `GET /manager/chats/{peer_id}/addons` — список аддонов чата.
2. `POST /manager/chats/{peer_id}/addons` — создать аддон в чате.
3. `PATCH /manager/chats/{peer_id}/addons/{name}` — изменить аддон.
4. `DELETE /manager/chats/{peer_id}/addons/{name}` — удалить аддон.
5. `POST /manager/chats/{peer_id}/addons/install` — установить аддон из каталога.
### Chat settings
1. `GET /manager/chats/{peer_id}/settings` — получить базовые настройки.
2. `PUT /manager/chats/{peer_id}/settings` — обновить базовые настройки.
### Groups / Callback
1. `GET /manager/groups` — группы пользователя.
2. `POST /manager/groups/connect` — подключить группу.
3. `GET /manager/groups/{group_id}/settings` — настройки группы.
4. `PUT /manager/groups/{group_id}/settings` — обновить настройки группы.
5. `POST /manager/groups/{group_id}/token` — сохранить token.
6. `POST /manager/groups/{group_id}/callback/rotate-secret` — ротация секрета.
7. `GET /manager/groups/{group_id}/callback/verify` — верификация callback.
8. `GET /manager/groups/{group_id}/callback/events` — лог callback событий.
9. `POST /manager/groups/{group_id}/callback/ping` — тест callback.
10. `GET /manager/groups/{group_id}/status` — статус callback-конфигурации.
### Addons catalog
1. `GET /manager/addons/catalog` — публичный каталог approved аддонов.
2. `GET /manager/addons/catalog/categories` — список стандартизированных категорий.
3. `GET /manager/addons/catalog/{addon_id}/versions` — история версий каталожного аддона.
4. `POST /manager/addons/catalog` — создать draft в каталоге.
5. `GET /manager/addons/catalog/mine` — мои каталогные аддоны.
6. `POST /manager/addons/catalog/{addon_id}/submit` — отправить на модерацию.
7. `GET /manager/addons/moderation/pending` — pending для модерации.
8. `POST /manager/addons/moderation/{addon_id}/decision` — решение модерации.
## Каталог аддонов: важные поля
1. `title`, `slug`, `addon_name`
2. `category` (стандартизированная)
3. `image_url`
4. `usage_example`
5. `gallery` (массив URL)
6. `description`
7. `code`
## Доступы
1. Модерация каталога (`pending`, `decision`) ограничена глобальным уровнем аккаунта `account_type >= moderator`.
2. Дополнительно поддерживается legacy-список moderator VK IDs.

80
05-data-model-notes.md Normal file
View File

@@ -0,0 +1,80 @@
# Data Model Notes
Это краткая карта ключевых сущностей. Полный состав — в `internal/domain/*`.
## Пользователь и менеджер
1. `users` (`domain.User`)
Базовый профиль пользователя, язык, ник, игровые поля.
2. `manager_accounts` (`domain.ManagerAccount`)
Связка user <-> manager, enabled, глобальный `account_type`.
3. `manager_user_settings` (`domain.ManagerUserSetting`)
Персональные настройки для miniapp.
## Группы и callback
1. `manager_groups` (`domain.ManagerGroup`)
Привязанные VK группы.
2. `manager_group_tokens` (`domain.ManagerGroupToken`)
Токены групп (зашифрованные).
3. `manager_callback_endpoints` (`domain.ManagerCallbackEndpoint`)
Параметры callback endpoint.
4. `manager_callback_events` (`domain.ManagerCallbackEvent`)
Лог входящих callback событий.
5. `manager_group_settings` (`domain.ManagerGroupSetting`)
Настройки групп в key/value.
## Чаты и чат-менеджер
1. `chats` (`domain.Chat`)
Чаты, `peer_id`, `chat_uid`.
2. `chat_settings` (`domain.ChatSetting`)
Основные настройки чата.
3. `chat_members`, `member_roles`, `roles`
Участники и RBAC.
4. `permission_roles`, `permission_users`
Права команд.
5. `sanctions`, `immunities`
Бан/мут/пред/иммунитеты.
6. `event_rules`, `prevent_rules`, `timer_tasks`
Автоматизация.
7. `audit_actions`, `command_logs`
Журналы действий и команд.
8. `statistics_message_daily`
Агрегированная статистика.
## Аддоны
1. `chat_addons` (`domain.ChatAddon`)
Установленные в чат аддоны.
2. `chat_addon_db` / `chat_addon_shared_db`
KV-хранилища для аддонов (локальное/shared).
3. `chat_addon_invoke_logs`
Логи вызовов аддонов.
## Каталог аддонов
1. `manager_addon_catalog` (`domain.ManagerAddonCatalog`)
Карточка аддона каталога (метаданные, код, статус модерации).
2. `manager_addon_catalog_versions` (`domain.ManagerAddonCatalogVersion`)
Снимки версий.
3. `manager_addon_moderation_logs` (`domain.ManagerAddonModerationLog`)
Логи переходов статуса.
4. `chat_addon_catalog_installs` (`domain.ChatAddonCatalogInstall`)
Фиксация установок в чаты.
## Account type (глобальный уровень)
`manager_accounts.account_type`:
1. `10` regular
2. `20` enhanced
3. `30` maximum
4. `40` moderator
5. `50` administrator
6. `60` developer
Применение:
1. доступ к модерации каталога;
2. staff-уведомления по аддонам (уровень `> 30`).

25
README.md Normal file
View File

@@ -0,0 +1,25 @@
# DuExpBot Technical Docs
Этот каталог содержит техническую документацию по проекту без глубокого разбора бизнес-логики.
## Состав
1. `techdocs/01-system-overview.md`
Что это за бот, ключевые подсистемы, общая архитектура.
2. `techdocs/02-processes-and-services.md`
Какие процессы запускаются, что делает каждый сервис.
3. `techdocs/03-bot-commands.md`
Команды бота по модулям (назначение, без внутренней логики).
4. `techdocs/04-manager-api.md`
HTTP API менеджера/miniapp: маршруты и смысл.
5. `techdocs/05-data-model-notes.md`
Основные сущности БД и их назначение.
## Обновление
Документация собрана по текущему коду репозитория и должна обновляться при:
1. добавлении/удалении команд;
2. изменении API;
3. изменении состава процессов;
4. изменении ключевых моделей БД.