docs: подробный README (разбор проекта при переносе в Gitea)
Старый README сохранён как README.upstream.md.
Этот коммит содержится в:
+58
-54
@@ -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 нет.
|
||||
|
||||
@@ -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 базу.
|
||||
Ссылка в новой задаче
Block a user
© 2026 StackWorks