docs: record source validation and bounded dev acceptance

This commit is contained in:
Aleksandr Meshchryakov
2026-10-05 17:49:22 +02:00
parent b1710408fd
commit 24616d160f
5 changed files with 225 additions and 1 deletions

View File

@@ -0,0 +1,123 @@
# Передача пяти источников, 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 факт.