Add configuration files and update project documentation
- Introduced .editorconfig for consistent coding styles across the project. - Added .golangci.yml for Go linting configuration. - Updated AGENTS.md to clarify project structure and components. - Enhanced CONTRIBUTING.md with Makefile usage for common tasks. - Updated Dockerfiles to use Go 1.24 and improved build instructions. - Refined README.md and deployment documentation for clarity. - Added testing documentation in testing.md for backend and frontend tests. - Introduced Makefile for streamlined development commands and tasks.
This commit is contained in:
@@ -1,43 +1,57 @@
|
||||
# Архитектура hnh-map
|
||||
# Architecture of hnh-map
|
||||
|
||||
## Обзор
|
||||
## Overview
|
||||
|
||||
hnh-map — сервер автомаппера для HnH: Go-бэкенд с хранилищем bbolt, сессиями и Nuxt 3 SPA по корню `/`. API, SSE и тайлы — по `/map/api/`, `/map/updates`, `/map/grids/`. Данные гридов и тайлов хранятся в каталоге `grids/` и в БД.
|
||||
hnh-map is an automapper server for HnH: a Go backend with bbolt storage, sessions, and a Nuxt 3 SPA served at `/`. API, SSE, and tiles are served at `/map/api/`, `/map/updates`, `/map/grids/`. Grid and tile data is stored in the `grids/` directory and in the database.
|
||||
|
||||
```
|
||||
┌─────────────┐ HTTP/SSE ┌──────────────────────────────────────┐
|
||||
│ Браузер │ ◄────────────────► │ Go-сервер (cmd/hnh-map) │
|
||||
│ (Nuxt SPA │ /, /login, │ • bbolt (users, sessions, grids, │
|
||||
│ по /) │ /map/api, │ markers, tiles, maps, config) │
|
||||
│ │ /map/updates, │ • Статика фронта (frontend/) │
|
||||
│ │ /map/grids/ │ • internal/app — вся логика │
|
||||
│ Browser │ ◄────────────────► │ Go server (cmd/hnh-map) │
|
||||
│ (Nuxt SPA │ /, /login, │ • bbolt (users, sessions, grids, │
|
||||
│ at /) │ /map/api, │ markers, tiles, maps, config) │
|
||||
│ │ /map/updates, │ • Frontend statics (frontend/) │
|
||||
│ │ /map/grids/ │ • internal/app — all logic │
|
||||
└─────────────┘ └──────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Структура бэкенда
|
||||
## Backend structure
|
||||
|
||||
- **cmd/hnh-map/main.go** — единственная точка входа (`package main`): парсинг флагов (`-grids`, `-port`) и переменных окружения (`HNHMAP_PORT`), открытие bbolt, запуск миграций, создание `App`, регистрация маршрутов, запуск HTTP-сервера. Пути к `frontend/` и `public/` задаются из рабочей директории при старте.
|
||||
The backend follows a layered architecture: **Store → Services → Handlers**.
|
||||
|
||||
- **internal/app/** — пакет `app` с типом `App` и всей логикой:
|
||||
- **app.go** — структура `App`, общие типы (`Character`, `Session`, `Coord`, `Position`, `Marker`, `User`, `MapInfo`, `GridData` и т.д.), регистрация маршрутов (`RegisterRoutes`), `serveSPARoot`, `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** — редирект `/logout` → `/login` (после удаления сессии).
|
||||
- **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)`.
|
||||
- **cmd/hnh-map/main.go** — the single entry point (`package main`): parses flags (`-grids`, `-port`) and environment variables (`HNHMAP_PORT`), opens bbolt, runs migrations, creates `App`, wires services and handlers, registers routes, and starts the HTTP server. Paths to `frontend/` and `public/` are resolved relative to the working directory at startup.
|
||||
|
||||
Сборка из корня репозитория:
|
||||
- **internal/app/** — package `app` with the `App` type and domain types:
|
||||
- **app.go** — `App` struct, domain types (`Character`, `Session`, `Coord`, `Position`, `Marker`, `User`, `MapInfo`, `GridData`, etc.), SPA serving (`ServeSPARoot`), character cleanup (`CleanChars`), constants.
|
||||
- **router.go** — route registration (`Router`), interface `APIHandler`.
|
||||
- **topic.go** — generic `Topic[T]` pub/sub for broadcasting tile and merge updates.
|
||||
- **migrations.go** — bbolt schema migrations; called from main via `RunMigrations(db)`.
|
||||
|
||||
- **internal/app/store/** — database access layer:
|
||||
- **db.go** — `Store` struct with bucket helpers and CRUD operations for users, sessions, tokens, config, maps, grids, tiles, markers, and OAuth states.
|
||||
- **buckets.go** — bucket name constants.
|
||||
|
||||
- **internal/app/services/** — business logic layer:
|
||||
- **auth.go** — `AuthService`: authentication, sessions, password hashing, token validation, OAuth (Google) login flow.
|
||||
- **map.go** — `MapService`: map data retrieval, tile save/get, zoom level processing, SSE watch, character/marker access.
|
||||
- **admin.go** — `AdminService`: user management, settings, map management, wipe, tile operations.
|
||||
- **client.go** — `ClientService`: game client operations (grid update, grid upload, position updates, marker uploads).
|
||||
- **export.go** — `ExportService`: data export (ZIP) and merge (import).
|
||||
|
||||
- **internal/app/handlers/** — HTTP handlers (thin layer over services):
|
||||
- **handlers.go** — `Handlers` struct (dependency container), `HandleServiceError`.
|
||||
- **response.go** — JSON response helpers.
|
||||
- **api.go** — top-level API router (`APIRouter`).
|
||||
- **auth.go** — login, logout, me, setup, OAuth, token, and password handlers.
|
||||
- **map.go** — config, characters, markers, and maps handlers.
|
||||
- **client.go** — game client HTTP handlers (grid update/upload, positions, markers).
|
||||
- **admin.go** — admin HTTP handlers (users, settings, maps, wipe, tile ops, export, merge).
|
||||
- **tile.go** — tile image serving and SSE endpoint.
|
||||
|
||||
- **internal/app/apperr/** — domain error types mapped to HTTP status codes by handlers.
|
||||
|
||||
- **internal/app/response/** — shared JSON response utilities.
|
||||
|
||||
Build from the repository root:
|
||||
|
||||
```bash
|
||||
go build -o hnh-map ./cmd/hnh-map
|
||||
|
||||
Reference in New Issue
Block a user