# PR-3: OpenAPI контракт `lk-gateway` (ESIA Finance API V1)

## Цель

Зафиксировать REST-контракт между `lk-gateway` (наш сервис) и ЛК
клиента на платформе ESIA Finance. Контракт — отправная точка для:

- собственного эмулятора ЛК (`lk-emulator`, PR будет позже);
- интеграции с командой реального ЛК (когда формы документа на
  стороне ЛК будут готовы).

## Источники правды

- `DOC/API ЛК ЕСИА.pdf` — официальное описание API V1 платформы
  ESIA Finance (`/api/v1/back_office/...`, Basic HTTP, JSON, UTF-8).
- `DOC/M2MSchemas_260408/*.xsd` — поля заявления должны быть
  достаточны для формирования `M2MTransferRequest`.

## Состав PR

### 1. `docs/lk-contract/v1/openapi.yaml`

Спецификация OpenAPI 3.0. Покрывает следующие операции:

- `POST /api/v1/back_office/claims/` — создание заявки на M2M-перевод.
  - Тело: подписанное заявление инвестора (XML или JSON, согласовать
    с командой ЛК; XML с XMLDSig — предпочтительнее, проще
    верифицировать на нашей стороне через `crypto-service`).
  - Ответ: `{ id, status, created_at, success: true }`.
- `GET /api/v1/back_office/claims/{id}` — получение заявки и её
  статуса.
- `PATCH /api/v1/back_office/claims/{id}` — обновление статуса от
  нашей стороны (callback).
- `GET /api/v1/back_office/claims` — список заявок (фильтры по статусу,
  периоду, инвестору).
- Аутентификация: Basic HTTP (как в API V1 ESIA Finance).
- Формат ошибок — как в `API ЛК ЕСИА.pdf`:
  `{ error: true, status, code, title, meta: { message, errors } }`.

### 2. Состав модели «Заявка»

Минимальный набор полей, нужный для формирования
`M2MTransferRequest`:

- `id` (uuid),
- `created_at`, `updated_at`,
- `status` — enum (`draft|signed|submitted|in_progress|confirmed|rejected|timed_out`),
- `investor` — ссылка на пользователя в ЛК (или встроенные ФИО+документ);
- `transferring_depository_inn`, `receiving_depository_inn`,
- `securities[]` — список с `security_code`, `isin` (или
  `security_info`), `quantity_whole|fractional`, `settlement_accounts[]`,
- `cost_info` — `yes { code } | no`,
- `iia_agreement` (опц., для ИИС) — `agreement_type T12|T03`,
  `agreement_number`, `agreement_date`, `broker_inn`,
- `signed_document` (base64) — подписанный XML заявления,
- `signature_format` — `XMLDSig-GOST` или `XMLDSig-RSA`.

### 3. Состав модели «Callback статуса»

Что мы отправляем обратно в ЛК:

- `claim_id`,
- `new_status` (по тому же enum),
- `reason_code` (для отказов — код причины из M2MTransferResponse),
- `reason_text`,
- `updated_at`,
- `nsd_response` — оригинал ответа НРД (опц., для аудита).

### 4. `docs/lk-contract/v1/examples/`

- `examples/claim-request.json` — пример заявки на перевод
  (3 ЦБ, ИИС, заполненные реквизиты).
- `examples/claim-response.json` — пример ответа.
- `examples/callback-confirmed.json` — пример callback подтверждения.
- `examples/callback-rejected.json` — пример callback отказа.
- `examples/error-422.json` — пример ошибки валидации.

### 5. `docs/lk-contract/v1/changelog.md`

Версионирование контракта. Первая запись — `v1.0.0`.

### 6. Обновить `docs/lk-contract/v1/README.md`

Описать состав, способ работы и порядок согласования с командой ЛК.

## Требования к коду

- OpenAPI 3.0.x, валидный по `spectral` или `openapi-cli`.
- Имена операций (operationId) — `snake_case`.
- Описания (description) — на русском.
- Все поля с `description` и примерами.
- Без эмодзи.

## Коммит

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

- docs/lk-contract/v1/openapi.yaml — спецификация
- docs/lk-contract/v1/examples/ — примеры запросов/ответов/callback
- docs/lk-contract/v1/changelog.md — v1.0.0

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

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

## После коммита

1. Обновить `docs/tasks/README.md`: PR-3 — «выполнено».
2. Сообщить заказчику, что OpenAPI готов и можно отправлять команде ЛК.