New external site management. New external prober heartbeat feature.

docs/API.md

@@ -209,7 +209,12 @@ target)` в рамках текущей попытки — безопасна и
 ### `POST /api/v1/probers/register`
 
 Регистрация пробера. `site_id` должен присутствовать в конфиге control-api
-(`sites[].site_id`), иначе — `400`.
+(`sites[].site_id`), иначе — `400`. Помимо привычной проверки, запоминает
+`hostname` и переводит площадку в состояние `idle` (если она была
+`unregistered`/`unreachable`) — то же самое, что делает `validator-agent`
+при своей регистрации (см.
+[«Управление площадками»](USAGE.md#управление-площадками-проберами) в
+USAGE.md про состояния площадки).
 
 Запрос:
 ```json
@@ -218,6 +223,17 @@ target)` в рамках текущей попытки — безопасна и
 
 Ответ: `{"ok": true, "poll_interval_seconds": 5}`.
 
+### `POST /api/v1/probers/{site_id}/heartbeat`
+
+«Я жив». Обновляет `last_heartbeat_at` площадки. Если площадка не
+присылает heartbeat дольше `orchestrator.heartbeat_timeout_seconds`
+(тот же параметр, что и для валидаторов), она помечается `unreachable`.
+Полный аналог `POST /api/v1/agents/{id}/heartbeat` для пробера.
+
+Запрос: тело не требуется.
+
+Ответ: `{"ok": true}`. `404`, если `site_id` не сконфигурирован.
+
 ### `GET /api/v1/probers/{site_id}/assignments`
 
 Список всех IP, которые сейчас находятся в состоянии `checking` — то есть
@@ -424,15 +440,23 @@ curl -s -X POST "$BASE/api/v1/admin/ips/clear"
 
 ### Площадки: `/api/v1/admin/config/sites`
 
-Слотов ровно три (`index` ∈ {1, 2, 3}) — это ограничение схемы БД
-(`ip_queue.site{1,2,3}_complete`), а не искусственное. Пустой список слотов
-— штатный сценарий, отключающий inbound-проверки целиком (см.
+Число слотов не ограничено — `index` может быть любым целым `>= 1`,
+столько площадок, сколько нужно оператору. Пустой список слотов — штатный
+сценарий, отключающий inbound-проверки целиком (см.
 [USAGE.md](USAGE.md#управление-площадками-проберами)).
 
+Помимо `index`/`site_id`, объект площадки несёт состояние подключения
+пробера — `hostname`/`state`/`last_heartbeat_at`, тот же смысл, что у
+аналогичных полей валидатора (`unregistered`/`idle`/`unreachable`,
+обновляются через `POST /api/v1/probers/register` и `POST
+/api/v1/probers/{site_id}/heartbeat`, см. выше). `PUT` на слот всегда
+сбрасывает эти три поля к значениям «ещё не подключался» — новый (или
+даже тот же) `site_id` трактуется как новая идентичность пробера.
+
 | Метод | Путь | Тело | Успех | Ошибки |
 |---|---|---|---|---|
-| GET | `/api/v1/admin/config/sites` | — | `[{"index","site_id"}]` (до 3 строк) | |
-| PUT | `/api/v1/admin/config/sites/{index}` | `{"site_id"}` | `200` | `400`, если `index` не 1..3; `409`, если `site_id` уже занят другим слотом |
+| GET | `/api/v1/admin/config/sites` | — | `[{"index","site_id","hostname","state","last_heartbeat_at"}]` | |
+| PUT | `/api/v1/admin/config/sites/{index}` | `{"site_id"}` | `200` | `400`, если `index < 1`; `409`, если `site_id` уже занят другим слотом |
 | DELETE | `/api/v1/admin/config/sites/{index}` | — | `200` | `404` |
 
 ### Группы целей: `/api/v1/admin/config/targets`
@@ -570,8 +594,8 @@ queued ──(control-api сам, без вызова API)──▶ assigning_fi
 в БД при этом уже `awaiting_self_check`.
 
 Площадки (`siteN_complete`) — опциональны: сколько их учитывается,
-целиком определяется текущим списком `sites` (0–3 записи, управляется
-через `/api/v1/admin/config/sites` — см.
+целиком определяется текущим списком `sites` (без ограничения по числу
+записей, управляется через `/api/v1/admin/config/sites` — см.
 [выше](#управление-очередью-и-конфигурацией)). Пустой список — агрегация
 ждёт только `egress_complete`, ни одна площадка не требуется. Подробнее —
 [USAGE.md](USAGE.md#управление-площадками-проберами).