Files
2026-11-16 17:26:44 -08:00

174 lines
7.5 KiB
TypeScript

// 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");
});
});