# site-ng code conventions & lessons

Recurring engineering conventions and hard-won lessons for site-ng code
(templates, routes, queries). User-facing *text* style lives in `style.md`;
this file is for *code* patterns and gotchas. Add to it when a mistake is
worth not repeating.

---

## Outbound product links: link by `parts.id`, NEVER the raw URL

**Rule:** every click-through to a retailer goes through the jump route as
`/jump?site=<parts.id>` (the numeric part id). NEVER emit the retailer URL in
the link (e.g. `/jump?site=<url>` or a direct `href="<retailer url>"`).

The `/jump` route (`ngsite/views/jump.py`) takes a **digits-only** `site`
(the part id) and, server-side:
1. looks up `url, company FROM parts WHERE id=? AND hidden=0` (the URL is the
   server's source of truth, not the client's),
2. logs the click to `jump_log` (count+1 per url/day; feeds `/instock/popular`),
3. affiliate-wraps the destination, and
4. enforces an **http(s)-only** 302 (safety floor).

Passing the URL instead breaks all of that:
- The route rejects a non-numeric `site` and soft-redirects to the homepage,
  so the link silently does nothing useful.
- A route that *did* accept a raw URL would be an **open redirect**: anyone
  could craft `/jump?site=https://evil.com` for phishing, bypass affiliate
  attribution (lost commission), and pollute `jump_log` with junk URLs.

**Correct, in templates:** `<a href="/jump?site={{ p.id }}">` (or
`it.parts_id` / `it.id` for build-item rows). The canonical card partials
(`partials/parts_grid.html`, `partials/parts_table.html`,
`partials/build_items.html`, `saves/public_view.html`) all do this — match
them. Any query feeding a link must therefore select the part `id`.

*Lesson logged 2026-06-04 after the home-page "Just in stock" strip was first
written with `?site={{ p.url|urlencode }}`.*
