md2vk/PRD.md

PRD — md2vk (публикация Markdown в VK)

Цель

Сервис для публикации статей в формате Markdown на стену VK (личную или сообщества) через официальный VK API (wall.post + format_data). Конвертация Markdown → VK-разметка, шифрование токенов, архив публикаций.

Пользователи

• Лично (estorozhenko) — публикация статей на стены VK.

Функциональные требования

• Конвертация Markdown → VK format_data (жирный, курсив, код, ссылки, заголовки, цитаты, блоки кода)
• Публикация поста на стене VK (wall.post) с VK-токеном
• Управление VK-аккаунтами (добавить, список, удалить) — ручной ввод access_token (Phase 1)
• Архив публикаций с фильтрацией (Publication)
• Конвертация без публикации (preview)
• Аутентификация по API-ключу (заголовок Authorization: Bearer + тело api_key)
• Шифрование VK-токенов (Fernet, AES-128-CBC + HMAC-SHA256)
• Аудит-лог всех /api/v1/* (JSONL, ротация по дням)
• OAuth-флоу VK ID (нужны client_id/secret VK-приложения) — открытая задача
• Планировщик отложенных постов (status=scheduled → wall.post) — открытая задача
• Web UI (форма поста + превью) — открытая задача

Нефункциональные требования

• HTTPS наружу (Caddy на vps02 + Let's Encrypt), basic_auth (пользователь estorozhenko, bcrypt)
• Защита от брутфорса: fail2ban на vps02, ban после 5 неудачных попыток (bantime=-1, ручной unban)
• Слушает ТОЛЬКО на WG-интерфейсе 10.8.0.2:8420 (наружу не доступен, кроме Caddy)
• БД и логи — bind-mount на хосте (вне контейнера)
• Контейнер read_only: true (кроме /data и /logs)
• Rate limiting: RATE_LIMIT_PER_MINUTE=10 в конфиге (in-memory bucket НЕ реализован — открытая задача)
• Graceful shutdown, retry при сетевых ошибках VK API — открытые задачи

Границы (что НЕ делаем в Phase 1)

• НЕ «взламываем» VK: только официальный OAuth 2.0 / VK API
• Лонгриды/статьи через API не публикуются (только wall.post с анонсами/ссылками) — ограничение VK API
• Планировщик отложенных постов не включается в текущую итерацию
• Полный OAuth-флоу — отдельная задача (после получения client_id/secret)

Критерии готовности

• Сквозная проверка: https + auth (401/200) + ban после 5 попыток + ручной unban
• Pull mirror gitverse → gitea синхронизирован
• Документация в docs/ (index, access, architecture, vk-api, security, deploy, status) + AGENTS.md
• openspec baseline зафиксирован

Доступы (реквизиты)

• Домен: https://md2vk.nixg.ru (vps02, Caddy)
• Пользователь basic_auth: estorozhenko (bcrypt-хэш в Caddyfile, пароль НЕ в git)
• Backend: bigbox 10.8.0.2:8420 (WG)
• Git: gitverse.ru/kpa39l/md2vk (primary) → gitea.nixg.ru/estorozhenko/md2vk (pull mirror, 8h)
• openspec: /opt/md2vk/openspec/