rf4-spotter/docs/PROJECT_AUDIT_2026-09-22.md

Аудит RF4 Spotter — 22 сентября 2026

Проверенный исходный commit: 25b6f39. Аудит охватывает API, Astro UI, исследовательские CLI, media, миграции, локальную БД, CI и эксплуатационные сценарии. Изменения этого прохода — отчёт и актуализация плана, не исправление продуктового кода. Внешние источники не запрашивались.

Вывод

Основа приложения работоспособна: production build собирается, OpenAPI синхронизирован, media audit чистый, локальные контейнеры healthy. Однако состояние «все локальные задачи закончились» неверно. Есть проблемы сохранности media-решений, конкурентных операций, навигации и достоверности UI. Несколько пунктов закрыли по проверке наличия элементов или пустой страницы, хотя их критерии включают наполненные состояния и визуальную приёмку.

Исполняемые проверки

Проверка	Результат текущего прохода
.venv/bin/pytest -q	228 passed, 1 failed, 1 skipped; 90 dependency deprecation warnings
npm --prefix apps/web run test:unit	FAIL; прямой запуск файла уточнил: 14 passed, 1 failed
npm --prefix apps/web run build	PASS; Astro: 87 файлов, 0 errors, 0 warnings, 2 hints по execCommand
PYTHONPATH=apps/api .venv/bin/python apps/api/export_openapi.py --check	PASS, 45 paths
media_cli --audit	704 записи: 466 approved, 226 superseded, 1 duplicate, 11 invalid; issues/orphans пусты
media_cli --quality-report	Среди 253 опубликованных fish-файлов один 48×48, известных альтернатив нет
docker compose ps	API, web, PostgreSQL, MinIO healthy
docker compose exec -T api alembic current	0022 (head)
SQL, транзакция BEGIN READ ONLY	waterbody: 21, source_external_id: 19; tackle_item: 0; rig: 0

Python failure: tests/test_community_cli.py:73 ожидает старый ответ reserve-only без reserved_at. Web failure: apps/web/tests/unit/presentation.test.ts:99 ожидает «Схема монтажа», тогда как продукт правильно показывает «Схема сборки». Это рассогласование тестов с изменёнными контрактами, не основание откатывать терминологию или идентификатор резерва.

Live E2E, новый screenshot/axe-прогон, production bootstrap, restore drill, нагрузка и проверка CVE в этом проходе не выполнялись. Уже запущенные Docker образы не пересобирались; их health не доказывает соответствие текущему коду. Старые browser-отчёты — исторические доказательства с указанными в них границами. Выводы о гонках ниже основаны на коде; конкурентные production-запросы не выполнялись.

Ошибки и недоработки

R01 · P1 · Сохранность media-решений

apps/api/Dockerfile:9 копирует data/media в образ, а сервис api в compose.production.yaml не имеет persistent media volume. Admin publish/rollback записывают manifest в этот каталог. Пересоздание контейнера вернёт состояние из образа. deploy/backup.sh сохраняет PostgreSQL и MinIO, но не этот manifest. Нужен единый долговременный writable store с bootstrap из Git, backup/restore и правилом обновления release. Критерий: решение переживает recreate, обновление образа и восстановление, не теряет provenance и fallback. Без cooldown.

R02 · P1 · Область публикации и конкурентная запись manifest

Кнопка apps/web/src/pages/admin/media.astro:57 появляется на отфильтрованной странице, но отправляет только note. Endpoint routers/admin.py:64 вызывает publish_quality_upgrades, который выбирает ВСЕ upgrade_stored (rf4_research/media_assets.py:205). Проверенная видимая выборка и область действия не связаны. Использование общего .tmp и отсутствие lock/version дополнительно допускают конфликт publish/rollback/CLI: atomic replace не защищает read-modify-write от потери чужого изменения. Нужны выбранные asset IDs, preview набора, версия manifest, блокировка и проверка реальных файлов перед продвижением. Критерий: скрытый кандидат не публикуется, устаревшее решение возвращает конфликт, одновременные операции сохраняют корректный JSON и обе истории решений. Без cooldown.

R03 · P1 · Идемпотентность отправки улова

routers/submissions.py:77 после IntegrityError возвращает winner без повторной проверки payload hash и времени действия ключа. Уникальность ключа хранится дольше пяти минут, поэтому путь достижим и при повторе старого ключа. Проверка replay token в обычной ветке также перестаёт проходить после успешного upload, который очищает token hash. Нужен единый replay-контракт для всех веток, включая завершённый upload, и различение конфликтов idempotency/Spot/Bait. Критерий: одинаковый запрос возвращает тот же результат, другой payload — 409; конкурентное создание одной точки/приманки не превращается в необработанный 500. Без cooldown; конкурентная проверка в изолированном PostgreSQL.

R04 · P1 · Скриншот: повтор, гонка и восстановление формы

