docs: specify FSSP Checko and unified exchange sources
This commit is contained in:
@@ -0,0 +1,333 @@
|
||||
# ФССП, Checko и биржи: проектирование backend Mostovik
|
||||
|
||||
Дата: 5 октября 2026, Europe/Madrid.
|
||||
Статус: схема согласована пользователем; письменная спецификация ожидает проверки.
|
||||
Рабочая ветка: `dev`. База исследования: backend `fedd2e0`, frontend `74c0c3e`.
|
||||
|
||||
## 1. Цель и границы
|
||||
|
||||
Добавить сбор, проверку, публикацию, чтение и экспорт пяти источников для организаций
|
||||
канонического реестра Mostovik:
|
||||
|
||||
1. ФССП: исполнительные производства юридических лиц.
|
||||
2. Checko: договоры лизинга.
|
||||
3. Checko: сообщения.
|
||||
4. Checko: лицензии.
|
||||
5. Активность организаций на фондовых биржах: СПБ и MOEX вместе.
|
||||
|
||||
Готовность означает работающий сборщик и согласованные backend API/OpenAPI,
|
||||
подтверждённые проверки данных и пакет документации для подключения фронта.
|
||||
Наличие карточки, DTO или синтетических данных само по себе готовность не доказывает.
|
||||
|
||||
Реализация выполняется только в `mostovik-backend`, в ветке `dev`. Frontend обновлён
|
||||
из Git по просьбе пользователя и используется только как источник требований.
|
||||
Его код, OpenAPI-копия, generated client, тесты и конфигурация не меняются.
|
||||
StateCorp, корневые deployment-файлы, указатели submodule и пользовательские `.env`
|
||||
не входят в эту задачу. План реализации отделяет подготовку выпуска от его выполнения.
|
||||
|
||||
## 2. Проверенные исходные требования
|
||||
|
||||
Основной документ: Дима, группа Telegram **ECOS**, 01.10.2026, сообщение **395115**,
|
||||
`описание_источников_которые_нужно_сделать.docx`.
|
||||
Именно этот свежий документ является основанием для ФССП и бирж; апрельское ТЗ
|
||||
фондового рынка и январские/апрельские перечни источников исключены из основания.
|
||||
|
||||
Документ описывает:
|
||||
|
||||
- ФССП: общедоступные сведения БДИП в отношении юрлиц и отдельную выгрузку
|
||||
оконченных ИП по указанным в документе основаниям;
|
||||
- СПБ: актуальный XLSX списка ценных бумаг, включая колонку ИНН;
|
||||
- MOEX: справочные запросы ISS, параметры инструментов и итоги торгов;
|
||||
- MOEX: поиск облигаций по ИНН эмитента и сбор параметров каждой бумаги;
|
||||
- MOEX: экспорт дюрации и доходности с привязкой к дате расчёта.
|
||||
|
||||
Дополнительные требования ФССП:
|
||||
|
||||
- Глеб, 01.10.2026, сообщение **395146**, `backend-api-csv-amendments.md`;
|
||||
- актуальные файлы frontend `docs/source-integration/sources/fssp-enforcement-proceedings/`;
|
||||
- фактический frontend-контракт `fsspEnforcementProceedings.contract.ts`.
|
||||
|
||||
Глеб уже добавил в frontend `origin_kind`, nullable `queried_inn`, три новых поля,
|
||||
отрицательный остаток и диагностику. Backend должен поддержать эти значения,
|
||||
а не требовать изменения frontend.
|
||||
|
||||
Три раздела Checko подтверждены пользователем и перепиской с Глебом 02.10.2026,
|
||||
сообщение **395213**. Свежий документ группы не описывает их API. Их нельзя
|
||||
приписывать этому документу или заменять существующим источником банкротств.
|
||||
|
||||
## 3. Решение и существующие точки интеграции
|
||||
|
||||
Использовать существующее хранилище и жизненный цикл источников:
|
||||
|
||||
`получение → проверка → staging → атомарная публикация → API → готовые выгрузки`.
|
||||
|
||||
Повторно использовать:
|
||||
|
||||
- `ParserSourceArtifact`, `ParserStagedRecord`, `ParserLoadLog`,
|
||||
`ParserBatchSequence`, `BackgroundJob`;
|
||||
- `registry_http.py` для ограниченных HTTP-запросов и скачивания;
|
||||
- `registry_snapshots.py` для промежуточного хранения и публикации;
|
||||
- `tasks_registry_snapshots.py` для фоновых задач и их результатов;
|
||||
- `OrganizationSourceExtension`, `OrganizationSourceRecord` и `source_groups.py`;
|
||||
- `source_registry.py`, `source_cards.py`, универсальные records/jobs/logs/export;
|
||||
- действующий Checko HTTP-клиент и месячные claims в `checko_collection.py`;
|
||||
- backend OpenAPI pipeline в `tools/openapi/`.
|
||||
|
||||
Не вводить отдельный сервис импорта, новое хранилище организаций или второй путь
|
||||
записи через legacy parser tables. Новые сборщики располагаются в небольших модулях
|
||||
по предметной области; общие файлы содержат регистрацию и вызовы этих модулей.
|
||||
|
||||
Предлагаемые идентификаторы новых источников:
|
||||
|
||||
| Карточка | Parser source | Source group | Record type |
|
||||
| --- | --- | --- | --- |
|
||||
| `fssp-enforcement-proceedings` | `fssp_enforcement_proceedings` | `enforcement_proceedings` | `enforcement_proceeding` |
|
||||
| `checko-leasing` | `checko_leasing` | `leasing` | `leasing_contract` |
|
||||
| `checko-messages` | `checko_messages` | `company_messages` | `company_message` |
|
||||
| `checko-licenses` | `checko_licenses` | `company_licenses` | `company_license` |
|
||||
| `stock-exchange-activity` | `stock_exchange_activity` | `stock_exchange_activity` | `exchange_instrument` |
|
||||
|
||||
Это проектируемые идентификаторы, а не утверждение об уже существующих API.
|
||||
Биржи имеют одну карточку, один parser source, одну группу, единые счётчики,
|
||||
историю запусков и экспорт. `exchange=moex|spb` находится внутри записи.
|
||||
|
||||
## 4. Организации, идентичность и публикация
|
||||
|
||||
Сбор выполняется для действующей популяции канонического реестра по существующим
|
||||
правилам eligibility. Не создавать организации из внешних CSV/XLSX/API и не
|
||||
сопоставлять их приблизительно по названию.
|
||||
|
||||
Нормализованный ИНН должен однозначно указывать на каноническую организацию.
|
||||
Неприменимые строки внешнего реестра считаются отдельно от строк с ошибками.
|
||||
Неоднозначные или некорректные идентификаторы изолируются с причиной.
|
||||
ОГРН и ОКПО выдаются из канонического справочника; ведущие нули сохраняются.
|
||||
|
||||
Публикация сохраняет UUID существующих записей при повторном импорте. Внешняя
|
||||
идентичность не зависит от суммы, текущей цены, статуса или даты скачивания:
|
||||
|
||||
- ФССП: ИНН должника и устойчивый номер ИП;
|
||||
- лизинг/сообщения: идентификатор записи провайдера и организация;
|
||||
- лицензии: организация, номер, выдавший орган и дата выдачи, если провайдер
|
||||
не предоставляет отдельного устойчивого идентификатора;
|
||||
- биржи: биржа и устойчивый идентификатор инструмента провайдера; ISIN сохраняется
|
||||
отдельно и не используется для слияния MOEX и СПБ в одну запись.
|
||||
|
||||
Если для лизинга/сообщения невозможно получить устойчивый ID, адаптер обязан
|
||||
использовать документированную неизменную комбинацию исходных полей, проверенную
|
||||
на fixtures. Одинаковые ключи с разными данными блокируют публикацию соответствующего
|
||||
набора, а не перезаписываются в случайном порядке.
|
||||
|
||||
Обрыв скачивания, непроверенная пагинация, неизвестные заголовки или ошибка
|
||||
публикации сохраняют предыдущий опубликованный набор. Проверенный пустой результат
|
||||
должен отличаться от недоступного источника. Исчезновение строки не доказывает
|
||||
закрытие ИП, прекращение лицензии или делистинг.
|
||||
|
||||
## 5. ФССП
|
||||
|
||||
### Получение и объём
|
||||
|
||||
Использовать открытые выгрузки двух наборов из свежего документа. Паспорта наборов
|
||||
определяют их точные идентификаторы, формат, дату и область; имя файла и сумма долга
|
||||
не определяют статус ИП. Web-поиск за CAPTCHA не является основным каналом сбора.
|
||||
|
||||
Скачивание полностью выполняет backend. Пользователь не передаёт файл, URL или
|
||||
локальный путь через публичный refresh/run API. Разрешённые адреса и предельные
|
||||
размеры задаются серверной конфигурацией по проверенным паспортам источника.
|
||||
|
||||
В дополнении Глеба исследован CSV размером 1 954 126 197 байт, 2 915 784 строки,
|
||||
17 колонок, UTF-8. Использовать потоковое скачивание на диск, стандартный CSV reader
|
||||
с поддержкой кавычек/многострочных значений и ограниченные batches staging.
|
||||
Не применять `response.content`, `list(reader)` или DataFrame всего реестра.
|
||||
|
||||
Полные исходные файлы сохраняются как артефакты. Строки вне канонического реестра
|
||||
подсчитываются при потоковом чтении и не создают миллионы staging-записей в БД.
|
||||
Staging содержит применимые записи и необходимую диагностику ошибок привязки.
|
||||
|
||||
Оба набора собираются в один логический источник, но сохраняют отдельные provenance,
|
||||
дату и область. Их объединённый опубликованный результат меняется только после
|
||||
полного чтения и проверки обоих входов. Повторяющиеся ИП дедуплицируются по устойчивому
|
||||
ключу; противоречивые сведения требуют явного правила по дате и паспорту набора,
|
||||
с сохранением происхождения обоих наблюдений.
|
||||
|
||||
Для объединённого запуска сохранять manifest входных артефактов с их датами,
|
||||
checksum и областью. Результат job и сведения об успешном snapshot относятся
|
||||
к объединённой публикации, а не к последнему отдельно скачанному файлу.
|
||||
|
||||
### Контракт
|
||||
|
||||
Сохранить frontend source/group/type, общую оболочку и все обязательные поля.
|
||||
Для CSV: `origin_kind=open_data_csv`, `queried_inn=null`, ИНН должника соответствует
|
||||
организации. `record_date` соответствует дате возбуждения; `amount` равен остатку
|
||||
`debt_amount`, а не `claim_amount`.
|
||||
|
||||
Сохранить все 17 исходных значений и добавить:
|
||||
|
||||
- `consolidated_proceeding_number`: номер сводного ИП;
|
||||
- `document_subject_raw`: предмет исполнительного документа;
|
||||
- `claim_amount`: отдельная сумма Amount due.
|
||||
|
||||
Остаток долга сохраняет отрицательный знак. Денежные значения проходят через
|
||||
`Decimal`, публикуются десятичными строками, пустое значение остаётся null.
|
||||
Ноль не превращается в отсутствие данных. Предмет документа не становится
|
||||
выдавшим органом. Будущая дата не исправляется автоматически.
|
||||
|
||||
Полноту и семантику отсутствующих полей разрешает паспорт конкретного набора.
|
||||
Статус остаётся `unknown`, если подтверждённого основания для другого значения нет.
|
||||
Предупреждения сохраняются по действующему набору frontend; ошибочные строки
|
||||
не подменяются фиктивными реквизитами или нулевыми суммами.
|
||||
|
||||
Добавить типизированную выдачу ФССП в list/detail/OpenAPI, сортировки и экспорт,
|
||||
которые уже предусмотрены документацией Глеба. Существующие денежные правила
|
||||
других источников не изменяются.
|
||||
|
||||
## 6. Checko
|
||||
|
||||
Добавить отдельные доменные сборщики лизинга, сообщений и лицензий через существующий
|
||||
клиент. Лицензии уже присутствуют в `CompanyData.licenses`; это не доказывает
|
||||
публикацию самостоятельного источника. `BankruptcyMessage` описывает ЕФРСБ и не
|
||||
может автоматически считаться полным набором требуемых сообщений.
|
||||
|
||||
До реализации конкретного upstream-вызова сверить актуальную документацию Checko
|
||||
и получить обезличенные fixtures структуры успешного, пустого, ошибочного и
|
||||
постраничного ответов. Не придумывать маршруты `/leasing` или `/messages` и поля
|
||||
ответа. Если выбранный тариф не предоставляет требуемый раздел, статус отражает
|
||||
отсутствие доступа, а не успешное получение нуля записей.
|
||||
|
||||
Доменный контракт содержит организацию, устойчивую внешнюю идентичность, даты,
|
||||
проверенные поля провайдера, источник и время получения. Конкретный набор данных
|
||||
лизинга/сообщения определяется проверенным ответом; не добавлять вымышленные
|
||||
суммы, участников договора или полный текст, если API их не выдаёт.
|
||||
Для лицензии использовать подтверждённые номер, даты, орган и виды деятельности.
|
||||
|
||||
Сохранить существующую месячную защиту квоты. Claim отдельный для организации
|
||||
и каждого нового источника, атомарный, не освобождается автоматически при ошибке.
|
||||
Worker пропускает уже занятые claims с явным статусом и счётчиками; refresh не обходит
|
||||
ограничение повторными запросами. Пагинация одного разрешённого сбора имеет явные
|
||||
ограничения, счётчики и проверку полноты. Настройки таймаутов/прокси сохраняют
|
||||
проектные правила. Реальные платные запросы не являются частью обычных тестов.
|
||||
|
||||
Успешно проверенный набор заменяет данные только запрошенной организации.
|
||||
Ошибочная или пропущенная по квоте организация сохраняет прошлые записи.
|
||||
Общий job не выдаёт неполный обход популяции за полноценное обновление всего источника;
|
||||
счётчики обновлённых, сохранённых, пустых и ошибочных организаций различаются.
|
||||
|
||||
## 7. Биржи как один источник
|
||||
|
||||
### СПБ
|
||||
|
||||
Выбирать актуальную выгрузку списка бумаг на официальной странице, сохранять её
|
||||
дату и checksum. XLSX читать через уже имеющийся `openpyxl` в read-only режиме,
|
||||
проверяя заголовки. Строки без ИНН или без соответствия каноническому реестру
|
||||
не сопоставляются по похожему названию. Их количество отражается в диагностике.
|
||||
|
||||
### MOEX
|
||||
|
||||
Использовать официальные ISS-запросы, когда они предоставляют требуемые данные:
|
||||
справочник инструментов, параметры и итоги торгов. Отбор эмитентов осуществляется
|
||||
по проверенному ИНН или другой подтверждённой связи с каноническим эмитентом.
|
||||
Внутренний `emitent_id` сам по себе не является ИНН.
|
||||
|
||||
Получать сведения по облигациям выбранных эмитентов и присоединять параметры,
|
||||
торговые результаты, дюрацию и доходность. Для дюрации/доходности сохранять дату
|
||||
расчёта. Если ISS не содержит нужного значения, проверить официальный экспорт
|
||||
страницы `/ru/bondization/durations`; не выдавать отсутствие поля за ноль.
|
||||
|
||||
### Общий контракт и завершённость
|
||||
|
||||
Запись представляет инструмент на конкретной бирже. Payload содержит `exchange`,
|
||||
идентификаторы инструмента и эмитента, ISIN при наличии, вид бумаги, даты листинга
|
||||
при наличии, проверенные параметры инструмента, торговые данные и их дату,
|
||||
дюрацию/доходность с датой расчёта и provenance.
|
||||
|
||||
Поля различаются по типу инструмента. Отсутствующее поле nullable; денежная сумма,
|
||||
цена, процент доходности и дюрация не смешиваются в общий `amount`.
|
||||
Историю изменений и исходные единицы измерения сохранять в артефактах; задачу
|
||||
полного исторического терминала и внутридневного мониторинга не добавлять.
|
||||
|
||||
Один refresh собирает СПБ и MOEX и публикует объединённый snapshot только после
|
||||
проверки обоих адаптеров. Сбой одного адаптера сохраняет предыдущий объединённый
|
||||
snapshot. Карточка показывает один источник и общие счётчики; диагностика внутри
|
||||
job/log различает адаптеры и стадии. Частичный набор не выглядит полным.
|
||||
|
||||
## 8. API, эксплуатация и совместимость
|
||||
|
||||
Регистрировать новые источники в существующих cards/registry/group mappings.
|
||||
Расширить допустимые enum, фильтры, ordering и типизированные payloads, не меняя
|
||||
контракты существующих источников. Records list/detail, организации, dashboard
|
||||
и экспорт читают один опубликованный результат.
|
||||
|
||||
Поддержать штатные refresh/run, защиту от параллельного запуска, progress,
|
||||
историю успешной и неуспешной попытки. Неуспешный сбор не сдвигает дату успешного
|
||||
обновления и не отключает старые export tickets.
|
||||
|
||||
Обновлять OpenAPI из backend serializers/annotations и существующего build pipeline;
|
||||
не редактировать generated frontend или bundled OpenAPI вручную.
|
||||
Сохранить нынешний export-ticket/export-download flow и правила поколений выгрузок.
|
||||
|
||||
Секрет Checko и другие machine-local настройки не читаются для составления
|
||||
спецификации, не сохраняются в Git и не попадают в ошибки/логи/API metadata.
|
||||
Публичные URL загрузки и редиректы проверяются по разрешённым hosts; неизвестный
|
||||
формат и непроверенная структура вызывают явную ошибку.
|
||||
|
||||
Новые расписания до подтверждения канала и полного сбора остаются disabled.
|
||||
Документация фиксирует режим ручного запуска, квоты, размеры, причины отказов
|
||||
и критерии включения расписания. Автоматический сбор означает серверное скачивание;
|
||||
он не требует запуска нового расписания во время разработки.
|
||||
|
||||
## 9. Проверки и критерии приёмки
|
||||
|
||||
### Обязательные регрессии
|
||||
|
||||
- CSV ФССП: 17 заголовков, изменение порядка колонок, UTF-8, кавычки и переносы,
|
||||
неизвестная структура, оборванный файл, повторные ИП, оба набора и их происхождение;
|
||||
- signed остаток, нулевой остаток, Amount due отдельно, nullable поля, будущие даты;
|
||||
- Checko: успешный/пустой ответ, ошибка/лимит, полнота пагинации, атомарная месячная
|
||||
claim, сохранение старых данных у незавершённых организаций;
|
||||
- СПБ/MOEX: точная связь эмитента, несколько бумаг одной организации, одинаковый
|
||||
ISIN на двух биржах, даты/единицы дюрации и доходности, сбой одного адаптера;
|
||||
- стабильные UUID при повторном импорте, отсутствие legacy writes и новых организаций;
|
||||
- совпадение list/detail/export, enum/ordering/discriminator/OpenAPI и счётчиков;
|
||||
- refresh/run permissions, двойной запуск, ошибка job, сохранение last_success.
|
||||
|
||||
Запускать адресные pytest в backend, Ruff и Django checks, проверку миграций,
|
||||
backend OpenAPI build/runtime contract gate. На границе интеграции запускать
|
||||
общий backend suite в пропорции изменениям. Frontend-тесты и генерация клиента
|
||||
в frontend не входят в задачу.
|
||||
|
||||
### Доказательства фактического сбора
|
||||
|
||||
Для принятия источника необходимы проверенные upstream fixtures и полный проход
|
||||
реального артефакта/обхода в согласованном dev-окружении: входные и опубликованные
|
||||
счётчики, checksum, дата, время, предел памяти и результат job. Большой CSV
|
||||
проверяется отдельно от быстрых синтетических регрессий. Тестовый PASS не заменяет
|
||||
фактическую доступность данных и тарифную доступность Checko.
|
||||
|
||||
Публичный API сравнивается с документированным контрактом. Для ФССП дополнительно
|
||||
проверяется совпадение с существующей схемой Глеба без записи в frontend checkout.
|
||||
Изменение базы, реальный paid API сбор и публикация релиза выполняются отдельными
|
||||
этапами плана с явно ограниченным контуром; никакого неявного main/customer deploy.
|
||||
|
||||
## 10. Входные данные, которые ещё требуют проверки
|
||||
|
||||
Эти ограничения исследования являются обязательными gates реализации адаптеров:
|
||||
|
||||
1. Паспорта и реальные headers обеих выгрузок ФССП: проверить до включения канала;
|
||||
документ Глеба подтверждает структуру одного CSV, но не обоих наборов.
|
||||
2. Точный API и состав лизинга/сообщений Checko: подтвердить документацией и fixtures;
|
||||
текущий клиент не доказывает наличие этих разделов в тарифе.
|
||||
3. Способ связи ISS-эмитента с ИНН и доступность дюрации/доходности: проверить
|
||||
официальными ответами/экспортом, не сопоставлять по неподтверждённому ID.
|
||||
4. Фактическое расписание источников: сохраняется disabled до полной приёмки;
|
||||
разработка не назначает произвольную частоту платных запросов.
|
||||
|
||||
При недоступном канале работа по другим адаптерам и контрактам продолжается,
|
||||
но этот источник не объявляется завершённым. Подмена данных fixtures или
|
||||
несогласованным альтернативным провайдером не допускается.
|
||||
|
||||
## 11. Порядок реализации
|
||||
|
||||
После проверки письменной спецификации подготовить отдельный план с точными
|
||||
файлами, тестами и этапами выполнения. Согласованный порядок: ФССП → Checko → биржи.
|
||||
Каждая область имеет самостоятельную проверку перед общей интеграцией пяти источников.
|
||||
План должен учитывать уже сделанный frontend Глеба и передавать ему только
|
||||
backend-контракт, примеры и результаты проверок.
|
||||
Reference in New Issue
Block a user