oa-auth-layout-wecom-login-ux 优化认证页登录布局

2026-05-26 21:23:05 +08:00
@@ -105,3 +105,80 @@ onNeedRefresh() {
  applyUpdate();
 }
 ```
+
+## Scenario: Auth Page Layout And Login Entry Hierarchy
+
+### 1. Scope / Trigger
+
+- Trigger: login, password recovery, forced password change or future
+  unauthenticated auth forms need layout changes.
+- Applies to `client/src/layouts/AuthLayout.tsx`, shared auth components under
+  `client/src/components/auth/`, and auth routes such as `/login`,
+  `/forgot-password` and `/change-password`.
+
+### 2. Component Contract
+
+- Auth routes should use one shared auth panel for brand, page title, subtitle,
+  content and optional footer links.
+- `AuthLayout` owns only the auth page shell: background, width constraint,
+  centering, PWA update prompt and route outlet.
+- Page implementations own only their form fields, submit actions, validation
+  messages and route-specific login-entry choices.
+
+### 3. Visual Contracts
+
+- Do not nest a form card inside another login card.
+- Put the brand block inside the auth panel so logo, system name, title and
+  form share one visual axis.
+- Keep the panel width stable around the current auth-shell width; auth pages
+  should feel like an OA workstation entry, not a marketing split hero.
+- Place `忘记密码？` beside the password label or directly below the password
+  input on the right; do not bury it in help text or page footer.
+- Use password visibility icon buttons with accessible labels and preserve the
+  current input value.
+
+### 4. Login Entry Hierarchy
+
+- Normal browser: account/password login is primary; Enterprise WeChat and OIDC
+  entries belong below the primary submit button as secondary methods.
+- Enterprise WeChat WebView: Enterprise WeChat one-click entry is primary;
+  account/password login remains available as the fallback path.
+- Enterprise WeChat entry changes must remain frontend entry hierarchy changes
+  unless the task explicitly approves backend OAuth, binding or WeCom API work.
+- Email verification-code login is a separate login mode. Do not infer it from
+  password-recovery verification-code flows without a backend login-code
+  contract and abuse-control plan.
+
+### 5. Tests Required
+
+- Frontend typecheck and build.
+- Focused auth E2E covering:
+  - password visibility and forgot-password navigation on `/login`;
+  - password recovery request-code and reset flow on `/forgot-password`;
+  - normal-browser Enterprise WeChat entry as secondary CTA;
+  - WeCom WebView Enterprise WeChat entry as primary CTA with password fallback.
+- UI design rules check and Playwright screenshot evidence when the auth layout
+  changes visibly.
+
+### 6. Wrong vs Correct
+
+#### Wrong
+
+```tsx
+<AuthLayout>
+  <Card>
+    <Card>
+      <LoginForm />
+    </Card>
+  </Card>
+</AuthLayout>
+```
+
+#### Correct
+
+```tsx
+<AuthPanel title="登录工作台" subtitle="账号密码登录">
+  <LoginForm />
+  <SecondaryLoginMethods />
+</AuthPanel>
+```