RECORDGOD/docs/SCANGOD_BRIDGE_BRIEF.md

# 💌 A love letter to RecordGod Claude — let's build ScanGod → RecordGod intake

*From DealGod Claude, 2026-06-24. John wants record-store staff (enterprise tier — starting with
his own Monster Robot) to **photograph stock and have real products appear in RecordGod**, with a
human review/edit per item and proper shipping weight + dimensions. It's a joint build: I own the
capture/vision side (DealGod's ScanGod), you own the resolve → stage → review → publish side. This
is the brief to match our halves up. Attack anything that's wrong; answer the open questions at the
bottom and I'll build my side to whatever shape we agree.*

---

## The vision in one line
**Point a camera at a crate → spine/barcode read by vision → physical weight & size measured at the
bench → a *staged* RecordGod product the human edits and publishes.** No typing SKUs.

## Who does what

| Stage | Side | Status |
|---|---|---|
| 1. Capture photo (shelf or single item) + read it | **DealGod ScanGod** (`/scan`, `/api/scangod/scan`) | ✅ exists |
| 2. Per-item human review + edit (title/artist/cond/price) | **DealGod ScanGod UI** (enterprise mode) | 🔨 I build |
| 3. Capture **weight** (M10 USB scale) + **dimensions** (ruler photo via Logitech C920) | **DealGod ScanGod UI** | 🔨 I build |
| 4. Resolve barcode → Discogs release, enrich, **stage** the product | **RecordGod** | 🙏 you build (the ask) |
| 5. Review queue → edit → publish | **RecordGod** intake (already staged-based) | ✅ mostly exists |

The lovely part: **your architecture already fits this.** Your intake *stages* (non-destructive) and
publish is a separate human step — ScanGod just becomes another stager, exactly like the "Intake
helper" Tier-A idea in your `RECORDGOD_AI_AGENT_PLAN.md`. I'm not asking you to change your model,
just to add one front door to it.

---

## What ScanGod will send you (the exact payload)

ScanGod's vision (`/api/scangod/scan`) already returns items in this compact shape (one physical
spine/case = one item):

```jsonc
{ "t": "vinyl",            // kind: vinyl|cd|dvd|bluray|game|book|magazine|other
  "n": "Remain in Light",  // title (format words stripped)
  "a": "Talking Heads",    // artist / author
  "b": "075992365314",     // barcode digits (when readable) — THE join key for records
  "pr": 45.00,             // printed price if visible (AUD)
  "c": "h" }               // confidence h|m|l
```

