Baseline md2vk: docs, audit log, docker 8420, openspec, deploy

2026-09-29 09:55:04 +00:00 · 2026-09-18 22:05:01 +00:00
commit 09e960a3a9
39 changed files with 3716 additions and 0 deletions
@@ -0,0 +1,83 @@
+# md2vk — Взаимодействие с VK API
+
+> Источник: официальная документация VK (dev.vk.com / id.vk.ru), проверено 2026-09.
+> Услуга работает через официальный протокол OAuth 2.0 и VK API — никакого «взлома».
+
+## Как это работает
+
+1. **OAuth-авторизация.** Пользователь нажимает «Прикрепить аккаунт» → редирект на VK.
+   Пользователь подтверждает вход и выдаёт приложению права (scopes, обязателен `wall`).
+   Сервис не получает пароль — только временный код/токен.
+2. **Access Token.** VK возвращает сервису access token — цифровой ключ с ограниченными правами
+   (например, только публикация записей).
+3. **Публикация через API.** Сервис вызывает `wall.post` с текстом/вложениями, `owner_id`, `from_group`.
+   Авторизация — `access_token` в параметрах запроса.
+
+## Ссылки на официальную документацию
+
+| Что | Ссылка |
+|-----|--------|
+| Создание и настройка приложения (VK ID, Standalone) | https://id.vk.com/about/business/go/docs/ru/vkid/latest/vk-id/connection/create-application |
+| Общая документация по API | https://dev.vk.com/ru/reference |
+| Авторизация (OAuth 2.0/2.1) | https://id.vk.com/about/business/go/docs/ru/vkid/latest/vk-id/connection/start-integration/auth-without-sdk/auth-without-sdk-web |
+| Метод wall.post | https://dev.vk.com/ru/method/wall.post |
+| Создать приложение (dev.vk.com) | https://dev.vk.com |
+
+## OAuth-флоу (ссылка для получения токена)
+
+```
+https://oauth.vk.com/authorize?client_id=<client_id>&scope=wall,offline&redirect_uri=<redirect>&response_type=token
+```
+
+- `client_id` — ID приложения VK (см. VK ID).
+- `scope` — обязателен `wall`; `offline` — долгоживущий токен.
+- `response_type=token` — токен приходит в фрагменте редиректа.
+- После ответа: `access_token`, `user_id`, `expires_in` (0 = бессрочно).
+
+## Публикация (wall.post)
+
+```
+https://api.vk.com/method/wall.post
+POST data: access_token, v=5.199, owner_id, message, from_group, attachments, publish_date, format_data
+```
+
+Параметры в нашем клиенте (`app/vk_client.py`):
+
+| Параметр | Когда | Значение |
+|----------|-------|----------|
+| `owner_id` | группа | отрицательный ID сообщества (`-123`), для пользователя не передаём |
+| `from_group` | группа | `1` — пост от имени группы |
+| `friends_only` | опц. | только друзьям |
+| `publish_date` | отложка | Unix timestamp |
+| `attachments` | опц. | `photo123_456,...` |
+| `signed` | группа | подпись автора |
+| `format_data` | всегда | JSON `{"version":1,"items":[...]}` |
+
+Ответ: `{"response":{"post_id":N,"owner_id":M}}` → URL `https://vk.com/wall{M}_{N}`.
+
+### Важно про токены
+
+- Для **личной стены** — токен пользователя.
+- Для **стены сообщества** — токен **администратора группы** с правами `wall` и `photos`.
+- Токены сообщества из настроек группы («Работа с API») для `wall.post` **не подходят** —
+  нужен именно пользовательский токен.
+
+## Лонгриды (статьи) — ограничение
+
+- **Создавать статьи через официальный VK API нельзя.** В FAQ VK: «методов для работы с лонгридами пока что нет».
+- Можно **опубликовать на стене существующую статью** через `wall.post`:
+  `attachments=articleXXX_YYY`, где `XXX` — ID автора (для сообщества — с минусом), `YYY` — ID статьи.
+  Статья должна быть уже опубликована (черновик прикрепить нельзя).
+- Значит, полный автоматический дубликат блога (генерация лонгридов «из коробки») невозможен.
+  Варианты: посты+фото+ссылки через API, статьи вручную, гибрид.
+
+## Версия API
+
+- В конфиге `VK_API_VERSION=5.199` (`app/config.py`).
+- Проверка токена: `users.get` (пустой user_ids → текущий пользователь).
+
+## Ошибки
+
+Формат ошибки VK: `{"error":{"error_code":N,"error_msg":"..."}}`.
+Наш клиент бросает `VkApiError(error_code, error_msg)`; в API публикации ошибка пишется в
+`publications.error_message`, ответ `success=false`.