fix(web): 大纲错误透传 FriendlyError, 不再向用户暴露内部 code

apps/web/components/outline/OutlineEditor.tsx

@@ -8,6 +8,7 @@ import { Button } from "@/components/ui/Button";
 import { EmptyState } from "@/components/ui/EmptyState";
 import { PageHeader } from "@/components/ui/PageHeader";
 import { Select } from "@/components/ui/Select";
+import { StatusNote } from "@/components/ui/StatusNote";
 import { TextInput } from "@/components/ui/TextInput";
 import type { OutlineChapterView, ProjectResponse } from "@/lib/api/types";
 import {
@@ -111,20 +112,20 @@ export function OutlineEditor({
         />
 
         {error ? (
-          <p className="mb-4 text-sm text-conflict">
+          <StatusNote variant="danger" title="大纲生成失败" className="mb-4">
-            大纲生成失败（{error.code}）：{error.message}
+            {error.text}
-            {error.code === "LLM_UNAVAILABLE" ? (
+            {error.actionHref ? (
               <>
                 {" "}
                 <a
-                  href="/settings/providers"
+                  href={error.actionHref}
                   className="underline hover:text-cinnabar"
                 >
-                  去设置提供商
+                  {error.actionLabel}
                 </a>
               </>
             ) : null}
-          </p>
+          </StatusNote>
         ) : null}
 
         <div className="min-h-0 flex-1 overflow-auto">

apps/web/lib/outline/useOutline.test.ts

@@ -61,7 +61,7 @@ describe("useOutline", () => {
     expect(result.current.chapters).toEqual([]);
   });
 
-  it("后端返回业务错误：status=error 并 surface 友好文案", async () => {
+  it("后端返回业务错误：透传 friendly 文案 + 跳转动作（不再固定 OUTLINE_FAILED）", async () => {
     post.mockResolvedValue({
       data: null,
       error: { error: { code: "LLM_UNAVAILABLE" } },
@@ -72,18 +72,36 @@ describe("useOutline", () => {
     });
 
     expect(result.current.status).toBe("error");
-    expect(result.current.error?.code).toBe("OUTLINE_FAILED");
+    // LLM_UNAVAILABLE → 透传 provider 文案 + 「去设置提供商」链接。
-    expect(result.current.error?.message).toContain("provider");
+    expect(result.current.error?.text).toContain("provider");
+    expect(result.current.error?.actionHref).toBe("/settings/providers");
+    expect(result.current.error?.actionLabel).toBe("去设置提供商");
     expect(toast).toHaveBeenCalledWith(expect.any(String), "error");
   });
 
-  it("data 为空且无 error 也走错误分支", async () => {
+  it("校验错误（422 detail 信封）：透传 VALIDATION 文案且无跳转动作", async () => {
+    post.mockResolvedValue({
+      data: null,
+      error: { detail: [{ msg: "字段缺失" }] },
+    });
+    const { result } = renderHook(() => useOutline([]));
+    await act(async () => {
+      await result.current.generate("p1", 1);
+    });
+    expect(result.current.status).toBe("error");
+    expect(result.current.error?.text).toBeTruthy();
+    expect(result.current.error?.actionHref).toBeUndefined();
+    expect(result.current.error?.actionLabel).toBeUndefined();
+  });
+
+  it("data 为空且无 error 也走错误分支（兜底文案、无跳转）", async () => {
     post.mockResolvedValue({ data: null, error: null });
     const { result } = renderHook(() => useOutline([]));
     await act(async () => {
       await result.current.generate("p1", 1);
     });
     expect(result.current.status).toBe("error");
-    expect(result.current.error?.code).toBe("OUTLINE_FAILED");
+    expect(result.current.error?.text).toBeTruthy();
+    expect(result.current.error?.actionHref).toBeUndefined();
   });
 });

apps/web/lib/outline/useOutline.ts

@@ -4,20 +4,20 @@ import { useCallback, useState } from "react";
 
 import { api } from "@/lib/api/client";
 import { useToast } from "@/components/Toast";
-import { friendlyFromApiError } from "@/lib/errors/messages";
+import {
+  friendlyFromApiError,
+  type FriendlyError,
+} from "@/lib/errors/messages";
 import type { OutlineChapterView } from "@/lib/api/types";
 
 export type OutlineStatus = "idle" | "generating" | "ready" | "error";
 
-export interface OutlineError {
-  code: string;
-  message: string;
-}
-
 export interface UseOutline {
   chapters: OutlineChapterView[];
   status: OutlineStatus;
-  error: OutlineError | null;
+  // 直接透传 friendlyFromApiError 的结果（含 text + 可选 actionHref/actionLabel），
+  // 不再拍平成固定的内部 code，UI 据 actionHref 是否存在决定显示跳转链接。
+  error: FriendlyError | null;
   generate: (projectId: string, volume: number) => Promise<void>;
 }
 
@@ -28,7 +28,7 @@ export function useOutline(initial: OutlineChapterView[]): UseOutline {
   const [status, setStatus] = useState<OutlineStatus>(
     initial.length > 0 ? "ready" : "idle",
   );
-  const [error, setError] = useState<OutlineError | null>(null);
+  const [error, setError] = useState<FriendlyError | null>(null);
   const toast = useToast();
 
   const generate = useCallback<UseOutline["generate"]>(
@@ -45,8 +45,9 @@ export function useOutline(initial: OutlineChapterView[]): UseOutline {
       if (apiError || !data) {
         // surface 真实错因（如 LLM_UNAVAILABLE→去设置 provider；422→校验文案），
         // 而非永远的通用「大纲生成失败」（QA #2：原 env.error.code 漏读 422 的 detail 信封）。
+        // 直接透传 friendly（保留 actionHref/actionLabel），不再拍平成固定 OUTLINE_FAILED。
         const friendly = friendlyFromApiError(apiError);
-        setError({ code: "OUTLINE_FAILED", message: friendly.text });
+        setError(friendly);
         setStatus("error");
         toast(friendly.text, "error");
         return;