Витрина товаров: читает каталог краулера по его 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 и сервисный ключ. Граница держится на стороне краулера:
- Роль в Postgres. Каталог читает через
wb_catalog_ro— роль сCONNECT,USAGEиSELECT, без владения объектами и без членства в других ролях. Права выдаёт скрипт краулераdb/roles/provision-catalog-readonly-role.sql, и запускает его тот, кто администрирует базу краулера, не деплой витрины. - Сессия. Соединения каталога открываются с
default_transaction_read_only=on, плюсstatement_timeoutиtimezone=UTC. - API. Публичный маршрут
/api/catalog/**закрыт на прокси. Без ключа каталог недоступен ни из одной точки.
Что именно заявлено — узко: API не опубликован наружу, публичный маршрут закрыт, без ключа каталог недоступен ни из одной точки. Заявление «только витрина может обращаться к каталогу» не делается: общая сеть контейнеров и ключ такой изоляции не дают.
Ключ можно ротировать без остановки: краулер принимает список ключей через запятую, новый добавляется первым, витрина переключается, старый удаляется.
just stack-up # база + краулер (он сам создаёт схему и наполняет её) + витринаОтдельно: just db-up — только база и краулер, just dev — только витрина на :3000.
Краулер сам наполняет базу собственным демо-сидом: 4 каталога, ~1200 наблюдений товаров, детерминированно. Сид защищён пятью барьерами сразу: флаг, профиль demo, точная роль, маркер базы и пустота таблиц — заполнить рабочую базу можно, только если совпало всё, включая роль, которой в рабочей базе нет.
Сид намеренно воспроизводит состояния, которых нет в «идеальных» данных, потому что именно они ломают вёрстку:
- каталог настроен, но пуст;
- часть карточек без картинки — срабатывает заглушка;
- у части товаров нет цены, скидки, кэшбэка или
match_id; - один товар встречается в нескольких каталогах — срабатывает свёртка по
match_idв «Топе по кэшбэку»; - у товара несколько наблюдений цены — строится график истории.
just check # гейты из config/gates.yaml — тот же список, что и в CIcontract-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'а и проверяет витрину против него. Это проверка «витрина против кода краулера».
Настоящая проверка — другая: «витрина, которую катываем, против краулера, которого катываем». Её делает краулер:
- краулер публикует образ и отправляет
repository_dispatchв витрину —.github/workflows/contract-compatibility.yml; - витрина поднимает именно тот образ (по digest) и прогоняет контрактный набор;
- краулер читает
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 выбирает по пину, больше ничем.
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. Дублировать здесь нельзя: правило, скопированное в два документа, обновляют в одном из них, и копию, которую никто не читает, читать перестанут. Здесь — указатель и одно место, где пара расходится намеренно (см. расхождение по полам выше).
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'а от базы — только ключ каталога.
Честный список, а не «работает идеально»:
-
Отсутствующий товар или категория отвечают статусом 200, а не 404. Контент 404-страницы корректный, статус — нет: в Next 15.4.11
notFound()в динамическом сегменте не может изменить статус после начала стриминга. Проверено и сforce-dynamic, и без — причина не в режиме рендера. Смягчено тремя способами, все работают:noindexв метаданных для несуществующих страниц,canonicalтолько для существующих, вsitemap.xmlтолько непустые категории. -
Нет ISR на статических по пути маршрутах.
/и/catalogпомеченыforce-dynamic, поэтому пересчитываются на каждый запрос. Причина — реальный баг: первыйnext buildпререндерил их, когда каталог был недоступен, запросы упали, страницы были запечены как «данных нет», а сборка завершиласьBUILD SUCCESSFUL. Данные динамических сегментов (/category/[slug],/product/[id]) кэшируются на 60 с через ISR по требованию — там нетgenerateStaticParams, поэтому сборка каталог не трогает. -
/targets— полный проход поscraped_items. Единственный запрос, который не масштабируется бесплатно; кэшируется на 10 минут — на стороне краулера. Правильное решение — поддерживаемый счётчик, а это запись в чужую базу. -
Слаги производные. Схемы нет — значит, нет и колонки
slug. Slug транслитерируется в JS и сопоставляется в памяти по списку целей; при совпадении у двух целей страница отдаёт 404, а не угадывает. Переименование каталога меняет его URL. -
Сортировка требует одного клика. Форма сортировки — обычная GET-форма, без
onChange: обработчик события нельзя передать в Server Component, а Next падает на этом при рендере. Авто-отправка стоила бы клиентского компонента и зависимости от JS. -
Цена и кэшбэк — на момент последнего обхода. Дата показана явно, но это снимок, а не котировка.
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. Каталог, цены, изображения и названия товаров принадлежат их владельцам; проект не связан с операторами источника данных и не претендует на них. Демо-сид краулера наполняет базу выдуманными товарами — это генератор для разработки, а не описание реального ассортимента.