Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

product-catalog

Витрина товаров: читает каталог краулера по его HTTP API и показывает товары, цены, кэшбэк и историю цен.

Ни ASP.NET, ни ORM, ни SQL, ни миграций: Next.js обращается к краулеру по сети и не знает, как устроена база.


Что это за проект и чего в нём нет

Проект не владеет схемой и не знает её. Он не подключается к PostgreSQL, не держит строки подключения и не пишет ни одного SQL-запроса. Поэтому здесь нет:

Нет Почему
SQL Схема принадлежит краулеру и меняется, когда он мигрирует. Витрина читает HTTP-ответы, у которых есть контракт — contract/catalog-v1.openapi.yaml, документ краулера. Витрина не может разойтись со схемой, потому что она её не видит
Копии схемы dev/db/ хранил копии миграций краулера, а just schema-sync следил за их совпадением. Копия — это копия ожиданий о схеме, и её поддерживал скрипт, который должен был знать про соседний checkout. Копии нет: схему создаёт сам краулер, своими миграциями
ORM Каждая из шести страниц читает предсказуемый набор полей; ORM добавил бы слой, который пришлось бы обходить при каждом новом поле
Собственного словаря Названия полей в ответах API — те же, что были у витрины (priceKopecks, cashbackPercent). Перевод имён колонок в имена полей происходит один раз, на стороне краулера
Кэша страниц на сборке Сборка не обращается к API (см. «Известные ограничения»)

Почему копии схемы нет

Копия миграций в dev/db/ была задумана как путь отката: если выкат витрины что-то ломает, старая схема под рукой. Но витрина не пишет SQL и не меняет базу — выкатывается только её образ, а база принадлежит краулеру. Откатывать в ней нечего: прежняя версия витрины читала те же колонки, что и новая, и миграция краулера её не ломает. Копия схемы давала ложное чувство безопасности: выглядела как страховка, которой никто не пользовался, и при этом стоила чужого pull request'а — гейт, сверявший копию с оригиналом, ронял чужие изменения из-за чужого репозитория.

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

Граница доступа

