@allbluecn/web-app 0.19.2 → 0.19.4

package/src/hooks/use-popover-outside-close.ts

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { useEffect, useRef } from "react";
+
+/** Base UI Popover 内容/触发器的 data-slot 选择器（ui/popover 约定） */
+const POPOVER_SLOT_SELECTOR = '[data-slot="popover-content"], [data-slot="popover-trigger"]';
+
+/**
+ * Dialog 嵌套场景下 Popover 的 outside-dismiss 可能被 Dialog 层拦截，
+ * 用 pointerdown 兜底关闭。判定以事件目标向上 closest 匹配任一 Popover
+ * 的 content/trigger（此前各调用点用 document.querySelector 取全局首个匹配，
+ * 页面存在多个弹层时会误判别人的弹层——审计 A7x-web-comp-15）。
+ *
+ * @param open 任一受控 Popover 处于打开态时传 true
+ * @param onClose 点击落在所有 Popover 之外时的关闭回调（身份可变，内部经 ref 透传）
+ */
+export function usePopoverOutsideClose(open: boolean, onClose: () => void) {
+  const onCloseRef = useRef(onClose);
+  onCloseRef.current = onClose;
+
+  useEffect(() => {
+    if (!open) return;
+    const handlePointerDown = (e: PointerEvent) => {
+      const target = e.target;
+      if (target instanceof Element && target.closest(POPOVER_SLOT_SELECTOR)) return;
+      onCloseRef.current();
+    };
+    document.addEventListener("pointerdown", handlePointerDown);
+    return () => document.removeEventListener("pointerdown", handlePointerDown);
+  }, [open]);
+}

package/src/hooks/use-scrolling.ts

@@ -16,7 +16,7 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import type { RefObject } from "react"
-import { useEffect, useState } from "react"
+import { useEffect, useRef, useState } from "react"
 import { useDebouncedCallback } from "@tanstack/react-pacer"
 
 type ScrollTarget = RefObject<HTMLElement> | Window | null | undefined
@@ -33,11 +33,14 @@ export function useScrolling(
 ): boolean {
   const { debounce = 150, fallbackToDocument = true } = options
   const [isScrolling, setIsScrolling] = useState(false)
+  // ref 镜像当前状态：监听器回调内不依赖 state，避免 isScrolling 进入依赖数组
+  // 导致滚动状态每次翻转都重跑 effect、重复挂载/摘除监听器
+  const isScrollingRef = useRef(false)
 
-  const debouncedSetFalse = useDebouncedCallback(
-    (value: boolean) => setIsScrolling(value),
-    { wait: debounce }
-  )
+  const debouncedSetNotScrolling = useDebouncedCallback(() => {
+    isScrollingRef.current = false
+    setIsScrolling(false)
+  }, { wait: debounce })
 
   useEffect(() => {
     const element: EventTargetWithScroll =
@@ -58,24 +61,29 @@ export function useScrolling(
       handler: EventListener
     ) => el.addEventListener(event, handler, true)
 
+    // capture 标志必须与 on 一致，否则移除无效（DOM 规范按 capture 匹配）
     const off = (
       el: EventTargetWithScroll,
       event: string,
       handler: EventListener
-    ) => el.removeEventListener(event, handler)
+    ) => el.removeEventListener(event, handler, true)
 
     const supportsScrollEnd = element === window && "onscrollend" in window
 
     const handleScroll: EventListener = () => {
-      if (!isScrolling) {
+      if (!isScrollingRef.current) {
+        isScrollingRef.current = true
         setIsScrolling(true)
       }
       if (!supportsScrollEnd) {
-        debouncedSetFalse(false)
+        debouncedSetNotScrolling()
       }
     }
 
-    const handleScrollEnd: EventListener = () => setIsScrolling(false)
+    const handleScrollEnd: EventListener = () => {
+      isScrollingRef.current = false
+      setIsScrolling(false)
+    }
 
     on(eventTarget, "scroll", handleScroll)
     if (supportsScrollEnd) {
@@ -88,7 +96,7 @@ export function useScrolling(
         off(eventTarget, "scrollend", handleScrollEnd)
       }
     }
-  }, [target, debounce, fallbackToDocument, isScrolling, debouncedSetFalse])
+  }, [target, debounce, fallbackToDocument, debouncedSetNotScrolling])
 
   return isScrolling
 }

