fix(semantic): 故障照實說是故障——不再把壞掉說成「沒開通」（leo 2026-08-09 直令）
一、文案（portal/console/kbdb hint）：語意搜尋是一安裝就提供的功能，
降級＝故障。橫幅改「語意搜尋目前故障／我們的問題／你不用做任何事」，
拿掉「還沒開通、想開通請匯出診斷檔」這種要使用者申請開通的假框架。
kbdb 降級回應加 degraded_reason（module_off / embed_query_failed）。
二、查詢向量化失敗不再偽裝成空結果（leo 點名的謊）：
semanticSearch 舊行為「AI 額度用完 → 回 []」會讓使用者以為
自己的知識庫裡沒有這筆資料。改丟 EmbedQueryFailedError，
route 誠實降級 keyword＋照實告知是暫時故障。
三、源頭機制（裝好的實例為什麼會失去語意搜尋）：
- acr update：kbdb_embed 判斷 ===true → !==false。config 缺欄位時
redeploy 會把 [[vectorize]]+[ai] binding 靜默剝掉（wrangler deploy
整份覆蓋），一台正常實例就此壞掉。init 預設同步翻成 [Y/n]。
-（另 repo）deploy-all.mjs ensureVectorizeIndex 失敗改致命中止。
四、順手自癒：孤兒向量/下架殘影搜尋時背景清除；空結果且 pending>0
背景 backfill；no_index 拆「故障」vs「還沒有資料」兩態。
測試：kbdb 146/146（新增 degraded 6 案＋selftest 1 案）；cli 10/10；
瀏覽器端到端兩種故障畫面實測（local wrangler dev＋portal 真登入）。
無 SDD 對應：leo 直令修故障（同 08-07 檢修孔前例的人閘直接授權路徑）。
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
uncle6me-web
+37
-3
@@ -325,7 +325,16 @@ export async function embedSelfTest(
|
||||
return { enabled: true, tested: false, passed: null, note: '取樣卡片內容為空，跳過自我檢查' };
|
||||
}
|
||||
// min_score:0——自我檢查要看「找不找得到」，不能被查詢端的相對門檻先濾掉。
|
||||
const hits = await semanticSearch(env, sample, { owner_id: opts.owner_id, topK: 10, min_score: 0 });
|
||||
let hits: SemanticHit[] | null;
|
||||
try {
|
||||
hits = await semanticSearch(env, sample, { owner_id: opts.owner_id, topK: 10, min_score: 0 });
|
||||
} catch (e) {
|
||||
if (e instanceof EmbedQueryFailedError) {
|
||||
// 向量化本身失敗（額度用完/模型故障）＝「這條路現在是斷的」，誠實回報，不算 passed/failed。
|
||||
return { enabled: true, tested: false, passed: null, note: `自我檢查沒跑成：${e.message}（語義搜尋此刻同樣會故障，多半是 Workers AI 額度或服務問題）` };
|
||||
}
|
||||
throw e;
|
||||
}
|
||||
if (hits === null) {
|
||||
return { enabled: false, tested: false, passed: null, note: 'embed 模組回報未開（binding 檢查期間消失，罕見）' };
|
||||
}
|
||||
@@ -349,6 +358,22 @@ export interface SemanticHit {
|
||||
library?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* 查詢向量化失敗（2026-08-09 leo 直令：「查詢的向量化如果失敗（例如當天額度用完），
|
||||
* 目前會回一個空的結果集——那是騙人，不是降級」）。
|
||||
*
|
||||
* 舊行為：embedText 拿不到向量 → semanticSearch 回 []，caller 分不出
|
||||
* 「真的沒命中」和「根本沒查成」，使用者看到「查無資料」，以為知識庫裡沒有這筆東西。
|
||||
* 新行為：AI.run 丟錯（額度用完/模型故障）或回不出向量 → 丟這個錯，
|
||||
* 由 route 層誠實降級 keyword ＋告知「這是我們的故障」，不再偽裝成空結果。
|
||||
*/
|
||||
export class EmbedQueryFailedError extends Error {
|
||||
constructor(detail: string) {
|
||||
super(`查詢向量化失敗：${detail}`);
|
||||
this.name = 'EmbedQueryFailedError';
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 語義搜尋（mode:'semantic'）。模組未開 → 回 null（caller 降級 keyword + 告知缺能力）。
|
||||
* owner_id / source / entry_type 過濾走 Vectorize metadata filter（entry_type 已 index，見上 upsert metadata）。
|
||||
@@ -369,8 +394,17 @@ export async function semanticSearch(
|
||||
opts: { owner_id?: string; source?: string; entry_type?: string; library?: string[]; topK?: number; min_score?: number } = {},
|
||||
): Promise<SemanticHit[] | null> {
|
||||
if (!embedEnabled(env)) return null;
|
||||
const vec = await embedText(env, q);
|
||||
if (!vec) return [];
|
||||
// 空查詢＝真的沒東西可查（route 層已擋 q 必填，這裡只兜底），不算故障。
|
||||
if (!(q ?? '').trim()) return [];
|
||||
// 🔴 2026-08-09（leo 直令）：向量化失敗**不准**回空結果集。空結果=「你的庫裡沒有」，
|
||||
// 向量化失敗=「我們沒查成」——兩者對使用者是完全不同的事實，混在一起就是說謊。
|
||||
let vec: number[] | null;
|
||||
try {
|
||||
vec = await embedText(env, q);
|
||||
} catch (e) {
|
||||
throw new EmbedQueryFailedError(e instanceof Error ? e.message : String(e));
|
||||
}
|
||||
if (!vec) throw new EmbedQueryFailedError('Workers AI 沒有回出向量（回應形狀異常或空回應）');
|
||||
const filter: VectorizeVectorMetadataFilter = {};
|
||||
if (opts.owner_id) filter.owner_id = opts.owner_id;
|
||||
if (opts.source) filter.source = opts.source;
|
||||
|
||||
+96
-23
@@ -13,11 +13,28 @@ import {
|
||||
searchEntries,
|
||||
isDeprecatedEntry,
|
||||
} from '../actions/entry-crud';
|
||||
import { embedEnabled, embedOnWrite, semanticSearch, relativeMinScore, backfillStatus } from '../embed';
|
||||
import {
|
||||
embedEnabled,
|
||||
embedOnWrite,
|
||||
semanticSearch,
|
||||
relativeMinScore,
|
||||
backfillStatus,
|
||||
backfillEmbeddings,
|
||||
EmbedQueryFailedError,
|
||||
} from '../embed';
|
||||
import { migrateLegacyCredentialsForOwner } from '../actions/credential-legacy-migration';
|
||||
|
||||
export const entryRoutes = new Hono<{ Bindings: Bindings }>();
|
||||
|
||||
// fire-and-forget：有 executionCtx（workerd）就 waitUntil，測試環境沒有就 detach（吞錯不吵）。
|
||||
// 給搜尋路徑的「自癒」動作用——修復是順手做的背景事，絕不拖慢也絕不弄壞查詢本身。
|
||||
function fireAndForget(c: { executionCtx?: ExecutionContext }, p: Promise<unknown>): void {
|
||||
let ctx: ExecutionContext | undefined;
|
||||
try { ctx = c.executionCtx; } catch { ctx = undefined; }
|
||||
if (ctx) ctx.waitUntil(p.catch(() => {}));
|
||||
else void p.catch(() => {});
|
||||
}
|
||||
|
||||
// library 多值參數（逗號分隔，portal-auth P1，design §3.3）。空值/全空白 → undefined（＝不過濾，
|
||||
// 行為與未帶參數一字不變——向後相容硬驗收）。
|
||||
function parseLibraryParam(raw: string | undefined): string[] | undefined {
|
||||
@@ -116,9 +133,12 @@ entryRoutes.get('/', async (c) => {
|
||||
// GET /entries/search?q=...&owner_id=...&source=...&entry_type=...&library=...&mode=keyword|semantic
|
||||
// - mode=keyword（預設）：D1 LIKE（base，永遠可用）。
|
||||
// - mode=semantic：需 embed 模組開（Vectorize+AI binding）。未開 → 降級 keyword +
|
||||
// capability_hint 告知缺能力（#7 發現閉環）。capability_hint 是講給非技術使用者聽的人話
|
||||
// capability_hint。capability_hint 是講給非技術使用者聽的人話
|
||||
// （2026-08-08 修：曾經直接透傳到封測用戶眼前的工程師導向文字，見該欄位旁註）；
|
||||
// 技術細節另放 admin_hint 給維運者/CC 看。
|
||||
// 🔴 2026-08-09（leo 直令）：語意搜尋是**一安裝就提供**的功能，模組不在＝故障，
|
||||
// 文案照實說「壞了、是我們的問題、使用者不用做任何事」，禁止說成「還沒開通/未啟用」。
|
||||
// 降級回應帶 degraded_reason（module_off / embed_query_failed）供前端與診斷分流。
|
||||
// - entry_type：base 通用 filter（caller 傳任意 type，如 workflow；base 不寫死語意，workflow-discovery Q4）。
|
||||
// - library：多值庫 filter（逗號分隔，portal-auth P1）。keyword 走 json_extract＋NULL→general；
|
||||
// semantic 走 Vectorize $in。未帶＝全庫（行為不變）。
|
||||
@@ -158,19 +178,41 @@ entryRoutes.get('/search', async (c) => {
|
||||
// 已在 PR 描述向 leo 說明這個 trade-off（多倍 margin vs 迴圈重撈的取捨）。
|
||||
const requestedTopK = top_k ?? 20; // 與 embed.ts semanticSearch 的預設 topK 對齊
|
||||
const fetchTopK = include_deprecated ? requestedTopK : Math.min(requestedTopK * 3, 100);
|
||||
const hits = await semanticSearch(c.env, q, {
|
||||
owner_id, source, entry_type, library, topK: fetchTopK, min_score,
|
||||
});
|
||||
// 🔴 2026-08-09（leo 直令）：語意搜尋壞掉時**照實說是故障**。
|
||||
// - 語意搜尋是一安裝就提供的功能。走到下面任一降級分支＝這台實例壞了，
|
||||
// 不是「還沒開通」「未啟用」——禁止把 bug 美化成沒提供（那會製造
|
||||
// 「請幫我開通」的客服工單，而真正的故障沒人修）。
|
||||
// - capability_hint 給一般使用者看：說清楚「是我們的問題、不是你的錯、
|
||||
// 你不用做任何事」；技術細節放 admin_hint 給維運者/CC。
|
||||
// - 降級仍回關鍵字結果：有退化的結果比空白有用，但誠實標示，不假裝是語意結果。
|
||||
let hits;
|
||||
try {
|
||||
hits = await semanticSearch(c.env, q, {
|
||||
owner_id, source, entry_type, library, topK: fetchTopK, min_score,
|
||||
});
|
||||
} catch (e) {
|
||||
if (e instanceof EmbedQueryFailedError) {
|
||||
// 查詢向量化失敗（Workers AI 額度用完/服務故障）：舊版在這裡回空結果集
|
||||
// ＝把「我們沒查成」偽裝成「你的庫裡沒有」——leo 08-09 點名的謊。改誠實降級。
|
||||
const entries = await searchEntries(c.env.DB, q, owner_id, entry_type, undefined, library, source, include_deprecated);
|
||||
return c.json({
|
||||
success: true,
|
||||
entries,
|
||||
count: entries.length,
|
||||
mode: 'keyword',
|
||||
requested_mode: 'semantic',
|
||||
degraded_reason: 'embed_query_failed',
|
||||
capability_hint:
|
||||
'語意搜尋暫時故障，先用關鍵字幫你找了下面的結果。這是我們系統的問題，不是你的操作問題，你不需要做任何事，稍後它會自動恢復。',
|
||||
admin_hint: `${e.message}。常見原因：Workers AI 當日額度用完或服務暫時異常；本次已降級關鍵字搜尋，資料與索引皆未受影響。`,
|
||||
});
|
||||
}
|
||||
throw e;
|
||||
}
|
||||
if (hits === null) {
|
||||
// 模組沒開：誠實降級 keyword（不假裝有語義）。
|
||||
// 🔴 2026-08-08（總管交辦，Oscar 封測回報「語義搜尋搜不到」的根因修復）：
|
||||
// capability_hint 是「誠實透傳」鏈路（cypher-executor portal-data.ts → portal 前端）
|
||||
// 唯一一次主動告訴非技術使用者「發生什麼事＋下一步」的機會，故預設文案改成人話：
|
||||
// - 不假設讀者懂 vectorize / binding / redeploy / 「叫 CC」這些我們內部的修法指令
|
||||
// - 誠實承認這次是降級（不是「一樣好，只是換個名字」）
|
||||
// - 給一個他自己做得到的下一步（換字重試 / 聯絡我們開通），不是要他自己修系統
|
||||
// 技術細節不丟掉，換到 admin_hint（機器可讀，給真正的維運者/CC 看）——薄殼原則：
|
||||
// 這裡是 base API 的一個回應形狀，兩個欄位並存，caller 自己挑要顯示哪一個。
|
||||
// embed 模組不在（缺 VECTORIZE/AI binding）：對一安裝就提供的功能而言，這**是故障**
|
||||
// ——多半是某次部署把 binding 弄丟了（更新時沒帶 kbdb_embed、或安裝時 Vectorize
|
||||
// 建立失敗被靜默放行）。誠實降級 keyword，照實說壞了，不說「還沒開通」。
|
||||
const entries = await searchEntries(c.env.DB, q, owner_id, entry_type, undefined, library, source, include_deprecated);
|
||||
return c.json({
|
||||
success: true,
|
||||
@@ -178,24 +220,43 @@ entryRoutes.get('/search', async (c) => {
|
||||
count: entries.length,
|
||||
mode: 'keyword',
|
||||
requested_mode: 'semantic',
|
||||
degraded_reason: 'module_off',
|
||||
capability_hint:
|
||||
'語意搜尋還沒開通，這次顯示的是關鍵字比對結果，不是用「意思」找的——你打的字要盡量貼近資料裡實際出現的詞才容易搜到。想啟用語意搜尋，請聯絡我們協助開通。',
|
||||
'語意搜尋目前故障，先用關鍵字幫你找了下面的結果。這是我們系統的問題，不是你的操作問題，你不需要做任何事，我們會修好它。',
|
||||
admin_hint:
|
||||
'語義查詢需先開 vectorize（embed 模組）。叫 CC「幫我開語義查詢」即可（設 kbdb_embed:true + redeploy）。本次已降級關鍵字搜尋。',
|
||||
'故障：kbdb worker 缺 VECTORIZE/AI binding（embedEnabled=false）。語意搜尋是安裝即提供的功能，缺 binding＝部署層事故（常見：redeploy 沒帶 kbdb_embed 注入、或安裝時 Vectorize index 建立失敗被放行）。修法：確認 Vectorize index 存在後以 kbdb_embed:true 重部 kbdb。本次已降級關鍵字搜尋。',
|
||||
});
|
||||
}
|
||||
// hydrate vector hits → 完整 entry（保持回應形狀與 keyword 一致）。
|
||||
// #67：entry 附 score（相似分數）——加欄不改形，既有 caller 不解析多的欄位不受影響。
|
||||
// 2026-08-09 自癒：hydrate 過程順手記下「索引裡有、資料已不在」的向量
|
||||
// - 孤兒（getEntry 找不到）→ 該向量已無對應資料，直接刪；
|
||||
// - 殘影（已下架但向量還在，0.971 案的病原）→ 刪向量＋is_embedded 歸零。
|
||||
// 背景執行（fireAndForget），失敗下次搜尋再清；查詢本身不受影響。
|
||||
const orphanIds: string[] = [];
|
||||
const deprecatedIds: string[] = [];
|
||||
let entries = (
|
||||
await Promise.all(
|
||||
hits.map(async (h) => {
|
||||
const e = await getEntry(c.env.DB, h.id);
|
||||
return e ? { ...e, score: h.score } : null;
|
||||
if (!e) { orphanIds.push(h.id); return null; }
|
||||
return { ...e, score: h.score };
|
||||
}),
|
||||
)
|
||||
).filter((e): e is NonNullable<typeof e> => e !== null);
|
||||
if (!include_deprecated) {
|
||||
entries = entries.filter((e) => !isDeprecatedEntry(e));
|
||||
entries = entries.filter((e) => {
|
||||
const dep = isDeprecatedEntry(e);
|
||||
if (dep) deprecatedIds.push(e.id);
|
||||
return !dep;
|
||||
});
|
||||
}
|
||||
const staleIds = [...orphanIds, ...deprecatedIds];
|
||||
if (staleIds.length > 0 && c.env.VECTORIZE) {
|
||||
fireAndForget(c, (async () => {
|
||||
await c.env.VECTORIZE!.deleteByIds(staleIds);
|
||||
await markUnembedded(c.env.DB, deprecatedIds);
|
||||
})());
|
||||
}
|
||||
// 🔴 2026-08-05：相對門檻砍低分尾（leo 實測「關懷型 AI」命中 20 筆、只有前 3 筆相關）。
|
||||
// **一定要接在濾掉下架的後面**——否則一筆 0.971 的下架殘影會把 0.6 的正解一起帶走
|
||||
@@ -233,21 +294,33 @@ entryRoutes.get('/search', async (c) => {
|
||||
let admin_hint: string;
|
||||
if (hits.length === 0) {
|
||||
const status = await backfillStatus(c.env, { owner_id });
|
||||
if (status.embedded === 0) {
|
||||
if (status.embedded === 0 && status.pending > 0) {
|
||||
// 資料在、索引卻一筆都沒建＝故障（寫入時嵌入沒成功過）。順手自癒：
|
||||
// 背景補嵌一批（冪等、分批），下次搜尋就有機會直接好——不叫使用者做任何事。
|
||||
empty_reason = 'no_index';
|
||||
capability_hint =
|
||||
'這個知識庫目前還沒有可供語意搜尋的資料，所以搜不到——不是你打的字有問題。請聯絡我們確認索引有沒有建好。';
|
||||
admin_hint = `owner_id=${owner_id ?? '(all)'} 範圍 backfillStatus.embedded=0：從未 embed，或 backfill 未跑過。`;
|
||||
'語意搜尋的索引出了狀況，所以暫時搜不到——這是我們系統的問題，不是你打的字有問題。系統正在自動重建，稍後再搜一次看看。';
|
||||
admin_hint = `owner_id=${owner_id ?? '(all)'} 範圍 embedded=0 但 pending=${status.pending}：資料在、索引從沒建成＝寫入端嵌入從未成功（故障）。本次已背景觸發 backfill 自癒（每批 100，冪等）。`;
|
||||
fireAndForget(c, backfillEmbeddings(c.env, { owner_id, limit: 100 }));
|
||||
} else if (status.embedded === 0) {
|
||||
// 連「該被嵌的資料」都沒有＝這個庫還沒有整理好的內容（新裝好還沒同步），不是故障。
|
||||
empty_reason = 'no_index';
|
||||
capability_hint =
|
||||
'這個知識庫還沒有整理好的內容可以搜尋——通常是剛裝好、資料還沒同步進來。等同步小幫手跑完再來搜就有了。';
|
||||
admin_hint = `owner_id=${owner_id ?? '(all)'} 範圍 embedded=0 且 pending=0：沒有任何標記 embed:true 的 entry——多半是 ingest 還沒跑（正常的空），少數情況是 ingest 管線沒標 embed 旗標（要查管線）。`;
|
||||
} else {
|
||||
empty_reason = 'no_match';
|
||||
capability_hint = '沒有找到符合的內容，換個說法或更具體的關鍵字再試試看。';
|
||||
admin_hint = `owner_id=${owner_id ?? '(all)'} 已有 ${status.embedded} 筆嵌入資料，但本次查詢在 Vectorize 端零命中（含 embed.ts 絕對門檻過濾）。`;
|
||||
// 順手自癒：pending>0＝有卡片在寫入時漏嵌（embedOnWrite 失敗是 fire-and-forget，
|
||||
// 沒有別的機制會回來補）。status 已經查了，不多花查詢，背景補一批。
|
||||
if (status.pending > 0) fireAndForget(c, backfillEmbeddings(c.env, { owner_id, limit: 100 }));
|
||||
}
|
||||
} else {
|
||||
empty_reason = 'stale_index';
|
||||
capability_hint =
|
||||
'找到的內容都已經被下架或移除了，所以沒有可顯示的結果——換個關鍵字再試試看，或聯絡我們確認索引有沒有過期。';
|
||||
admin_hint = `Vectorize 命中 ${hits.length} 筆，但 hydrate 後全部是已下架或找不到對應資料（孤兒向量），非分數門檻造成——相對門檻數學上不可能砍光非空結果（cut<=top）。`;
|
||||
'這次比對到的內容源頭已經被移除或下架了，所以沒有可顯示的結果。系統已自動清理過期索引（我們的問題，你不用做任何事），換個關鍵字就能正常搜。';
|
||||
admin_hint = `Vectorize 命中 ${hits.length} 筆，但 hydrate 後全部是已下架或找不到對應資料（孤兒向量），非分數門檻造成——相對門檻數學上不可能砍光非空結果（cut<=top）。本次已背景觸發向量清理（deleteByIds）。`;
|
||||
}
|
||||
return c.json({
|
||||
success: true, entries, count: entries.length, mode: 'semantic',
|
||||
|
||||
@@ -89,6 +89,21 @@ describe('embedSelfTest（檢修孔：卡片自我查詢，驗證 index 真的
|
||||
expect(r.passed).toBe(false);
|
||||
});
|
||||
|
||||
it('向量化本身失敗（AI 額度用完）→ tested:false＋note 說明故障，不 throw 也不假 passed', async () => {
|
||||
const store = [mkEntry('e1', '取樣內容', 'o1')];
|
||||
const env = {
|
||||
DB: makeFakeDB(store),
|
||||
ENVIRONMENT: 'test',
|
||||
AI: { async run() { throw new Error('3040: daily limit'); } },
|
||||
VECTORIZE: { async query() { return { matches: [] }; } },
|
||||
} as unknown as Bindings;
|
||||
const r = await embedSelfTest(env, { owner_id: 'o1' });
|
||||
expect(r.enabled).toBe(true);
|
||||
expect(r.tested).toBe(false);
|
||||
expect(r.passed).toBeNull();
|
||||
expect(r.note).toContain('沒跑成');
|
||||
});
|
||||
|
||||
it('依 owner_id 隔離：別的租戶的已嵌入卡片不會被拿來測', async () => {
|
||||
const store = [mkEntry('e1', 'content', 'other-tenant')];
|
||||
const env = makeEnv(store, { matches: [] });
|
||||
|
||||
@@ -0,0 +1,208 @@
|
||||
// 語意搜尋「故障要照實說是故障」的回歸測試（2026-08-09 leo 直令）。
|
||||
//
|
||||
// 事故：portal 曾把「kbdb 缺 VECTORIZE/AI binding（＝壞了）」顯示成「語意搜尋還沒開通，
|
||||
// 想開通請匯出診斷檔給我們」——把 bug 美化成沒提供的功能，會製造「幫我開通」的客服工單，
|
||||
// 而真正的故障沒人修。leo 原話：「沒有人會把 bug 美化成沒提供沒開通」。
|
||||
//
|
||||
// 三條鐵則（本檔全部驗死）：
|
||||
// 1. 模組不在（module_off）＝故障：文案說「故障/我們的問題/你不用做任何事」，
|
||||
// 禁出現「開通/未啟用/尚未提供」這類把壞說成沒有的字眼，也不要求使用者任何動作。
|
||||
// 2. 查詢向量化失敗（embed_query_failed）＝故障：**不准回空結果集**（舊行為＝
|
||||
// 使用者以為自己的庫裡沒有這筆資料）。誠實降級 keyword＋帶 degraded_reason。
|
||||
// 3. 索引與資料不同步（孤兒向量/下架殘影）→ 搜尋順手自癒（背景刪向量），不留給用戶撞。
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { Hono } from 'hono';
|
||||
import { entryRoutes } from '../src/routes/entries';
|
||||
import type { Bindings, Entry } from '../src/types';
|
||||
|
||||
function mkEntry(id: string, opts: { deprecated?: boolean } = {}): Entry {
|
||||
return {
|
||||
id, content: '一些內容', entry_type: 'block', owner_id: 't1', parent_id: null,
|
||||
page_name: null, refs_json: '[]', tags_json: '[]', task_status: null, content_hash: null,
|
||||
is_embedded: 1, confidence: null,
|
||||
metadata_json: opts.deprecated ? JSON.stringify({ status: 'deprecated', embed: true }) : JSON.stringify({ embed: true }),
|
||||
created_at: 1, updated_at: 1,
|
||||
};
|
||||
}
|
||||
|
||||
// fake D1：紀錄所有 prepare 過的 SQL（驗自癒有沒有真的動手）；COUNT 依 SQL 內容回
|
||||
// embedded/pending 兩種計數；getEntry（WHERE id = ?）回可配置 entry。
|
||||
function makeFakeDB(opts: {
|
||||
embeddedCount?: number;
|
||||
pendingCount?: number;
|
||||
hydrate?: Record<string, Entry | null>;
|
||||
pendingRows?: Entry[];
|
||||
} = {}) {
|
||||
const sqls: string[] = [];
|
||||
const prepare = (sql: string) => {
|
||||
sqls.push(sql);
|
||||
let bound: unknown[] = [];
|
||||
const stmt = {
|
||||
bind(...args: unknown[]) { bound = args; return stmt; },
|
||||
async first<T>() {
|
||||
if (sql.includes('WHERE id = ?')) {
|
||||
const id = String(bound[0]);
|
||||
return ((opts.hydrate ?? {})[id] ?? null) as unknown as T;
|
||||
}
|
||||
if (sql.includes('COUNT(*)')) {
|
||||
// backfillStatus：pending 用 BACKFILL_PREDICATE（含 is_embedded = 0），embedded 用 is_embedded = 1
|
||||
if (sql.includes('is_embedded = 0')) return { c: opts.pendingCount ?? 0 } as unknown as T;
|
||||
return { c: opts.embeddedCount ?? 0 } as unknown as T;
|
||||
}
|
||||
return null as unknown as T;
|
||||
},
|
||||
async all<T>() {
|
||||
// backfillEmbeddings 的候選 SELECT（含 is_embedded = 0）
|
||||
if (sql.includes('is_embedded = 0') && sql.includes('SELECT *')) {
|
||||
return { results: (opts.pendingRows ?? []) as unknown as T[] };
|
||||
}
|
||||
return { results: [] as T[] };
|
||||
},
|
||||
async run() { return { success: true }; },
|
||||
};
|
||||
return stmt;
|
||||
};
|
||||
return { db: { prepare } as unknown as D1Database, sqls };
|
||||
}
|
||||
|
||||
function makeApp() {
|
||||
const app = new Hono<{ Bindings: Bindings }>();
|
||||
app.route('/entries', entryRoutes);
|
||||
return app;
|
||||
}
|
||||
|
||||
/** 收集 waitUntil 的 promise，測試結尾 await 全部，讓背景自癒動作跑完再斷言。 */
|
||||
function makeCtx() {
|
||||
const tasks: Promise<unknown>[] = [];
|
||||
return {
|
||||
ctx: { waitUntil: (p: Promise<unknown>) => { tasks.push(p); }, passThroughOnException() {}, props: {} } as unknown as ExecutionContext,
|
||||
flush: async () => { await Promise.allSettled(tasks); return tasks.length; },
|
||||
};
|
||||
}
|
||||
|
||||
const NO_BLAME_USER = (hint: string) => {
|
||||
// 禁把故障說成「沒提供/沒開通」；禁要求使用者做「申請開通」類動作
|
||||
expect(/開通|尚未啟用|未啟用|還沒啟用|尚未提供|沒有提供/.test(hint)).toBe(false);
|
||||
expect(/請聯絡我們(開通|啟用)|匯出診斷/.test(hint)).toBe(false);
|
||||
// 必須講明是系統端的問題、使用者不用動作
|
||||
expect(/我們(系統)?的問題|系統的問題/.test(hint)).toBe(true);
|
||||
};
|
||||
|
||||
describe('mode=semantic 但 embed 模組不在（module_off）——故障，不是「沒開通」', () => {
|
||||
it('誠實降級 keyword＋degraded_reason=module_off，文案照實說故障、不叫使用者做事', async () => {
|
||||
const app = makeApp();
|
||||
const { db } = makeFakeDB();
|
||||
const env = { DB: db, ENVIRONMENT: 'test' } as unknown as Bindings; // 無 AI/VECTORIZE
|
||||
const res = await app.request('/entries/search?q=x&mode=semantic&owner_id=t1', {}, env);
|
||||
expect(res.status).toBe(200);
|
||||
const body = (await res.json()) as Record<string, unknown>;
|
||||
expect(body.mode).toBe('keyword');
|
||||
expect(body.requested_mode).toBe('semantic');
|
||||
expect(body.degraded_reason).toBe('module_off');
|
||||
const hint = body.capability_hint as string;
|
||||
expect(hint).toContain('故障');
|
||||
NO_BLAME_USER(hint);
|
||||
// admin_hint 保留技術細節給維運者
|
||||
expect(String(body.admin_hint)).toMatch(/VECTORIZE|binding/);
|
||||
});
|
||||
});
|
||||
|
||||
describe('查詢向量化失敗（embed_query_failed）——不准偽裝成「查無資料」', () => {
|
||||
it('AI.run 丟錯（額度用完）→ 200 誠實降級 keyword，不回空語意結果', async () => {
|
||||
const app = makeApp();
|
||||
const { db } = makeFakeDB();
|
||||
const env = {
|
||||
DB: db, ENVIRONMENT: 'test',
|
||||
AI: { async run() { throw new Error('3040: daily limit exceeded'); } },
|
||||
VECTORIZE: { async query() { throw new Error('不應該走到 Vectorize'); } },
|
||||
} as unknown as Bindings;
|
||||
const res = await app.request('/entries/search?q=閉環機&mode=semantic&owner_id=t1', {}, env);
|
||||
expect(res.status).toBe(200);
|
||||
const body = (await res.json()) as Record<string, unknown>;
|
||||
expect(body.mode).toBe('keyword');
|
||||
expect(body.requested_mode).toBe('semantic');
|
||||
expect(body.degraded_reason).toBe('embed_query_failed');
|
||||
const hint = body.capability_hint as string;
|
||||
expect(hint).toContain('故障');
|
||||
NO_BLAME_USER(hint);
|
||||
expect(String(body.admin_hint)).toContain('daily limit exceeded');
|
||||
});
|
||||
|
||||
it('AI.run 回不出向量（形狀異常）→ 同樣走誠實降級，不是空結果', async () => {
|
||||
const app = makeApp();
|
||||
const { db } = makeFakeDB();
|
||||
const env = {
|
||||
DB: db, ENVIRONMENT: 'test',
|
||||
AI: { async run() { return {}; } }, // 沒有 data
|
||||
VECTORIZE: { async query() { return { matches: [] }; } },
|
||||
} as unknown as Bindings;
|
||||
const res = await app.request('/entries/search?q=x&mode=semantic&owner_id=t1', {}, env);
|
||||
const body = (await res.json()) as Record<string, unknown>;
|
||||
expect(body.degraded_reason).toBe('embed_query_failed');
|
||||
expect(body.mode).toBe('keyword');
|
||||
});
|
||||
});
|
||||
|
||||
describe('索引與資料不同步 → 搜尋順手自癒（不留給下一個用戶撞）', () => {
|
||||
it('孤兒向量＋下架殘影：背景 deleteByIds 兩顆、殘影 is_embedded 歸零', async () => {
|
||||
const app = makeApp();
|
||||
const deleted: string[][] = [];
|
||||
const { db, sqls } = makeFakeDB({
|
||||
embeddedCount: 5,
|
||||
hydrate: { live1: mkEntry('live1'), dep1: mkEntry('dep1', { deprecated: true }), gone1: null },
|
||||
});
|
||||
const env = {
|
||||
DB: db, ENVIRONMENT: 'test',
|
||||
AI: { async run() { return { data: [[0.1, 0.2]] }; } },
|
||||
VECTORIZE: {
|
||||
async query() {
|
||||
return { matches: [ { id: 'live1', score: 0.9 }, { id: 'dep1', score: 0.8 }, { id: 'gone1', score: 0.7 } ] };
|
||||
},
|
||||
async deleteByIds(ids: string[]) { deleted.push(ids); },
|
||||
},
|
||||
} as unknown as Bindings;
|
||||
const { ctx, flush } = makeCtx();
|
||||
const res = await app.request('/entries/search?q=x&mode=semantic&owner_id=t1', {}, env, ctx);
|
||||
const body = (await res.json()) as Record<string, unknown>;
|
||||
expect(body.count).toBe(1); // 正常結果不受自癒影響
|
||||
await flush();
|
||||
expect(deleted.flat().sort()).toEqual(['dep1', 'gone1']);
|
||||
// 殘影（dep1）另外把 is_embedded 歸零，讓 D1 與 Vectorize 不說兩套話
|
||||
expect(sqls.some((s) => s.includes('SET is_embedded = 0'))).toBe(true);
|
||||
});
|
||||
|
||||
it('no_index 且 pending>0（資料在、索引從沒建成＝故障）→ 文案不怪用戶＋背景觸發 backfill', async () => {
|
||||
const app = makeApp();
|
||||
let aiCalls = 0;
|
||||
const { db } = makeFakeDB({ embeddedCount: 0, pendingCount: 3, pendingRows: [mkEntry('p1')] });
|
||||
const env = {
|
||||
DB: db, ENVIRONMENT: 'test',
|
||||
AI: { async run() { aiCalls++; return { data: [[0.1, 0.2]] }; } },
|
||||
VECTORIZE: { async query() { return { matches: [] }; }, async upsert() {}, async deleteByIds() {} },
|
||||
} as unknown as Bindings;
|
||||
const { ctx, flush } = makeCtx();
|
||||
const res = await app.request('/entries/search?q=x&mode=semantic&owner_id=t1', {}, env, ctx);
|
||||
const body = (await res.json()) as Record<string, unknown>;
|
||||
expect(body.empty_reason).toBe('no_index');
|
||||
const hint = body.capability_hint as string;
|
||||
NO_BLAME_USER(hint);
|
||||
await flush();
|
||||
// backfill 有真的跑（查詢那次 + 補嵌那批 ≥ 2 次 AI.run）
|
||||
expect(aiCalls).toBeGreaterThanOrEqual(2);
|
||||
});
|
||||
|
||||
it('no_index 且 pending=0（庫真的還沒內容）→ 誠實說還沒有資料，不謊稱故障', async () => {
|
||||
const app = makeApp();
|
||||
const { db } = makeFakeDB({ embeddedCount: 0, pendingCount: 0 });
|
||||
const env = {
|
||||
DB: db, ENVIRONMENT: 'test',
|
||||
AI: { async run() { return { data: [[0.1, 0.2]] }; } },
|
||||
VECTORIZE: { async query() { return { matches: [] }; } },
|
||||
} as unknown as Bindings;
|
||||
const res = await app.request('/entries/search?q=x&mode=semantic&owner_id=t1', {}, env);
|
||||
const body = (await res.json()) as Record<string, unknown>;
|
||||
expect(body.empty_reason).toBe('no_index');
|
||||
expect(String(body.capability_hint)).toContain('還沒有');
|
||||
expect(/故障/.test(String(body.capability_hint))).toBe(false);
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user