docs: record source validation and bounded dev acceptance
This commit is contained in:
123
docs/sources/2026-10-05-implementation-handoff.md
Normal file
123
docs/sources/2026-10-05-implementation-handoff.md
Normal 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 факт.
|
||||
Reference in New Issue
Block a user