План работ RF4 Spotter

Этот файл — рабочий источник правды по развитию проекта. После завершения задачи её чекбокс меняется с [ ] на [x], рядом добавляется ссылка на коммит или короткое подтверждение проверки. Новые задачи добавляются в соответствующий этап, а не хранятся только в переписке.

Последняя сверка плана со спецификацией и кодом: 4 сентября 2026 года.

Обозначения:

[x] — выполнено и проверено;
[ ] — ещё не выполнено;
пункты выполняются сверху вниз, если явно не зафиксирована другая зависимость.

Текущее состояние

Этап 0: исследован официальный источник, добавлены парсер, фикстуры и docs/data-sources.md (a6f91a1).
Этап 1: создан Docker-каркас Astro + FastAPI + PostgreSQL, миграции, seed, публичный API и базовый E2E (d3a4524).
Основная часть этапа 2: адаптер официальных рекордов, нормализация, дедупликация, журнал импорта и страница рекордов (d3a4524).
Основная часть этапа 3: форма пользовательского улова, модерация, rate limit, MinIO и безопасная обработка скриншотов (6d536d0, c524272).
Визуальный референс перенесён в Astro без Next.js, Vinext и React (c524272).

Этап 2 — завершить официальный импорт

Добавить административный endpoint ручного запуска импорта POST /api/v1/admin/imports/official-records (проверено API-тестом).
Привести журнал импорта к административному контракту GET /api/v1/admin/imports с авторизацией, пагинацией и стабильной сортировкой (проверено API-тестом).
Добавить HTTP-кэширование источника (ETag/Last-Modified, если источник их отдаёт) и сохранить диагностические метаданные ответа (миграция 0005, тест условного запроса и 304).
Добавить планировщик импорта с безопасной частотой по умолчанию один раз в 60 минут; отдельный opt-in контейнер/процесс (профиль scheduler, обычным запуском не активируется).
Защитить официальный импорт PostgreSQL advisory lock или эквивалентом, чтобы ручной endpoint и несколько scheduler-процессов не импортировали одну категорию одновременно.
Проверить актуальные robots.txt и условия использования перед включением расписания; результат записать в docs/data-sources.md (robots.txt вернул 404; автоматический профиль оставлен выключенным до явного разрешения).
Добавить интеграционные тесты: повторный импорт не создаёт дубликаты, сбой источника не удаляет данные, изменение DOM завершается понятной ошибкой.

Критерий готовности: официальный импорт запускается вручную и по расписанию, наблюдаем, идемпотентен и безопасно переживает недоступность источника.

Этап 3 — завершить пользовательские уловы

Добавить административный веб-интерфейс очереди модерации поверх существующего API (/admin/moderation, токен только в памяти страницы).
Показать скриншот, данные улова и причину решения; реализовать действия «одобрить» и «отклонить» (проверено в браузере на desktop и 390 px).
Добавить удаление пользовательского сообщения администратором с аудитом действия (обезличивание записи, удаление объекта MinIO, миграция 0006).
Заменить in-memory rate limit на общее хранилище, пригодное для нескольких API-процессов и перезапусков (PostgreSQL, HMAC-отпечаток без хранения исходного IP, миграция 0007).
Валидировать одновременно содержимое, MIME, расширение и лимит изображения; добавить тесты каждого отказа.
Добавить сквозной тест: отправка → pending → модерация → появление одобренного улова в публичной статистике (Compose/Playwright: 2 passed).
Добавить понятные состояния успеха и ошибок загрузки в форму, включая отдельную ошибку скриншота без потери уже созданной заявки (повторная загрузка по ID сохранённой заявки).

Критерий готовности: полный пользовательский сценарий проходит через браузер, а модератору не нужен ручной вызов API.

Этап 4 — индекс клёва

Сверить текущую формулу активности и уверенности с разделом 11 спецификации и зафиксировать формулу в docs/activity-index.md.
Покрыть unit-тестами затухание по свежести, доверие к официальным и пользовательским источникам, повторные сообщения одного игрока и вклад разных игроков.
Не учитывать pending/rejected/удалённые записи и доказать это тестами.
Добавить детерминированные агрегаты для окон 6, 12, 24 и 72 часа.
На карточке и странице точки показывать человекочитаемое объяснение оценки и объём данных, на котором она основана (unit-тест объяснения и Astro build).
Реализовать состояния «данных мало», «данных нет», «источник недоступен» и ошибки валидации фильтров (Astro build; браузерная проверка войдёт в общий прогон фильтров).
Проверить фильтры главной страницы сквозным тестом на desktop и mobile (Playwright, 1280 px и 390 px).

Критерий готовности: оценка объяснима, воспроизводима тестами и никогда не маскирует недостаток или устаревание данных.

Подготовка MVP к пилоту

Добавить health/readiness-проверки PostgreSQL, MinIO, API и импорта; отразить их в Compose (/health без зависимостей, /ready с компонентами и режимом обязательного импорта).
Добавить структурированные JSON-логи без пользовательских секретов и персональных технических данных (whitelist полей, redaction, request ID; Uvicorn access-log отключён).
Добавить Gitea Actions CI: backend tests, Astro check/build, E2E и применение всех миграций на чистой PostgreSQL; сохранять логи Compose и Playwright-артефакты при падении (.gitea/workflows/ci.yml).
Добавить отдельный тест полного bootstrap: пустые volumes → миграции → seed → readiness → основной E2E.
Сделать seed устойчивым к частично заполненной БД и покрыть повторный/частичный запуск тестом; текущая реализация прекращает работу при наличии любой рыбы.
Проверить списочные API по требованию раздела 12: пагинация, предсказуемая сортировка и валидация фильтров для справочников, импортов, модерации и внешнего staging.
Проверить необходимые индексы PostgreSQL и планы запросов для activity, модерации, дедупликации и очистки rate limit; зафиксировать допустимый бюджет запросов пилота.
Провести security-проверку admin-аутентификации, CORS, security headers, загрузок и управления секретами; вынести допустимые origins в конфигурацию и исключить демонстрационные секреты в production-режиме.
Проверить авторизацию повторной загрузки скриншота: один UUID pending-заявки не должен быть достаточным полномочием для изменения чужой записи.
Определить сроки хранения ников, исходных payload, staging-наблюдений, moderation events и submission attempts; добавить документированную очистку/анонимизацию.
Добавить резервное копирование и документированное восстановление PostgreSQL и MinIO; проверить восстановление на отдельных временных volumes.
Проверить доступность интерфейса: клавиатура, focus states, контраст, подписи полей и семантика таблиц/карточек.
Провести Lighthouse-проверку основных страниц и устранить критические проблемы производительности.
Добавить smoke-проверку административной очереди внешних источников на desktop/mobile без публикации реальных записей.
Обновить README: архитектура, все переменные окружения, импорт, модерация, backup/restore, эксплуатация логов и известные ограничения.
Выбрать лицензию кода и политику использования данных.
Определить production-профиль Compose/развёртывания: TLS/reverse proxy, домены, CORS, volumes, restart policy, resource limits и порядок обновления миграций.
Заменить демонстрационные секреты и определить целевое размещение перед внешней публикацией.

Источники данных и согласование

