diff --git a/.claude/rules/backend.md b/.claude/rules/backend.md index 0913c909..39aee438 100644 --- a/.claude/rules/backend.md +++ b/.claude/rules/backend.md @@ -76,6 +76,22 @@ Reference: vault `Bug_Nspd_Geo_Sql_Injection_May14`. - ❌ Hardcode credentials — `os.environ.get("KEY")` или `settings.KEY` - ❌ `Any` без комментария почему +## Web probing (scrapers — use playwright MCP, not curl) + +При исследовании веба (как страница реагирует на параметры/фильтры, что меняется в DOM, какие селекторы возвращают данные, anti-bot behavior) — **сначала** `mcp__playwright__*`, а не curl/curl_cffi. + +**Why:** Реальный браузер видит финальный URL после canonicalization + JS state без anti-bot ловушек. Curl попадает в captcha на 2-3-й итерации. User rule (2026-05-23): «если что-то не понятно лучше через плэйврайт смотри чем через консоль». + +**How to apply:** +- Discover URL params / filter behavior → `browser_navigate` + `browser_snapshot` +- Verify selectors / count cards → `browser_evaluate` с JS возвращающим counts +- Inspect network → `browser_network_requests` +- Captcha detection → `browser_snapshot` + check для challenge elements + +**Curl/curl_cffi оставляем** для actual scraping в production-скриптах **после** того как param set уже известен (playwright медленнее + heavier для bulk fetch). + +Reference incident: 2026-05-23 reverse-engineering Yandex SERP filter params через curl — captcha на 2-й итерации, recovery через cookie-warm session. С playwright сразу видели бы JS state. + ## Worker crash checklist Worker падает на старте → скорее всего import error: `pyproject.toml` имеет dep но `uv.lock` не обновлён → `cd backend && uv lock` → commit lock → push. diff --git a/.claude/rules/deploy.md b/.claude/rules/deploy.md index 4c40ac55..84480ea7 100644 --- a/.claude/rules/deploy.md +++ b/.claude/rules/deploy.md @@ -9,6 +9,20 @@ paths: # Deploy conventions +## Post-deploy verification (MANDATORY) + +После КАЖДОГО успешного merge+deploy на main — **немедленно** spawn `qa-tester` subagent с playwright smoke по тому, что merged. + +**Why:** Без auto-smoke user сам ловит prod TypeErrors / 4xx / overlay bugs которые qa-tester catched бы за 2 мин. Плохой UX + потерянное время на P0 hotfixes уже после того как user увидел проблему. User rule (2026-05-18): «проверяй через плэйврайт сразу после деплоя». + +**How to apply:** +- После `mcp__forgejo__get_pull_request` `merged: true` И подтверждения deploy success (HTTP 200 на routes / GHA run finished / user сказал «deploy прошёл») — `Agent` subagent_type=qa-tester. +- Prompt: routes изменённые в PR + expected behaviour из PR body + console errors check + critical API calls (4xx/5xx detection) + regression baseline (`/`, `/health`, `/landing/stats`). +- Background OK — wait notification, не блокировать остальной flow. +- НЕ дожидаться user feedback «не работает» — qa-tester ловит сам. + +Reference incident: PR #346 (2026-05-18) deploy → user сам нашёл prod 500 на by-bbox, потом 400 на analyze, потом TypeError на poi-score, потом UI overlap. Каждое ловилось бы playwright smoke по `/site-finder/analysis/{cad}`. + ## GHA path triggers - `backend/**`, `frontend/**`, `Caddyfile`, `docker-compose.prod.yml`, `data/sql/*.sql` → `deploy.yml` (main stack) diff --git a/.claude/rules/frontend.md b/.claude/rules/frontend.md index 2606f6cf..6aad4009 100644 --- a/.claude/rules/frontend.md +++ b/.claude/rules/frontend.md @@ -32,6 +32,22 @@ cd frontend && npm run codegen Обновляет `src/types/openapi.ts` из live OpenAPI. Без этого frontend build упадёт на missing types. +## package.json + lockfile sync (CRITICAL — deploy aborts on mismatch) + +Если меняешь `frontend/package.json` (add/remove/bump dep) — **обязан** также: + +```bash +cd frontend && npm install --legacy-peer-deps --no-audit --no-fund +``` + +И закоммитить обновлённый `frontend/package-lock.json` в той же ветке. + +**Why:** `frontend/Dockerfile` использует `npm ci --legacy-peer-deps` — этот режим **требует** точного match между `package.json` и `package-lock.json`. Mismatch → `npm error Missing: @ from lock file` → builder fails → `docker compose --abort-on-container-exit` → **весь deploy aborts** (frontend + backend rollback). + +- Pre-push check: `git diff main..HEAD -- frontend/package.json frontend/package-lock.json` — если только один из двух тронут → STOP, regen lock. +- Imports без deps entry (TypeScript авто-resolve через transitive) — **latent bomb** до first `npm ci`. +- Reference incident: PR #344 (2026-05-17) добавил `lucide-react` без regen lockfile → deploy #135 fail → P0 hotfix PR #345 (commit `6ee20294f2`). + ## Prettier / lint - 2 spaces, trailing comma, double quotes (config)