// MUST be first — pins env before anything that reads it at module load. import "./setup_env"; import { test, expect, describe } from "bun:test"; import { classifyLarkError, readAsEach } from "../src/lark_doc"; import { resolveKbImportSource, KbImportSourceError } from "../src/kb_import_source"; import type { LarkDocResult, LarkDocText } from "../src/lark_doc"; /** * 这一组守的是「读飞书文档失败时,用户看得见能自救的东西」。 * * 真实事故:2026-09-04 23:19/23:20 两次 KB 批量导入,飞书回 HTTP 403 * `code: 1770032, msg: "forBidden"`(文档没分享给控制面这个应用)。1770032 不在 * FORBIDDEN_CODES 里,于是落进兜底的 `error` 分支,面板显示「读取飞书文档失败, * 请稍后重试」—— 一个永远不会好的问题被说成临时故障,而真正有用的 code 和 * log_id 全烂在服务端日志里,最后要 SSH 上控制面按时间戳去凑。 * * 所以两条性质:分类要对,以及**任何**失败都要把 code / log_id 带到用户面前。 */ /** Lark SDK 的错误形状:诊断信息在 err.response.data 里。 */ const larkErr = (code: number, msg: string, logId = "20260904231956E8C20116FA7C733056E5") => ({ response: { data: { code, msg, log_id: logId } } }); describe("classifyLarkError", () => { test("1770032 是「文档没分享给我们」,不是未知错误", () => { const r = classifyLarkError(larkErr(1770032, "forBidden")); expect(r.status).toBe("forbidden"); expect(r.code).toBe(1770032); expect(r.logId).toBe("20260904231956E8C20116FA7C733056E5"); }); test("缺 scope 仍然单独成一类,并带出飞书给的申请链接", () => { const msg = "Access denied. One of the following scopes is required: [wiki:node:read]." + "点击链接申请 https://open.feishu.cn/app/cli_aa874a31dff89bed/auth?q=wiki:node:read"; const r = classifyLarkError(larkErr(99991672, msg)); expect(r.status).toBe("scope_missing"); expect(r.applyUrl).toContain("open.feishu.cn/app/"); }); test("认不出来的错误码也要把证据带上 —— 兜底分支恰恰最需要它", () => { const r = classifyLarkError(larkErr(1770099, "something new", "LOGID-XYZ")); expect(r.status).toBe("error"); expect(r.code).toBe(1770099); expect(r.logId).toBe("LOGID-XYZ"); expect(r.larkMsg).toBe("something new"); }); test("扁平形状(没有 response.data)也能取到码", () => { const r = classifyLarkError({ code: 1770001, msg: "not found" }); expect(r.status).toBe("not_found"); expect(r.code).toBe(1770001); }); }); describe("批量导入给用户的报错文案", () => { const LINK = "https://bytedance.larkoffice.com/docx/A8xqd2ktzo8fRJxU3aecuDSGnef"; const failWith = (result: LarkDocText) => resolveKbImportSource({ source: LINK }, async () => result); test("无权限:说清是权限问题,并附上 code 与 log_id", async () => { const err = await failWith({ status: "forbidden", code: 1770032, logId: "LOG-1" }) .then(() => null, (e: Error) => e.message); expect(err).toContain("权限"); expect(err).toContain("code=1770032"); expect(err).toContain("log_id=LOG-1"); }); test("未识别的错误:不许说「请稍后重试」,要给证据和求助路径", async () => { const err = await failWith({ status: "error", code: 1770099, logId: "LOG-2", larkMsg: "brand new failure" }) .then(() => null, (e: Error) => e.message); expect(err).not.toContain("请稍后重试"); expect(err).toContain("code=1770099"); expect(err).toContain("log_id=LOG-2"); expect(err).toContain("brand new failure"); }); test("飞书什么都没给时不硬凑括号", async () => { const err = await failWith({ status: "not_found" }).then(() => null, (e: Error) => e.message); expect(err).toContain("没有找到这篇飞书文档"); expect(err).not.toContain("code="); expect(err).not.toContain("()"); }); test("粘纯文本时根本不碰飞书 API", async () => { let called = false; const r = await resolveKbImportSource({ source: "第一条知识\n第二条知识", filename: "笔记" }, async () => { called = true; return { status: "forbidden" } as LarkDocText; }); expect(called).toBe(false); expect(r.markdown).toContain("第一条知识"); expect(r.evidenceRef).toBe("text:笔记"); }); }); describe("失败时给出的自救动作(hint)", () => { const LINK = "https://bytedance.larkoffice.com/docx/A8xqd2ktzo8fRJxU3aecuDSGnef"; const hintOf = async (result: LarkDocText) => { try { await resolveKbImportSource({ source: LINK }, async () => result); return null; } catch (err) { expect(err).toBeInstanceOf(KbImportSourceError); return (err as KbImportSourceError).hint ?? null; } }; test("无权限 → 让用户去共享这篇文档,并带上要搜的 app", async () => { const hint = await hintOf({ status: "forbidden", code: 1770032, logId: "LOG-1" }); expect(hint?.kind).toBe("share_doc"); expect(hint?.docUrl).toBe(LINK); // 点开的必须是他刚粘的那篇 expect(hint?.code).toBe(1770032); expect(hint?.logId).toBe("LOG-1"); }); test("缺 scope → 指向飞书自己生成的申请链接(这条才是真·一键)", async () => { const applyUrl = "https://open.feishu.cn/app/cli_x/auth?q=wiki:node:read"; const hint = await hintOf({ status: "scope_missing", code: 99991672, applyUrl }); expect(hint?.kind).toBe("grant_scope"); expect(hint?.applyUrl).toBe(applyUrl); }); test("其它失败 → 引导到不经过飞书接口的纯文本路径", async () => { expect((await hintOf({ status: "error", code: 1770099 }))?.kind).toBe("paste_text"); expect((await hintOf({ status: "not_found" }))?.kind).toBe("paste_text"); }); test("正文为空也给纯文本出口,而不是只丢一句报错", async () => { const hint = await hintOf({ status: "ok", text: " " }); expect(hint?.kind).toBe("paste_text"); expect(hint?.docUrl).toBe(LINK); }); }); describe("readAsEach:先用提交人身份读,失败再退到应用身份", () => { /** 记录每个身份是否被调用过。 */ const attempt = (calls: string[], name: string, result: LarkDocResult) => async () => { calls.push(name); return result; }; test("用户无权限、应用能读 → 用应用的结果", async () => { const calls: string[] = []; const r = await readAsEach([ attempt(calls, "user", { status: "forbidden", code: 1770032, logId: "LOG-U" }), attempt(calls, "app", { status: "ok", title: "PRD" }), ]); expect(r).toMatchObject({ status: "ok", title: "PRD" }); expect(calls).toEqual(["user", "app"]); }); test("两个身份都失败 → 报用户那次的结果,code / log_id 也是用户的", async () => { const r = await readAsEach([ attempt([], "user", { status: "forbidden", code: 1770032, logId: "LOG-U" }), attempt([], "app", { status: "scope_missing", code: 99991672, logId: "LOG-A" }), ]); expect(r).toMatchObject({ status: "forbidden", code: 1770032, logId: "LOG-U" }); }); test("用户读到 not_found → 文档本身不存在,不再换身份重试", async () => { const calls: string[] = []; const r = await readAsEach([ attempt(calls, "user", { status: "not_found", code: 1770002 }), attempt(calls, "app", { status: "ok", title: "不该走到这里" }), ]); expect(r.status).toBe("not_found"); expect(calls).toEqual(["user"]); }); test("一个身份都没有 → disabled", async () => { expect((await readAsEach([])).status).toBe("disabled"); }); });