Files
mostovik-backend/docs/sources/2026-10-05-implementation-handoff.md
2026-10-05 17:49:22 +02:00

124 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Передача пяти источников, 5 октября 2026
Локальная реализация в `mostovik-backend/dev` завершена. Реальное наполнение dev
и включение расписаний не выполнены. Frontend обновлён из Git ранее в этой работе,
его код не менялся. StateCorp, root repo, env и submodule pointers не коммитились.
| Источник | Карточка | 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 |
СПБ и MOEX — одна карточка/источник; поле `payload.exchange=spb|moex` различает
записи. ФССП последняя карточка, item code `fssp_inn_search`. Привязка только к
каноническому справочнику по точным реквизитам; организации не создаются.
## Контракт для frontend
- `GET /api/v1/sources/` и `/api/v1/sources/<slug>/`: карточки, счётчики,
последний job/load и последний полный успешный snapshot.
- `POST /api/v1/sources/<slug>/refresh/`: только администратор, пустой JSON;
202 принят, 400 некорректные параметры, 403 нет прав, 404 карточка отсутствует,
409 этот источник уже запущен. File URLs от пользователя не принимаются.
- `GET /api/v2/organization-source-records/?source_group=<group>`;
detail `/api/v2/organization-source-records/<uid>/`. Общие фильтры source,
record_type, organization, search, date_from/date_to, ordering, page/page_size.
Поля payload и ordering перечислены в документах каждого источника.
- Биржи: `exchange=moex|spb`, `instrument_kind`; номинал, yield, duration —
отдельные nullable metrics, `amount=null`. MOEX effectiveyield сохранён под
своим именем в provenance, его unit пока null; duration unit=days.
- ФССП: `amount=debt_amount`, signed decimal string; claim отдельно. Отрицательное
значение и ноль не заменяются null. Будущие даты сохраняются с warnings.
Выход за последнюю страницу возвращает 200/пустой массив.
- Checko: суммы договоров и полный текст сообщения не выдумываются; amount null.
Истечение даты лицензии не используется как доказательство её прекращения.
- CSV/XLSX/JSON через существующие export-ticket/generation API сохраняют текущий
snapshot независимо от года ИП, выдачи лицензии или listing. UUID совпадают с
list/detail; ранее выданный ticket привязан к своей generation.
Canonical contract: `src/core/openapi.json`; generator и инструкции —
`tools/openapi/README.md`. Новые SourceRefresh error DTO отражают реальный envelope,
включая произвольные details. 43 синтетических отрендеренных HTTP-ответа проверены
generated Orval/Zod без изменения/потери полей. Frontend генерация не запускалась.
## Публикация и отказы
ФССП требует два полных файла, биржи — оба полных входа. Staging batches ≤500,
публикация атомарна; ошибка сохраняет прежний snapshot и last-success.
Raw/manifest приватны. Повторяющиеся биржевые vendor IDs отвергают весь snapshot.
Checko использует один необратимый месячный claim на organization/source до
первого HTTP. Полная пагинация проверяет одновременно количество полученных строк
и уникальных GUID **до фильтра лизинга**. Пересечение страниц при заявленном total
не считается полным результатом; прежние записи такой организации сохраняются,
attempt failed. Partial job показывает counters, но не двигает полный last-success.
## Итоговая локальная проверка
Один независимый whole-branch reviewer: 0 Critical, 3 Important, 0 Minor.
Все три Important воспроизведены тестами RED и исправлены GREEN:
пересечение страниц Checko, завершение MOEX cursor pagination на TOTAL и экспорт
ФССП с предыдущим/будущим годом начала ИП. Повторный reviewer не запускался.
- Полный suite, кроме отдельно проверенного API inventory: **1922 passed,
44 skipped, 13 warnings**. Пропуски не считаются успешными проверками.
- PostgreSQL с `--migrations`: исправления и связанные сценарии **72 passed,
0 skipped**. Ранее отдельный `--migrations --create-db`: **66 passed**,
граф применён до parsers 0047 / organizations 0018; admission/export 64 passed.
- API inventory: **9 passed с явно подменённым async dispatch**. Это проверка
HTTP surface, а не выполнение настоящих Celery задач/полный CI без подмены.
- Ruff src и format всех 235 src файлов, Django check, canonical OpenAPI,
strict TypeScript, Zod **43 responses**, git diff --check — PASS.
- Обычные настройки pytest содержат `--nomigrations`: прежние утверждения о
применении графа в этих прогонах были неточны; фактическое применение доказано
отдельными указанными выше прогонами с `--migrations`.
Полные публичные ФССП inputs: **7 066 820 строк, 4 695 702 827 байт**, оба EOF/SHA
проверены. СПБ: **2287 строк**, 251 с корректным ИНН. MOEX reference: shares 526,
bonds 3175; dated durations 2478; одна реальная бумага проверена по parameters и
primary-board trading. MOEX probe использовал дату из ранее проверенного HTML:
повторная загрузка самой страницы вернула 403. Это не полный worker acceptance.
Подробные hashes и ограничения — в [ФССП](fssp.md),
[Checko](checko-sections.md), [биржах](exchanges.md).
## Конкретный следующий этап: dev acceptance
Этот этап подготовлен, **не выполнен и не разрешён текущей локальной разработкой**.
Push `dev` запускает CI/CD из `.gitea/workflows/ci-cd.yml`, включая web/celery release.
Следовать актуальному root `DEPLOYMENT.md` и `deploy/ecos-dev/README.md`,
а не его историческим privileged SSH процедурам. Проверить точные commit/digests,
CI и соответствие web/celery, migrations через штатный release wrapper.
1. Только Mostovik backend; все пять новых schedules оставлять disabled.
До записи проверить текущий private storage и свободное место: raw ФССП уже
4.7 GB, staging/manifest/exports требуют дополнительного измеренного запаса.
Проверить worker limits и однозначность canonical directory. Сделать
согласованный backup затрагиваемых published records/artifacts.
2. Один ручной полный ФССП refresh через admin API, без переданных URL.
Зафиксировать job, оба SHA/версии, matched/skipped/quarantine/published counts,
сохранение UID, list/detail signed/null fields и prepared export generation.
Обрыв/отказ не должен менять старую публикацию; сравнивать с backup.
3. Checko: сначала согласовать аккаунт/тариф и денежный лимит, затем одна
однозначная eligible canonical организация, три раздела. Предлагаемый потолок
пробы **11 HTTP: 1 company + ≤5 messages pages + ≤5 leasing pages**. Это
ограничение будущего transport wrapper, не существующий CLI параметр:
обычный refresh проходит весь eligible scope и до 100 pages/source/org,
его нельзя использовать для этой ограниченной пробы. При исчерпании бюджета
отказ до следующего HTTP, staging discard, claim остаётся; полный обход
отдельно после оценки всей eligible population. Денежная стоимость неизвестна.
4. Биржи: runtime trust СПБ отдельно согласовать; имеющееся разрешение CA касается
только уже проведённой публичной проверки/загрузки. Сначала подтвердить
доступность MOEX durations HTML из worker и единицу effectiveyield официальным
field-specific источником. Затем один полный combined refresh, отдельные
counters входов, единый publish/list/detail/export. Не обходить TLS/WAF.
5. Только после этой приёмки источники можно объявлять ready; включение schedules
отдельно. Frontend изменения, StateCorp, main и Telegram sends вне этапа.
Header-only CSV с подтверждёнными headers трактуется как пустой по согласованному
плану. Независимого publisher row count нет: semantic truncation до одних headers
не доказуем существующим каналом и может очистить записи при формально полном
пустом snapshot. Это сохраняемый предел проверки, не установленный live факт.