# md2vk

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

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

**Прод:** https://md2vk.nixg.ru (basic auth — см. `docs/security.md`; Swagger `/docs`).

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

Вся документация — в [`docs/`](docs/index.md):

- [docs/index.md](docs/index.md) — указатель, обзор
- [docs/access.md](docs/access.md) — **реквизиты и доступы** (vps02, Caddy, gitverse, gitea, DNS, VK API)
- [docs/architecture.md](docs/architecture.md) — архитектура, порты, схема
- [docs/vk-api.md](docs/vk-api.md) — порядок взаимодействия с VK API (OAuth, wall.post, лонгриды)
- [docs/security.md](docs/security.md) — безопасность (basic auth, fail2ban, Fernet, API-ключ)
- [docs/deploy.md](docs/deploy.md) — деплой (docker, Caddy, fail2ban)
- [docs/status.md](docs/status.md) — статус/история

Инструкции для агентов (Hermes и др.): [`AGENTS.md`](AGENTS.md).

## Возможности

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

## API

| Метод | Путь | Описание |
|-------|------|----------|
| `GET` | `/api/v1/health` | Проверка работоспособности |
| `GET` | `/api/v1/accounts` | Список VK-аккаунтов |
| `POST` | `/api/v1/accounts` | Добавить VK-аккаунт |
| `DELETE` | `/api/v1/accounts/{id}` | Удалить VK-аккаунт |
| `POST` | `/api/v1/publish` | Опубликовать пост на стене |
| `POST` | `/api/v1/convert` | Конвертировать Markdown (без публикации) |
| `POST` | `/api/v1/publications` | Архив публикаций |

Swagger UI: `http://127.0.0.1:8420/docs` (прод — за basic auth).

## Быстрый старт

```bash
cd /opt/md2vk
make docker-up        # docker compose up -d --build
curl -s http://127.0.0.1:8420/api/v1/health   # {"status":"ok"}
```

Детали деплоя и проверки — [docs/deploy.md](docs/deploy.md).

## Технологии

Python 3.12+, FastAPI, SQLAlchemy 2.0 (async), SQLite (aiosqlite), httpx, cryptography (Fernet), Docker, Caddy, fail2ban.