diff --git a/README.md b/README.md index 70b6e4e..af1394b 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,9 @@ RF4 Spotter — неофициальный сервис свежих точек ## Статус разработки -- этапы 0 и 1 завершены; -- этап 2, официальный импорт, завершён технически; автоматический профиль остаётся выключенным до явного разрешения владельца источника; -- этап 3 функционально завершён: форма, раздельные ошибки создания/скриншота с повторной загрузкой, MinIO, модерация, удаление с аудитом и постоянный rate limit готовы; -- для полного пользовательского сценария добавлен E2E-тест `отправка → pending → модерация → публичная статистика`; -- начат этап 4: формула индекса зафиксирована, детерминированные агрегаты и правила включения данных покрыты тестами; далее — сквозная проверка фильтров; -- RF4DB/RF4-STAT загружаются в изолированный staging; добавлены канонические алиасы и ручная очередь публикации. -- RF4MAP и RF4 Posts разрешены для исследовательского staging с интервалом не менее 30 минут на источник; CLI обеспечивает cooldown, источники выключены и не публикуются автоматически. +Функциональный MVP и локальный production-контур готовы к закрытой альфе: официальный импорт, пользовательские заявки, модерация, объяснимый индекс, staging внешних источников, адаптивный Astro UI, миграции, резервное копирование, retention, мониторинг и security/accessibility-проверки реализованы. Автоматические импорты внешних источников выключены. Публичный запуск блокируют покупка и настройка сервера, DNS/TLS, реальные секреты, внешний backup и канал уведомлений. + +RF4DB/RF4-STAT/RF4MAP/RF4 Posts принимаются только в изолированный staging и не влияют на индекс без ручного сопоставления и публикации. Для разрешённых community-источников действует интервал не менее 30 минут на источник. Подробный план и актуальные чекбоксы находятся в [`docs/ROADMAP.md`](docs/ROADMAP.md). Результаты проверки интерфейса и пять приоритетных UX-пакетов описаны в [`docs/UI_UX_AUDIT.md`](docs/UI_UX_AUDIT.md). @@ -24,6 +20,19 @@ Host-side мониторинг контейнеров, readiness, диска, р Фактическое состояние DNS/TLS домена и серверный чек-лист ведутся в [`docs/deployment-status.md`](docs/deployment-status.md). Результаты security review и остаточные ограничения закрытой альфы записаны в [`docs/security-review.md`](docs/security-review.md). +## Архитектура + +```text +Caddy :80/:443 + ├─ Astro SSR web + ├─ FastAPI /api и /health + └─ MinIO: только health и подписанные объекты +FastAPI ─ PostgreSQL 17 + └ MinIO/S3 +``` + +Наружу production-профиль публикует только Caddy. PostgreSQL, API, Astro и MinIO находятся во внутренних Docker-сетях. Caddy завершает TLS и защищает административные маршруты Basic Auth; административный API дополнительно требует bearer token. + Gitea Actions workflow `.gitea/workflows/ci.yml` на каждый push и pull request проверяет Python, миграции на чистой PostgreSQL, Astro build и полный Compose/Playwright-сценарий. При падении E2E сохраняются логи контейнеров и Playwright-артефакты. Актуальная инвентаризация источников и правила подключения адаптеров находятся в [`docs/data-source-audit.md`](docs/data-source-audit.md). Разрешённый технический пилот RF4DB/RF4-STAT описан в [`docs/community-source-pilot.md`](docs/community-source-pilot.md), а статус разрешений и лимитов — в [`docs/data-permissions.md`](docs/data-permissions.md). Данные сохраняются только в промежуточный staging и не влияют на индекс без явной проверки и публикации администратором. @@ -84,6 +93,20 @@ docker compose up --build Переменные и локальные значения по умолчанию перечислены в [.env.example](.env.example). Секретов в репозитории нет. +### Основные переменные окружения + +| Группа | Переменные | +|---|---| +| База | `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `DATABASE_URL` | +| Домены | `SITE_DOMAIN`, `FILES_DOMAIN`, `ACME_EMAIL` | +| Администрирование | `ADMIN_TOKEN`, `ADMIN_BASIC_USER`, `ADMIN_BASIC_PASSWORD_HASH` | +| Объекты | `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `S3_BUCKET` | +| Импорт | `OFFICIAL_RECORDS_URL`, `OFFICIAL_RECORDS_REGION`, `OFFICIAL_RECORDS_CATEGORY`, `OFFICIAL_IMPORT_REQUIRED`, `IMPORT_INTERVAL_SECONDS` | +| Privacy/retention | `RATE_LIMIT_SECRET`, `RETENTION_*_DAYS` | +| Эксплуатация | `BACKUP_ROOT`, `MONITOR_*`, `LOG_LEVEL` | + +Полный production-шаблон с комментариями находится в [.env.production.example](.env.production.example). Перед запуском `deploy/preflight.sh` блокирует известные заглушки и ошибочное повторное использование MinIO credentials. + ## Что реализовано - FastAPI и SQLAlchemy 2; @@ -126,6 +149,8 @@ cd apps/web npm install npm run build npm audit --omit=dev +npm run audit:axe +npm run audit:lighthouse ``` E2E после запуска Compose: @@ -173,6 +198,25 @@ curl -H "Authorization: Bearer change-me-in-production" \ Администратор может одобрить, отклонить или удалить сообщение. Удаление очищает ник, комментарий, исходную ссылку и объект скриншота, исключает запись из статистики, но сохраняет обезличенный факт действия в журнале аудита. +## Эксплуатация production + +- первый запуск, обновление и preflight: [deploy/README.md](deploy/README.md); +- backup/restore и учебное восстановление: [deploy/README.md](deploy/README.md#6-резервное-копирование-и-восстановление); +- мониторинг, systemd timer и реакция на сбои: [docs/production-monitoring.md](docs/production-monitoring.md); +- сроки хранения и очистка: [docs/data-retention.md](docs/data-retention.md); +- лимиты и планы запросов: [docs/query-performance.md](docs/query-performance.md). + +Production-логи структурированы в JSON и не содержат query string, IP, заголовков авторизации или пользовательских payload. Docker хранит не более пяти файлов по 10 МБ на сервис. Ежедневное обслуживание выполняет backup до retention и защищено от параллельного запуска. + +## Известные ограничения альфы + +- нет пользовательских аккаунтов, OCR, Telegram-бота и уведомлений о клёве; +- community-источники требуют ручной проверки; неполные наблюдения не публикуются; +- offset pagination рассчитана на пилотные объёмы, не на бесконечную ленту; +- Lighthouse LCP локального прогона — 9,3 с; оптимизация изображения/CDN остаётся после размещения; +- один сервер остаётся точкой отказа, поэтому обязательны внешний backup и мониторинг; +- текущий публичный DNS/TLS не подтверждён, см. [статус развёртывания](docs/deployment-status.md). + ## Исследовательский парсер официальных рекордов ```bash diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 0d5553c..8c8437c 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -79,7 +79,7 @@ - [x] Заменить slug-фильтры справочниками, добавить сброс и самодостаточные мобильные строки рекордов (пакет D UI/UX-аудита; detail уже адаптивен). - [x] Завершить accessibility/admin safety пакет с воспроизводимыми axe/Lighthouse-командами (пакет E). - [ ] Добавить smoke-проверку административной очереди внешних источников на desktop/mobile без публикации реальных записей. -- [ ] Обновить README: архитектура, все переменные окружения, импорт, модерация, backup/restore, эксплуатация логов и известные ограничения. +- [x] Обновить README: актуальный статус, архитектура, группы переменных окружения, импорт, модерация, backup/restore, эксплуатация логов и известные ограничения. - [ ] Выбрать лицензию кода и политику использования данных. - [ ] Завершить production-профиль для `rf4spotter.ru`: приложение и `deploy/preflight.sh` готовы; внешняя проверка 7 сентября не установила соединение с обоими доменами, требуются IP целевого сервера, DNS, запуск и канал уведомлений (`docs/deployment-status.md`). - [ ] Заменить демонстрационные секреты и определить целевое размещение перед внешней публикацией. @@ -119,8 +119,8 @@ Технический production-контур, health/readiness, backup/restore и безопасные логи готовы. Следующие пункты выполняются строго по одному: -1. мониторинг, DNS/TLS и проверка production-профиля на целевом сервере; -2. финальное обновление README, лицензия кода и политика данных. +1. выбрать лицензию кода и оформить политику использования данных; +2. мониторинг, DNS/TLS и проверка production-профиля на целевом сервере. После каждого пункта необходимо: