fix(web): recover pre-render boot failures

vehicle-data-platform/docs/frontend-production-readiness.md

@@ -2,6 +2,14 @@
 
 This document records verified risks, the production controls that address them, and the next evidence to collect. It is intentionally operational: a passing build alone is not proof that the browser application is production-ready.
 
+## 2026-07-16: pre-React boot recovery
+
+Route Suspense and error boundaries can recover failures only after the React entry has loaded and committed. The production HTML previously contained an empty `#root`, so an entry-script fetch failure, synchronous initialization exception, unhandled startup rejection or permanently stalled module graph could leave a completely blank page with no operator action. React documents error boundaries as protection for errors in their descendant component tree; the browser `error` event separately reports resources that fail to load or scripts that cannot execute: <https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary>, <https://developer.mozilla.org/en-US/docs/Web/API/Window/error_event>.
+
+The HTML now paints a credential-free static loading shell before any application JavaScript runs. A ten-second watchdog listens for startup resource errors and unhandled rejections; the first committed React tree emits a ready event that removes all listeners and the timer. If readiness never arrives, the existing shell becomes an explicit startup failure card with a manual “重新加载最新版本” action that adds a cache-busting query parameter. It never auto-reloads, so a persistent outage cannot create a reload loop, and it never replaces an already-rendered application tree. After React commits, a separate root boundary covers authentication, the router and the application shell, while the narrower route boundaries continue isolating individual modules.
+
+Source tests protect the complete handshake and prove a shell-level render exception remains actionable, while the production build gate inspects the generated `index.html` and entry bundle so bundler changes cannot silently remove the pre-React boundary or ready signal. Release QA covers both the normal immediate replacement and a deliberately blocked module request that reaches the static recovery action without a blank viewport.
+
 ## 2026-07-16: throttled selected-vehicle address lookup
 
 The selected vehicle position refreshes every ten seconds so its map marker, ripple and tracking camera remain current. The detail card previously used every six-decimal coordinate as part of the reverse-geocode query key, so a moving vehicle could create a new remote AMap request on every realtime response: up to 360 calls per hour for one selected vehicle in one operator tab. AMap documents reverse geocoding as an HTTP/HTTPS remote service that converts an input coordinate into a structured address, while TanStack Query caches independently by query key: <https://lbs.amap.com/api/webservice/guide/api/georegeo>, <https://tanstack.com/query/latest/docs/framework/react/guides/query-keys>.