Main.java

/*
 * Клиент API обратного геокодинга Atlorium — адрес по координатам.
 *
 * Запуск (работает сразу, без регистрации — на демо-ключе).
 * Начиная с Java 11 файл запускается напрямую, без компиляции и без зависимостей:
 *
 *     java Main.java 55.788226 49.121984
 *
 * Боевой ключ: получить на https://atlorium.com и положить в переменную окружения
 * ATLORIUM_API_KEY. Код при этом не меняется.
 */

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class Main {

    /**
     * Публичный демо-ключ. С ним API отвечает МОКАМИ (не данными реестра) — чтобы
     * можно было встроить и протестировать интеграцию до оплаты. Ответы
     * детерминированы: один и тот же запрос всегда даёт один и тот же результат,
     * поэтому на них можно писать стабильные тесты.
     */
    static final String SANDBOX_KEY = "ak_sandbox_demo_mockdata_v1";

    static final String API_KEY = envOr("ATLORIUM_API_KEY", SANDBOX_KEY);
    static final String BASE_URL = envOr("ATLORIUM_BASE_URL", "https://atlorium.com");

    static final HttpClient CLIENT = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(30))
            .build();

    static String envOr(String key, String fallback) {
        String value = System.getenv(key);
        return (value == null || value.isEmpty()) ? fallback : value;
    }

    /** Ошибка API: HTTP-код разложен в человекочитаемую причину. */
    static class AtloriumException extends RuntimeException {
        private static final Map<Integer, String> REASONS = new HashMap<Integer, String>();

        static {
            REASONS.put(400, "Координаты вне допустимого диапазона либо радиус ориентиров больше предельного");
            REASONS.put(401, "API-ключ отсутствует, просрочен или недействителен");
            REASONS.put(402, "Недостаточно кредитов на балансе — пополните на https://atlorium.com");
            REASONS.put(404, "Рядом с точкой нет адресных объектов (такой ответ не тарифицируется)");
            REASONS.put(429, "Превышен лимит запросов — повторите позже");
            REASONS.put(503, "Геокодер временно недоступен (за сбой на своей стороне мы не списываем деньги)");
        }

        final int status;

        AtloriumException(int status, String body) {
            super("HTTP " + status + ": "
                    + REASONS.getOrDefault(status, "Неизвестная ошибка")
                    + ". Ответ сервера: " + body.substring(0, Math.min(200, body.length())));
            this.status = status;
        }
    }

    static String get(String path, String query) throws IOException, InterruptedException {
        HttpRequest request = HttpRequest.newBuilder(URI.create(BASE_URL + path + "?" + query))
                .header("Authorization", "Bearer " + API_KEY)
                .header("Accept", "application/json")
                .timeout(Duration.ofSeconds(30))
                .GET()
                .build();

        HttpResponse<byte[]> response = CLIENT.send(request, HttpResponse.BodyHandlers.ofByteArray());
        String body = new String(response.body(), StandardCharsets.UTF_8);
        if (response.statusCode() != 200) {
            throw new AtloriumException(response.statusCode(), body);
        }
        return body;
    }

    // ── Вызовы API ───────────────────────────────────────────────────────────

    /**
     * Адрес по координатам. Базовый ответ — один ближайший адресный объект и
     * расстояние до него. Каждое из трёх обогащений включается своим параметром и
     * стоит ещё одну единицу работы — но только если действительно вернуло данные.
     */
    static String reverse(double lat, double lon,
                          boolean includeNeighbors, boolean includeAdmin, boolean includeNearby,
                          int neighborsSize, double nearbyRadiusKm, int nearbySize)
            throws IOException, InterruptedException {
        String query = "lat=" + number(lat)
                + "&lon=" + number(lon)
                + "&includeNeighbors=" + includeNeighbors
                + "&neighborsSize=" + neighborsSize
                + "&includeAdmin=" + includeAdmin
                + "&includeNearby=" + includeNearby
                + "&nearbyRadiusKm=" + number(nearbyRadiusKm)
                + "&nearbySize=" + nearbySize;
        return get("/api/geocodereverse", query);
    }

    /**
     * Что рядом: ориентиры вокруг точки — магазины, аптеки, остановки, заправки.
     * Это НЕ перечисление соседних домов: соседние дома — обогащение обратного
     * геокодинга (includeNeighbors), и стоит оно по-другому.
     */
    static String nearby(double lat, double lon, double radiusKm, int size)
            throws IOException, InterruptedException {
        return get("/api/geocodereverse/nearby",
                "lat=" + number(lat) + "&lon=" + number(lon)
                        + "&radiusKm=" + number(radiusKm) + "&size=" + size);
    }

    /**
     * Числа в строке запроса печатаются с явной локалью ROOT: на машине с русской
     * локалью дробный разделитель по умолчанию — запятая, и сервер получил бы
     * «55,788226» вместо координаты.
     */
    static String number(double value) {
        String text = String.format(Locale.ROOT, "%.6f", value);
        text = text.replaceAll("0+$", "");
        return text.endsWith(".") ? text.substring(0, text.length() - 1) : text;
    }

    // ── Разбор JSON ──────────────────────────────────────────────────────────
    // Пример намеренно оставлен без внешних зависимостей, чтобы запускаться одной
    // командой `java Main.java`. В рабочем проекте берите Jackson или Gson и
    // маппьте ответ в полноценные классы — разбор ниже существует только ради
    // отсутствия pom.xml.

    static String str(String json, String field) {
        if (json == null) return null;
        Matcher matcher = Pattern.compile("\"" + field + "\"\\s*:\\s*\"((?:[^\"\\\\]|\\\\.)*)\"").matcher(json);
        return matcher.find() ? matcher.group(1).replace("\\\"", "\"") : null;
    }

    static Double number(String json, String field) {
        if (json == null) return null;
        Matcher matcher = Pattern.compile("\"" + field + "\"\\s*:\\s*(-?\\d+(?:\\.\\d+)?)").matcher(json);
        return matcher.find() ? Double.valueOf(matcher.group(1)) : null;
    }

    static int intOf(String json, String field) {
        Double value = number(json, field);
        return value == null ? 0 : value.intValue();
    }

    /**
     * Возвращает содержимое вложенного объекта или массива по имени поля, считая
     * скобки. Регулярным выражением такое не берётся: во вложенном объекте свои
     * скобки, и «до первой закрывающей» обрезало бы его посередине.
     */
    static String block(String json, String field, char open, char close) {
        if (json == null) return null;

        int key = json.indexOf("\"" + field + "\"");
        if (key < 0) return null;

        int start = json.indexOf(open, key);
        if (start < 0) return null;

        // Поле может быть равно null — тогда открывающая скобка принадлежит уже
        // следующему полю, и брать её нельзя.
        String between = json.substring(key + field.length() + 2, start);
        if (between.contains("null")) return null;

        int depth = 0;
        boolean inString = false;
        boolean escaped = false;

        for (int i = start; i < json.length(); i++) {
            char symbol = json.charAt(i);

            if (escaped) {
                escaped = false;
                continue;
            }
            if (symbol == '\\') {
                escaped = true;
                continue;
            }
            if (symbol == '"') {
                inString = !inString;
                continue;
            }
            if (inString) continue;

            if (symbol == open) depth++;
            else if (symbol == close && --depth == 0) return json.substring(start + 1, i);
        }
        return null;
    }

    /** Разбивает содержимое массива на объекты верхнего уровня. */
    static List<String> objects(String arrayBody) {
        List<String> result = new ArrayList<String>();
        if (arrayBody == null) return result;

        int depth = 0;
        int start = -1;
        boolean inString = false;
        boolean escaped = false;

        for (int i = 0; i < arrayBody.length(); i++) {
            char symbol = arrayBody.charAt(i);

            if (escaped) {
                escaped = false;
                continue;
            }
            if (symbol == '\\') {
                escaped = true;
                continue;
            }
            if (symbol == '"') {
                inString = !inString;
                continue;
            }
            if (inString) continue;

            if (symbol == '{') {
                if (depth == 0) start = i;
                depth++;
            } else if (symbol == '}' && --depth == 0 && start >= 0) {
                result.add(arrayBody.substring(start, i + 1));
            }
        }
        return result;
    }

    // ── Применение данных: годится ли точка как адрес доставки ───────────────
    // Координата из мобильного приложения почти никогда не стоит ровно на здании.
    // Практический вопрос — можно ли считать найденный адрес адресом клиента, или
    // курьеру придётся звонить. Отвечают на него три величины: расстояние до
    // ближайшего объекта, разрыв до следующего дома и наличие ориентиров рядом.

    static final String CONFIRMED = "CONFIRMED"; // адрес можно принимать как есть
    static final String AMBIGUOUS = "AMBIGUOUS"; // точка между домами — нужен выбор человеком
    static final String TOO_FAR = "TOO_FAR";     // рядом со зданиями точки нет

    /** Порог «точка стоит на здании». 50 м — обычная погрешность бытового GPS в городе. */
    static final double ON_BUILDING_KM = 0.05;
    /** Дальше этого адрес считается не адресом точки, а «ближайшим, что нашлось». */
    static final double MAX_USABLE_KM = 0.15;
    /** Если следующий дом ближе этого разрыва, выбор между ними произволен. */
    static final double AMBIGUITY_GAP_KM = 0.03;

    /** Вердикт о точке и то, что пригодится курьеру. */
    static class DeliveryPoint {
        String decision = CONFIRMED;
        final List<String> reasons = new ArrayList<String>();
        String courierHint;
        String serviceArea;
        final List<String> notes = new ArrayList<String>();
    }

    /** Расстояние в метрах: в заявке курьера километры с тремя знаками нечитаемы. */
    static String metres(Double distanceKm) {
        if (distanceKm == null) return "неизвестно";
        return Math.round(distanceKm * 1000) + " м";
    }

    /** Выносит вердикт о точке и собирает то, что пригодится курьеру. */
    static DeliveryPoint describeDeliveryPoint(String response) {
        String address = block(response, "address", '{', '}');
        Double distance = number(address, "distanceKm");

        DeliveryPoint result = new DeliveryPoint();

        if (distance == null) {
            result.decision = AMBIGUOUS;
            result.reasons.add("Сервис не вернул расстояние до объекта");
        } else if (distance > MAX_USABLE_KM) {
            result.decision = TOO_FAR;
            result.reasons.add("До ближайшего адресного объекта " + metres(distance) + " — точка не у здания");
        } else if (distance > ON_BUILDING_KM) {
            result.decision = AMBIGUOUS;
            result.reasons.add("До ближайшего адресного объекта " + metres(distance) + " — точка рядом, но не на здании");
        } else {
            result.reasons.add("Точка стоит на доме: до ближайшего адреса " + metres(distance));
        }

        // Соседние дома отвечают на вопрос «а не соседнее ли это здание». Если разрыв
        // между первым и вторым домом меньше погрешности, автоматический выбор спорный.
        List<String> neighbors = objects(block(response, "neighbors", '[', ']'));
        if (!neighbors.isEmpty() && distance != null) {
            String nearest = neighbors.get(0);
            Double nearestDistance = number(nearest, "distanceKm");
            if (nearestDistance != null) {
                double gap = nearestDistance - distance;
                if (gap < AMBIGUITY_GAP_KM) {
                    if (CONFIRMED.equals(result.decision)) result.decision = AMBIGUOUS;
                    result.reasons.add("Соседний дом " + str(nearest, "houseNumber")
                            + " всего на " + metres(gap) + " дальше — выбор спорный");
                }
            }
        }

        // Ориентир рядом с точкой стоит в курьерской заявке дороже любого поля адреса:
        // именно по нему адрес находят на месте.
        List<String> places = objects(block(response, "nearby", '[', ']'));
        if (!places.isEmpty()) {
            String landmark = places.get(0);
            result.courierHint = "рядом " + str(landmark, "name")
                    + " (" + str(landmark, "kind") + ", " + metres(number(landmark, "distanceKm")) + ")";
        }

        // ВАЖНО: adminAreas — это НЕ иерархия найденного дома. Дом «числится» по
        // реестру (поле admin внутри address), а adminAreas считается попаданием точки
        // в полигон границы. Для дома в городе ответы совпадают, для точки в поле —
        // расходятся, и это содержательное расхождение, а не ошибка.
        List<String> areas = objects(block(response, "adminAreas", '[', ']'));
        if (!areas.isEmpty()) {
            List<String> parts = new ArrayList<String>();
            for (int i = 0; i < Math.min(2, areas.size()); i++) {
                parts.add((str(areas.get(i), "kind") + " " + str(areas.get(i), "name")).trim());
            }
            result.serviceArea = String.join(" / ", parts);
        }

        String notice = str(response, "nearbyCompletenessNotice");
        if (notice != null) result.notes.add(notice);

        return result;
    }

    // ── Печать ───────────────────────────────────────────────────────────────

    public static void main(String[] args) throws Exception {
        if (API_KEY.equals(SANDBOX_KEY)) {
            System.out.println("Демо-ключ: ответы сгенерированы (моки), не данные реестра.\n");
        }

        double lat = args.length > 1 ? Double.parseDouble(args[0]) : 55.788226;
        double lon = args.length > 1 ? Double.parseDouble(args[1]) : 49.121984;

        String result;
        try {
            // Просим все три обогащения сразу: так видно, из чего складывается счёт.
            result = reverse(lat, lon, true, true, true, 5, 1.0, 10);
        } catch (AtloriumException error) {
            System.err.println("Ошибка: " + error.getMessage());
            System.exit(1);
            return;
        }

        System.out.println("Точка: " + number(lat) + ", " + number(lon) + "\n");

        String address = block(result, "address", '{', '}');
        System.out.println("Ближайший адрес: " + str(address, "label"));
        System.out.println("  precision=" + str(address, "precision")
                + " · до объекта " + metres(number(address, "distanceKm"))
                + " · placeId " + str(address, "placeId"));

        String admin = block(address, "admin", '{', '}');
        List<String> hierarchy = new ArrayList<String>();
        for (String key : new String[] { "region", "county", "locality", "street" }) {
            String value = str(admin, key);
            if (value != null) hierarchy.add(value);
        }
        System.out.println("  Реестровая иерархия (где дом ЧИСЛИТСЯ): " + String.join(" · ", hierarchy));

        List<String> neighbors = objects(block(result, "neighbors", '[', ']'));
        if (!neighbors.isEmpty()) {
            System.out.println("\nСоседние дома (точка может стоять между зданиями):");
            for (String item : neighbors) {
                System.out.println("  " + str(item, "street") + ", " + str(item, "houseNumber")
                        + " — " + metres(number(item, "distanceKm")));
            }
        }

        List<String> areas = objects(block(result, "adminAreas", '[', ']'));
        if (!areas.isEmpty()) {
            System.out.println("\nАдминистративная принадлежность (где точка ЛЕЖИТ, расчёт по границам):");
            for (String area : areas) {
                System.out.println("  уровень " + intOf(area, "level") + ": "
                        + str(area, "kind") + " " + str(area, "name")
                        + " [" + str(area, "certainty") + "]");
            }
        }

        List<String> places = objects(block(result, "nearby", '[', ']'));
        if (!places.isEmpty()) {
            System.out.println("\nОриентиры вокруг:");
            for (String place : places) {
                System.out.println("  " + str(place, "name") + " (" + str(place, "kind") + ") — "
                        + metres(number(place, "distanceKm")));
            }
        }

        DeliveryPoint verdict = describeDeliveryPoint(result);
        System.out.println("\n[" + verdict.decision + "] " + String.join("; ", verdict.reasons));
        if (verdict.courierHint != null) {
            System.out.println("  Подсказка курьеру: " + verdict.courierHint);
        }
        if (verdict.serviceArea != null) {
            System.out.println("  Зона обслуживания: " + verdict.serviceArea);
        }

        // billedUnits — это факт, а не план: обогащение, не давшее данных, не оплачивается.
        System.out.println("\nСписано единиц работы: " + intOf(result, "billedUnits"));
        for (String note : verdict.notes) {
            System.out.println("[!] " + note);
        }

        // Показывать источник данных обязательно: этого требует лицензия исходных наборов.
        System.out.println("\n" + str(result, "attribution"));
    }
}