docs: specify FSSP Checko and unified exchange sources

This commit is contained in:
Aleksandr Meshchryakov
2026-10-05 14:51:36 +02:00
parent fedd2e00a3
commit 764556fc4b

View File

@@ -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-контракт, примеры и результаты проверок.