addrkit/README.md

addrkit

Детерминированный сервис нормализации и поиска адресов с подключаемым внешним слоем отключений. Разбирает вольные реплики (дроби, литеры, корпуса, строения, опечатки), сопоставляет их с каноническим реестром и отдаёт ответ только из данных — LLM не участвует в пути корректности.

Проект на Go, живёт офлайн (один статический бинарь + SQLite), без MCP в рантайме.

Зачем

Существующая логика поиска адреса в диалоговом сценарии страдала от нечёткого поиска по всей строке (fuzziness: AUTO, size:1), из-за чего дробь/корпус/литера могли дать неверный дом. addrkit разделяет задачу на компоненты, сопоставляет дом строго и вместо угадывания возвращает явный статус (partial/ambiguous).

Архитектура

Гексагональная: домен чистый и без I/O, всё внешнее — в адаптерах.

cmd/addrkitd            сервис (HTTP)
cmd/addrkit             CLI: seed | verify | resolve
internal/
  domain/address        нормализация и разбор адреса (чистые функции)
  domain/match          сопоставление с индексом, статусы
  domain/outages        выборка отключений по дому (чистая логика)
  adapters/registrystore SQLite (modernc, без CGO)
  adapters/arcgis       клиент портала (timeout/retry)
  adapters/llm          опциональный rewriter (OpenAI-совместимый)
  adapters/httpapi      версионированный JSON API
  config                конфиг + ${VAR}
  seed                  сборка индекса из дампа реестра

Поток запроса:

"2-я Станционная улица 1/1 стр."
   -> address.Parse  -> {ordinal:2, name:станционная, house:1, frac:1}
   -> match.Resolve  -> exact street -> exact house -> FOUND
   -> (опц.) outages.Source -> фильтр по дому -> ответ

Быстрый старт

make build

# 1. Собрать индекс из дампа реестра (Bulk NDJSON или JSONL).
./bin/addrkit seed -in registry.ndjson -out registry.db -version 2026-10-01

# 2. Запустить сервис.
cp config.example.json config.json
ADDRKIT_PORTAL_URL='https://map.example/.../101/query' ./bin/addrkitd -config config.json

# 3. Проверить.
curl -s localhost:6171/v1/resolve -d '{"address":"2-я Станционная улица 1/1 стр."}'
curl -s localhost:6171/v1/outages -d '{"address":"станционная 30а к9/1"}'

CLI без сервиса:

./bin/addrkit resolve -db registry.db "кошурникова 11/1"
./bin/addrkit verify  -db registry.db

API v1

Метод	Путь	Назначение
POST	/v1/resolve	адрес → {status, address, district, confidence, candidates[]}
POST	/v1/outages	адрес → канонический адрес + отключения по дому
GET	/v1/healthz	живость
GET	/v1/readyz	готовность (индекс загружен)
GET	/v1/version	версия данных

Статусы: found, partial, ambiguous, not_found, portal_timeout, infra_error.

Конфигурация

config.json (см. config.example.json). Значения поддерживают ${VAR}; незаданная переменная = ошибка запуска (fail closed). Секреты — только из окружения.

Принятые решения

• Детерминизм. Один вход — один выход, порядок кандидатов стабилен. resolve не зависит от сети.
• Дом сравнивается строго. Литера/дробь/корпус должны совпасть; иначе partial, а не «похожий» дом.
• LLM — опция, выключена по умолчанию. adapters/llm лишь предлагает варианты записи адреса; результат всегда берётся из реестра, поэтому модель не может «выдумать» адрес.
• Данные. Сервис владеет своим индексом, построенным из дампа реестра. Источник истины и регламент обновления — предмет отдельного согласования.
• Часовой пояс. Даты отключений трактуются в Asia/Novosibirsk (UTC+7).

Тесты

make test          # go test -race ./...

Проверка парсера на реальном реестре (вне репозитория):

ADDRKIT_REGISTRY=/path/to/address_registry.ndjson \
  go test ./internal/seed -run TestRealRegistryParseRate -v

На дампе из 73 936 строк парсер распознаёт 99.98 % (14 строк — заведомо битые форматы; они не угадываются, а попадают в отчёт stats.unparsed_sample).