diff --git a/docs/superpowers/specs/2026-10-05-fssp-checko-exchanges-design.md b/docs/superpowers/specs/2026-10-05-fssp-checko-exchanges-design.md new file mode 100644 index 0000000..b6f9090 --- /dev/null +++ b/docs/superpowers/specs/2026-10-05-fssp-checko-exchanges-design.md @@ -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-контракт, примеры и результаты проверок.