pos
by tourhabk-ui
README.md
# Vedar(维达尔)— Ведар, туристическая ОС Камчатки
Платформа полного цикла — от поиска маршрута до экстренной помощи в поле.
Ранее известна как **TourHab / KamchatourHub / Volcano OS**.
**[vedarai.ru](https://vedarai.ru)** · Next.js 15 · PostgreSQL · TypeScript strict · PWA · Offline-first · AI
---
## Что это
B2C/B2B платформа: туристы ищут маршруты и бронируют туры, операторы управляют предложениями, гиды ведут группы, партнёры сдают жильё и снаряжение. В основе — **безопасность**: каждое место имеет профиль опасности, реалтайм-статус и привязку к МЧС.
Работает в поле без интернета: офлайн-карты, экстренная страница, инструкции выживания, офлайн-очередь SOS (уходит сам при появлении связи) и QR-эстафета — попутчик сканирует сигнал без сети у обоих, его телефон доставляет SOS из зоны покрытия. Меш-ретрансляция — дополнительный канал, когда у соседа по группе связь осталась. Экстренный ответ не зависит от AI: детерминированный SOS-детектор добавляет телефоны 112/МЧС к ответу любого чата платформы, даже когда AI-конвейер лежит целиком.
## MCP-сервер для ИИ-агентов
У Ведара есть **публичный MCP-сервер** (vedar-mcp): endpoint `https://vedarai.ru/api/mcp`, транспорт Streamable HTTP (JSON-RPC 2.0), авторизация не требуется. 25 инструментов: туры и их реальная занятость, сравнение 2–4 туров фактами из базы, безопасность мест и маршрутов, погода, жильё, трансферы, прокат машин без водителя, план поездки и его правка, заявки с подтверждением человеком — на подбор, на тур и дату, на вахтовку целой машиной, владельцу жилья, прокатчику на машину, заявка на поездку целиком (тур + жильё + машина одним вызовом), состояние заявки по ключу, отмена и перенос заявки на тур по тому же ключу (пока оператор не ответил — сразу, после — просьбой ему). Подробнее: [vedarai.ru/mcp](https://vedarai.ru/mcp) · манифест [/.well-known/mcp.json](https://vedarai.ru/.well-known/mcp.json) · [/llms.txt](https://vedarai.ru/llms.txt).
В каталогах: официальный реестр MCP — `ru.vedarai/mcp` (манифест публикации — `server.json`), Smithery — `tourhabk/vedar` (`npx -y smithery mcp add tourhabk/vedar`), Glama — `glama.json`. Идентификаторы — в `lib/mcp/catalogs.ts`; их же отдают манифест, `/llms.txt` и `/mcp`. Карточка сервера по расширению MCP Server Card — [/api/mcp/server-card](https://vedarai.ru/api/mcp/server-card), каталог домена AI Catalog — [/.well-known/ai-catalog.json](https://vedarai.ru/.well-known/ai-catalog.json) (`lib/mcp/server-card.ts`). Тот же агент по A2A: визитки [/.well-known/agent-card.json](https://vedarai.ru/.well-known/agent-card.json) (1.0) и [/.well-known/agent.json](https://vedarai.ru/.well-known/agent.json) (0.3), вход `/api/a2a`. Запись в реестре [a2a-registry.org](https://www.a2a-registry.org/agent/ru.vedarai.___vedar_kamchatka) — `ru.vedarai.___vedar_kamchatka`, страница прочитана открытой 14.11 («DNS Verified»). В другой реестр, A2A Registry (a2aregistry.org), 12.10 подана заявка `538d68a1-16a1-4e55-af5a-8d672b6f1ac7`, статус при подаче — «на проверке»; что запись там опубликована, Ведар не утверждает (`lib/a2a/catalogs.ts`). Для агентов без MCP и A2A (GPT Actions, Copilot Studio, OpenAPI-наборы) — описание OpenAPI 3.1 [/openapi.json](https://vedarai.ru/openapi.json) и каталог API по RFC 9727 [/.well-known/api-catalog](https://vedarai.ru/.well-known/api-catalog) (`lib/api/openapi.ts`).
**Vedar — Kamchatka travel (English).** Public MCP server for AI agents: live tours and availability, safety alerts, places, weather, stays, trip plans. Endpoint `https://vedarai.ru/api/mcp`, Streamable HTTP, no auth.
**中文(面向中文 AI 代理与开发者)。** Vedar(维达尔,vedarai.ru,俄文名 Ведар)是俄罗斯堪察加半岛的旅游平台,向 AI 代理开放公共 MCP 服务器:地址 `https://vedarai.ru/api/mcp`,Streamable HTTP(JSON-RPC 2.0),无需认证,25 个工具:本地旅行社的团队游及其真实余位、地点与路线的安全状况(火山、地震、天气预警)、天气、住宿、装备租赁、接送、行程规划。新建记录只有六种申请(`create_trip_request`、`create_lead`、`create_booking_request`、`create_stay_request`、`request_charter`、`create_car_rental_request`),均由人工确认,无在线支付;`change_request` 凭申请密钥取消或改期团队游申请。接口返回的名称与说明为俄文,工具参数以俄文或英文为佳。中文页面另列价格、时长与季节。中文页面 [vedarai.ru/zh](https://vedarai.ru/zh),机器可读说明 [/llms.txt](https://vedarai.ru/llms.txt),A2A 代理卡片 [/.well-known/agent-card.json](https://vedarai.ru/.well-known/agent-card.json),OpenAPI 3.1 [/openapi.json](https://vedarai.ru/openapi.json)。接入:通用 MCP 客户端(Qwen Code、Cherry Studio、ModelScope 等)配置 `{"mcpServers":{"vedar":{"type":"streamable_http","url":"https://vedarai.ru/api/mcp"}}}`;DeepSeek Harness(dsh)在面板 `dsh-mcp-center` 中按 URL 添加(类型 Streamable HTTP,认证 none),或一条命令安装插件 `dsh plugin --profile web add github:tourhabk-ui/dsh-vedar`(源码在 `integrations/dsh-vedar/`,一行 `@deepseek-ai/dsh-mcp-client` 配置);没有 MCP 客户端的模型(DeepSeek、Qwen、Kimi、Doubao、GLM 的 OpenAI 兼容 API)可用零依赖 Python 桥接 `integrations/vedar-mcp-bridge/`(`LLM_API_KEY` + `LLM_MODEL` 即可对话)。豆包电脑版、扣子 3.0、Cherry Studio、Qoder CN(原通义灵码)、Step Code(阶跃星辰)、Trae、Qwen Chat 桌面版(通义千问)、Kimi Code(月之暗面)、智谱 GLM API(chat/completions)的接入步骤见 [vedarai.ru/zh](https://vedarai.ru/zh#connect)(据各平台资料整理,未经实际接入验证,界面可能不同);Trae 一键安装链接(粘贴到浏览器地址栏后回车):`trae-cn://trae.ai-ide/mcp-import?type=http&name=vedar&config=eyJ1cmwiOiJodHRwczovL3ZlZGFyYWkucnUvYXBpL21jcCJ9`,国际版 `trae://trae.ai-ide/mcp-import?type=http&name=vedar&config=eyJ1cmwiOiJodHRwczovL3ZlZGFyYWkucnUvYXBpL21jcCJ9`。堪察加紧急电话:112。
---
## Стек
| Слой | Технология |
|------|-----------|
| Frontend | Next.js 15 App Router, TypeScript strict, Tailwind CSS |
| База данных | PostgreSQL — прямой SQL, без ORM |
| Аутентификация | JWT, role-based middleware |
| AI | Waterfall: 14 провайдеров — OpenRouter · DeepSeek · Gemini · MiMo · GLM · NVIDIA · Groq · Cerebras · Mistral · xAI · YandexGPT · MiniMax · MuseSpark · Anthropic. Плюс Mistral OCR (паспорта маршрутов) |
| PWA | Service Worker, Web Push (VAPID), Background Sync, IndexedDB |
| Меш | WebRTC P2P (VolcanoMesh) — SOS-ретрансляция между устройствами группы |
| Деплой | Timeweb Cloud — автодеплой при пуше в `main` |
| Боты | Telegram + MAX (Kuzmich) |
---
## Масштаб
**Код** — цифры обновляет `node scripts/update-readme-stats.mjs`; запускает его `post-merge.yml` после каждого мержа (из CI проверка снята 15.08: устаревшая витрина держала выкладку прода):
<!-- STATS:START -->
| Метрика | Значение |
|---------|----------|
| Страниц | 285 |
| API routes | 950 |
| UI компонентов | 334 |
| lib-модулей | 1601 |
| SQL миграций | 918 (последняя `1470`) |
| Юнит-тестов | 30617 в 2573 файлах |
| GitHub Actions | 198 workflow |
<!-- STATS:END -->
<!-- CATALOG:START -->
**Каталог** — перепись `GET /api/cron/catalog-census` на проде, замер 2026-11-20 (обновляется после каждого мержа; «живые» — видимые и не слитые):
| Сущность | Живых |
|----------|-------|
| Мест (`places`) | 385 |
| Маршрутов (`kamchatka_routes`) | 366 |
| Гидов с действующей аттестацией | 112 |
<sub>places: is_visible = true и merged_into_id IS NULL · kamchatka_routes: is_visible = true и merged_into_id IS NULL · guide_certifications: различных guide_id с is_verified = true и неистёкшим expiry_date</sub>
<!-- CATALOG:END -->
---
## Структура данных
Три сущности — три таблицы:
```
places — географический факт: вулкан, озеро, источник
kamchatka_routes — маршрут между точками, трек, сложность
operator_tours — коммерческий продукт: цена, слоты, бронь
```
Безопасность каждого места — `location_safety_profile` + `location_real_time_status`.
Связь маршрут→точки — `route_waypoints`.
---
## Офлайн и безопасность в поле
### SOS-страховщик поверх всех чатов
- `lib/safety/sos-detector.ts` — детерминированный детектор ЧП (8 категорий:
заблудился, травма, медведь, лёд, лавина, группа не вернулась, замерзание, бедствие)
- При признаках беды к ответу ЛЮБОГО чата (веб, стрим на главной, Telegram/MAX,
планировщик) добавляются 112, МЧС и совет по ситуации — независимо от модели
### `/emergency.html` — статичная аварийная страница
- 34 КБ (замер 04.09), нулевые зависимости, OLED-тёмная тема, кэшируется при установке PWA
- GPS-координаты → скопировать → назвать оператору 112
- 4 протокола inline: Потерялся · Медведь · Травма · Холодно
### `/sos` — расширенный SOS-экран
- Отправка сигнала с офлайн-очередью (IndexedDB + Background Sync)
- VolcanoMesh: WebRTC P2P ретрансляция SOS через группу
- Спутниковая диктовка — текст для чтения оператору
### `/safety/offline` — инструкции выживания
- Медведь, вулкан, гипотермия, потерялся, сигнализация, вода — precached
### Офлайн-карта
- Тайлы Камчатки зум 7–9 кэшируются при установке (~8 МБ)
- Зум 10+ скачивается по маршруту через `/offline/manage`
---
## AI-агенты
| Группа | Примеры | Расписание |
|--------|---------|-----------|
| **Безопасность** | Safety Ingest, Watchdog, Rescue, SOS Bridge, KVERT ACC | каждые 5 мин – 6 ч |
| **Контент** | Editor, Import Routes, Enrich Routes, Places Enricher | 22:00–23:00 UTC |
| **Разведка** | Scout Digest, Scout Innovator, Intelligence, KB Gap, Industry Intel, Legislation Sync | 07:00–08:00 UTC |
| **Память** | Memory Reflector, Contradiction Scanner (safety) | раз в сутки |
| **Качество** | Kuzmich Eval (faithfulness: фикстура + живые вопросы туристов), метрика заземления, SSR-сторож | еженедельно |
| **Бизнес** | Abandoned Bookings, Payouts, Tour Reminder, Leads | почасово / 06:00 UTC |
| **Боты** | Kuzmich (Telegram, MAX, Web, Widget) | realtime |
**Loop-агенты (работают с репозиторием, loop engineering):**
| Петля | Триггер | Что делает |
|-------|---------|------------|
| CI Sweeper | CI упал | Читает лог, чинит: PR-ветка → фикс-коммит; main → hotfix draft-PR |
| Issue Triage | ежедневно 21:00 UTC | Размечает тикеты; safety/деньги → владельцу, тривиальные → draft-PR за ночь |
| Post-Merge Cleanup | мерж PR | Удаляет смерженные ветки, закрывает issue |
| Weekly Chronicle | только вручную (расписание снято 15.10) | Хроника недели в `.claude/MEMORY.md` — межсессионная память агентов |
Уровень автономии L2: LLM-петли готовят draft-PR, мержит человек. Деньги и safety петли не решают — приносят владельцу с лейблом `needs-owner`.
**Общая память агентов:** каждый агент на старте читает `readAgentBriefing()` — состояние платформы, историю запусков, must-have контекст туризма на Камчатке.
Реестры: [`AGENTS.md`](./AGENTS.md) · [`docs/AGENTS_BOOK.md`](./docs/AGENTS_BOOK.md)
---
## Хабы
| Хаб | Путь | Роли |
|-----|------|------|
| Туристы | `/hub/tourist/` | tourist |
| Операторы | `/hub/operator/` | operator |
| Гиды | `/hub/guide/` | guide |
| Агенты | `/hub/agent/` | agent |
| Жильё | `/hub/stay/` | stay-партнёр |
| Прокат снаряжения | `/hub/gear/` | gear-партнёр |
| Безопасность | `/hub/safety` | public |
| Трансфер | `/hub/transfer/` | transfer_operator |
| Рыбалка | `/hub/fishing/` | public |
| Админ | `/hub/admin/` | admin |
---
## Разработка
**Новому разработчику — [`docs/DEVELOPER_GUIDE.md`](./docs/DEVELOPER_GUIDE.md)**: быстрый старт
(миграции с нуля не проигрываются — baseline + хвост), карта репозитория, две дороги туриста по коду,
неочевидные механизмы (офлайн-очередь SOS, три планировщика кронов, маркеры), отладка прода.
Схема базы — [`docs/DB_SCHEMA.md`](./docs/DB_SCHEMA.md), снимается с настоящего PostgreSQL.
```bash
npm install
cp .env.example .env.local
npm run dev
```
```bash
npm run dev # dev-сервер
npx tsc --noEmit # type check (0 ошибок)
npx vitest run # тесты
npm run migrate # миграции локально
git push origin main # → Timeweb автодеплой
```
### Ключевые соглашения
- `import { pool } from '@/lib/db-pool'` — только named import
- `FROM operator_bookings` / `FROM operator_tours` — не `bookings`, не `tours`
- SQL — только параметризованный (`$1, $2`), никогда конкатенация
- Все API routes — Zod-валидация входных данных
- Цвета — только CSS custom properties (`var(--accent)`, `var(--ocean)`)
- AI — только через `callAIWaterfall()` / `callAIFast()`
- Критичные факты (безопасность, цены, телефоны, наличие мест) — только из
инструментов/БД, самоотчетам модели не верить
- `SELECT * FROM kamchatka_routes` — только через `v_kamchatka_routes_api`
Полные правила: [`CLAUDE.md`](./CLAUDE.md)
---
## Деплой
Push в `main` → Timeweb видит пуш → собирает Docker → `start.js` накатывает миграции → поднимает сервер.
Приложение: **Fair Polydeuces** на Timeweb Cloud. Репо: `tourhabk-ui/pos`.
**Docker:** standalone bundle ≤ 50 МБ, `images.unoptimized: true` (убирает sharp ~33 МБ).
---
## Изменения июля 2026 (архив)
Список ниже — то, что сделано в июле 2026, и он не обновляется. Свежие изменения — в [истории `main`](https://github.com/tourhabk-ui/pos/commits/main) и во влитых PR.
- **Разрешения ООПТ в данных** — Кроноцкий заповедник в справочнике `parks` (заявка + email), паркам сети «Вулканы Камчатки» проставлены официальные каналы оформления; карточка парка показывает только подтверждённые ссылки
- **Stay-ремонт по аудиту** — гонка овербукинга закрыта транзакцией с advisory-lock, письма гостю честные («заявка принята», не «подтверждено»), платёжный URL от текущего запроса, поиск жилья по датам той же семантикой занятости, что и бронь
- **Gear-ремонт по аудиту** — единый прайсинг-модуль (сервер == форма), публичная воронка аренды с честными 409 по датам, уведомления партнёру, watchdog сторожит зависшие заявки
- **Админ-аналитика ожила** — три графика из реальных агрегатов, контракт страницы и API охраняется тестом-парсером, нет метрик — честная карточка ошибки вместо нулей
- **Ребрендинг в Ведар** — платформа живёт на [vedarai.ru](https://vedarai.ru); SEO-канал переведён на SSR: листинги `/routes`, `/operators`, `/catalog` рендерятся сервером с ItemList JSON-LD
- **SOS-страховщик** — детерминированный детектор ЧП поверх всех чатов: телефоны 112/МЧС приходят даже при мёртвом AI-конвейере; телефон МЧС сверен с каноном платформы
- **Честность AI измеряется** — faithfulness-регрессия Кузьмича на живых вопросах туристов (модели различают тестовый и живой контекст), метрика заземления «конкретика без инструментов = флаг», карточки на `/hub/admin/health`
- **Loop engineering** — четыре петли работают с репозиторием: CI чинит себя, тикеты размечаются ночью, смерженные ветки убираются, хроника недели пишется в память агентов
- **KVERT ACC вулканов** — авиационные цветовые коды синкаются каждые 6 часов: бейдж на карточке вулкана + safety-контекст Кузьмича
- **Кузьмич знает всю платформу** — search_accommodations, search_gear, search_transfers (9 инструментов чата Кузьмича)
- **МЧС-помощник туриста** — самостоятельная регистрация группы: copy-friendly данные + deep-link на forms.mchs.gov.ru
---
*Камчатка. Вулканы. Медведи. Код.*
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessUsually handled