add_screenshot читает report через db.get, без row lock: два запроса могут пройти проверку пустого screenshot_key и записать два объекта. После успешного upload повтор уже получает 401 из-за очищенного token hash. Если клиент потерял ответ, он не может отличить успех от неудачи. Кроме того, pages/api/report-screenshot.ts:15 удаляет только upload-cookie, сохраняя старый rf4-idempotency-key после восстановления; следующий новый улов может конфликтовать с предыдущим. Нужны одноразовая атомарная операция, повторяемый ответ и завершение состояния формы. Критерий: lost response + retry успешно восстанавливаются, новый улов отправляется, лишние S3-объекты не остаются.

R05 · P1 · Пагинация и семантика каталога снастей

pages/tackle/index.astro:18 использует общий offset для предметов и сборок, а Pagination в конце зависит только от result.total. При 0 предметов и 49 сборках вторую страницу сборок нельзя открыть через UI. Сбой предметов скрывает и успешно загруженные сборки. Неверная category или слишком длинный q дают API 422, но UI называет это временной недоступностью 503. Empty search описан как незаполненный каталог. Нужны отдельные пагинации/состояния и валидация параметров. Критерий: доступны все 49+ сборок независимо от предметов, фильтры сохраняются, ошибка ввода отличается от сбоя API и отсутствия данных. Без cooldown.

Дополнительно карточки этого каталога обёрнуты в <a>, а вложенный DataPassport через SourceBadge создаёт ещё один <a> при source_url. Это недопустимое вложение интерактивных ссылок; браузер может перестроить DOM. Сделать отдельные ссылки названия и источника, проверить наполненную карточку клавиатурой и по итоговому DOM. На пустом каталоге дефект не виден.

R06 · P1 · Импорт и срок годности сохранённого плана

pages/plan.astro:45 автоматически заменяет localStorage при открытии share URL. Параметр остаётся в URL: удаление точки или очистка отменяются при reload. Свежесть показывается как «Свежесть сохранена» без пересчёта времени, а ссылки строятся из query JSON. Поэтому текст «Данные не отправляются на сервер» некорректен для открытия share URL: query приходит серверу. Нужны preview/merge/replace, однократный импорт с удалением параметра, восстановление предыдущего плана, обработка storage errors и вычисляемый возраст. Рассмотреть fragment для переносимого payload. Критерий: чужая ссылка не стирает план без выбора, reload не воскрешает удалённое, старые сведения явно устаревшие.

R07 · P1 · Координатная схема

components/ActivityMap.astro рисует все переданные items; index.astro:100 не ограничивает их одним водоёмом или точностью координат. На одной сетке смешиваются независимые системы координат. Несколько элементов одной grid cell накладываются, минимальная ширина маркера превышает ширину ячейки; overflow hidden может обрезать содержимое без document overflow. Нужны группировка по водоёму, явные approximate/area-состояния, обработка совпадений и доступный список. Критерий: все точки различимы и достижимы мышью/клавиатурой на 320 px, водоём виден в подписи, схемы разных водоёмов не смешаны. Без cooldown.

R08 · P1 · Достоверность рекомендаций и стоимость аналитики

routers/analytics.py:32 разрешает публичному клиенту снизить min_samples и min_players до 1 и получить recommendation, хотя UI обещает минимум 3/2. Группировка идёт по raw строке, а не canonical identity; один подтверждённый ID может дать ссылку всей группе, содержащей unresolved-строки. Данные выбираются по reported_at: старый улов, импортированный сегодня, выглядит свежим. Все отчёты и компоненты окна загружаются в Python без лимита ответа. Нужны неизменяемый публичный порог, явное время улова/получения, conservative identity-группировка и измерение фактического endpoint на больших fixtures. Критерий: 1/1 никогда не рекомендация, unresolved не наследует подтверждение, старый улов не представлен свежим; ограниченный ответ и документированный бюджет.

R09 · P1 · Полнота удаления и retention

tackle_components.py:35 копирует source_url/raw_payload в дочерние записи. retention.py:94 и routers/admin.py при удалении очищают только родительский CatchReport. Дочерние копии provenance остаются. Нужно определить поля, содержащие личные сведения, и каскадно очищать их с сохранением разрешённых агрегатов. Удаление S3 до commit БД также требует повторяемой процедуры при отказе транзакции. Критерий: повторная очистка безопасна, чувствительные копии не остаются в дочерних payload, ошибки между S3/БД восстанавливаются. Без cooldown.

R10 · P1 · Согласованная модель cooldown

community_cli.py:385 освобождает резерв при любом URLError кроме HTTPError. После ответа-редиректа DNS-ошибка следующего hop тоже попадает сюда, хотя первый сервер уже получил запрос. Community CLI и media CLI используют общий helper и JSON-состояние при одинаковом state-file, scheduler — отдельную историю БД. Media CLI не применяет новую отмену резерва при локальном сбое. Единого координирующего хранилища и одинаковой классификации исходов у всех путей нет. Нужны признаки стадии запроса и единая координация запусков; отменять резерв только при доказанном отсутствии обращения. Критерий: DNS до первого запроса освобождает свой резерв, сбой после redirect — нет; CLI и scheduler не расходуют одно окно одновременно. Проверять offline, без запросов к RF4DB.

