# md2vk — Документация

Указатель документации проекта. Все реквизиты и доступы — в [access.md](access.md).

## Разделы

| Файл | Содержание |
|------|------------|
| [index.md](index.md) | Этот указатель, обзор проекта |
| [access.md](access.md) | **Все реквизиты и доступы к смежным сервисам** (vps02, Caddy, gitverse, gitea, DNS, VK API, fail2ban) |
| [architecture.md](architecture.md) | Архитектура, компоненты, порты, схема |
| [vk-api.md](vk-api.md) | Порядок взаимодействия с VK API: OAuth-флоу, wall.post, format_data, ограничения (лонгриды) |
| [security.md](security.md) | Безопасность: пароль, basic auth, блокировка после 5 попыток, Fernet, API-ключ |
| [deploy.md](deploy.md) | Деплой: docker на bigbox, Caddy на vps02, fail2ban |
| [status.md](status.md) | Статус реализации по фазам (в т.ч. история) |

## Обзор

Сервис публикации Markdown-текста на стене VK через официальный VK API (`wall.post`).

```
┌─────────────┐     ┌─────────────┐     ┌──────────────┐
│  Hermes     │────▶│  md2vk      │────▶│  VK API      │
│  Agent      │     │  :8420      │     │  wall.post   │
│  (skill)    │◀────│  FastAPI    │     │  vk.com      │
└─────────────┘     └─────────────┘     └──────────────┘
```

- Публикация Markdown → VK wall.post с `format_data` (жирный, курсив, код, ссылки, заголовки, цитаты)
- Конвертация Markdown → VK format_data без публикации (preview)
- Управление VK-аккаунтами (несколько страниц), шифрование токенов (Fernet)
- Архив публикаций с фильтрацией по статусу
- Отложенные посты (статус `scheduled`; планировщик — открытая задача)

## Внешние точки

| Что | Адрес |
|-----|-------|
| Прод | https://md2vk.nixg.ru (basic auth, см. [security.md](security.md)) |
| Swagger | https://md2vk.nixg.ru/docs (за basic auth) |
| Локально | http://127.0.0.1:8420 (bigbox), Swagger http://127.0.0.1:8420/docs |

## Быстрый старт (dev)

```bash
cd /opt/md2vk
source venv/bin/activate
pip install -r requirements.txt
# ключ шифрования уже есть: secrets/token_encryption_key (не в git)
make dev   # uvicorn :8000 --reload (для dev; прод-порт 8420 в docker)
```

## Git

Схема: **gitverse.ru (истина) → gitea.nixg.ru (pull mirror)**. Подробности в [access.md](access.md).

## Открытые задачи (см. [status.md](status.md) и openspec/)

- Планировщик отложенных постов (worker + cron)
- Web UI (форма поста + превью), сейчас только API
- OAuth-флоу VK VK ID (кнопка «Прикрепить аккаунт») — сейчас токен вводится вручную
- Unit/integration тесты (pytest)
- Rate limiting (in-memory bucket)
- Retry при сетевых ошибках VK API
- Read-only rootfs в Docker (частично: `read_only: true` в compose)