package/src/hooks/use-translator.ts

@@ -17,63 +17,80 @@
 
 import { useState, useEffect, useRef } from "react";
 import { translateFn } from '@/server/serverFns/translation'
+import { getLocale } from '@/paraglide/runtime'
+import { m } from '@/paraglide/messages.js'
 
 interface TranslationCache {
   [key: string]: string;
 }
 
+// 缓存上限：超过后丢弃最早写入的条目，避免长会话无界增长
+const TRANSLATION_CACHE_LIMIT = 200;
 const translationCache: TranslationCache = {};
+const translationCacheOrder: string[] = [];
+
+function pushTranslationCache(key: string, value: string) {
+  if (translationCache[key]) return;
+  translationCache[key] = value;
+  translationCacheOrder.push(key);
+  while (translationCacheOrder.length > TRANSLATION_CACHE_LIMIT) {
+    const oldest = translationCacheOrder.shift();
+    if (oldest !== undefined) delete translationCache[oldest];
+  }
+}
+
+/** 目标语言随 paraglide locale 派生，而非固定 zh-CN */
+function resolveTargetLocale(): string {
+  return getLocale() === "en" ? "en" : "zh-CN";
+}
 
 export function useTranslator(text: string) {
   const [translatedText, setTranslatedText] = useState("");
   const [isTranslating, setIsTranslating] = useState(false);
   const [error, setError] = useState<string | null>(null);
-  const abortRef = useRef<AbortController | null>(null);
+  // 递增请求序号：仅最后一次发起的请求可 setState，防止快速切换 text 时
+  // 旧响应（慢回）覆盖新响应（stale 覆盖）
+  const reqIdRef = useRef(0);
 
   useEffect(() => {
     if (!text) {
       setTranslatedText("");
+      setError(null);
       return;
     }
 
     const cacheKey = text.trim();
-    if (translationCache[cacheKey]) {
-      setTranslatedText(translationCache[cacheKey]);
+    const cached = translationCache[cacheKey];
+    if (cached) {
+      setTranslatedText(cached);
       return;
     }
 
-    if (abortRef.current) {
-      abortRef.current.abort();
-    }
-    abortRef.current = new AbortController();
-
-    async function translate() {
-      setIsTranslating(true);
-      setError(null);
+    const reqId = ++reqIdRef.current;
+    setIsTranslating(true);
+    setError(null);
 
-      try {
-        const data = await translateFn({ data: { text, from: 'auto', to: 'zh-CN' } })
+    translateFn({ data: { text, from: 'auto', to: resolveTargetLocale() } })
+      .then((data) => {
+        if (reqIdRef.current !== reqId) return;
         if (data.translated) {
-          translationCache[cacheKey] = data.translated;
+          pushTranslationCache(cacheKey, data.translated);
           setTranslatedText(data.translated);
         }
-      } catch (err) {
-        if ((err as Error).name !== "AbortError") {
-          setError(err instanceof Error ? err.message : "翻译失败");
-        }
-      } finally {
-        setIsTranslating(false);
-      }
-    }
-
-    translate();
+      })
+      .catch((err: unknown) => {
+        if (reqIdRef.current !== reqId) return;
+        setError(err instanceof Error ? err.message : m.common_translator_failed());
+      })
+      .finally(() => {
+        if (reqIdRef.current === reqId) setIsTranslating(false);
+      });
 
     return () => {
-      if (abortRef.current) {
-        abortRef.current.abort();
-      }
+      // text 变化/卸载时使在途请求失效（serverFn 不支持 signal，用序号守卫实现取消语义）
+      reqIdRef.current += 1;
     };
   }, [text]);
 
   return { translatedText, isTranslating, error };
-}
+}

package/src/lib/__tests__/ai-adapter.test.ts

@@ -15,39 +15,17 @@
 // You should have received a copy of the GNU Affero General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
-import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { describe, it, expect, vi } from 'vitest'
 
