New: Asset scanning — Developer Guide (the deep dive)
The scanning journey was spread across three pages and mostly implied.
This traces it end to end: how a printed square of ink becomes an
updated database row.
Twelve sections, the substantive ones being:
- Three scanning surfaces (native camera / in-app scanner / USB gun)
and why none of them is redundant.
- The public base URL — the single most consequential line in the
feature. Why it must not come from the request, the localhost
banner, the sub-folder double-append that would otherwise be
printed onto physical labels, and the two tunnel traps (a rotating
free ngrok URL, and its browser-only interstitial that curl won't
show you).
- The resolve flow, including why three regexes deliberately disagree
(routing is permissive, validation is strict, dispatch is neither).
- The write path: one door, shared with the desktop editor, so a
phone edit gets the same audit trail and warranty sync — and why
the no-op skip is load-bearing both in production and in tests.
- The security model: the token is a name, not a password, and the
unknown-vs-another-company answers are identical on purpose.
- Two mobile strategies in one module — mobile-FIRST scan pages
versus the mobile-ADAPTED module — and the five-step hinge where
they meet, which is what makes a scan land on the detail pane with
the device Back button working.
- How to test a camera headlessly (Y4M fake camera) plus the four
traps hit doing it.
- Failure modes, each mapped to its actual cause.
Section 1b of the labels guide now points here instead of duplicating
it; cross-linked from both QR pages, Mobile: Assets, and the sidebar.