diff --git a/README.md b/README.md index 37f3dc8..fc32536 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,84 @@ # vkmgr — StackWorks VK Hub -Универсальное VK Mini App для групп ВКонтакте: заявки, услуги, клиенты, статусы, Telegram-уведомления и базовая админка. +Заготовка VK Mini App для владельцев групп ВКонтакте. Замысел: дать группе мини-кабинет, где не теряются заявки — каталог услуг, форма заявки, статусы, роли (owner / manager / client), админский список и уведомление в Telegram о новой заявке. -## Назначение +Фактически в репозитории от этого замысла есть только схема базы SQLite, манифест зависимостей backend и пример файла окружения. Кода приложения — ни серверного, ни клиентского — нет. -`vkmgr` — SaaS/Mini App для владельцев групп VK. Первая версия закрывает самую частую боль групп: заявки теряются в личке, комментариях и сообщениях. Приложение даёт группе единый мини-кабинет: услуги, форма заявки, статусы, админка и уведомления. +## Стек -## Что внутри +По тому, что есть в коде: -- `frontend/` — VK Mini App на React + VKUI + VK Bridge. -- `backend/` — Node.js API на Express + SQLite. -- `docs/` — roadmap, API, схема базы. -- `infra/` — docker-compose и nginx-заготовка. -- `install.sh` — базовый установщик на VPS. +- Node.js, ES-модули (`"type": "module"`). +- Express 4, helmet, cors, morgan, zod — заявлены в зависимостях. +- SQLite через `better-sqlite3`, режим WAL, включённые внешние ключи. +- dotenv, node-fetch. -## MVP v0.1.0 +По исходному README (в репозитории не реализовано): React + VKUI + VK Bridge на фронтенде, Vite, VK Mini Apps API, Telegram Bot API, nginx и docker-compose. -- Инициализация пользователя через VK launch params. -- Подключение группы. -- Каталог услуг. -- Создание заявки клиентом. -- Админский список заявок. -- Смена статусов заявки. -- Telegram-уведомление о новой заявке. -- Базовые роли: owner, manager, client. +## Структура -## Быстрый запуск backend +| Путь | Назначение | +| --- | --- | +| `backend/src/db.js` | Единственный файл с кодом. Подключение к SQLite, создание каталога БД, `migrate()` с полной DDL-схемой, запуск миграции при импорте и режим `--migrate` | +| `backend/package.json` | Зависимости и скрипты `dev` / `start` / `migrate` | +| `backend/.env.example` | Пример переменных окружения | +| `VERSION` | `0.1.0` | +| `.gitignore` | Игнор `node_modules`, `.env`, `data/`, `dist/`, файлов SQLite | +| `README.upstream.md` | Исходное описание замысла и планов от автора | + +Таблицы в схеме: `users`, `groups`, `group_members`, `services`, `clients`, `leads`, `lead_comments`, `faq_items`, `audit_logs`. + +Каталоги `frontend/`, `docs/`, `infra/` и скрипт `install.sh`, описанные в исходном README, в репозитории отсутствуют. + +## Как запустить + +Приложение запустить нельзя: `backend/src/server.js`, на который ссылаются скрипты `dev` и `start`, в репозитории отсутствует. + +Работает только создание схемы БД: ```bash cd backend cp .env.example .env npm install -npm run dev +npm run migrate ``` -API будет доступен на `http://localhost:8080`. +После этого в `DATABASE_PATH` появится файл SQLite со всеми таблицами. -## Быстрый запуск frontend +Команды из исходного README (`npm run dev` в backend, весь блок про frontend, `install.sh`, настройка VK Mini App и certbot) относятся к ненаписанному коду и сейчас не выполняются. -```bash -cd frontend -cp .env.example .env -npm install -npm run dev -``` +## Конфигурация -Frontend будет доступен на `http://localhost:5173`. +Всё из `backend/.env.example`. В коде реально читается только `DATABASE_PATH`, остальные переменные заготовлены под ненаписанный сервер. -## Установка из репозитория на VPS +| Имя | Назначение | Пример | +| --- | --- | --- | +| `APP_PORT` | Порт HTTP-сервера | `8080` | +| `APP_ORIGIN` | Разрешённый источник для CORS (адрес фронтенда) | `http://localhost:5173` | +| `DATABASE_PATH` | Путь к файлу SQLite | `./data/vk_hub.sqlite` | +| `VK_APP_ID` | ID приложения VK Mini App | см. `.env` | +| `VK_APP_SECRET` | Секрет приложения VK для проверки подписи launch params | см. `.env` | +| `TELEGRAM_BOT_TOKEN` | Токен бота для уведомлений о заявках | см. `.env` | +| `TELEGRAM_ADMIN_CHAT_ID` | Чат, куда шлются уведомления | см. `.env` | -```bash -git clone https://github.com/viktor138irk/vkmgr.git -cd vkmgr -sudo bash install.sh -``` +Переменная `VITE_API_URL` для фронтенда упоминается в исходном README, но файла `frontend/.env.example` в репозитории нет. -Можно задать домены перед запуском: +## Состояние -```bash -sudo FRONTEND_DOMAIN=vk.example.com API_DOMAIN=api-vk.example.com bash install.sh -``` +Заброшено на стадии заготовки. 6 коммитов, все за один день — 19.05.2026, последний коммит той же датой. Версия 0.1.0. -После установки HTTPS: +По сути это спроектированная схема данных плюс описание планов. Ни одного HTTP-обработчика, ни одной строки фронтенда. -```bash -certbot --nginx -d vk.example.com -d api-vk.example.com -``` +## Что не доделано -## Для VK Mini Apps - -1. Создать приложение в кабинете VK-разработчика. -2. Указать URL frontend в настройках mini app. -3. В `frontend/.env` указать `VITE_API_URL`. -4. В `backend/.env` указать `VK_APP_SECRET` для проверки подписи launch params. -5. Для продакшна поставить HTTPS. - -## Важно - -Это стартовый MVP-скелет, не финальный SaaS. Перед боевым запуском нужно добавить полноценную проверку прав администратора группы через VK API, оплату тарифов, rate-limit, аудит действий и нормальную PostgreSQL/MySQL базу. +- Нет `backend/src/server.js` — сервер не написан. Скрипты `npm run dev` и `npm start` падают. +- Нет ни одного маршрута API: инициализация пользователя, подключение группы, каталог услуг, создание заявки, список заявок, смена статуса — всё только в планах. +- Нет фронтенда: каталог `frontend/` отсутствует целиком. +- Нет проверки подписи VK launch params, хотя `VK_APP_SECRET` заготовлен. +- Нет отправки уведомлений в Telegram, хотя `node-fetch` и токен заготовлены. +- Заявленные зависимости `express`, `helmet`, `cors`, `morgan`, `zod`, `node-fetch` нигде не импортируются. +- Нет `install.sh`, `docker-compose`, конфигурации nginx и каталога `docs/`, упомянутых в исходном README. +- Миграции одноразовые: `migrate()` выполняется как побочный эффект импорта `db.js`, версионирования схемы нет. Изменение схемы потребует ручных ALTER. +- Таблица `audit_logs` создана, но писать в неё некому. +- Проверка прав администратора группы через VK API, тарифы и оплата, rate-limit — сам автор в исходном README отметил их как обязательные перед боевым запуском. +- Тестов нет, CI нет. diff --git a/README.upstream.md b/README.upstream.md new file mode 100644 index 0000000..37f3dc8 --- /dev/null +++ b/README.upstream.md @@ -0,0 +1,80 @@ +# vkmgr — StackWorks VK Hub + +Универсальное VK Mini App для групп ВКонтакте: заявки, услуги, клиенты, статусы, Telegram-уведомления и базовая админка. + +## Назначение + +`vkmgr` — SaaS/Mini App для владельцев групп VK. Первая версия закрывает самую частую боль групп: заявки теряются в личке, комментариях и сообщениях. Приложение даёт группе единый мини-кабинет: услуги, форма заявки, статусы, админка и уведомления. + +## Что внутри + +- `frontend/` — VK Mini App на React + VKUI + VK Bridge. +- `backend/` — Node.js API на Express + SQLite. +- `docs/` — roadmap, API, схема базы. +- `infra/` — docker-compose и nginx-заготовка. +- `install.sh` — базовый установщик на VPS. + +## MVP v0.1.0 + +- Инициализация пользователя через VK launch params. +- Подключение группы. +- Каталог услуг. +- Создание заявки клиентом. +- Админский список заявок. +- Смена статусов заявки. +- Telegram-уведомление о новой заявке. +- Базовые роли: owner, manager, client. + +## Быстрый запуск backend + +```bash +cd backend +cp .env.example .env +npm install +npm run dev +``` + +API будет доступен на `http://localhost:8080`. + +## Быстрый запуск frontend + +```bash +cd frontend +cp .env.example .env +npm install +npm run dev +``` + +Frontend будет доступен на `http://localhost:5173`. + +## Установка из репозитория на VPS + +```bash +git clone https://github.com/viktor138irk/vkmgr.git +cd vkmgr +sudo bash install.sh +``` + +Можно задать домены перед запуском: + +```bash +sudo FRONTEND_DOMAIN=vk.example.com API_DOMAIN=api-vk.example.com bash install.sh +``` + +После установки HTTPS: + +```bash +certbot --nginx -d vk.example.com -d api-vk.example.com +``` + +## Для VK Mini Apps + +1. Создать приложение в кабинете VK-разработчика. +2. Указать URL frontend в настройках mini app. +3. В `frontend/.env` указать `VITE_API_URL`. +4. В `backend/.env` указать `VK_APP_SECRET` для проверки подписи launch params. +5. Для продакшна поставить HTTPS. + +## Важно + +Это стартовый MVP-скелет, не финальный SaaS. Перед боевым запуском нужно добавить полноценную проверку прав администратора группы через VK API, оплату тарифов, rate-limit, аудит действий и нормальную PostgreSQL/MySQL базу.