feat(lk-contract): OpenAPI контракт lk-gateway по ESIA Finance API V1

- docs/lk-contract/v1/openapi.yaml — OpenAPI 3.0: POST/GET/PATCH /api/v1/back_office/claims, схемы Claim/CreateClaimRequest/StatusCallback/ErrorResponse
- docs/lk-contract/v1/examples/claim-request.json — заявка с 3 ЦБ, ИИС T03
- docs/lk-contract/v1/examples/claim-response.json — ответ на создание
- docs/lk-contract/v1/examples/callback-confirmed.json — callback подтверждения
- docs/lk-contract/v1/examples/callback-rejected.json — callback отказа
- docs/lk-contract/v1/examples/error-422.json — ошибка валидации
- docs/lk-contract/v1/changelog.md — v1.0.0

Контракт предлагается команде реального ЛК как точка синхронизации.
В lk-emulator (отдельный PR) контракт реализуется как «как-будто-ЛК»
для проверки сквозного потока.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/lk-contract/v1/README.md

@@ -1,18 +1,58 @@
-# docs/lk-contract/v1 — контракт с ЛК клиента (ESIA Finance)
+# docs/lk-contract/v1 — контракт с ЛК клиента (ESIA Finance API V1)
 
-ЛК клиента работает на платформе **ESIA Finance**, контракт описан
-в `DOC/API ЛК ЕСИА.pdf` (`/api/v1/back_office/...`, Basic HTTP, JSON,
+ЛК клиента работает на платформе **ESIA Finance**, контракт описан в
+`DOC/API ЛК ЕСИА.pdf` (`/api/v1/back_office/...`, Basic HTTP, JSON,
 UTF-8).
 
-На этапе M1 в `lk-emulator` мы воспроизводим этот контракт для запуска
-сквозного потока. Реальный ЛК подключится по тому же контракту, без
-правок на нашей стороне.
+На этапе M1 в `lk-emulator` (отдельный PR) мы реализуем этот контракт
+как «как-будто-ЛК» для запуска сквозного потока. Реальный ЛК
+подключится по тому же контракту без правок на нашей стороне.
 
-В этом каталоге будут:
+## Состав каталога
 
-- `openapi.yaml` — наш OpenAPI-контракт `lk-gateway`, согласованный
-  с командой ЛК.
-- `examples/` — примеры заявлений и ответов.
-- `changelog.md` — версионирование контракта.
+- **`openapi.yaml`** — OpenAPI 3.0 контракт lk-gateway. Описывает
+  четыре операции: создание, чтение, callback статуса и список заявок.
+  Модель `Claim` включает все поля, нужные m2m-core для формирования
+  `M2MTransferRequest`.
+- **`examples/`**:
+  - `claim-request.json` — пример заявки на перевод (3 ЦБ, ИИС T03).
+  - `claim-response.json` — пример ответа на создание.
+  - `callback-confirmed.json` — callback подтверждения (status_code
+    INFO, 3 коды 01).
+  - `callback-rejected.json` — callback отказа (status_code ERROR).
+  - `error-422.json` — ошибка валидации подписи.
+- **`changelog.md`** — версионирование контракта.
 
-Реализация — задача M1.
+## Что входит в модель заявки
+
+- Идентификация инвестора (UUID в ЛК, ФИО, документ).
+- Реквизиты передающего и принимающего депозитариев (ИНН).
+- Информация об учёте стоимости (`cost_info: yes | no`).
+- Опциональный блок ИИС (тип T12/T03, номер договора, дата, ИНН брокера).
+- Массив ценных бумаг (1..N), каждая с:
+  - `security_code` (НРД-код, 12 символов),
+  - идентификацией (`isin` или развёрнутый `security_info`),
+  - количеством (целое `whole` или дробное `fractional` до 16 знаков),
+  - списком счетов депо (`settlement_accounts[]`).
+- Подписанный XML заявления (base64) и формат подписи
+  (XMLDSig-GOST или XMLDSig-RSA).
+
+## Что входит в callback статуса
+
+- `claim_id`, `new_status`, `updated_at`.
+- Для `rejected`/`timed_out`: код и текст причины из ответа НРД.
+- Полное `nsd_response` (опц., для аудита).
+
+## Порядок согласования
+
+1. Передать команде ЛК ссылку на эту папку (тег `lk-contract-v1`).
+2. Обсудить базовый URL, авторизацию (Basic, через VPN), окна.
+3. Запустить `lk-emulator` на нашей стороне как опорную реализацию.
+4. После приёмки — поднимать реальную интеграцию.
+
+## Принципы
+
+- OpenAPI 3.0, валидный по spectral / openapi-cli.
+- Operation IDs в snake_case.
+- Описания на русском, имена полей на английском.
+- Enum'ы значений M2M — буквально как в XSD НРД (T12/T03, BOND/SHAR/MFUN, ...).