zuevav
3fdc526031
- docs/architecture/plan.md — полный план проекта (архитектура, стек, SLA, регуляторика, Реестр ПО, roadmap M1–M5, открытые вопросы и решения). - docs/tasks/README.md — индекс задач и инструкция запуска для Claude Code на dev-ВМ. - docs/tasks/PR-1-go-models-m2m.md — Go-модели M2M, парсер windows-1251, NSDDateTime, round-trip тесты на эталонах. - docs/tasks/PR-2-fansy-ddl.md — DDL принимающей БД для команды Fansy (контракт данных, ETL-требования, словарь полей, тестовые данные). - docs/tasks/PR-3-lk-openapi.md — OpenAPI контракт lk-gateway по ESIA Finance API V1, для синхронизации с командой ЛК. - docs/tasks/PR-4-m2m-core-skeleton.md — FSM сделки, репозиторий, идемпотентность по GUID, метрики SLA. - docs/tasks/PR-5-nsd-adapter-skeleton.md — REST-клиент ИШ НРД, маршрутизация типов пакетов (M2MTR/M2MTD/M2MER/SUBBR/SUBER/SUB16). - docs/tasks/PR-6-crypto-service-skeleton.md — gRPC-каркас Java-сервиса криптографии (КриптоПро JCP, UDS, Provider-абстракция). С этого коммита дальнейшая разработка идёт на dev-ВМ через запущенный там Claude Code. Промпты PR-1..PR-3 готовы к параллельному запуску; PR-4 после PR-1; PR-5 и PR-6 ждут поставку артефактов (ИШ НРД, сертификаты, КриптоПро JCP). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
114 lines
5.4 KiB
Markdown
114 lines
5.4 KiB
Markdown
# 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 готов и можно отправлять команде ЛК.
|