Update project documentation and improve frontend functionality

- Updated the backend documentation in CONTRIBUTING.md and README.md to reflect changes in application structure and API endpoints.
- Enhanced the frontend components in MapView.vue for better handling of context menu actions.
- Added new types and interfaces in TypeScript for improved type safety in the frontend.
- Introduced new utility classes for managing characters and markers in the map.
- Updated .gitignore to include .vscode directory for better development environment management.
This commit is contained in:
2026-02-24 23:32:50 +03:00
parent 605a31567e
commit 82cb8a13f5
39 changed files with 1788 additions and 2631 deletions

View File

@@ -36,8 +36,9 @@ API доступно по префиксу `/map/api/`. Для запросов,
- **POST /map/api/admin/rebuildZooms** — пересобрать зум-уровни тайлов.
- **GET /map/api/admin/export** — скачать экспорт данных (ZIP).
- **POST /map/api/admin/merge** — загрузить и применить merge (ZIP с гридами и маркерами).
Дополнительные админ-действия (формы или внутренние вызовы): wipeTile, setCoords, hideMarker — см. реализацию в `internal/app/api.go` и `admin.go`.
- **GET /map/api/admin/wipeTile** — удалить тайл. Query: `map`, `x`, `y`.
- **GET /map/api/admin/setCoords** — сдвинуть координаты гридов. Query: `map`, `fx`, `fy`, `tx`, `ty`.
- **GET /map/api/admin/hideMarker** — скрыть маркер. Query: `id`.
## Коды ответов

View File

@@ -2,37 +2,41 @@
## Обзор
hnh-map — сервер автомаппера для HnH: Go-бэкенд с хранилищем bbolt, сессиями, HTML-шаблонами и Nuxt 3 SPA по пути `/map/`. Данные гридов и тайлов хранятся в каталоге `grids/` и в БД.
hnh-map — сервер автомаппера для HnH: Go-бэкенд с хранилищем bbolt, сессиями и Nuxt 3 SPA по пути `/map/`. Данные гридов и тайлов хранятся в каталоге `grids/` и в БД.
```
┌─────────────┐ HTTP/SSE ┌──────────────────────────────────────┐
│ Браузер │ ◄────────────────► │ Go-сервер (cmd/hnh-map) │
│ (Nuxt SPA │ /map/, /map/api │ • bbolt (users, sessions, grids, │
│ по /map/) │ /map/updates │ markers, tiles, maps, config) │
│ │ /map/grids/ │ • Шаблоны (embed в webapp)
└─────────────┘ │ • Статика фронта (frontend/)
│ • internal/app — вся логика │
│ • webapp — рендер шаблонов │
│ │ /map/grids/ │ • Статика фронта (frontend/)
└─────────────┘ │ • internal/app — вся логика
└──────────────────────────────────────┘
```
## Структура бэкенда
- **cmd/hnh-map/main.go** — единственная точка входа (`package main`): парсинг флагов (`-grids`, `-port`) и переменных окружения (`HNHMAP_PORT`), открытие bbolt, запуск миграций, создание `App`, регистрация маршрутов, запуск HTTP-сервера. Пути к `frontend/` и `public/` задаются из рабочей директории при старте; шаблоны встроены в бинарник (webapp, `//go:embed`).
- **cmd/hnh-map/main.go** — единственная точка входа (`package main`): парсинг флагов (`-grids`, `-port`) и переменных окружения (`HNHMAP_PORT`), открытие bbolt, запуск миграций, создание `App`, регистрация маршрутов, запуск HTTP-сервера. Пути к `frontend/` и `public/` задаются из рабочей директории при старте.
- **internal/app/** — пакет `app` с типом `App` и всей логикой:
- **app.go** — структура `App`, общие типы (`Character`, `Session`, `Coord`, `Position`, `Marker`, `User`, `MapInfo`, `GridData` и т.д.), регистрация маршрутов (`RegisterRoutes`), хелперы сессий и страниц (`getSession`, `getUser`, `serveMapFrontend`, `CleanChars`).
- **api.go** — HTTP API: авторизация (login, me, logout, setup), кабинет (tokens, password), админ (users, settings, maps, wipe, rebuildZooms, export, merge), редиректы и роутер `/map/api/...`.
- **admin.go** — админка: HTML-страницы и действия (wipe, setPrefix, setDefaultHide, setTitle, rebuildZooms, export, merge, adminMap, wipeTile, setCoords, hideMarker и т.д.).
- **client.go** — хендлеры клиента маппера (`/client/{token}/...`): locate, gridUpdate, gridUpload, positionUpdate, markerUpdate, updateZoomLevel.
- **app.go** — структура `App`, общие типы (`Character`, `Session`, `Coord`, `Position`, `Marker`, `User`, `MapInfo`, `GridData` и т.д.), регистрация маршрутов (`RegisterRoutes`), `serveMapFrontend`, `CleanChars`.
- **auth.go** — сессии и авторизация: `getSession`, `deleteSession`, `saveSession`, `getUser`, `getPage`, `createSession`, `setupRequired`, `requireAdmin`.
- **api.go** — HTTP API: авторизация (login, me, logout, setup), кабинет (tokens, password), админ (users, settings, maps, wipe, rebuildZooms, export, merge), роутер `/map/api/...`.
- **handlers_redirects.go** — редиректы: `/``/map/profile` или `/map/setup`, `/login``/map/login`, `/logout``/map/login`, `/admin``/map/admin`.
- **client.go** — роутер клиента маппера (`/client/{token}/...`), `locate`.
- **client_grid.go** — `gridUpdate`, `gridUpload`, `updateZoomLevel`.
- **client_positions.go** — `updatePositions`.
- **client_markers.go** — `uploadMarkers`.
- **admin_rebuild.go** — `doRebuildZooms`.
- **admin_tiles.go** — `wipeTile`, `setCoords`.
- **admin_markers.go** — `hideMarker`.
- **admin_export.go** — `export`.
- **admin_merge.go** — `merge`.
- **map.go** — доступ к карте: `canAccessMap`, `getChars`, `getMarkers`, `getMaps`, `config`.
- **tile.go** — тайлы и гриды: `GetTile`, `SaveTile`, `watchGridUpdates` (SSE), `gridTile`, `reportMerge`.
- **topic.go** — типы `topic` и `mergeTopic` для рассылки обновлений тайлов и слияний карт.
- **manage.go** — страницы управления: index, login, logout, generateToken, changePassword.
- **migrations.go** — миграции bbolt; из main вызывается `app.RunMigrations(db)`.
- **webapp/** — отдельный пакет в корне репозитория: загрузка и выполнение HTML-шаблонов. Импортируется из `cmd/hnh-map` и из `internal/app`.
Сборка из корня репозитория:
```bash

View File

@@ -17,7 +17,7 @@ go build -o hnh-map ./cmd/hnh-map
go run ./cmd/hnh-map -grids=./grids -port=8080
```
Сервер будет отдавать статику из каталога `frontend/` (нужно предварительно собрать фронт, см. ниже). HTML-шаблоны встроены в бинарник (пакет webapp).
Сервер будет отдавать статику из каталога `frontend/` (нужно предварительно собрать фронт, см. ниже).
### Фронтенд (Nuxt)