-describe('getActiveAgent / switchAgent', () => {
-  beforeEach(() => {
-    vi.resetModules()
-  })
-
-  it('returns null when no agent is active', async () => {
-    const { getActiveAgent } = await import('@/shared/ai-cli/adapter')
-    expect(getActiveAgent()).toBeNull()
-  })
+// 模块级 activeAgentId 单例已删除（跨请求/跨用户共享串扰，审计 🟠）：
+// agent 一律经 executeViaAgent 参数显式传递，相关 store/get 测试随之移除。
 
-  it('switchAgent sets active agent', async () => {
-    const { switchAgent, getActiveAgent } = await import('@/shared/ai-cli/adapter')
-    switchAgent('openai-api')
-    expect(getActiveAgent()).toBe('openai-api')
-  })
-
-  it('switchAgent overwrites previous agent', async () => {
-    const { switchAgent, getActiveAgent } = await import('@/shared/ai-cli/adapter')
-    switchAgent('claude-code')
-    switchAgent('ollama')
-    expect(getActiveAgent()).toBe('ollama')
-  })
-})
+const AGENT = { id: 'openai-api', name: 'OpenAI', binary: 'api', version: 'v1', available: true }
 
 describe('executeViaAgent', () => {
-  beforeEach(() => {
-    vi.resetModules()
-  })
-
-  it('calls OpenAI API for openai-api agent', async () => {
+  it('openai-api 分支调用配置端点并返回内容', async () => {
     const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
       json: () => Promise.resolve({ choices: [{ message: { content: 'Hello!' } }] }),
     })
     vi.stubGlobal('fetch', mockFetch)
@@ -55,11 +33,7 @@ describe('executeViaAgent', () => {
     process.env.AI_BASE_URL = 'https://test.api.com/v1'
 
     const { executeViaAgent } = await import('@/shared/ai-cli/adapter')
-    const result = await executeViaAgent(
-      { id: 'openai-api', name: 'OpenAI', binary: 'api', version: 'v1', available: true },
-      'Say hello',
-      {} as any
-    )
+    const result = await executeViaAgent(AGENT, 'Say hello', {} as never)
 
     expect(mockFetch).toHaveBeenCalledWith(
       'https://test.api.com/v1/chat/completions',
@@ -70,23 +44,50 @@ describe('executeViaAgent', () => {
     )
     expect(result).toBe('Hello!')
     vi.unstubAllGlobals()
+    delete process.env.AI_BASE_URL
   })
 
-  it('returns empty string on empty response', async () => {
+  it('空响应返回空串', async () => {
     const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
       json: () => Promise.resolve({ choices: [] }),
     })
     vi.stubGlobal('fetch', mockFetch)
     process.env.OPENAI_API_KEY = 'sk-test'
 
     const { executeViaAgent } = await import('@/shared/ai-cli/adapter')
-    const result = await executeViaAgent(
-      { id: 'openai-api', name: 'OpenAI', binary: 'api', version: 'v1', available: true },
-      'Say hello',
-      {} as any
-    )
+    const result = await executeViaAgent(AGENT, 'Say hello', {} as never)
 
     expect(result).toBe('')
     vi.unstubAllGlobals()
   })
+
+  it('Key 未配置时快速失败，不发空 Bearer', async () => {
+    const mockFetch = vi.fn()
+    vi.stubGlobal('fetch', mockFetch)
+    const saved = process.env.OPENAI_API_KEY
+    delete process.env.OPENAI_API_KEY
+
+    const { executeViaAgent } = await import('@/shared/ai-cli/adapter')
+    await expect(executeViaAgent(AGENT, 'x', {} as never)).rejects.toThrow(/OPENAI_API_KEY/)
+    expect(mockFetch).not.toHaveBeenCalled()
+
+    if (saved !== undefined) process.env.OPENAI_API_KEY = saved
+    vi.unstubAllGlobals()
+  })
+
+  it('非 2xx 响应抛错并保留上游错误信息', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 429,
+      text: () => Promise.resolve('{"error":{"message":"quota exceeded"}}'),
+    })
+    vi.stubGlobal('fetch', mockFetch)
+    process.env.OPENAI_API_KEY = 'sk-test'
+
+    const { executeViaAgent } = await import('@/shared/ai-cli/adapter')
+    await expect(executeViaAgent(AGENT, 'x', {} as never)).rejects.toThrow(/quota exceeded/)
+
+    vi.unstubAllGlobals()
+  })
 })

package/src/lib/__tests__/annotation-prompt.test.ts

@@ -41,9 +41,13 @@ describe("buildFillPrompt", () => {
     }
     const sections = await buildFillPrompt(info)
     const prompt = sections.join("\n")
-    // 指令段来自模板（收编到 PromptRegistry），组件信息在「组件信息：」与「要求：」之间
+    // 指令段来自模板（收编到 PromptRegistry），组件信息在「组件信息：」与「要求：」之间。
+    // 组件信息源自最终用户可写的设计文档数据（审计 🟡），经 fenceLlmData 围栏后再注入——
+    // 围栏不影响内部行文，模板内的字段行仍可逐行断言。
     expect(prompt).toContain("你是产品文档注释填充助手")
-    expect(prompt).toContain("组件信息：\n- 类型：button\n- 名称：登录按钮\n- 可编辑属性：")
+    expect(prompt).toContain("- 类型：button")
+    expect(prompt).toContain("- 名称：登录按钮")
+    expect(prompt).toContain("- 可编辑属性：")
     expect(prompt).toContain("- 按钮文案（text）（当前值：登录）")
     expect(prompt).toContain("注释模板（保持此 HTML 结构不变")
     expect(prompt).toContain("<p>按钮文案：{{text}}</p>")

package/src/lib/__tests__/datetime.test.ts

@@ -17,6 +17,12 @@
 
 import { describe, it, expect } from 'vitest'
 import { formatDate, formatRelative, resolveTimezone, formatTimestamp } from '../datetime'
+import { overwriteGetLocale } from '@/paraglide/runtime'
+
+// formatRelative/formatChatDate 的用户可见文案经 paraglide 按 locale 解析：
+// jsdom 测试环境 navigator.language 为 en-US 会解析成英文——显式钉住 zh，
+// 断言与文案解耦（文案本身由 i18n 资源保证）
+overwriteGetLocale(() => 'zh')
 
 describe('resolveTimezone', () => {
   it('项目时区优先', () => {

package/src/lib/__tests__/github.test.ts

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// 审计 2026-10-25：GITHUB_TOKEN 曾随直连失败后的 ghproxy.com 回落请求原样发出。
+// 钉死：Authorization 只发给 api.github.com；代理端点一律无 token；请求带超时。
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { fetchGitHubRepoData, fetchLatestRelease, parseGithubUrl } from "../github";
+
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  vi.stubGlobal("fetch", fetchMock);
+  vi.stubEnv("GITHUB_TOKEN", "ghp_secret");
+  fetchMock.mockReset();
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+});
+
+const headersOf = (callIndex: number) =>
+  (fetchMock.mock.calls[callIndex]![1] as RequestInit).headers as Record<string, string>;
+
+describe("GITHUB_TOKEN 只随直连发出", () => {
+  it("直连成功：仅一次请求，带 Authorization 与超时信号", async () => {
+    fetchMock.mockResolvedValueOnce(
+      new Response(JSON.stringify({ full_name: "a/b", stargazers_count: 1 }), { status: 200 }),
+    );
+    const data = await fetchGitHubRepoData("a", "b");
+    expect(data?.fullName).toBe("a/b");
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0]![0]).toBe("https://api.github.com/repos/a/b");
+    expect(headersOf(0).Authorization).toBe("Bearer ghp_secret");
+    expect((fetchMock.mock.calls[0]![1] as RequestInit).signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it("直连失败回落代理：代理请求不携带 Authorization", async () => {
+    fetchMock
+      .mockResolvedValueOnce(new Response("", { status: 503 }))
+      .mockResolvedValueOnce(new Response(JSON.stringify({ full_name: "a/b" }), { status: 200 }));
+    await fetchGitHubRepoData("a", "b");
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(fetchMock.mock.calls[1]![0]).toBe("https://ghproxy.com/https://api.github.com/repos/a/b");
+    expect(headersOf(1)).not.toHaveProperty("Authorization");
+  });
+
+  it("fetchLatestRelease 同口径", async () => {
+    fetchMock
+      .mockRejectedValueOnce(new Error("network"))
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify({ tag_name: "v1", published_at: "2026-01-01" }), { status: 200 }),
+      );
+    await fetchLatestRelease("a", "b");
+    expect(headersOf(0).Authorization).toBe("Bearer ghp_secret");
+    expect(headersOf(1)).not.toHaveProperty("Authorization");
+  });
+});
+
+describe("parseGithubUrl 路径段白名单", () => {
+  it("合法 owner/repo 解析", () => {
+    expect(parseGithubUrl("https://github.com/TanStack/router.git")).toEqual({ owner: "TanStack", repo: "router" });
+    expect(parseGithubUrl("https://github.com/a-b/c.d_e/tree/main/x")).toEqual({ owner: "a-b", repo: "c.d_e" });
+  });
+
+  it("含 ? # .. 等可改写请求路径的字符 → null", () => {
+    expect(parseGithubUrl("https://github.com/a/b?x=1")).toBeNull();
+    expect(parseGithubUrl("https://github.com/a/b#frag")).toBeNull();
+    expect(parseGithubUrl("https://github.com/a/..")).toBeNull();
+    expect(parseGithubUrl("https://github.com/a")).toBeNull();
+  });
+});

package/src/lib/__tests__/login-redirect.test.ts

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { describe, expect, it } from "vitest"
+
+import { isSafeRelativeRedirect, resolveLoginCallbackUrl } from "../login-redirect"
+
+const AUTH_PATHS = ["/login", "/register", "/forgot-password", "/reset-password"]
+
+const resolve = (redirectTo?: string | null) =>
+  resolveLoginCallbackUrl({
+    redirectTo,
+    authPaths: AUTH_PATHS,
+    desktopCallbackPath: "/api/auth/desktop-callback",
+    fallbackPath: "/dashboard",
+  })
+
+describe("resolveLoginCallbackUrl（审计 2026-10-25：协议相对开放重定向）", () => {
+  it("desktop 标记优先", () => {
+    expect(resolve("/login?desktop_redirect=true")).toBe("/api/auth/desktop-callback")
+  })
+
+  it("desktop 标记携带 desktop_state → 透传到回调端点（深链一次性比对消费）", () => {
+    expect(resolve("/login?desktop_redirect=true&desktop_state=abc123")).toBe(
+      "/api/auth/desktop-callback?desktop_state=abc123",
+    )
+    // 特殊字符经 encode，不能把 state 注成第二个 query 键
+    expect(resolve("/login?desktop_redirect=true&desktop_state=a%26b")).toBe(
+      "/api/auth/desktop-callback?desktop_state=a%26b",
+    )
+  })
+
+  it("登录页自身路径 → 默认页", () => {
+    expect(resolve("/login")).toBe("/dashboard")
+    expect(resolve("/register?from=x")).toBe("/dashboard")
+  })
+
+  it("站内相对路径放行", () => {
+    expect(resolve("/dashboard/settings?tab=profile")).toBe("/dashboard/settings?tab=profile")
+    expect(resolve("/stories/abc")).toBe("/stories/abc")
+  })
+
+  it("协议相对与反斜杠形态一律回落默认页（此前原样透传）", () => {
+    expect(resolve("//evil.example/phish")).toBe("/dashboard")
+    expect(resolve("/\\evil.example")).toBe("/dashboard")
+    expect(resolve("javascript:alert(1)")).toBe("/dashboard")
+    // 绝对 URL 分支剥掉外部 origin，只剩站内 pathname（不会跳到外部域）
+    expect(resolve("https://evil.example")).toBe("/")
+  })
+
+  it("绝对同站 URL 取 pathname+search（既有语义保留）", () => {
+    expect(resolve("https://app.example.com/stories/1?x=2")).toBe("/stories/1?x=2")
+  })
+
+  it("空值 → 默认页", () => {
+    expect(resolve(undefined)).toBe("/dashboard")
+    expect(resolve(null)).toBe("/dashboard")
+  })
+
+  it("isSafeRelativeRedirect", () => {
+    expect(isSafeRelativeRedirect("/a")).toBe(true)
+    expect(isSafeRelativeRedirect("//a")).toBe(false)
+    expect(isSafeRelativeRedirect("/\\a")).toBe(false)
+    expect(isSafeRelativeRedirect("a")).toBe(false)
+  })
+})

package/src/lib/__tests__/project-display-id.test.ts

@@ -17,6 +17,7 @@
 
 import { describe, it, expect } from 'vitest'
 import { extractDisplayId, validateDisplayId } from '../project-display-id'
+import { m } from '@/paraglide/messages.js'
 
 describe('extractDisplayId', () => {
   it('提取纯字母数字并转大写', () => {
@@ -50,16 +51,16 @@ describe('validateDisplayId', () => {
     expect(validateDisplayId('ABC123')).toBeNull()
   })
   it('空字符串返回错误', () => {
-    expect(validateDisplayId('')).toBe('项目ID不能为空')
+    expect(validateDisplayId('')).toBe(m.common_project_displayId_required())
   })
   it('小写字母返回错误', () => {
-    expect(validateDisplayId('abc')).toBe('仅全大写字母数字，最多10位')
+    expect(validateDisplayId('abc')).toBe(m.common_project_displayId_format())
   })
   it('含特殊字符返回错误', () => {
-    expect(validateDisplayId('ABC-123')).toBe('仅全大写字母数字，最多10位')
+    expect(validateDisplayId('ABC-123')).toBe(m.common_project_displayId_format())
   })
   it('超过10位返回错误', () => {
-    expect(validateDisplayId('ABCDEFGHIJK')).toBe('仅全大写字母数字，最多10位')
+    expect(validateDisplayId('ABCDEFGHIJK')).toBe(m.common_project_displayId_format())
   })
   it('10 位边界有效', () => {
     expect(validateDisplayId('ABCDEFGHIJ')).toBeNull()

package/src/lib/__tests__/safe-url.test.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { describe, expect, it } from "vitest"
+
+import { isSafeHref, safeHrefOr, toSafeHref } from "../safe-url"
+
+describe("toSafeHref 白名单", () => {
+  it("http / https / mailto / tel 放行并归一化", () => {
+    expect(toSafeHref("https://example.com/a?b=1#c")).toBe("https://example.com/a?b=1#c")
+    expect(toSafeHref("HTTP://Example.com")).toBe("http://example.com/")
+    expect(toSafeHref("mailto:a@b.io")).toBe("mailto:a@b.io")
+    expect(toSafeHref("tel:+8613800000000")).toBe("tel:+8613800000000")
+  })
+
+  it("javascript / data / vbscript / file / blob 一律拒绝（含大小写与控制字符混淆）", () => {
+    for (const bad of [
+      "javascript:alert(1)",
+      "JaVaScRiPt:alert(1)",
+      "java\tscript:alert(1)",
+      "java\nscript:alert(1)",
+      "  javascript:alert(1)",
+      "data:text/html,<script>alert(1)</script>",
+      "vbscript:msgbox(1)",
+      "file:///etc/passwd",
+      "blob:https://example.com/uuid",
+    ]) {
+      expect(toSafeHref(bad), bad).toBeNull()
+    }
+  })
+
+  it("站内相对引用原样放行；协议相对按绝对 https 处理", () => {
+    expect(toSafeHref("/knowledge/doc-1")).toBe("/knowledge/doc-1")
+    expect(toSafeHref("./x")).toBe("./x")
+    expect(toSafeHref("../x")).toBe("../x")
+    expect(toSafeHref("?page=2")).toBe("?page=2")
+    expect(toSafeHref("#section")).toBe("#section")
+    expect(toSafeHref("foo/bar")).toBe("foo/bar")
+    expect(toSafeHref("//evil.example/x")).toBe("https://evil.example/x")
+  })
+
+  it("allowRelative:false（iframe src 等）拒绝全部相对引用", () => {
+    expect(toSafeHref("/x", { allowRelative: false })).toBeNull()
+    expect(toSafeHref("foo", { allowRelative: false })).toBeNull()
+    expect(toSafeHref("https://ok.example", { allowRelative: false })).toBe("https://ok.example/")
+  })
+
+  it("自定义 scheme 白名单", () => {
+    expect(toSafeHref("http://x.example", { allowedSchemes: ["https:"] })).toBeNull()
+    expect(toSafeHref("https://x.example", { allowedSchemes: ["https:"] })).toBe("https://x.example/")
+  })
+
+  it("空值 / 非字符串 / 不可解析 → null", () => {
+    expect(toSafeHref("")).toBeNull()
+    expect(toSafeHref("   ")).toBeNull()
+    expect(toSafeHref(null)).toBeNull()
+    expect(toSafeHref(undefined)).toBeNull()
+    expect(toSafeHref("http://[::1")).toBeNull()
+  })
+})
+
+describe("便捷形态", () => {
+  it("isSafeHref / safeHrefOr", () => {
+    expect(isSafeHref("https://a.b")).toBe(true)
+    expect(isSafeHref("javascript:1")).toBe(false)
+    expect(safeHrefOr("javascript:1")).toBe("#")
+    expect(safeHrefOr("javascript:1", "")).toBe("")
+    expect(safeHrefOr("https://a.b")).toBe("https://a.b/")
+  })
+})