Add initial project structure with backend and frontend setup

- Created backend structure with Go, including main application logic and API endpoints. - Added Docker support for both development and production environments. - Introduced frontend using Nuxt 3 with Tailwind CSS for styling. - Included configuration files for Docker and environment variables. - Established basic documentation for contributing, development, and deployment processes. - Set up .gitignore and .dockerignore files to manage ignored files in the repository.
2026-02-24 22:27:05 +03:00
commit 605a31567e
97 changed files with 18350 additions and 0 deletions
--- a/docs/api.md
+++ b/docs/api.md
@@ -0,0 +1,51 @@
+# HTTP API
+
+API доступно по префиксу `/map/api/`. Для запросов, требующих авторизации, используется cookie `session` (устанавливается при логине).
+
+## Авторизация
+
+- **POST /map/api/login** — вход. Тело: `{"user":"...","pass":"..."}`. При успехе возвращается JSON с данными пользователя и выставляется cookie сессии. При первом запуске возможен bootstrap: логин `admin` и пароль из `HNHMAP_BOOTSTRAP_PASSWORD` создают первого админа.
+- **GET /map/api/me** — текущий пользователь (по сессии). Ответ: `username`, `auths`, при необходимости `tokens`, `prefix`.
+- **POST /map/api/logout** — выход (инвалидация сессии).
+- **GET /map/api/setup** — проверка, нужна ли первичная настройка. Ответ: `{"setupRequired": true|false}`.
+
+## Кабинет
+
+- **POST /map/api/me/tokens** — сгенерировать новый токен загрузки (требуется право `upload`). Ответ: `{"tokens": ["...", ...]}`.
+- **POST /map/api/me/password** — сменить пароль. Тело: `{"pass":"..."}`.
+
+## Карта и данные
+
+- **GET /map/api/config** — конфиг для клиента (title, auths). Требуется сессия.
+- **GET /map/api/v1/characters** — список персонажей на карте (требуется право `map` и при необходимости `markers`).
+- **GET /map/api/v1/markers** — маркеры (требуется право `map` и при необходимости `markers`).
+- **GET /map/api/maps** — список карт (с учётом прав и скрытых карт).
+
+## Админ (все эндпоинты ниже требуют право `admin`)
+
+- **GET /map/api/admin/users** — список имён пользователей.
+- **POST /map/api/admin/users** — создать/обновить пользователя. Тело: `{"user":"...","pass":"...","auths":["admin","map",...]}`.
+- **GET /map/api/admin/users/:name** — данные пользователя.
+- **DELETE /map/api/admin/users/:name** — удалить пользователя.
+- **GET /map/api/admin/settings** — настройки (prefix, defaultHide, title).
+- **POST /map/api/admin/settings** — сохранить настройки. Тело: `{"prefix":"...","defaultHide":true|false,"title":"..."}` (поля опциональны).
+- **GET /map/api/admin/maps** — список карт для админки.
+- **POST /map/api/admin/maps/:id** — обновить карту (name, hidden, priority).
+- **POST /map/api/admin/maps/:id/toggle-hidden** — переключить скрытие карты.
+- **POST /map/api/admin/wipe** — очистить гриды, маркеры, тайлы, карты в БД.
+- **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`.
+
+## Коды ответов
+
+- **200** — успех.
+- **400** — неверный запрос (метод, тело, параметры).
+- **401** — не авторизован (нет или недействительная сессия).
+- **403** — нет прав.
+- **404** — не найдено.
+- **500** — внутренняя ошибка.
+
+Формат ошибок — текст в теле ответа или стандартные HTTP-статусы без тела.
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -0,0 +1,40 @@
+# Архитектура hnh-map
+
+## Обзор
+
+hnh-map — сервер автомаппера для HnH: Go-бэкенд с хранилищем bbolt, сессиями, HTML-шаблонами и 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 — рендер шаблонов            │
+                                  └──────────────────────────────────────┘
+```
+
+## Структура бэкенда
+
+- **cmd/hnh-map/main.go** — единственная точка входа (`package main`): парсинг флагов (`-grids`, `-port`) и переменных окружения (`HNHMAP_PORT`), открытие bbolt, запуск миграций, создание `App`, регистрация маршрутов, запуск HTTP-сервера. Пути к `frontend/` и `public/` задаются из рабочей директории при старте; шаблоны встроены в бинарник (webapp, `//go:embed`).
+
+- **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.
+  - **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
+go build -o hnh-map ./cmd/hnh-map
+```
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -0,0 +1,27 @@
+# Настройка
+
+## Переменные окружения и флаги
+
+| Переменная / флаг | Описание | По умолчанию |
+|-------------------|----------|--------------|
+| `HNHMAP_PORT` | Порт HTTP-сервера | 8080 |
+| `-port` | То же (флаг командной строки) | значение `HNHMAP_PORT` или 8080 |
+| `HNHMAP_BOOTSTRAP_PASSWORD` | Пароль для первой настройки: при отсутствии пользователей вход как `admin` с этим паролем создаёт первого админа | — |
+| `-grids` | Каталог гридов (флаг командной строки; в Docker обычно `-grids=/map`) | `grids` |
+
+Пример для первого запуска:
+
+```bash
+export HNHMAP_BOOTSTRAP_PASSWORD=your-secure-password
+./hnh-map -grids=./grids -port=8080
+```
+
+В Docker часто монтируют том в `/map` и запускают с `-grids=/map`.
+
+Для фронта (Nuxt) в режиме разработки:
+
+| Переменная | Описание |
+|------------|----------|
+| `NUXT_PUBLIC_API_BASE` | Базовый путь к API (например `/map/api` при прокси к бэкенду) |
+
+См. также [.env.example](../.env.example) в корне репозитория.
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -0,0 +1,31 @@
+# Деплой
+
+## Docker
+
+Образ собирается из репозитория. Внутри контейнера приложение слушает порт **8080** и ожидает, что каталог данных смонтирован в `/map` (база и изображения гридов).
+
+Пример запуска:
+
+```bash
+docker run -v /srv/hnh-map:/map -p 80:8080 andyleap/hnh-auto-mapper:v-4
+```
+
+Или с переменными:
+
+```bash
+docker run -v /srv/hnh-map:/map -p 8080:8080 \
+  -e HNHMAP_PORT=8080 \
+  -e HNHMAP_BOOTSTRAP_PASSWORD=your-secure-password \
+  andyleap/hnh-auto-mapper:v-4
+```
+
+Рекомендуется после первой настройки убрать или не передавать `HNHMAP_BOOTSTRAP_PASSWORD`.
+
+## Reverse proxy
+
+Разместите сервис за nginx, Traefik, Caddy и т.п. на нужном домене. Проксируйте весь трафик на порт 8080 контейнера (или тот порт, на котором слушает приложение). Отдельная настройка для `/map` не обязательна: приложение само отдаёт SPA и API по путям `/map/`, `/map/api/`, `/map/updates`, `/map/grids/`.
+
+## Обновление и бэкапы
+
+- При обновлении образа сохраняйте volume с `/map`: в нём лежат `grids.db` и каталоги с тайлами.
+- Регулярно делайте бэкапы каталога данных (и при необходимости экспорт через админку «Export»).
--- a/docs/development.md
+++ b/docs/development.md
@@ -0,0 +1,50 @@
+# Разработка
+
+## Локальный запуск
+
+### Бэкенд (Go)
+
+Из корня репозитория:
+
+```bash
+go build -o hnh-map ./cmd/hnh-map
+./hnh-map -grids=./grids -port=8080
+```
+
+Или без сборки:
+
+```bash
+go run ./cmd/hnh-map -grids=./grids -port=8080
+```
+
+Сервер будет отдавать статику из каталога `frontend/` (нужно предварительно собрать фронт, см. ниже). HTML-шаблоны встроены в бинарник (пакет webapp).
+
+### Фронтенд (Nuxt)
+
+```bash
+cd frontend-nuxt
+npm install
+npm run dev
+```
+
+В dev-режиме приложение доступно по адресу с baseURL `/map/` (например `http://localhost:3000/map/`). Бэкенд должен быть доступен; при необходимости настройте прокси в `nuxt.config.ts` (например на `http://localhost:8080`).
+
+### Docker Compose (разработка)
+
+```bash
+docker compose -f docker-compose.dev.yml up
+```
+
+- Фронт: порт **3000** (Nuxt dev-сервер).
+- Бэкенд: порт **3080** (чтобы не конфликтовать с другими сервисами на 8080).
+
+Откройте http://localhost:3000/map/. Запросы к `/map/api`, `/map/updates`, `/map/grids` проксируются на бэкенд (host `backend`, порт 3080).
+
+### Сборка образа и prod-композ
+
+```bash
+docker build -t hnh-map .
+docker compose -f docker-compose.prod.yml up -d
+```
+
+В prod фронт собран в образ и отдаётся бэкендом из каталога `frontend/`; порт 8080.