fix(auth): 修复邮箱验证跳转死页面、重置密码链接失效与登录循环

内测用户点击 QQ 邮箱验证链接后落到 localhost:3000 死页面，误以为
验证失败（实际已验证成功），进而反馈'不用验证也能登录'。

- signUp 补 emailRedirectTo 指向官网新增 /verified 落地页，该页兼顾
  成功与链接过期（hash 含 error）两种结果，用 useSyncExternalStore
  读取 hash 以规避静态导出的 hydration 不匹配
- ResetPassword 改为应用内验证码（OTP）流程：桌面端 file:// 协议无法
  作为 redirectTo，链接回跳结构性不可用；顺带移除原 token_hash 分支
  从未调用 verifyOtp 的死代码
- 修复登录循环：AuthGuard 与'跳过登录'的模式降级缺口 + session-expired
  事件风暴

需配合 Supabase Dashboard：Site URL、Redirect URLs 白名单、Recovery
邮件模板加 Token 占位符（均已配置）

Author: Aparencia

client/src/hooks/useSessionExpiry.test.ts

@@ -0,0 +1,59 @@
+/**
+ * @ai-context: useSessionExpiry 回归测试——并发 401 与 SIGNED_OUT 会在短时间
+ * 内派发多个 kb:session-expired 事件，冷却窗口内必须只弹一次 Toast。
+ * @ai-context: Regression test — bursts of kb:session-expired events must be
+ * deduplicated within the cooldown window (single toast, single redirect).
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import React from 'react';
+import { MemoryRouter } from 'react-router-dom';
+import { useSessionExpiry } from './useSessionExpiry';
+
+const toastSpy = vi.fn();
+
+vi.mock('@/components/ui', () => ({
+  useToast: () => ({ toast: toastSpy }),
+}));
+
+function wrapper({ children }: { children: React.ReactNode }) {
+  return React.createElement(MemoryRouter, null, children);
+}
+
+describe('useSessionExpiry - 事件风暴去重', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    toastSpy.mockClear();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('冷却窗口内的多个 session-expired 事件只弹一次 Toast', () => {
+    renderHook(() => useSessionExpiry(), { wrapper });
+
+    act(() => {
+      // 模拟多个并发 401 请求 + SIGNED_OUT 各自派发事件
+      window.dispatchEvent(new CustomEvent('kb:session-expired'));
+      window.dispatchEvent(new CustomEvent('kb:session-expired'));
+      window.dispatchEvent(new CustomEvent('kb:session-expired'));
+    });
+
+    expect(toastSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('冷却窗口过后允许再次提示', () => {
+    renderHook(() => useSessionExpiry(), { wrapper });
+
+    act(() => {
+      window.dispatchEvent(new CustomEvent('kb:session-expired'));
+    });
+    act(() => {
+      vi.advanceTimersByTime(10000); // 越过冷却窗口
+      window.dispatchEvent(new CustomEvent('kb:session-expired'));
+    });
+
+    expect(toastSpy).toHaveBeenCalledTimes(2);
+  });
+});

client/src/hooks/useSessionExpiry.ts

@@ -7,6 +7,13 @@ import { useToast } from '@/components/ui';
 
 const SESSION_EXPIRED_EVENT = 'kb:session-expired';
 
+/**
+ * 事件去重冷却窗口：并发 401 请求与 Supabase SIGNED_OUT 会在短时间内
+ * 各自派发 session-expired，窗口内只处理第一个，避免重复弹 Toast
+ * 让用户感知为"持续要求登录"（内测反馈 bug）
+ */
+const SESSION_EXPIRED_COOLDOWN_MS = 5000;
+
 /**
  * 监听 session 过期事件，弹出 Toast 提示并提供重新登录入口
  * 需在 AppLayout 或其他全局组件中调用
@@ -23,9 +30,16 @@ export function useSessionExpiry() {
 
   // Bug #15: 防止重复设置 setTimeout
   const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // 冷却窗口去重：记录上次处理事件的时间戳
+  const lastHandledAtRef = useRef(0);
 
   useEffect(() => {
     function handleSessionExpired() {
+      // 冷却窗口内的重复事件（并发 401 / SIGNED_OUT 风暴）直接忽略
+      const now = Date.now();
+      if (now - lastHandledAtRef.current < SESSION_EXPIRED_COOLDOWN_MS) return;
+      lastHandledAtRef.current = now;
+
       toastRef.current({
         type: 'warning',
         message: '登录已过期，请重新登录',

client/src/lib/auth/AuthContext.tsx

@@ -100,7 +100,14 @@ export function AuthProvider({ children }: { children: ReactNode }) {
     if (isPlaceholder) {
       return { error: { message: '云服务尚未配置，请先在 .env 中设置 VITE_SUPABASE_URL 和 VITE_SUPABASE_ANON_KEY' } as AuthError };
     }
-    const { error } = await supabase.auth.signUp({ email, password });
+    // emailRedirectTo：验证邮件链接在系统浏览器打开，桌面端无法回到应用，
+    // 故落地到官网验证成功页（需同步加入 Supabase Redirect URLs 白名单，
+    // 否则回退到 Site URL）
+    const { error } = await supabase.auth.signUp({
+      email,
+      password,
+      options: { emailRedirectTo: 'https://entropydecrease.com/verified' },
+    });
     return { error };
   }, []);
 

client/src/pages/LoginPage.test.tsx

@@ -0,0 +1,39 @@
+/**
+ * @ai-context: LoginPage 回归测试——"跳过登录"必须降级到 local 模式，
+ * 否则 AuthGuard 会在 hybrid/full 模式下把未登录用户弹回登录页（死循环）。
+ * @ai-context: Regression test — "skip login" must downgrade to local mode,
+ * otherwise AuthGuard keeps redirecting unauthenticated users back to /login.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { MemoryRouter } from 'react-router-dom';
+import LoginPage from './LoginPage';
+import { modeManager } from '@/lib/mode/ModeManager';
+
+vi.mock('@/lib/auth/AuthContext', () => ({
+  useAuth: () => ({
+    signIn: vi.fn().mockResolvedValue({ error: null }),
+  }),
+}));
+
+describe('LoginPage - 跳过登录', () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  it('点击"跳过登录"应将模式降级为 local，避免 AuthGuard 循环重定向', () => {
+    // 模拟内测用户此前开启过云同步（hybrid 模式已持久化）
+    modeManager.setMode('hybrid');
+
+    render(
+      <MemoryRouter initialEntries={['/login']}>
+        <LoginPage />
+      </MemoryRouter>,
+    );
+
+    fireEvent.click(screen.getByText(/跳过登录/));
+
+    // 核心断言：模式必须降级，否则回到 / 会被 AuthGuard 再次踢回 /login
+    expect(modeManager.getMode()).toBe('local');
+  });
+});

client/src/pages/LoginPage.tsx

@@ -7,6 +7,7 @@ import { Mail, Lock, AlertCircle } from 'lucide-react';
 import { Button, Input, Card } from '@/components/ui';
 import { cn } from '@/lib/utils';
 import { useAuth } from '@/lib/auth/AuthContext';
+import { modeManager } from '@/lib/mode/ModeManager';
 
 export default function LoginPage() {
   const navigate = useNavigate();
@@ -17,6 +18,16 @@ export default function LoginPage() {
   const [error, setError] = useState<string | null>(null);
   const [loading, setLoading] = useState(false);
 
+  /**
+   * 跳过登录：必须先把模式降级为 local，再回首页。
+   * 否则 hybrid/full 模式下 AuthGuard 会立即把未登录用户踢回登录页，
+   * 形成"持续要求登录"的死循环（内测反馈 bug）。
+   */
+  const handleSkipLogin = () => {
+    modeManager.setMode('local');
+    navigate('/', { replace: true });
+  };
+
   const handleSubmit = async (e: FormEvent) => {
     e.preventDefault();
     setError(null);
@@ -136,11 +147,15 @@ export default function LoginPage() {
           </p>
         </Card>
 
-        {/* Skip link */}
+        {/* Skip link：降级到本地模式后再离开，避免 AuthGuard 循环重定向 */}
         <p className="text-c1 text-text-tertiary text-center mt-5">
-          <Link to="/" className="hover:text-text-secondary transition-colors">
+          <button
+            type="button"
+            onClick={handleSkipLogin}
+            className="hover:text-text-secondary transition-colors"
+          >
             跳过登录，继续使用本地功能
-          </Link>
+          </button>
         </p>
       </div>
     </div>

client/src/pages/ResetPassword.tsx

@@ -1,36 +1,32 @@
 /**
- * @ai-context: 页面组件：ResetPassword。
+ * @ai-context: 页面组件：ResetPassword。重置密码采用邮箱验证码（OTP）流程：
+ * 请求重置 → 邮件收 6 位验证码 → 应用内输入验证码+新密码。
+ * Why: 桌面端邮件链接在系统浏览器打开、恢复会话无法回到应用（file:// 协议
+ * 也无法作为 redirectTo），链接回跳模式结构性不可用，故全程留在应用内。
+ * 依赖 Supabase Recovery 邮件模板包含 {{ .Token }} 验证码。
  */
 import { useState, useEffect, useRef, type FormEvent } from 'react';
-import { Link, useSearchParams, useNavigate } from 'react-router-dom';
-import { Mail, Lock, AlertCircle, CheckCircle2, ArrowLeft } from 'lucide-react';
+import { Link, useNavigate } from 'react-router-dom';
+import { Mail, Lock, KeyRound, AlertCircle, CheckCircle2, ArrowLeft } from 'lucide-react';
 import { Button, Input, Card } from '@/components/ui';
 import { cn } from '@/lib/utils';
 import { supabase } from '@/lib/auth/supabaseClient';
 
 type ViewMode = 'request' | 'reset';
 
 export default function ResetPassword() {
-  const [searchParams] = useSearchParams();
   const navigate = useNavigate();
 
-  const tokenHash = searchParams.get('token_hash');
-  const type = searchParams.get('type');
-  const isResetMode = tokenHash && type === 'recovery';
-
-  const [viewMode, setViewMode] = useState<ViewMode>(isResetMode ? 'reset' : 'request');
+  const [viewMode, setViewMode] = useState<ViewMode>('request');
   const [email, setEmail] = useState('');
+  const [otpCode, setOtpCode] = useState('');
   const [password, setPassword] = useState('');
   const [confirmPassword, setConfirmPassword] = useState('');
   const [error, setError] = useState<string | null>(null);
   const [success, setSuccess] = useState(false);
   const [loading, setLoading] = useState(false);
   const navigateTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  useEffect(() => {
-    if (isResetMode) setViewMode('reset');
-  }, [isResetMode]);
-
   useEffect(() => {
     return () => {
       if (navigateTimerRef.current) clearTimeout(navigateTimerRef.current);
@@ -48,12 +44,10 @@ export default function ResetPassword() {
 
     setLoading(true);
     try {
-      const redirectTo = `${window.location.origin}${window.location.pathname}#/reset-password`;
-      const { error: resetError } = await supabase.auth.resetPasswordForEmail(email.trim(), {
-        redirectTo,
-      });
+      // 不传 redirectTo：验证走应用内 OTP 验证码，不依赖邮件链接跳转
+      const { error: resetError } = await supabase.auth.resetPasswordForEmail(email.trim());
       if (resetError) throw resetError;
-      setSuccess(true);
+      setViewMode('reset');
     } catch (err: unknown) {
       const msg = err instanceof Error ? err.message : '发送失败，请稍后重试';
       setError(msg);
@@ -66,6 +60,10 @@ export default function ResetPassword() {
     e.preventDefault();
     setError(null);
 
+    if (!otpCode.trim() || otpCode.trim().length < 6) {
+      setError('请输入邮件中的 6 位验证码');
+      return;
+    }
     if (!password || password.length < 8) {
       setError('密码长度至少 8 位');
       return;
@@ -77,6 +75,13 @@ export default function ResetPassword() {
 
     setLoading(true);
     try {
+      // 先用验证码换取恢复会话，再更新密码
+      const { error: otpError } = await supabase.auth.verifyOtp({
+        email: email.trim(),
+        token: otpCode.trim(),
+        type: 'recovery',
+      });
+      if (otpError) throw otpError;
       const { error: updateError } = await supabase.auth.updateUser({ password });
       if (updateError) throw updateError;
       setSuccess(true);
@@ -107,7 +112,9 @@ export default function ResetPassword() {
               {viewMode === 'request' ? '重置密码' : '设置新密码'}
             </h1>
             <p className="text-b2 text-text-tertiary mt-1">
-              {viewMode === 'request' ? '输入邮箱以接收重置链接' : '输入你的新密码'}
+              {viewMode === 'request'
+                ? '输入邮箱以接收验证码'
+                : `验证码已发送至 ${email}`}
             </p>
           </div>
         </div>
@@ -117,41 +124,25 @@ export default function ResetPassword() {
           {success ? (
             <div className="flex flex-col items-center gap-4 py-2">
               <CheckCircle2 className="w-12 h-12 text-emerald-500" strokeWidth={1.5} />
-              <p className="text-b1 font-medium text-text-primary text-center">
-                {viewMode === 'request'
-                  ? '重置邮件已发送'
-                  : '密码重置成功'}
-              </p>
-              <p className="text-b2 text-text-tertiary text-center">
-                {viewMode === 'request'
-                  ? `如果 ${email} 已注册，你将收到一封重置密码的邮件`
-                  : '即将跳转到登录页...'}
-              </p>
-              {viewMode === 'request' && (
-                <Link
-                  to="/login"
-                  className="text-b2 text-brand-600 font-medium hover:text-brand-700 transition-colors mt-2"
-                >
-                  返回登录
-                </Link>
-              )}
+              <p className="text-b1 font-medium text-text-primary text-center">密码重置成功</p>
+              <p className="text-b2 text-text-tertiary text-center">即将跳转到登录页...</p>
             </div>
           ) : (
             <>
-              {viewMode === 'request' ? (
-                <form onSubmit={handleRequestReset} className="flex flex-col gap-kb-md">
-                  {error && (
-                    <div
-                      className={cn(
-                        'flex items-start gap-2 px-3 py-2.5 rounded-kb-md',
-                        'bg-[#F43F5E]/10 border border-[#F43F5E]/30',
-                      )}
-                    >
-                      <AlertCircle className="w-icon-sm h-icon-sm text-[#F43F5E] flex-shrink-0 mt-0.5" strokeWidth={1.5} />
-                      <p className="text-b3 text-[#F43F5E]">{error}</p>
-                    </div>
+              {error && (
+                <div
+                  className={cn(
+                    'flex items-start gap-2 px-3 py-2.5 rounded-kb-md mb-4',
+                    'bg-[#F43F5E]/10 border border-[#F43F5E]/30',
                   )}
+                >
+                  <AlertCircle className="w-icon-sm h-icon-sm text-[#F43F5E] flex-shrink-0 mt-0.5" strokeWidth={1.5} />
+                  <p className="text-b3 text-[#F43F5E]">{error}</p>
+                </div>
+              )}
 
+              {viewMode === 'request' ? (
+                <form onSubmit={handleRequestReset} className="flex flex-col gap-kb-md">
                   <Input
                     label="注册邮箱"
                     type="email"
@@ -163,22 +154,21 @@ export default function ResetPassword() {
                   />
 
                   <Button type="submit" variant="primary" size="lg" loading={loading} className="w-full mt-1">
-                    发送重置链接
+                    发送验证码
                   </Button>
                 </form>
               ) : (
                 <form onSubmit={handleResetPassword} className="flex flex-col gap-kb-md">
-                  {error && (
-                    <div
-                      className={cn(
-                        'flex items-start gap-2 px-3 py-2.5 rounded-kb-md',
-                        'bg-[#F43F5E]/10 border border-[#F43F5E]/30',
-                      )}
-                    >
-                      <AlertCircle className="w-icon-sm h-icon-sm text-[#F43F5E] flex-shrink-0 mt-0.5" strokeWidth={1.5} />
-                      <p className="text-b3 text-[#F43F5E]">{error}</p>
-                    </div>
-                  )}
+                  <Input
+                    label="邮箱验证码"
+                    type="text"
+                    inputMode="numeric"
+                    placeholder="邮件中的 6 位验证码"
+                    autoComplete="one-time-code"
+                    prefix={<KeyRound className="w-icon-sm h-icon-sm" strokeWidth={1.5} />}
+                    value={otpCode}
+                    onChange={(e) => setOtpCode(e.target.value)}
+                  />
 
                   <Input
                     label="新密码"
@@ -203,6 +193,14 @@ export default function ResetPassword() {
                   <Button type="submit" variant="primary" size="lg" loading={loading} className="w-full mt-1">
                     重置密码
                   </Button>
+
+                  <button
+                    type="button"
+                    onClick={() => { setViewMode('request'); setError(null); }}
+                    className="text-b3 text-text-tertiary hover:text-text-secondary transition-colors text-center"
+                  >
+                    没收到验证码？返回重新发送
+                  </button>
                 </form>
               )}
             </>