fix(review): 修复 Copilot PR CR 8 条

longsizhuo · longsizhuo · commit fc864c5a5a24 · 2026-04-16T14:57:31.000Z
安全修复（P0）：
- fetchProfile 只在后端真返 404 或 success=false 时 notFound()；其他非 2xx 抛错进 error boundary
  （避免后端故障伪装成"用户不存在"）
- links/projects/papers 的 URL 在渲染前过 sanitizeExternalUrl 白名单
  （仅 http/https/mailto + 相对路径，拦 javascript:/data: 等 XSS 向量）
- ProfileCard 内部再加 safeHref 二次防御

UX / a11y（P1）：
- ProfileCard 的 click toggle 用 matchMedia('(hover: none)') 限定触屏设备
  （桌面端仍走 group-hover，避免"离开 hover 后仍保持展开"幽灵状态）
- 补 role="button" / tabIndex=0 / onKeyDown(Enter|Space) / aria-expanded，
  键盘 / 读屏用户可用；只在有 detail 时才挂这些属性

文档（P2）：
- docs/architecture/frontend-backend-separation.md
  环境变量章节改成"生产禁 fallback，开发态过渡允许"，与现状（next.config.mjs/upload 仍用 fallback）自洽
- fetchProfile 注释说"直连后端（BACKEND_URL）"，不再错写"走 rewrite"
diff --git a/app/u/[username]/ProfileCard.tsx b/app/u/[username]/ProfileCard.tsx
@@ -3,6 +3,31 @@
 import { useState } from "react";
 import Link from "next/link";
 