Раньше витрина получала права SELECT в чужой базе и обещала их не превысить. Теперь у неё нет ни одного credential'а от базы: только URL API и сервисный ключ. Граница держится на стороне краулера:

  1. Роль в Postgres. Каталог читает через wb_catalog_ro — роль с CONNECT, USAGE и SELECT, без владения объектами и без членства в других ролях. Права выдаёт скрипт краулера db/roles/provision-catalog-readonly-role.sql, и запускает его тот, кто администрирует базу краулера, не деплой витрины.
  2. Сессия. Соединения каталога открываются с default_transaction_read_only=on, плюс statement_timeout и timezone=UTC.
  3. API. Публичный маршрут /api/catalog/** закрыт на прокси. Без ключа каталог недоступен ни из одной точки.

Что именно заявлено — узко: API не опубликован наружу, публичный маршрут закрыт, без ключа каталог недоступен ни из одной точки. Заявление «только витрина может обращаться к каталогу» не делается: общая сеть контейнеров и ключ такой изоляции не дают.

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

Быстрый старт

just stack-up   # база + краулер (он сам создаёт схему и наполняет её) + витрина

Отдельно: just db-up — только база и краулер, just dev — только витрина на :3000.

Данные в dev — синтетические

Краулер сам наполняет базу собственным демо-сидом: 4 каталога, ~1200 наблюдений товаров, детерминированно. Сид защищён пятью барьерами сразу: флаг, профиль demo, точная роль, маркер базы и пустота таблиц — заполнить рабочую базу можно, только если совпало всё, включая роль, которой в рабочей базе нет.

Сид намеренно воспроизводит состояния, которых нет в «идеальных» данных, потому что именно они ломают вёрстку:

  • каталог настроен, но пуст;
  • часть карточек без картинки — срабатывает заглушка;
  • у части товаров нет цены, скидки, кэшбэка или match_id;
  • один товар встречается в нескольких каталогах — срабатывает свёртка по match_id в «Топе по кэшбэку»;
  • у товара несколько наблюдений цены — строится график истории.

Проверка

just check     # гейты из config/gates.yaml — тот же список, что и в CI

contract-check поднимает настоящий образ краулера и проверяет живые ответы против контракта валидатором JSON Schema — это единственная проверка, которая ловит расхождение между тем, что краулер отдаёт, и тем, что витрина ожидает.

Контрактная проверка разложена по слоям, и каждый слой — отдельный файл под tests/contract/: имя слоя в отчёте о падении говорит, что именно не сошлось, а не «контракт». Слои: закреплённый образ (pinned-image), документ, который отдаёт API (tests/api-contract.test.ts), поля ответа (fields), схема документа (schema), страница и порядок (paging), поиск и фильтры (search), страница товара (product), топ скидок (top-deals), каталоги и счётчики (targets).

Гейт Что не даёт
architecture.test.ts SQL в src/lib/**; потерю read-only-guard; незакрытый whitelist сортировки; зависимость от pg; прямые обращения к базе
api-client.test.ts Ошибки HTTP-клиента: код ответа, ретраи, обрезка ключа из сообщений, разбор параметров запроса; потерю X-Request-Id в сообщении об ошибке
tests/contract/* Расхождение между живыми ответами краулера и контрактом: поднимает образ краулера, проверяет, что закреплён тот самый образ, что отдаёт контракт, что ответы несут поля документа и валидны по его схеме
contract-types.test.ts, contract-types-axis.test.ts Устаревшие типы: контракт краулера изменился, а сгенерированные типы витрины — нет; и то, что контракт берётся у пина, а не у main краулера
server-rendering.test.ts loading.tsx в корне (HTML становится скелетом); обработчики событий в Server Component

Типы — из контракта, а не рукопись

src/lib/api/types.generated.ts генерируется из документа контракта краулера (npm run contract-types) и коммитится. Типы витрины в src/lib/api/types.ts выводятся из сгенерированного файла, поэтому рукописи контракта в этом репозитории больше нет: два описания одних и тех же форм — это два источника правды, и тот, который никто не читает, разрешает дрейф молча.

Гейт staleness'а (npm run contract-types:check, tests/contract-types.test.ts и отдельный workflow .github/workflows/contract-types.yml) перегенерирует файл и падает, если он разошёлся с закоммиченным: контракт в чужом репозитории изменился, а типы — нет. SHA-256 самого документа лежит в сгенерированном файле, поэтому гейт замечает и правку комментария, а не только переименование поля. Документ при этом остаётся в репозитории краулера: витрина читает его оттуда и никогда не правит.

Контракт для типов — контракт пина. Витрина говорит не с main краулера, а с образом, который закреплён в contract/crawler-image.txt; рядом с digest'ом пин записывает коммит, из которого образ собран, — а коммит говорит, какой контракт этот образ знает. Гейт staleness'а читает коммит из пина той ветки, которую проверяет, и сверяет типы с контрактом этого коммита. Раньше он сверял их с main краулера — это другая ось: изменение контракта краулера роняло тогда все pull request'ы витрины, включая пин-PR, который к контракту отношения не имеет, и разгребать это должен был человек. Теперь обе стороны гейта живут на одной оси: «типы описывают контракт образа, который эта ветка закрепляет».

Пин привозит типы с собой. Pull request, который двигает пин, перегенерирует типы по контракту закрепляемого коммита и кладёт их в тот же PR (scripts/update-image-pin.sh --contract-document …): пин говорит «этот краулер», типы говорят «вот какой у него контракт», и одно без другого — витрина, адаптированная наполовину. Если типы требуют правки кода витрины, это видно по красному typecheck в этом же PR, и сообщение гейта называет, что именно не компилируется.

Контракт между репозиториями

Два репозитория — значит два CI, и контракт между ними должен проверяться с обеих сторон. Свой CI витрины собирает образ краулера из соседнего checkout'а и проверяет витрину против него. Это проверка «витрина против кода краулера».

Настоящая проверка — другая: «витрина, которую катываем, против краулера, которого катываем». Её делает краулер:

  1. краулер публикует образ и отправляет repository_dispatch в витрину — .github/workflows/contract-compatibility.yml;
  2. витрина поднимает именно тот образ (по digest) и прогоняет контрактный набор;
  3. краулер читает conclusion этого запуска — джоб site-compatibility в его .github/workflows/site-compatibility.yml — и падает, если conclusion не success.

Токен SITE_REPO_TOKEN и переменная vars.SITE_REPO в репозитории краулера обязательны: без них джоб падает с явным сообщением, а не «молча зелёный» — правило «гейт, который не может честно упасть, хуже отсутствия гейта» здесь стоит дороже всего.

Пин образа — contract/crawler-image.txt — это либо локальный тег (собирается из соседнего checkout'а), либо digest из реестра (ghcr.io/…@sha256:…, вытягивается, и контейнер проверяется на то, что он запустил ровно этот образ). CI выбирает по пину, больше ничем.

Образ краулера: лимит pull'ов и секрет GHCR_READ_TOKEN

GHCR отдаёт анонимным клиентам не больше 100 pull'ов в час на один адрес, а адреса runner'ов GitHub общие. Пока в репозитории нет секрета GHCR_READ_TOKEN, pull образа краулера анонимный — и его могут отказать из-за чужих прогонов.

Секрет репозитория Зачем
GHCR_READ_TOKEN read-only токен на ghcr.io: с ним pull не анонимный и лимит в 100/час не считается по адресу
VPS_HOST, VPS_USER, VPS_PORT, VPS_APP_DIR, VPS_SSH_KEY деплой на VPS (workflow «Deploy to VPS»)

Пока секрета нет, путь говорит об этом прямо, а не висит: scripts/pull-crawler-image.sh — единственное место, где образ тянется (и CI, и тестовый набор ходят в него), и оно называет и лимит в 100/час, и секрет, который его снимает.

Образ ещё и кэшируется в CI: ключ кэша — digest пина, так что в кэше лежит ровно тот образ, который назван пином; после загрузки ссылка на образ проверяется, и если она не разрешается, образ тянется заново. Кэш, из которого образ не читается, хуже, чем никакого кэша: набор проверяет, что контейнер запустил именно тот образ, что назван пином.

Что осталось за владельцем: создать секрет GHCR_READ_TOKEN в gazon1/product-catalog (Settings → Secrets and variables → Actions → New repository secret). Скрипт и README об этом говорят, но создать секрет может только владелец.

Пин двигается не коммитом, а pull request'ом: джоб pin ждёт зелёной совместимости, пишет digest в файл и открывает PR — потому что пин это решение, а решение автоматическим не бывает. Вместе с digest'ом в тот же PR едут перегенерированные типы: контракт образа и типы витрины — это одно решение, а не два. Открыть PR должен какой-то токен, и их два: либо токен самого запуска — тогда в репозитории должно быть включено «Allow GitHub Actions to create and approve pull requests» (Settings → Actions → General), либо fine-grained токен владельца с Contents: RW и Pull requests: RW, сохранённый как секрет PIN_PR_TOKEN; секрет предпочтительнее токена запуска, у него нет срока жизни. Без того и другого джоб падает с явным сообщением, а не радостно зелёный.

PR, который открыл джоб, не запускает проверки без одобрения. Pull request'ы, созданные токеном запуска, триггерят workflow'и — но их прогоны висят в action_required, пока кто-то их не одобрит. Смотреть некому: PR открывает джоб, и одобрить должен тоже джоб — тем же токеном, которым он открыл PR. Это и делает джоб pin: находит прогоны по SHA'у головы PR, одобряет их через API и ждёт их завершения. Контрактный набор читает contract/crawler-image.txt, поэтому идёт против образа, который пин называет: пин проверяется тем, что он утверждает. Проверки зелёные — PR просит автослияние; красные или не одобренные — пин не двигается, и это видно.

Защита main. Ветка защищена: обязательные проверки — typecheck-and-test, build-and-push, staleness; форс-пуш и удаление ветки запрещены. Аппрувы не требуются — репозиторий ведёт один человек (и агенты от его имени), а правило, которое всегда обходят, учат обходить. Пин-PR проходит ту же защиту: его проверки — те же, что требует защита, и автослияние срабатывает, только когда они зелёные.

Зависимости. Dependabot шлёт обновления patch и minor одной группой: такой бамп не может изменить смысл кода — гейты решают, собралось ли. Major едет отдельным PR и ждёт человека. Бамп читается из описания PR (scripts/dependabot_bump.py), а не из названия группы: у сгруппированного PR название называет группу, а версии — в теле. Workflow .github/workflows/dependabot-auto-merge.yml просит автослияние только для patch и minor; последнее слово остаётся за защитой ветки.

Пин показывает, насколько он отстал. Digest говорит, какой образ закреплён, но не говорит, когда он собран: витрина, закреплённая за образом трёх релизов краулера назад, выглядит ровно как закреплённая за текущим. scripts/pin-lag.sh берёт коммит из меток образа (org.opencontainers.image.revision) и спрашивает у GitHub, насколько main краулера уехал с него; CI пишет это в сводку прогона. Это отчёт, а не гейт: витрина догоняет краулер после его движения, и отставание между релизом краулера и следующим релизом витрины — нормальное состояние.

Деплой витрины сверяется с пином. Workflow деплоя читает на сервере .deployed-digest (его пишет Ansible-роль краулера) и отказывается деплоить витрину против краулера, чей digest не совпадает с пином. Витрина, которую проверили против одного образа краулера, не должна ехать против другого: расхождение здесь — это ровно тот случай, когда «всё зелёное» и «работает» расходятся.

Один список гейтов

Гейты написаны в одном месте — config/gates.yaml — и оттуда их запускают и just check, и CI, одним и тем же скриптом scripts/run-gates.mjs. Наборы жили в трёх местах (justfile, ci.yml, deploy.yml) и разошлись: комментарий в justfile обещал «зелёный локальный прогон = зелёный пайплайн», а обещание было неправдой — локально гонялось шесть гейтов, в пайплайне два.

scripts/check-gates.mjs — первый гейт в списке — сравнивает стороны и называет расхождение: если CI запускает гейт в одиночку или just check перечисляет гейты вместо того, чтобы взять список, гейт падает и говорит, какой именно. Тот же скрипт проверяет обязательные проверки main через gh api: имя обязательной проверки, у которого нет джоба ни в одном workflow, — это проверка, которая никогда не станет зелёной, и pull request будет ждать её вечно. Токен нужен свой (gh auth login или GH_TOKEN); без него скрипт говорит, что проверить не смог, — и не говорит, что всё в порядке.

Остальные workflow'и — про другое и по другому поводу (устаревание типов контракта, dispatch от краулера) — гоняют часть списка, и это не расхождение: часть списка есть часть списка. deploy.yml в списке не участвует: деплой — это публикация уже проверенного образа, а не гейт над кодом.

«Тесты зелёные» ≠ «тесты выполнились»

npm test завершается с кодом 0 и печатает сводку независимо от того, выполнилось 145 тестов или один файл выпал из include. Отсутствие Docker уже ловится отдельно и громко (global-setup.ts бросает исключение), но остаётся дыра похуже: набор, который никогда не был выбран, до гейта, способного пожаловаться, не доходит.

scripts/check-test-runs.py читает JUnit XML, который пишет прогон, и сверяет его с config/test-runs-floor.tsv. Пол задан на каждый файл, а не на сумму: сумма в 145 позволила бы росту остальных файлов замаскировать исчезновение database.test.ts — того единственного, который разговаривает с базой.

Проверено контролем: npx vitest run tests/slug.test.ts отчитывается 1 passed и выходит с 0, гейт выходит с 1 и называет каждый невыполненный файл.

Осознанное расхождение с краулером. У него check-test-runs.py задаёт пол на модуль Gradle и явно документирует слепое пятно. Здесь оно закрыто пофайлово: под угрозой там «добавили тест, а задача перестала его выбирать», здесь — «единственный набор, работающий с базой, перестал запускаться», а такое здесь уже приходилось ловить. Расхождение зафиксировано здесь и в шапке скрипта, а не оставлено на волю случая.

Правило, общее для пары репозиториев

«Гейт, который не может честно упасть, хуже отсутствия гейта» — не только про отсутствие Docker. За один день в двух репозиториях нашлись четыре воплощения одного и того же: зелёная сборка, проверившая меньше, чем заявляла.

  • Always указывать, что именно инспектирует гейт, и доказывать, что он срабатывает — ломая вход намеренно и наблюдая падение.
  • Never проходить гейт правкой того, что он инспектирует. Переформулировка, замолчавшая проверку, — это регрессия в одежде исправления.
  • Never деградировать проверку до молчания, когда она не может выполниться.
  • Always предпочитать обнаружение входу его объявлению: файлы, миграции, наборы тестов — везде, где список может тихо отстать.
  • Always вычитывать комментарии перед сканом исходников на код.

Формулировка живёт в одном месте — docs/decisions/2026-10-08-gates-that-can-fail.md в репозитории краулера, откуда DIGEST.md поднимает её в Critical. Дублировать здесь нельзя: правило, скопированное в два документа, обновляют в одном из них, и копию, которую никто не читает, читать перестанут. Здесь — указатель и одно место, где пара расходится намеренно (см. расхождение по полам выше).

Нужен Docker

npm test поднимает контейнер, поэтому без работающего Docker-daemon набор падает, а не пропускается. Зелёный прогон, в котором 30 тестов к Postgres не выполнились, хуже отсутствия тестов — это ровно тот дефект, который остальные гейты репозитория и ловят.

Схему для тестов теперь создаёт сам краулер: тестовый набор поднимает его образ, и тот применяет свои миграции и наполняет базу. Раньше набор применял копию миграций из dev/db/ — и копия была слабым местом: переименование колонки оставляло оба репозитория зелёными, а витрину — пустой в проде. Теперь тесты проверяют тот же образ, который разворачивается.

Известное косметическое предупреждение: каждый прогон заканчивается close timed out after 10000ms … something prevents Vite server from exiting. Код возврата 0, все тесты выполнены и отчитались; открыт поток логов контейнера testcontainers, а не соединение с БД. Поднимать teardownTimeout пробовали — становится хуже. Зафиксировано в шапке tests/global-setup.ts.

Команды

just stack-up / stack-down вся локальная стенка: база, краулер, витрина
just db-up / db-reset / db-down база и краулер
just dev Next.js на :3000
just clean убрать стенку, сборку и артефакты тестов (--purge — ещё и том БД, --modules — ещё и node_modules)
just contract-check живой образ краулера против контракта
just contract-types перегенерировать типы витрины по контракту краулера
just check гейты из config/gates.yaml — тот же список, что и в CI
just docker-build локальный образ

Копии схемы в репозитории нет, и just schema-sync/just schema-check вместе с ней: см. «Почему копии схемы нет».

Развёртывание

Готово по формату dacha-na-udachu-website: образ в GHCR, workflow_dispatch для выката, гейт дрейфа Caddy-маршрута через sha256sum, smoke-test через публичный домен.

just route product-catalog deploy/caddy.conf.caddy   # из репозитория Caddy-vps

Состояние на 2026-10: маршрут wb-parser.maxdrobin.ru установлен на VPS и совпадает с deploy/caddy.conf.caddy побайтово (гейт деплоя сверяет sha256sum), сертификат Let's Encrypt выпущен, DNS указывает на сервер. Переменные CRAWLER_REPO* и PUBLIC_URL заданы; секреты VPS_HOST/VPS_USER/VPS_PORT/VPS_APP_DIR/VPS_SSH_KEY и environment production — тоже. Каталог деплоя на сервере — ~/product-catalog.

Выкат отложен: витрина теперь читает каталог по HTTP у краулера, и для этого у неё должны быть CRAWLER_API_URL и CRAWLER_API_KEY в ~/product-catalog/.env на сервере. Пока их нет, Deploy to VPS прогнать можно, но /api/health вернёт 503 — витрина честно скажет, что каталог недоступен, вместо того чтобы показать пустую витрину.

Отличия от предыдущего решения: в deploy.yml нет шага миграции — витрина не может изменить базу, поэтому выкат нечего откатывать; docker compose на сервере не содержит сервиса db; у витрины нет ни одного credential'а от базы — только ключ каталога.

Известные ограничения

Честный список, а не «работает идеально»:

  1. Отсутствующий товар или категория отвечают статусом 200, а не 404. Контент 404-страницы корректный, статус — нет: в Next 15.4.11 notFound() в динамическом сегменте не может изменить статус после начала стриминга. Проверено и с force-dynamic, и без — причина не в режиме рендера. Смягчено тремя способами, все работают: noindex в метаданных для несуществующих страниц, canonical только для существующих, в sitemap.xml только непустые категории.

  2. Нет ISR на статических по пути маршрутах. / и /catalog помечены force-dynamic, поэтому пересчитываются на каждый запрос. Причина — реальный баг: первый next build пререндерил их, когда каталог был недоступен, запросы упали, страницы были запечены как «данных нет», а сборка завершилась BUILD SUCCESSFUL. Данные динамических сегментов (/category/[slug], /product/[id]) кэшируются на 60 с через ISR по требованию — там нет generateStaticParams, поэтому сборка каталог не трогает.

  3. /targets — полный проход по scraped_items. Единственный запрос, который не масштабируется бесплатно; кэшируется на 10 минут — на стороне краулера. Правильное решение — поддерживаемый счётчик, а это запись в чужую базу.

  4. Слаги производные. Схемы нет — значит, нет и колонки slug. Slug транслитерируется в JS и сопоставляется в памяти по списку целей; при совпадении у двух целей страница отдаёт 404, а не угадывает. Переименование каталога меняет его URL.

  5. Сортировка требует одного клика. Форма сортировки — обычная GET-форма, без onChange: обработчик события нельзя передать в Server Component, а Next падает на этом при рендере. Авто-отправка стоила бы клиентского компонента и зависимости от JS.

  6. Цена и кэшбэк — на момент последнего обхода. Дата показана явно, но это снимок, а не котировка.

Структура

src/lib/       db.ts (пул, read-only) · queries.ts (весь SQL) · money · slug · format · params
src/app/       / · /catalog · /category/[slug] · /product/[id] · /search · /top-deals
               /api/health · /product-image · sitemap · robots · manifest
src/components/ карточка, сетка, пагинация, фильтры, история цены, крошки, JSON-LD
deploy/        caddy.conf.caddy
scripts/       stack-up · stack-down · wait-healthy · wait-catalog-ready
               docker-timeout (потолок на каждый вызов Docker) · pull-crawler-image
               run-gates · check-gates (список гейтов и его проверка)
tests/         vitest, включая архитектурные гейты

Лицензия и данные

Код витрины — MIT. Каталог, цены, изображения и названия товаров принадлежат их владельцам; проект не связан с операторами источника данных и не претендует на них. Демо-сид краулера наполняет базу выдуманными товарами — это генератор для разработки, а не описание реального ассортимента.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages