From 44c3e797aa11838e589d4546d889e3355958db90 Mon Sep 17 00:00:00 2001 From: IK Date: Thu, 3 Sep 2026 07:56:32 +0700 Subject: [PATCH] Add tracked MVP delivery roadmap --- docs/ROADMAP.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/ROADMAP.md diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..b326977 --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,91 @@ +# План работ RF4 Spotter + +Этот файл — рабочий источник правды по развитию проекта. После завершения задачи её чекбокс меняется с `[ ]` на `[x]`, рядом добавляется ссылка на коммит или короткое подтверждение проверки. Новые задачи добавляются в соответствующий этап, а не хранятся только в переписке. + +Обозначения: + +- `[x]` — выполнено и проверено; +- `[ ]` — ещё не выполнено; +- пункты выполняются сверху вниз, если явно не зафиксирована другая зависимость. + +## Текущее состояние + +- [x] Этап 0: исследован официальный источник, добавлены парсер, фикстуры и `docs/data-sources.md` (`a6f91a1`). +- [x] Этап 1: создан Docker-каркас Astro + FastAPI + PostgreSQL, миграции, seed, публичный API и базовый E2E (`d3a4524`). +- [x] Основная часть этапа 2: адаптер официальных рекордов, нормализация, дедупликация, журнал импорта и страница рекордов (`d3a4524`). +- [x] Основная часть этапа 3: форма пользовательского улова, модерация, rate limit, MinIO и безопасная обработка скриншотов (`6d536d0`, `c524272`). +- [x] Визуальный референс перенесён в Astro без Next.js, Vinext и React (`c524272`). + +## Этап 2 — завершить официальный импорт + +- [ ] Добавить административный endpoint ручного запуска импорта `POST /api/v1/admin/imports/official-records`. +- [ ] Привести журнал импорта к административному контракту `GET /api/v1/admin/imports` с авторизацией, пагинацией и стабильной сортировкой. +- [ ] Добавить HTTP-кэширование источника (`ETag`/`Last-Modified`, если источник их отдаёт) и сохранить диагностические метаданные ответа. +- [ ] Добавить планировщик импорта с безопасной частотой по умолчанию один раз в 60 минут; отдельный контейнер/процесс без дублирования запусков. +- [ ] Проверить актуальные `robots.txt` и условия использования перед включением расписания; результат записать в `docs/data-sources.md`. +- [ ] Добавить интеграционные тесты: повторный импорт не создаёт дубликаты, сбой источника не удаляет данные, изменение DOM завершается понятной ошибкой. + +Критерий готовности: официальный импорт запускается вручную и по расписанию, наблюдаем, идемпотентен и безопасно переживает недоступность источника. + +## Этап 3 — завершить пользовательские уловы + +- [ ] Добавить административный веб-интерфейс очереди модерации поверх существующего API. +- [ ] Показать скриншот, данные улова и причину решения; реализовать действия «одобрить» и «отклонить». +- [ ] Добавить удаление пользовательского сообщения администратором с аудитом действия. +- [ ] Заменить in-memory rate limit на общее хранилище, пригодное для нескольких API-процессов и перезапусков. +- [ ] Валидировать одновременно содержимое, MIME, расширение и лимит изображения; добавить тесты каждого отказа. +- [ ] Добавить сквозной тест: отправка → pending → модерация → появление одобренного улова в публичной статистике. +- [ ] Добавить понятные состояния успеха и ошибок загрузки в форму, включая отдельную ошибку скриншота без потери уже созданной заявки. + +Критерий готовности: полный пользовательский сценарий проходит через браузер, а модератору не нужен ручной вызов API. + +## Этап 4 — индекс клёва + +- [ ] Сверить текущую формулу активности и уверенности с разделом 9 спецификации и зафиксировать формулу в `docs/activity-index.md`. +- [ ] Покрыть unit-тестами затухание по свежести, вес официальных и пользовательских источников, дубликаты и вклад разных игроков. +- [ ] Не учитывать pending/rejected записи и доказать это тестами. +- [ ] Добавить детерминированные агрегаты для окон 6, 12, 24 и 72 часа. +- [ ] На карточке и странице точки показывать человекочитаемое объяснение оценки и объём данных, на котором она основана. +- [ ] Реализовать и проверить состояния «данных мало», «данных нет», «источник недоступен» и ошибки валидации фильтров. +- [ ] Проверить фильтры главной страницы сквозным тестом на desktop и mobile. + +Критерий готовности: оценка объяснима, воспроизводима тестами и никогда не маскирует недостаток или устаревание данных. + +## Подготовка MVP к пилоту + +- [ ] Добавить health/readiness-проверки PostgreSQL, MinIO, API и импорта; отразить их в Compose. +- [ ] Добавить структурированные логи без пользовательских секретов и персональных технических данных. +- [ ] Добавить резервное копирование и документированное восстановление PostgreSQL и MinIO. +- [ ] Провести security-проверку admin-аутентификации, CORS, заголовков, загрузок и управления секретами. +- [ ] Добавить CI: backend tests, Astro check/build, E2E и проверка миграций на чистой БД. +- [ ] Проверить доступность интерфейса: клавиатура, focus states, контраст, подписи полей и семантика таблиц/карточек. +- [ ] Провести Lighthouse-проверку основных страниц и устранить критические проблемы производительности. +- [ ] Обновить README: архитектура, все переменные окружения, импорт, модерация, backup/restore и известные ограничения. +- [ ] Выбрать лицензию кода и политику использования данных. +- [ ] Заменить демонстрационные секреты и определить целевое размещение перед внешней публикацией. + +## Этап 5 — пилот + +- [ ] Согласовать первые категории рекордов, водоёмы и виды рыб. +- [ ] Наполнить базу небольшим разрешённым набором реальных данных. +- [ ] Провести тестирование с несколькими игроками по подготовленному сценарию. +- [ ] Собрать обратную связь по полезности точек, понятности уверенности, форме улова и мобильному интерфейсу. +- [ ] Исправить блокирующие проблемы пилота и повторить проверку критериев MVP из раздела 16 спецификации. +- [ ] Только после пилота принять решение по OCR, Telegram, профилям, уведомлениям и импорту сообществ. + +## Ближайший рабочий пакет + +Следующим выполняется завершение этапа 2: + +1. административные endpoints импорта; +2. тесты идемпотентности и безопасного сбоя; +3. кэширование и диагностические метаданные; +4. планировщик на 60 минут после повторной проверки допустимой частоты источника. + +После каждого пункта необходимо: + +1. запустить затронутые unit/integration-тесты; +2. выполнить `docker compose up --build -d` и проверить health; +3. для UI-изменений проверить desktop и ширину 390 px; +4. обновить чекбокс в этом файле; +5. зафиксировать результат отдельным небольшим коммитом.