Провести аудит подключённых источников, потенциальных поставщиков и всех существующих парсеров; результат записан в docs/data-source-audit.md.
Проверить оба официальных HTML-парсера на актуальной странице и добавить общий контрактный тест эквивалентности.
Добавить data_source и алиасы рыб/водоёмов до подключения второго автоматического источника (миграции 0008–0009; алиасы приманок уже нормализуются в bait).
Вынести общий официальный DOM-парсер, устранив дублирование исследовательской и продуктивной реализации (rf4_research/official_parser.py).
Добавить отдельную фикстуру и безопасный ручной импорт недельных официальных рекордов одной категории.
Получено подтверждение владельца проекта о разрешениях RF4DB и RF4-STAT; добавлены пилотные HTML-парсеры и отчёт docs/community-source-pilot.md.
Добавлены общий nullable-контракт, парсер detail-страницы RF4DB и ограниченный read-only CLI для RF4DB/RF4-STAT.
Исследовать дополнительные публичные источники: добавлены read-only detail-парсеры RF4MAP и RF4 Posts, живые контрольные прогоны и тест разделения пространств ID; rf4pro/Farm.Trof отклонены для текущего пилота.
До подключения RF4MAP/RF4 Posts получить разрешение и зафиксировать лимиты, атрибуцию, правила изображений и семантику агрегированной точки RF4 Posts.
Зафиксировать проектное подтверждение разрешений, текущую атрибуцию и консервативные пилотные лимиты в docs/data-permissions.md.
Приложить или сослаться на первичный документ разрешения и зафиксировать точные продуктивные лимиты, срок хранения, удаление и обязательную атрибуцию до включения scheduler RF4DB/RF4-STAT.
Добавить staging-модель внешних наблюдений и идемпотентный импорт RF4DB/RF4-STAT без автоматического влияния на индекс (миграция 0008, сквозной контрактный тест).
Добавить административную очередь сопоставления staging-записей с каноническими рыбами/водоёмами и явную публикацию в catch_report (/admin/external-sources, миграция 0009; неполные записи публиковать запрещено).
Найти разрешённый способ получать полные наблюдения с рыбой, водоёмом, координатами и весом из одного источника либо через подтверждённый общий ID; текущие 139 записей неполны и не публикуются.
Добавить безопасные подсказки алиасов по уже подтверждённым сопоставлениям без автоматической публикации и тест конфликтующих алиасов.
Добавить управляемый повторный импорт staging с отчётом created/updated/rejected, лимитами запросов и наблюдаемым отказом при изменении DOM; регулярный запуск оставить выключенным до фиксации условий.
Определить процедуру повторной проверки опубликованного внешнего улова при изменении или удалении записи у источника.
Согласовать один добровольный канал сообщества и правила происхождения, модерации и удаления сообщений.

Этап 5 — пилот

Зафиксировать короткий сценарий приёмки пилота и измеримые критерии: успешная отправка/модерация, понятность оценки, свежесть данных и допустимое время ответа.
Согласовать первые категории рекордов, водоёмы и виды рыб.
Наполнить базу небольшим разрешённым набором реальных данных.
Провести тестирование с несколькими игроками по подготовленному сценарию.
Собрать обратную связь по полезности точек, понятности уверенности, форме улова и мобильному интерфейсу.
Исправить блокирующие проблемы пилота и повторить проверку критериев MVP из раздела 16 спецификации.
Только после пилота принять решение по OCR, Telegram, профилям, уведомлениям и импорту сообществ.

Ближайший рабочий пакет

Технические health/readiness и безопасные логи готовы. Следующие пункты выполняются строго по одному:

защита официального импорта от конкурентных запусков;
полный bootstrap-тест и исправление seed для частично заполненной БД;
security-аудит admin/CORS/headers/secrets и повторной загрузки скриншота;
backup/restore PostgreSQL и MinIO с реальной проверкой восстановления;
пагинация/сортировка списочных API и индексы PostgreSQL;
accessibility и Lighthouse;
production-профиль и финальное обновление README.

После каждого пункта необходимо:

запустить затронутые unit/integration-тесты;
выполнить docker compose up --build -d и проверить health;
для UI-изменений проверить desktop и ширину 390 px;
обновить чекбокс в этом файле;
зафиксировать результат отдельным небольшим коммитом.

20 KiB Raw Blame History Unescape Escape