# API

Документ фиксирует baseline API для беспилотного весового контура.

## 1. Общие правила

- Статус: `design baseline`
- Префикс: `/api/v1`
- Envelope: `item/list + meta.request_id/meta.timestamp`
- Изоляция: `tenant_id`, `industry_code=weighbridge`, `site_id`, `lane_id`
- ANPR policy:
  - prototype: primary ANPR в `iT-2110-015700`;
  - production: primary ANPR в `iT-2210`, панель получает готовый результат.
- Identity policy:
  - QR/RFID enrich карточку, но не блокируют автоматический цикл взвешивания.

## 2. Группы endpoint-ов

### 2.1. Weigh Session

- `GET /api/v1/weighbridge-session/scheme`
- `GET /api/v1/weighbridge-session/list`
- `GET /api/v1/weighbridge-session/offline-queue`
- `POST /api/v1/weighbridge-session/commands/detect`
- `POST /api/v1/weighbridge-session/commands/complete-phase`
- `POST /api/v1/weighbridge-session/commands/interlock`
- `POST /api/v1/weighbridge-session/commands/erp-sync`

List-фильтры phase-1:
- `q`, `vehicle_plate`, `trip_token`, `status`, `lane_id`, `direction`, `operation_mode`, `limit`, `offset`

Ключевые команды:
- `detect`:
  - создает или продолжает `weigh_session` по въезду или ANPR;
- `complete-phase`:
  - записывает `tare` или `gross`, сохраняет evidence refs и пересчитывает состояние;
- `interlock`:
  - фиксирует состояние шлагбаума, светофора и связанных gate-контуров;
- `erp-sync`:
  - публикует очередь синхронизации карточек во внешнюю систему.

### 2.2. Driver Identity

- `GET /api/v1/weighbridge-identity/scheme`
- `GET /api/v1/weighbridge-identity/list`
- `POST /api/v1/weighbridge-identity/commands/resolve`
- `POST /api/v1/weighbridge-identity/commands/attach`

Правило:
- `resolve` допускается вызывать как до первой фазы, так и после нее;
- отсутствие `resolve` не блокирует automatic close.

### 2.3. Media Evidence

- `GET /api/v1/weighbridge-media/scheme`
- `GET /api/v1/weighbridge-media/list`
- `POST /api/v1/weighbridge-media/commands/ingest`

Правило media policy:
- `gross`: верхняя камера обязательна;
- `tare`: верхняя камера обязательна только если кузов не пустой или сессия помечена как спорная/manual review.
- `ingest` обязан возвращать `storage_ref` исходного evidence и при наличии `preview_ref` для UI/handover.

### 2.4. Weigh Alarms

- `GET /api/v1/weighbridge-alarms/scheme`
- `GET /api/v1/weighbridge-alarms/list`
- `POST /api/v1/weighbridge-alarms/commands/publish`
- `POST /api/v1/weighbridge-alarms/commands/ack`

Базовые alarm codes phase-1:
- `weighbridge_weight_unstable`
- `weighbridge_duplicate_entry`
- `weighbridge_partial_exit`
- `weighbridge_anpr_mismatch`
- `weighbridge_camera_unavailable`
- `weighbridge_scale_timeout`

## 3. Пример payload

### 3.1. `POST /api/v1/weighbridge-session/commands/complete-phase`

```json
{
  "item": {
    "session_id": "wbs-2026-03-10-0001",
    "phase": "gross",
    "weight_kg": 28420,
    "stability_state": "stable",
    "plate": "A123AA797",
    "camera_media_ids": ["med-plate-out-001", "med-cargo-top-001"],
    "captured_at": "2026-03-10T12:15:00Z"
  }
}
```

### 3.2. `POST /api/v1/weighbridge-identity/commands/resolve`

```json
{
  "item": {
    "session_id": "wbs-2026-03-10-0001",
    "rfid_uid": "04AABBCCDD",
    "qr_payload": "trip=TR-2026-00045;driver=DRV-1007",
    "vehicle_plate": "A123AA797"
  }
}
```

### 3.3. `POST /api/v1/weighbridge-alarms/commands/publish`

```json
{
  "item": {
    "session_id": "wbs-2026-03-10-0001",
    "alarm_code": "weighbridge_anpr_mismatch",
    "severity": "high",
    "message": "plate mismatch between entry and gross phase"
  }
}
```

## 4. Принятые правила цикла

- partial session допустима: карточка может быть сохранена после одной фазы и позже закрыта второй;
- управление шлагбаумом и светофором входит в базовый автоматический контур через `iU-6130` / `iU-6135`;
- `completed` допустим только при наличии обязательного evidence и двух фаз;
- `manual_review` используется как controlled fallback вместо silent reject;
- `rejected` применяется только по явному review-решению и не должен выставляться автоматически при отсутствии evidence;
- повторный `detect` в пределах активного lane/cycle context обязан вернуть существующий `session_id` и зафиксировать duplicate condition без создания второй карточки;
- `offline-queue` хранит session/media/alarm entities до подтвержденного sync и не должен порождать duplicate session после recovery.

## 5. Первая реализационная очередь

В phase-1 обязательны:

1. `weighbridge-session/scheme|list|offline-queue|detect|complete-phase|interlock|erp-sync`
2. `weighbridge-identity/resolve|attach`
3. `weighbridge-media/ingest`
4. `weighbridge-alarms/publish|ack`

Во phase-1 не требуется:

- сложная ERP-оркестрация beyond queue/export;
- авто-классификация груза beyond basic `cargo_top`;
- сложная пропускная логика по расписаниям.