mostovik-backend/docs/source-records-contract-plan.md

Полный контракт записей источников — 14.09.2026

Основание: source-records-backend-improvements.md, присланный пользователем. Пользователь явно включил весь документ, включая СРО, специальные фильтры МСП и полный detail бюджета. Запрет на сообщения Глебу сохраняется.

База backend: 49cbfd2, ветка codex/source-records-contract. 14.09 штатный SSH-маршрут оказался недоступен на первом переходе; доступ восстановлен через существующий российский узел Tailscale с проверенными ключами. Свежий fetch подтвердил backend 49cbfd2, frontend origin/dev c6f2ec7; проверки генерации выполняются в отдельном worktree, рабочий frontend не меняется.

Задачи и владельцы

1. Budget/SME normalization и named list/detail payload schemas — агент Mostovik. Файлы budget_registry.py, sme_support.py, новые payload-модули и тесты.
2. СРО: нормализация, разрешённый HTTP loader, staging, models/descriptors/tasks, access gate, миграции и тесты — агент требований.
3. Cards/dashboard/jobs/logs/export typed contracts и counts — агент State Corp. Реализация находится исключительно в Mostovik backend.
4. Root: organization-source-records validation/search/filter/order/pagination, serializer integration, discriminated OpenAPI, generated client checks.
5. Независимое ревью, регрессия SQLite/PostgreSQL, migration/OpenAPI, dev release и доступные живые проверки после восстановления соединения.

Согласование общих границ

Участки	Общая поверхность	Решение
1/4	Payload normalizers и response serializer	Агент создаёт отдельные typed payload serializers и нормализатор старого payload; root подключает их в serializers.py.
2/3	Source cards и parser run	Агент 2 передаёт descriptor/task/gate интерфейсы; source_cards.py и parser views редактирует агент 3.
1/2	Snapshot infrastructure	Переиспользуется registry_snapshots.py; изменения общего механизма согласуются сообщением.
3/4	Record export actions	source_record_export.py — агент 3; organizations/views.py — root по переданному интерфейсу.
1	Известные/неизвестные поля	Не угадывать коды и значения; unknown blocks сохраняются с lineage и метрикой.
2	Upstream approval	Default disabled; до разрешения владельца upstream оба ручных запуска дают typed409 до enqueue. Задача повторно проверяет gate.
3	Counts	Для трёх новых источников весь published dataset; ОПК coverage отдельно. Legacy источники сохраняют scope.
4	Совместимость	Legacy payload/search сохраняются. Новые source-specific поля валидируются и не игнорируются.

Ruling: канонический ticket flow остаётся ready201 → native form download200, как в новом handoff и действующем frontend; устаревшее требование preparing202 в SME/SRO source-first docs синхронизируется с этим контрактом. Стоимость ошибки: если требуется отдельная on-demand генерация, понадобится согласованный frontend polling.

Ruling: публикация СРО без согласованного доступа не запускается. Реализация и fixture acceptance обязательны; отсутствие разрешения отражается typed409, а не успешной пустой загрузкой. Стоимость: СРО останется без живого snapshot до разрешения.

Проверки завершения

• Все требования отмечаются результатами в этом документе, пропуски отдельно.
• Runtime и OpenAPI: required/nullable, source variants, errors, page metadata.
• Фильтры, null-last ordering и ties UID до пагинации на PostgreSQL.
• Fixtures: empty/one/many, Budget partial/large/unknown blocks, SME mixed units, документы/нарушения, несколько СРО, unsafe URL и идентификационные конфликты.
• Генерация bun run apigen, затем bun run type-check без ручного изменения generated.
• Совместимость опубликованных данных и сохранение предыдущего snapshot при ошибке.
• Миграции, pytest, scope review, dev release только после сверки remote.