# Архитектура hnh-map

## Обзор

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/     │  • Статика фронта (frontend/)           │
└─────────────┘                   │  • internal/app — вся логика            │
                                  └──────────────────────────────────────┘
```

## Структура бэкенда

- **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`), `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` для рассылки обновлений тайлов и слияний карт.
  - **migrations.go** — миграции bbolt; из main вызывается `app.RunMigrations(db)`.

Сборка из корня репозитория:

```bash
go build -o hnh-map ./cmd/hnh-map
```