# tradein-mvp/backend/scripts/

Ops scripts that touch the production database directly. Run via `python -m
scripts.<name>` from the `backend/` working directory after `uv sync`.

All scripts are idempotent / resumable where they write — re-running the same
`--batch` label skips already-processed rows (UNIQUE constraints in target
tables). Failures inside a per-row loop never roll back the outer transaction;
each row is wrapped in a SAVEPOINT (`db.begin_nested()`) per `.claude/rules/backend.md`.

---

## Production usage (canonical)

Scripts ship inside the `tradein-backend` image (PR F — `COPY scripts ./scripts`
в `backend/Dockerfile`). На VPS они уже в `/app/scripts/` — никаких manual
`docker cp` не нужно.

`YANDEX_GEOCODER_API_KEY` подтягивается из `/opt/gendesign/tradein-mvp/backend/
.env.runtime` через `env_file:` в `docker-compose.prod.yml` — никакого `-e` в
`docker exec` не нужно.

```bash
# Backfill (forward geocode 4170 houses без coords)
ssh gendesign 'docker exec tradein-backend python -m scripts.backfill_house_coords --batch 2026-05-27_backfill'

# Audit-only (reverse geocode проверка для уже geocoded houses)
ssh gendesign 'docker exec tradein-backend python -m scripts.backfill_house_coords --audit-only --batch 2026-05-27_audit'

# Canary first
ssh gendesign 'docker exec tradein-backend python -m scripts.backfill_house_coords --limit 100 --batch canary_$(date +%F)'
```

После изменения `backend/.env.runtime` нужен `--force-recreate` контейнера
(см. `.claude/rules/deploy.md`):

```bash
ssh gendesign 'cd /opt/gendesign/tradein-mvp && docker compose -p gendesign-tradein -f docker-compose.prod.yml up -d --force-recreate --no-deps backend'
```

---

## Address audit + backfill (issue #582)

End-to-end address quality pipeline. Three scripts, two helpers, two SQL files.

> Локальные примеры ниже — для dev-машины с `uv run` и переменными в shell.
> На prod используй canonical `docker exec` команды из секции выше — там
> `YANDEX_GEOCODER_API_KEY` уже подгружен из `backend/.env.runtime`.

### `audit_address_mismatch.py` — Phase 1 baseline (PR #583)

Stratified-sample audit (200 EKB houses) comparing `houses.address` vs
Yandex Geocoder reverse lookup. Writes one row per house into
`address_mismatch_audit` with the snapped point + canonical address + distance.

```bash
DATABASE_URL=postgresql+psycopg://... \
YANDEX_GEOCODER_API_KEY=... \
uv run python -m scripts.audit_address_mismatch \
    --batch 2026-05-25_run1 \
    --limit-per-district 25
```

Mode `auto` picks API if the key is set, otherwise Playwright (CAPTCHA-aware,
4-7s sleep between calls). API tier free is 25k req/day → 200-row sample
takes ~10s with no quota concern.

Report:

```bash
psql "$DATABASE_URL" -v batch='2026-05-25_run1' \
    -f scripts/address_audit_report.sql
```

### `backfill_house_coords.py` — Phase 2-3 (PR for #582)

Two modes (`--audit-only` flag switches between them):

**Backfill (default)** — forward-geocode `houses.address` for the ~4141 rows
WHERE `lat IS NULL OR lon IS NULL`. Only writes back if Yandex returns
`precision='exact'` or `'number'` (skips street-only / locality matches).
Each processed row gets an `address_mismatch_audit` entry with status
`backfill` / `imprecise` / `no_match` / `error`.

```bash
DATABASE_URL=postgresql+psycopg://... \
YANDEX_GEOCODER_API_KEY=... \
uv run python -m scripts.backfill_house_coords \
    --batch 2026-05-27_backfill
```

Expected duration (~4141 rows, 50ms between calls, ~250ms RTT per request):
20-25 min. Expected output split (rough baseline from Phase 1 numbers):

| Status      | Approx rows | What it means                                       |
|-------------|-------------|-----------------------------------------------------|
| `backfill`  | ~3.3k–3.7k  | UPDATE landed, lat/lon now populated                |
| `imprecise` | ~300–500    | Match returned but precision too low — needs review |
| `no_match`  | ~100–300    | Yandex couldn't resolve; address probably mangled   |
| `error`     | <50         | HTTP errors / timeouts — re-run picks them up       |

**Audit-only** — reverse-geocode the ~4452 houses WITH coords, write
audit rows with status `ok` (≤50m) / `mismatch` (>50m) / `no_match` / `error`.
Does NOT modify the `houses` table.

```bash
uv run python -m scripts.backfill_house_coords \
    --batch 2026-05-27_audit --audit-only
```