+/**
+ * URL scheme 白名单：仅允许 http(s)/mailto 和相对路径（/ 开头）。
+ * 防备 preferences 里注入 javascript: / data: 等导致的 XSS。
+ * 上游 page.tsx 已做一次过滤，这里二次防御以免组件被复用到未过滤的地方。
+ */
+function safeHref(raw: string | undefined | null): string | null {
+  if (!raw || typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  try {
+    if (trimmed.startsWith("/") && !trimmed.startsWith("//")) return trimmed;
+    const u = new URL(trimmed);
+    if (
+      u.protocol === "http:" ||
+      u.protocol === "https:" ||
+      u.protocol === "mailto:"
+    ) {
+      return u.toString();
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 interface ProfileCardProps {
   kind: "PROJ" | "PAPER" | "DOC";
   index: number;
@@ -41,15 +66,41 @@ export function ProfileCard({
     DOC: "Docs",
   }[kind];
 
+  // desktop 走 hover（CSS 驱动，见下面的 group-hover 样式），mobile 走 tap toggle；
+  // 这里用 `@media (hover: none)` 探测"不支持 hover 的设备"（触屏），只有这种设备才在 click 时翻转 state。
+  // 避免桌面端点击导致"离开 hover 后仍保持展开"的幽灵状态。
+  const toggleIfTouchDevice = () => {
+    if (typeof window === "undefined") return;
+    if (window.matchMedia?.("(hover: none)").matches) {
+      setExpanded((v) => !v);
+    }
+  };
+
+  const hasDetail = Boolean(detail);
+
   return (
     <article
-      // onClick 提供 mobile tap toggle；desktop 的 hover 通过 group-hover 样式实现
-      onClick={() => setExpanded((v) => !v)}
+      onClick={hasDetail ? toggleIfTouchDevice : undefined}
+      onKeyDown={
+        hasDetail
+          ? (e) => {
+              if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                setExpanded((v) => !v);
+              }
+            }
+          : undefined
+      }
+      role={hasDetail ? "button" : undefined}
+      tabIndex={hasDetail ? 0 : undefined}
+      aria-expanded={hasDetail ? expanded : undefined}
       className={[
         "group relative border border-[var(--foreground)] bg-[var(--background)]",
-        "p-6 flex flex-col gap-3 min-h-[180px] cursor-pointer",
+        "p-6 flex flex-col gap-3 min-h-[180px]",
+        hasDetail ? "cursor-pointer" : "",
         "transition-shadow duration-200 ease-out",
         "hover:shadow-[6px_6px_0_var(--foreground)]",
+        "focus-visible:outline-none focus-visible:shadow-[6px_6px_0_var(--foreground)] focus-visible:ring-2 focus-visible:ring-[#CC0000]",
         spanFull ? "sm:col-span-2" : "",
       ].join(" ")}
     >
@@ -96,12 +147,16 @@ export function ProfileCard({
         </div>
       )}
 
-      {href && (
+      {safeHref(href) && (
         <div className="mt-auto pt-3">
           <Link
-            href={href}
-            target={href.startsWith("http") ? "_blank" : undefined}
-            rel={href.startsWith("http") ? "noopener noreferrer" : undefined}
+            href={safeHref(href)!}
+            target={safeHref(href)!.startsWith("http") ? "_blank" : undefined}
+            rel={
+              safeHref(href)!.startsWith("http")
+                ? "noopener noreferrer"
+                : undefined
+            }
             onClick={(e) => e.stopPropagation()}
             className="font-mono text-[10px] uppercase tracking-widest text-[#CC0000] hover:underline"
           >
diff --git a/app/u/[username]/page.tsx b/app/u/[username]/page.tsx
@@ -102,22 +102,74 @@ interface ProfileResponse {
 
 /**
  * SSR 获取用户主页基础信息（账户 + preferences）。
+ * 服务端使用 BACKEND_URL 直连 Java 后端（不走 next.config.mjs rewrites，那是给浏览器用的）。
  * 贡献文档不走后端 DB，而是在组件里从 build-time 的 site-leaderboard.json 读取，
  * 目的：每次访问 /u/{x} 省一次 Neon 查询（免费额度有限）。docs 本来就是 git-based，
  * JSON 新鲜度和 DB 一致，都是 deploy 级。
+ *
+ * 错误策略：只有后端明确返回 404 或 success=false 才 return null（走 notFound()）。
+ * 其他失败（500 / 网关异常 / JSON 解析错 / BACKEND_URL 缺失）一律抛错，
+ * 让 Next error boundary 兜底，避免把"后端故障"伪装成"用户不存在"。
  */
+function warnFetchProfile(message: string, details?: Record<string, unknown>) {
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(`[fetchProfile] ${message}`, details ?? {});
+  }
+}
+
 async function fetchProfile(identifier: string): Promise<ProfileData | null> {
   const backendUrl = process.env.BACKEND_URL;
-  if (!backendUrl) return null;
-  try {
-    const res = await fetch(
-      `${backendUrl}/api/user-center/profile/${encodeURIComponent(identifier)}`,
-      { next: { revalidate: 300 } },
+  if (!backendUrl) {
+    // 关键配置缺失不能静默 notFound，给个可见错误
+    throw new Error("BACKEND_URL is not configured");
+  }
+  const res = await fetch(
+    `${backendUrl}/api/user-center/profile/${encodeURIComponent(identifier)}`,
+    { next: { revalidate: 300 } },
+  );
+  // 404：用户确实不存在 → notFound
+  if (res.status === 404) {
+    warnFetchProfile("backend 404", { identifier });
+    return null;
+  }
+  // 其他非 2xx 都抛，进 Next error boundary
+  if (!res.ok) {
+    throw new Error(
+      `profile backend ${res.status} ${res.statusText} for ${identifier}`,
     );
-    if (!res.ok) return null;
-    const json = (await res.json()) as ProfileResponse;
-    if (!json.success || !json.data) return null;
-    return json.data;
+  }
+  const json = (await res.json()) as ProfileResponse;
+  // 后端用 {success:false, message:"用户不存在"} 表示软 404
+  if (!json.success || !json.data) {
+    warnFetchProfile("backend success=false", {
+      identifier,
+      message: json.message,
+    });
+    return null;
+  }
+  return json.data;
+}
+
+/**
+ * URL scheme 白名单：仅允许 http(s)/mailto，拦截 javascript: / data: 等向量。
+ * 任何 preferences 里的 URL 在渲染前必须过这里。
+ */
+function sanitizeExternalUrl(raw: string | undefined | null): string | null {
+  if (!raw || typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  try {
+    // 允许相对路径（以 / 开头），直接放行
+    if (trimmed.startsWith("/") && !trimmed.startsWith("//")) return trimmed;
+    const u = new URL(trimmed);
+    if (
+      u.protocol === "http:" ||
+      u.protocol === "https:" ||
+      u.protocol === "mailto:"
+    ) {
+      return u.toString();
+    }
+    return null;
   } catch {
     return null;
   }
@@ -283,17 +335,32 @@ export default async function UserProfilePage({ params }: Param) {
               <FollowButton identifier={username} targetUserId={user.id} />
               {links.length > 0 && (
                 <div className="border-t border-[var(--foreground)] pt-4 flex flex-wrap gap-2">
-                  {links.slice(0, 5).map((link) => (
-                    <a
-                      key={link.url}
-                      href={link.url}
-                      target="_blank"
-                      rel="noopener noreferrer"
-                      className="font-mono text-[10px] uppercase tracking-widest px-2 py-1 border border-[var(--foreground)] hover:bg-[var(--foreground)] hover:text-[var(--background)] transition-colors"
-                    >
-                      {link.label}
-                    </a>
-                  ))}
+                  {links.slice(0, 5).map((link, idx) => {
+                    // 过滤 javascript: / data: 等危险 scheme，不合法直接渲染成不可点击的纯文本
+                    const safe = sanitizeExternalUrl(link.url);
+                    if (!safe) {
+                      return (
+                        <span
+                          key={`${link.label}-${idx}`}
+                          className="font-mono text-[10px] uppercase tracking-widest px-2 py-1 border border-dashed border-neutral-400 text-neutral-400"
+                          title="链接协议不安全，已禁用"
+                        >
+                          {link.label}
+                        </span>
+                      );
+                    }
+                    return (
+                      <a
+                        key={safe}
+                        href={safe}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        className="font-mono text-[10px] uppercase tracking-widest px-2 py-1 border border-[var(--foreground)] hover:bg-[var(--foreground)] hover:text-[var(--background)] transition-colors"
+                      >
+                        {link.label}
+                      </a>
+                    );
+                  })}
                 </div>
               )}
             </section>
@@ -309,7 +376,7 @@ export default async function UserProfilePage({ params }: Param) {
                   meta={p.tags?.join(" · ")}
                   summary={p.description}
                   detail={p.description}
-                  href={p.url}
+                  href={sanitizeExternalUrl(p.url) ?? undefined}
                 />
               ))}
               {papers.map((p, idx) => (
@@ -322,7 +389,7 @@ export default async function UserProfilePage({ params }: Param) {
                   meta={[p.authors, p.year].filter(Boolean).join(", ")}
                   summary={p.abstract}
                   detail={p.abstract}
-                  href={p.url}
+                  href={sanitizeExternalUrl(p.url) ?? undefined}
                 />
               ))}
               {docs.slice(0, 8).map((doc, idx) => (
diff --git a/docs/architecture/frontend-backend-separation.md b/docs/architecture/frontend-backend-separation.md
@@ -93,7 +93,13 @@ involutionhell.com 早期为了快，前端 Next.js 做了不少后端该做的
 
 ## 环境变量约定
 
-**不做硬编码 fallback**（`?? "http://localhost:8081"` 这种禁止）。理由：端口不一致（8080/8081/其他），fallback 到错的端口会让配置漏配变成静默失败。
+**生产环境不做硬编码 fallback**（`?? "http://localhost:8081"` 这类写法在生产环境禁止）。
+当前仓库里还有少量开发态 / 历史路径在用 `BACKEND_URL ?? "http://localhost:8080"`
+（例如 `next.config.mjs` 的 rewrites 和 `app/api/upload/route.ts`），目的是本地联调
+时减少启动门槛；这些只是过渡状态，**不能作为长期约定**。
+
+原因：端口不一致（8080/8081/其他）时，fallback 很容易把"漏配"变成"静默请求到错误地址"，
+排查成本更高。新代码应该在 env 缺失时显式报错或返回空结果。
 
 | 变量                      | 前端读取场景                | 设置位置                               |
 | ------------------------- | --------------------------- | -------------------------------------- |
