docs: план проекта + промпты задач PR-1..PR-6 для Claude Code на ВМ
- 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>
This commit is contained in:
zuevav
@@ -0,0 +1,113 @@
|
||||
# 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 готов и можно отправлять команде ЛК.
|
||||
Reference in New Issue
Block a user