docs: перевести документацию на русский

2026-07-13 21:21:42 +03:00
parent d3be367910
commit 3ed29fa8e6
2 changed files with 158 additions and 128 deletions
--- a/README.md
+++ b/README.md
@@ -1,77 +1,79 @@
 # Mila

-Mila is a small Go library for BVK media-complex content exchange.
+Mila — небольшая Go-библиотека для обмена данными между БВК и
+медиакомплексом.

-It implements the HTTP protocol where BVK pushes the currently displayed
-content state to the media complex:
+Библиотека реализует HTTP-протокол, в котором БВК отправляет в медиакомплекс
+текущее состояние отображаемого контента:

 ```text
 GET /set-content?route=<R>&str=<S>&tpl_name=<T>
 GET /get-content
 ```

-The library intentionally does not know anything about snapshots, route
-progress, geolocation, frontend state, or media playback rules. It only parses,
-validates, stores, logs, and returns BVK content state.
+Mila намеренно не знает ничего про снапшоты, геопозицию, прогресс маршрута,
+фронтенд, правила воспроизведения медиа и структуру контента White Nights. Она
+только принимает, валидирует, сохраняет, логирует и возвращает состояние,
+полученное от БВК.

-## Install
+## Установка

 ```bash
 go get gitea.unprism.ru/KRBL/mila
 ```

-## Scope
+## Зона Ответственности

-Mila is a protocol library. It should be embedded into an application service,
-for example `wn-content`, and exposed on the address required by the transport
-integration.
+Mila — библиотека протокола. Ее нужно встраивать в прикладной сервис, например
+в `wn-content`, и открывать на адресе, который требуется транспортной
+интеграцией.

-Mila does:
+Mila делает:

- parse `GET /set-content`
- parse `GET /get-content`
- validate `route`, `str`, and `tpl_name`
- URL-decode query parameters through Go's standard HTTP parser
- store the latest state in memory or in a JSON file
- return protocol-compatible JSON
- log each HTTP request with method, path, status, remote address, and duration
- call an optional callback after successful `set-content`
+- разбирает `GET /set-content`;
+- разбирает `GET /get-content`;
+- валидирует `route`, `str` и `tpl_name`;
+- декодирует URL-параметры стандартным HTTP-парсером Go;
+- хранит последнее состояние в памяти или JSON-файле;
+- возвращает JSON, совместимый с протоколом;
+- логирует каждый HTTP-запрос: метод, путь, статус, удаленный адрес и время;
+- вызывает опциональный callback после успешного `set-content`.

-Mila does not:
+Mila не делает:

- calculate route progress
- work with geolocation or NMEA
- map `tpl_name` to real media playlists
- read or write snapshots
- communicate with frontend directly
- decide how content should be rendered
+- не считает прогресс маршрута;
+- не работает с геопозицией или NMEA;
+- не сопоставляет `tpl_name` с реальными плейлистами;
+- не читает и не пишет снапшоты;
+- не общается с фронтендом напрямую;
+- не решает, как именно должен отображаться контент.

-## Protocol
+## Протокол

-The media complex acts as an HTTP server. BVK acts as an HTTP client.
+Медиакомплекс выступает HTTP-сервером. БВК выступает HTTP-клиентом.

-Default address from the PDF:
+Адрес по документу:

 ```text
 172.16.16.2:13280
 ```

-Endpoints:
+Ручки:

 ```text
 GET /set-content?route=<R>&str=<S>&tpl_name=<T>
 GET /get-content
 ```

-`set-content` accepts URL-encoded query parameters:
+`set-content` принимает URL-encoded query-параметры:

-| Parameter | Required | Meaning |
+| Параметр | Обязательный | Описание |
 | --- | --- | --- |
-| `route` | yes | route number, default limit is 1-3 characters |
-| `str` | no | ticker/running text, default limit is 200 characters |
-| `tpl_name` | yes | media content template name, default limit is 200 characters |
+| `route` | да | номер маршрута, по умолчанию 1-3 символа |
+| `str` | нет | текст бегущей строки, по умолчанию до 200 символов |
+| `tpl_name` | да | название шаблона медиаконтента, по умолчанию до 200 символов |

-`get-content` response:
+Ответ `get-content`:

 ```json
 {
@@ -81,96 +83,101 @@ GET /get-content
 }
 ```

-`updated_at` is stored internally but is not exposed by `/get-content`, because
-the protocol response should stay strict.
+Поле `updated_at` хранится внутри состояния, но не отдается через
+`/get-content`, потому что ответ должен оставаться строгим относительно
+протокола.

-## Usage
+## Использование

 ```go
 package main

 import (
-    "log"
-    "net/http"
+	"log"
+	"net/http"

-    "gitea.unprism.ru/KRBL/mila"
+	"gitea.unprism.ru/KRBL/mila"
 )

 func main() {
-store := mila.NewFileStore("/srv/persistence/client_logs/bvk_content.json")
+	store := mila.NewFileStore("/srv/persistence/client_logs/bvk_content.json")

-handler := mila.NewHandler(mila.DefaultConfig(), store,
-    mila.WithOnSet(func(state mila.ContentState) {
-        // Application-specific integration goes here.
-    }),
-)
+	handler := mila.NewHandler(mila.DefaultConfig(), store,
+		mila.WithOnSet(func(state mila.ContentState) {
+			// Здесь прикладная интеграция:
+			// - передать route/str/tpl_name в состояние приложения;
+			// - сопоставить state.Template с локальным шаблоном;
+			// - записать дополнительные логи.
+		}),
+	)

-srv := &http.Server{
-    Addr:    "0.0.0.0:13280",
-    Handler: handler,
-}
+	srv := &http.Server{
+		Addr:    "0.0.0.0:13280",
+		Handler: handler,
+	}

-log.Fatal(srv.ListenAndServe())
+	log.Fatal(srv.ListenAndServe())
 }
 ```