Combined budget for both phases (~8.6k requests) is well under the 25k/day
Geocoder free tier.

### Common ops

Canary first — run with `--limit 100` and inspect the audit table before
letting the full job loose:

```bash
uv run python -m scripts.backfill_house_coords \
    --batch canary_$(date +%F) --limit 100
psql "$DATABASE_URL" -c "
  SELECT audit_status, COUNT(*)
    FROM address_mismatch_audit
   WHERE audit_batch = 'canary_$(date +%F)'
   GROUP BY audit_status;
"
```

Resume after crash / quota hit — same `--batch` label, the UNIQUE
`(house_id, audit_batch)` index skips finished rows:

```bash
uv run python -m scripts.backfill_house_coords --batch 2026-05-27_backfill
# ... interruption ...
uv run python -m scripts.backfill_house_coords --batch 2026-05-27_backfill
# logs: "resuming batch 2026-05-27_backfill: N rows already processed"
```

### Helpers (not entry points)

- `_yandex_reverse.py` — `forward_via_api()`, `reverse_via_api()`,
  `reverse_via_playwright()`, `YandexReverseResult` dataclass. Both API
  paths share `_parse_api_payload` because Yandex's forward/reverse
  envelopes have the same shape.
- `audit_address_sample.sql` — random sample for the Phase 1 audit (used
  by `audit_address_mismatch.py`).
- `address_audit_report.sql` — psql-driven post-run summary (p50/p75/p95
  distance, top-20 outliers, per-district breakdown).

---

## Matching backfill (PR J)

### `backfill_listing_sources.py` — retroactive matching for ~18k listings

PR I (commit 7e24ccb) hooked the matching service into `save_listings()` so
every **new** scrape now writes a `listing_sources` row + resolves a canonical
`houses` row. This script does the same work retroactively for all
**existing** listings — `listing_sources` only had rows from new scrapes
post-PR I.

What it does per row:

1. `match_or_create_house()` (Tier 0-3) — uses `listings.house_source` /
   `house_ext_id` when present (Avito Houses Catalog, Cian newbuilding),
   else falls back to address/lat/lon/cadastrals.
2. `upsert_listing_source()` with `method='backfill'`, `confidence=0.9`
   (vs real-time `source_link` 1.0 — distinguishes the two in audits).
3. `UPDATE listings.house_id_fk` when the row didn't already have one.

```bash
# Canary
DATABASE_URL=postgresql+psycopg://... \
    uv run python -m scripts.backfill_listing_sources \
        --limit 100 --dry-run

# Real run, one source at a time (staged rollout)
uv run python -m scripts.backfill_listing_sources --source avito

# Full run
uv run python -m scripts.backfill_listing_sources --batch-size 500
```

**Idempotent / resumable** — the source query is
`WHERE NOT EXISTS (SELECT 1 FROM listing_sources ls WHERE ls.ext_source =
listings.source AND ls.ext_id = COALESCE(listings.source_id,
listings.dedup_hash))`. Re-runs only pick up rows still missing from
`listing_sources`. `upsert_listing_source` adds a second layer of safety via
`ON CONFLICT (ext_source, ext_id) DO UPDATE`.

**No network calls** — pure in-DB matching (Yandex Geocoder is blocked on
prod, and `match_or_create_house` does not call it anyway).

**Per-row SAVEPOINT** (`db.begin_nested()`) per `.claude/rules/backend.md` —
one bad row never aborts the surrounding batch.

**Expected output (PR J initial run):**

| Source | Rows  | Expected matched | Notes                                          |
|--------|-------|-------------------|------------------------------------------------|
| avito  | 9302  | 9000+             | Many carry `house_source`/`house_ext_id`       |
| cian   | 5158  | 5000+             | Most carry `house_source`/`house_ext_id`       |
| yandex | 3704  | 3700+             | No `source_id` → uses `dedup_hash` as `ext_id` |
| n1     | 264   | 264               | All have address/coords                        |

**Expected duration**: rough estimate ~5-15 minutes on prod for ~18k rows
(advisory-lock + 1-3 DB roundtrips per listing for Tier 0-3, ~500 commit
checkpoints at default batch size). Run with `--limit 100` first to
calibrate, then let the full job loose.

Final summary in the log includes per-source coverage % so you can verify
the run landed:

```
backfill done (dry_run=False): processed=18428 matched=18428
  house_resolved=18200 house_failed=228 skipped=0 errors=0
  avito      processed=9302 matched=9302 house_resolved=9290 ...
  cian       processed=5158 matched=5158 house_resolved=5100 ...
  yandex     processed=3704 matched=3704 house_resolved=3540 ...
  n1         processed=264  matched=264  house_resolved=270  ...
final listing_sources coverage:
  avito      9302 / 9302 (100.0%)
  cian       5158 / 5158 (100.0%)
  ...
```