R11 · P2 · Media: подписи, происхождение и размеры

EntityMedia.astro:16 при любом размере <256 заявляет, что источник не содержит проверенной крупной версии; размеры сами этого не доказывают. Новая подпись не проверена в compact/light/dark после добавления. media_catalog.py:40 считает всякий неизвестный URL официальным RF4 и распознаёт домен подстрокой. Нужны unknown-источник по умолчанию, точное сопоставление hostname, отдельное подтверждение отсутствия альтернатив, перенос длинных подписей и review низкого разрешения по всем типам assets. Для revoked media отдельно определить TTL: годовой immutable cache позволяет старому клиенту показывать ранее выданный файл. Критерий: неизвестный источник не «официальный», компактная подпись не обрезана, обещания отзыва соответствуют фактической cache-политике. Без загрузок.

R12 · P2 · Честная визуальная и административная приёмка

docs/ux-reference-review-2026-09-21.md описывает representative light/mobile review и прямо оставляет production CLS/INP и хранение references открытыми. Поэтому фраза D07 «подтверждены WCAG AA, отсутствие CLS» не доказана. Последняя проверка G07 видела только empty-state (в БД нет снастей/сборок), U06 — DOM одной точки. Наличие кнопки не подтверждает её работу. Административная форма входа не заменяет authenticated review очереди и конфликтов. Критерий: привязанные к revision screenshots light/dark на mobile/desktop, наполненные, длинные, ошибочные состояния, keyboard, contrast, theme без потери ввода и реальные действия на изолированных fixtures. Production metrics остаются отдельным gate. Это локальная приёмка, cooldown не нужен.

R13 · P2 · Вернуть зелёные проверки и устойчивые CI artifacts

Исправить две устаревшие проверки, описанные выше, добавить адресные regressions для R01–R12 после исправления функций. CI есть в .gitea/workflows/, а не в .github: Python/миграции, Astro, Compose E2E и pip-audit уже настроены. Нужны сохранение успешных visual reports, явный Node/Python baseline, проверка web dependency advisories и версий контейнеров. Текущий аудит не подтверждает отсутствие CVE; внешнюю проверку зависимостей выполнять отдельно.

Улучшения продукта и эксплуатации

• R14 · P2 · Разделение подтверждённого и демонстрационного каталога. seed.py создаёт справочники, точки и описания до проверки seed_demo_data. При production false демо-уловы выключены, но редакционные описания точек остаются. Отделить обязательный справочник от demo seed, показывать полноту реального каталога/unknown отдельно от числа загруженных элементов. Счётчик media-файлов не означает наличие canonical карточек. Критерий: чистый production не создаёт неподтверждённых описаний, local fixtures явно обозначены.
• R15 · P2 · Восстановление пользовательских действий. Сохранение формы при 422/429/timeout, понятный конфликт повторной отправки, undo удаления из плана, общие utility для clipboard/storage. Критерий: пользователь не вводит весь улов заново и различает «улов сохранён, фото не загружено» от полного отказа.
• R16 · P2 · Измеряемая производительность. Media manifest перечитывается и сканируется для каждого изображения (published_file); аналитика грузит ORM объекты целиком. Измерить реальный API, RSS, число SQL и количество reads, затем добавить индекс digest/mtime cache и bounded aggregation. SQL-only query-plan drill не подменяет endpoint measurement. Redis заранее не нужен.
• R17 · P2 · Публичная навигация и SEO снастей. sitemap.xml.ts перечисляет рыбу/водоёмы/точки, но не каталог и карточки снастей. Добавить только реально подтверждённые индексируемые карточки; единый переход из каталога к снастям, объяснение справочника и аналитики, корректные пустые/недоступные состояния.
• R18 · P1 · Release gate и инфраструктурные границы. Dev Compose публикует API, web и MinIO console на всех интерфейсах; defaults известны. Привязать dev-порты к loopback либо явно выделить opt-in LAN. Проверить production proxy/client-IP цепочку и rate-limit на двух клиентах. Секреты, DNS/TLS, внешние backup/alerts, права источников и пилот остаются отдельными блокерами.

Состояние данных и корректировка плана

В .cache/waterbodies/rf4db-level_019_american_pond-20260921.json уже есть сохранённый snapshot: 19 видов, 2 URL изображений, description null, point_urls пустой. Старое утверждение ROADMAP о текущей Cloudflare-странице устарело. Это подтверждение локального файла, не нового сетевого запроса и не импорта. Подготовка его versioned provenance и offline import может выполняться без cooldown; полнота всех detail-страниц W02 всё ещё не достигнута.

Повторно открываются A04/B23 (media mutation), G06/G07, U04/U05, B25/D07/A06/U06. Остальные ранее реализованные функции не объявляются несуществующими. Новые критерии и порядок работ — в ROADMAP; полный пункт закрывается только после устранения дефекта и адресной приёмки.