-## Configuration
+## Конфигурация

-Default validation config:
+Конфигурация валидации по умолчанию:

 ```go
 cfg := mila.DefaultConfig()
 ```

-Which currently means:
+Сейчас это:

 ```go
 mila.Config{
-    MaxRouteLen:    3,
-    MaxTextLen:     200,
-    MaxTemplateLen: 200,
+	MaxRouteLen:    3,
+	MaxTextLen:     200,
+	MaxTemplateLen: 200,
 }
 ```

-The text/template limits should be confirmed with the integrator. The provided
-PDF has an ambiguous text layer for those values.
+Лимиты для `str` и `tpl_name` нужно подтвердить у интегратора. В переданном PDF
+текстовый слой неоднозначно распознает исходное значение.

-## Stores
+## Хранилища

-Use `MemoryStore` when state does not need to survive process restart:
+`MemoryStore` подходит, когда состояние не должно переживать рестарт процесса:

 ```go
 store := mila.NewMemoryStore()
 ```

-Use `FileStore` on a device when the latest BVK state should be persisted:
+`FileStore` подходит для устройства, если последнее состояние от БВК нужно
+сохранять на диске:

 ```go
 store := mila.NewFileStore("/srv/persistence/client_logs/bvk_content.json")
 ```

-`FileStore` writes atomically through a temporary file and keeps an in-memory
-copy after the first successful read or write.
+`FileStore` пишет состояние атомарно через временный файл и держит копию в
+памяти после первого успешного чтения или записи.

 ## Callback

-`WithOnSet` lets the host application react to a valid BVK update:
+`WithOnSet` позволяет приложению отреагировать на валидное обновление от БВК:

 ```go
 handler := mila.NewHandler(mila.DefaultConfig(), store,
-    mila.WithOnSet(func(state mila.ContentState) {
-        // Example host-side decisions:
-        // - publish route and ticker to frontend state
-        // - map state.Template to a local playlist/template
-        // - write application-specific logs
-    }),
+	mila.WithOnSet(func(state mila.ContentState) {
+		// Возможные действия на стороне приложения:
+		// - опубликовать номер маршрута и бегущую строку;
+		// - сопоставить state.Template с локальным плейлистом;
+		// - записать прикладные логи.
+	}),
 )
 ```

-The callback is intentionally synchronous. Keep it fast; if integration work is
-heavy, push the state into an internal queue.
+Callback выполняется синхронно. Его нужно держать быстрым. Если интеграционная
+логика тяжелая, лучше положить состояние во внутреннюю очередь.

-## State Model
+## Модель Состояния

 ```json
 {
@@ -181,29 +188,29 @@ heavy, push the state into an internal queue.
 }
 ```

-Go type:
+Go-тип:

 ```go
 type ContentState struct {
-    Route     string    `json:"route"`
-    Text      string    `json:"str"`
-    Template  string    `json:"tpl_name"`
-    UpdatedAt time.Time `json:"updated_at,omitempty"`
+	Route     string    `json:"route"`
+	Text      string    `json:"str"`
+	Template  string    `json:"tpl_name"`
+	UpdatedAt time.Time `json:"updated_at,omitempty"`
 }
 ```

-## Status Codes
+## Коды Ответов

-| Code | When |
+| Код | Когда возвращается |
 | ---: | --- |
-| 200 | valid `set-content` or ready `get-content` |
-| 400 | invalid request parameters |
-| 404 | unknown path |
-| 405 | method is not `GET` |
-| 500 | store/internal error |
-| 503 | `get-content` before first state, canceled/deadline context, unavailable dependency |
+| 200 | валидный `set-content` или готовый `get-content` |
+| 400 | невалидные параметры запроса |
+| 404 | неизвестный путь |
+| 405 | метод не `GET` |
+| 500 | ошибка хранилища или внутренняя ошибка |
+| 503 | `get-content` до первого состояния, отмененный контекст, недоступная зависимость |

-Error response:
+Формат ошибки:

 ```json
 {
@@ -211,17 +218,17 @@ Error response:
 }
 ```

-## Testing
+## Тестирование

 ```bash
 go test ./...
 ```

-Current tests cover:
+Текущие тесты покрывают:

- successful `set-content` + `get-content`
- `get-content` before state is ready
- invalid route validation
- UTF-8 text/template validation
- file store persistence
- missing file store state
+- успешный `set-content` + `get-content`;
+- `get-content` до готовности состояния;
+- невалидный `route`;
+- UTF-8 и лимиты для текста/шаблона;
+- сохранение и чтение через `FileStore`;
+- отсутствие файла состояния в `FileStore`.