修复(08-10-session-fallback-failure-classification): 定性并修复会话夹具回落

.trellis/spec/hyb-oa/frontend-react-vite-design.md

@@ -105,6 +105,88 @@ and verification contracts. Do not copy broad aesthetic guidance from
   with `AUTH_005`.
 - Run `cd client && npm run typecheck && npm run build` for frontend changes.
 
+## Scenario: Playwright API Mocks Against A Production PWA Build
+
+### 1. Scope / Trigger
+
+- Trigger: an E2E spec uses `page.route` or `browserContext.route` to mock
+  authentication or business APIs and may run against `client/dist`, Vite
+  preview or another production-built PWA runner.
+- Purpose: keep the route fixture as the only network fact source after full
+  navigation, reload or repeated page bootstrap.
+
+### 2. Signatures
+
+- Spec-level context contract: `test.use({ serviceWorkers: "block" })`.
+- Production-build witness: single worker, zero retries, same business
+  assertions and full-navigation sequence as the original spec.
+
+### 3. Contracts
+
+- A spec that depends on Playwright route mocks must block Service Workers when
+  it can run a PWA build. Do not rely on Service Worker installation or takeover
+  timing to keep requests visible to `page.route`.
+- Vite dev success is not equivalent evidence: the generated PWA worker is a
+  production-build behavior and may be absent in dev.
+- Blocking the worker is a fixture boundary, not an authentication bypass. The
+  spec must retain session hint, refresh, `/api/me`, full navigation and
+  business assertions.
+- Tests whose purpose is offline/PWA behavior may allow Service Workers, but
+  they must not also treat page-level API mocks as a complete network witness.
+
+### 4. Validation & Error Matrix
+
+- Dev passes, production build stalls during session bootstrap -> inspect the
+  Service Worker policy before changing authentication code.
+- `serviceWorkers=allow` and a mocked API request becomes incomplete after a
+  later navigation -> fixture/harness candidate; prove causality with the
+  single-variable blocked control.
+- Blocked control still reproduces a real refresh failure -> do not classify as
+  fixture-only; continue with loopback real-backend session evidence.
+- A fix deletes navigation/session assertions or adds retry -> invalid fix.
+
+### 5. Good/Base/Bad Cases
+
+- Good: a mock-heavy ledger spec blocks Service Workers and passes the same
+  repeated full-navigation sequence against the production build.
+- Base: a focused PWA offline spec allows the worker and uses a network setup
+  designed for worker-owned requests.
+- Bad: accept Vite dev green as proof that a production-built PWA runner has no
+  session problem, or modify `AuthContext` to accommodate a route-fixture race.
+
+### 6. Tests Required
+
+- Reproduce once against the production build with single worker and zero
+  retries; record only safe request path/status and cookie presence.
+- Add the blocked-worker control without changing navigation or assertions,
+  then rerun the historically failing titles and the complete target spec.
+- Run an independent frontend bootstrap refresh test and a loopback backend
+  refresh/session regression before declaring the issue fixture-only.
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```ts
+import { test } from "@playwright/test";
+
+test.beforeEach(async ({ page }) => {
+  await page.route("**/api/**", mockApi);
+});
+```
+
+#### Correct
+
+```ts
+import { test } from "@playwright/test";
+
+test.use({ serviceWorkers: "block" });
+
+test.beforeEach(async ({ page }) => {
+  await page.route("**/api/**", mockApi);
+});
+```
+
 ## Scenario: UTC Date-Time Display In The Company Time Zone
 
 ### 1. Scope / Trigger