oa-login-password-recovery-ux 改进登录找回密码体验

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

@@ -25,3 +25,83 @@ or hidden according to the active Issue; do not silently re-enable them.
   and post-trial capabilities instead of page-local warning blocks.
 - Trial-facing PC lists must hide obvious TEST/SMOKE records by default when a
   page-level toggle exists; the toggle may reveal them for troubleshooting.
+
+## Scenario: Auth Pages And PWA Updates
+
+### 1. Scope / Trigger
+
+- Trigger: login, password change, password recovery or other unauthenticated
+  forms are active while the PWA service worker finds a new frontend version.
+- Applies to `client/src/pwa.ts`, `client/src/layouts/AuthLayout.tsx`, and
+  auth routes such as `/login`, `/change-password`, `/forgot-password`, and
+  future reset-password pages.
+
+### 2. Signatures
+
+- Event name: `hyb-oa:pwa-update-ready`.
+- Event detail: `{ applyUpdate?: () => void | Promise<void> }`.
+- Route predicate: auth input pages must be checked by pathname before calling
+  `updateServiceWorker(true)`.
+
+### 3. Contracts
+
+- Auth input pages must not auto-reload when `onNeedRefresh()` fires.
+- Auth input pages must show an explicit update prompt with a user-triggered
+  refresh action.
+- Non-auth pages may keep automatic service-worker update behavior when the
+  task does not change broader runtime policy.
+- Passwords and verification codes must stay only in React component state; do
+  not write them to `localStorage`, `sessionStorage`, URL params, reports, or
+  Trellis task evidence.
+- Password visibility controls must use icon buttons with accessible labels and
+  preserve the current input value.
+
+### 4. Validation & Error Matrix
+
+- PWA update on `/login` -> dispatch update-ready event and keep form state.
+- PWA update on `/forgot-password` -> dispatch update-ready event and keep
+  email/code/password fields in memory.
+- User clicks refresh in the prompt -> run the captured update handler.
+- User dismisses prompt -> no reload and no form reset.
+- Password reset request returns success for any email -> show generic sent
+  message; do not reveal whether the account exists.
+
+### 5. Good/Base/Bad Cases
+
+- Good: user is typing a password, update prompt appears, typed values remain.
+- Base: user is on a normal portal page, PWA update can refresh per existing
+  runtime behavior.
+- Bad: service-worker update auto-refreshes an auth form and clears credentials.
+- Bad: tests use real-looking personal email addresses or persist example
+  passwords outside the test file.
+
+### 6. Tests Required
+
+- Frontend typecheck and build.
+- Focused Playwright auth UX test asserting:
+  - login password can be shown/hidden without losing value;
+  - forgot-password flow calls request-code and reset endpoints;
+  - auth-page PWA update prompt appears without clearing inputs.
+- UI design rules check when auth page layout changes.
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```ts
+onNeedRefresh() {
+  void updateServiceWorker?.(true);
+}
+```
+
+#### Correct
+
+```ts
+onNeedRefresh() {
+  if (isAuthInputPath(window.location.pathname)) {
+    window.dispatchEvent(new CustomEvent(PWA_UPDATE_READY_EVENT, { detail: { applyUpdate } }));
+    return;
+  }
+  applyUpdate();
+}
+```