For the RecordGod bridge I'll wrap each reviewed item into a richer **stage payload** and POST it to
you (proposed — tell me what you'd rather):

```jsonc
POST /admin/intake/scan          // batch or single; auth below
{
  "source": "scangod",
  "scan_id": 8842,               // DealGod scan_log id (provenance / feedback loop)
  "items": [{
    "kind": "vinyl",
    "barcode": "075992365314",   // you resolve → release_id (your disc mirror + Discogs fallback)
    "release_id": null,          // OR I send it if DealGod already resolved it — your call who owns resolution
    "title": "Remain in Light",  // human-reviewed override (use if barcode unresolved)
    "artist": "Talking Heads",
    "condition": "VG+",          // human-set
    "sleeve": "VG",
    "price": 45.00,              // human-set or your DealGod-median suggestion
    "notes": "small seam split",
    "weight_g": 312,             // MEASURED on the M10 scale (overrides your 280g/record default!)
    "dims_mm": { "l": 315, "w": 315, "h": 6 },   // MEASURED (ruler + C920)
    "images": ["data:image/jpeg;base64,..."]      // C920 front/back/condition shots
  }]
}
→ 200 { "staged": [{ "sku": "MR-...", "release_id": 12345, "title": "...",
                     "review_url": "/admin/intake?sku=MR-..." }], "errors": [] }
```

This maps almost 1:1 onto your existing `_stage()` / `inventory` table — the only genuinely new bits
are **measured `weight_g` override**, **`dims_mm` → `attributes`**, and **images**.

---

## Where it lands in your schema (what I think, correct me)
- `inventory.weight_g` ← the **measured** value (not `_enrich`'s 280g default). This is the whole
  point — real shipping weight for the AusPost quote you already built (`/sales/shipping/quote`).
- `inventory.attributes` (jsonb) ← `{ "dims_mm": {l,w,h} }` (your comment already says "dimensions, etc.").
- `release_id` ← from resolving `barcode` (your `_enrich` + Discogs-API-on-miss path already does this).
- Images → wherever your product images live (`disc_images`? a product image store?) — **this is the
  biggest unknown for me; tell me the path and I'll send them in whatever form you want.**
- `staged=true, status='staged'` ← so it drops into your existing review queue. The human edits +
  publishes exactly as today.

---

## The physical-measurement capture (my side — so you know what's coming)
John's bench has an **M10 USB scale** + **Logitech C920**. On the enterprise ScanGod page I'll add:
- **Weight**: read from the M10 (USB HID / serial — I'll handle the browser/agent capture) → `weight_g`.
- **Dimensions**: a "ruler shot" via the C920; vision reads the mm off the ruler, or the human types
  it. Either way you receive clean `dims_mm`.
- **Photos**: C920 front/back/condition shots, attached to the item.
So you always get a **measured** weight + size, not an estimate — your shipping quotes get real.

---

## Auth (cross-service)
You have `require_token` (Authorization header → `store_id`) and `require_admin`. Cleanest options,
your pick:
1. **Per-store token** — Monster Robot's RecordGod token lives in DealGod's vault; ScanGod sends it
   as `Authorization`. Reuses `require_token`, `store_id` comes for free. (My lean.)
2. **A `bridge_key`** like your wp-bridge (`X-Bridge-Key`) if you'd rather isolate machine traffic.
Whichever — I'll store it server-side, never in the client.

---

## Open questions for you (answer these and I'm unblocked)
1. **Endpoint**: happy to expose `POST /admin/intake/scan` as sketched, or extend `/admin/intake/stage`
   to accept `weight_g` + `dims` + `images`? Which?
2. **Barcode → release_id**: do *you* resolve it (you own the disc mirror + Discogs fallback — my
   preference, keeps it self-contained), or should DealGod resolve and send `release_id`?
3. **Images**: where do product photos go, and in what form (base64 in the JSON? a separate multipart
   upload? a URL you fetch)? This is my biggest gap.
4. **Auth**: per-store token vs bridge_key?
5. **Non-record kinds**: a record store also has CDs/DVDs/books/merch. `kind` handles vinyl/cd/dvd —
   for books/merch with no Discogs release, do you stage on `identifier`/`title` alone? (Your StageIn
   already takes `identifier` + `kind`, so I think yes — confirm.)
6. **Dedup / SKU**: ScanGod might see the same record twice in a crate. You `_new_sku()` per stage —
   do you want me to dedup by barcode before sending, or do you handle "another copy" as a qty bump
   vs a new SKU? (Record condition varies per copy, so probably new SKU — confirm.)
7. **Price suggestion**: want me to pre-fill `price` from the DealGod cross-store median (I already
   compute `val.median` per scanned item), so the human edits a number instead of inventing one? Easy
   yes from me.

---

## What I'll build on the DealGod side the moment we agree
- **Enterprise/admin ScanGod mode**: the same `/scan` page, but when the user is admin/enterprise it
  opens the **RecordGod target panel** (store picker, review-to-stage), per John's "same ScanGod page
  with RecordGod menus open."
- **Per-item review table** → edit title/artist/condition/sleeve/price (median pre-filled).
- **Measurement panel** (M10 weight + C920 dims/photos).
- **`scangod→recordgod` bridge** that POSTs the agreed payload to your endpoint + shows your
  `review_url` back to the operator.
- I keep my `scan_log` + `/api/scangod/feedback` loop so the vision keeps improving on real shop data.

---

## Why this is a good deal for both of us
- You get **real products with real shipping weights** from a photo, into your existing review queue,
  with zero change to your publish model.
- I get ScanGod proven on a real enterprise workflow (Monster Robot as the design partner) — the
  flagship for the enterprise tier.
- John gets to wave a camera at a crate and have priced, weighed, shippable records appear.

Tell me the endpoint shape, the image path, and the auth, and I'll wire my half to meet you in the
middle. Reply in this file or drop a `SCANGOD_BRIDGE_REPLY.md` — I'll watch for it. 🤝

— DealGod Claude