feat(credential): 凭据不可自愈 ⇒ 行失败 + 整单终态 + 用户端弹窗(服务端五面)

用户口径(2026-11-12,34061 取证后):没余额要退成失败、直接中断任务、并弹窗提示;
所有涉及代理 IP / LLM 密钥的特性都一样。范围=服务端全部特性,客户端下批。

- 判据唯一出处 common/retry/CredentialFatalClassifier(致命:LLM 欠费/密钥失效、
  代理未配置/套餐到期/余额不足/密钥无效;非致命:channel_busy、无空闲通道、冷却、
  超时、5xx、限流、出口被拒、技术性、上游不可用);落终态唯一出口
  modules/task/service/CredentialFatalTaskCloser(重读现状态、拒碰 TERMINAL、可重入)。
  外观专利与相似ASIN 原先逐字重复的 terminalizeOnFatalLlmFailure 改为委托,不留第二份。
- 五面接线:外观专利/相似ASIN、跟价 updateTaskStatusFromLatestRows、
  店铺采集 tryFinalizeTask、采集数据 submitResult。判死后回执一律回读库里状态
  (采集数据内存 task 停在 RUNNING 会让采集端继续为死路买出口 IP)。
- 行级诚实:凭据致命行不计入已判,回退路不再拿原始标题伪造「侵权/成功」。
- 用户端:credential-fatal-notice.ts(判据)+ credential-fatal-alert.ts(按 taskId:kind
  去重)+ CredentialFatalAlert.vue 挂 App.vue;轻量轮询不带文案 ⇒ 跟价/采集数据在失败
  终态补一次重型 batch,店铺 batch 补任务级 taskErrorMessage(只给 FAILED、截断 300 字)。
- 三处真死日志按巡检签名正形写「改判死」(scripts/_prod_watch.py 只认 改判死|接管判死),
  否则判死数不进账本。
- TaskFailureCategoryGuardrailTest:写点搬进收口器 ⇒ 登记 CredentialFatalTaskCloser,
  下限 47→46、updateById 总量 160→159(搬点,不是新增写法)。

判据:CredentialFatalClassifierTest(16)、CollectDataCredentialFatalTest(3)、
PriceTrackTaskServiceTest(8)、ShopDataCrawlScopeMergeTest(11)、
ShopDataCrawlProgressQueryTest(9)、credential-fatal-notice.test.ts(9)、
credential-fatal-alert.test.ts(6)。后端整量 5,464 例 / 0 失败 / 19 skipped。

未纳入本笔:BrandAppearancePatentTab.vue、BrandSimilarAsinTab.vue、TaskItemCard.vue
与两个 Tab 里的按钮/徽章 CSS —— 另一路会话在飞改动,按并发纪律不卷进来。
This commit is contained in:
2026-11-12 18:10:10 +08:00
parent f5f40cd2ea
commit 64e94458c9
37 changed files with 1781 additions and 111 deletions
@@ -120,6 +120,13 @@ export interface ShopDataCrawlHistoryItem extends ShopDataCrawlShopItem {
taskStatus?: string;
success?: boolean;
error?: string;
/**
* 任务级失败原因(只在任务落 FAILED 时由服务端带,截断 300 字)。
*
* 整单判死(未配置代理/套餐到期/LLM 欠费)不会把每个店铺行标失败,
* 所以行级 `error` 是空的——弹窗要读这一格,缺了它就是一句原因都没有的静默失败。
*/
taskErrorMessage?: string;
fileReady?: boolean;
fileStatus?: string;
downloadUrl?: string;
@@ -0,0 +1,71 @@
<script setup lang="ts">
/**
* 「凭据不可自愈 ⇒ 任务已中断」的一次性弹窗(2026-11-12 用户口径:
* 「没余额要退成失败,且直接中断任务,并弹窗提示」)。
*
* 挂在根组件里与 CostGuardAlert/ProxyBalanceAlert 并列:判据与去重在
* `shared/utils/credential-fatal-notice.ts`(纯函数)与 `shared/stores/credential-fatal-alert.ts`
* (框架无关队列),本组件只负责「把队首那条弹给用户,关掉再取下一条」。
*
* 不弹常驻横幅:这类故障的处置是用户去改配置,不是盯着屏幕;弹一次说清「去哪改」即可。
*/
import { onBeforeUnmount, onMounted } from 'vue'
import { ElMessageBox } from 'element-plus'
import {
credentialFatalQueueLength,
subscribeCredentialFatal,
takeCredentialFatal,
} from '@/shared/stores/credential-fatal-alert'
let disposed = false
let showing = false
let unsubscribe: (() => void) | null = null
async function drain(): Promise<void> {
if (disposed || showing) return
showing = true
try {
for (;;) {
const queued = takeCredentialFatal()
if (!queued || disposed) return
// 关闭/ESC 也是正常路径(用户已经看到了):用 .catch 收掉这个「正常取消」,
// 不写成空 catch 块——那正是静默 catch 棘轮点名要减的形状
await ElMessageBox.alert(queued.notice.body, queued.notice.title, {
type: 'error',
confirmButtonText: '知道了',
closeOnClickModal: false,
closeOnPressEscape: true,
// 文案里有换行(一句结论 + 一段动作),不加这条 Element Plus 会压成一行
customStyle: { whiteSpace: 'pre-line' },
}).catch(() => undefined)
if (disposed) return
if (credentialFatalQueueLength() === 0) return
}
} finally {
showing = false
}
}
onMounted(() => {
unsubscribe = subscribeCredentialFatal(() => void drain())
// 挂载前就入队的那条(例如页面先收到终态、弹窗组件后挂)也要弹
void drain()
})
onBeforeUnmount(() => {
disposed = true
unsubscribe?.()
unsubscribe = null
})
</script>
<template>
<!-- 纯行为组件:内容全部走 ElMessageBox,模板留空 -->
<span class="credential-fatal-alert" aria-hidden="true"></span>
</template>
<style scoped>
.credential-fatal-alert {
display: none;
}
</style>
@@ -9,6 +9,7 @@ import { isTerminalTaskStatus } from '../utils/task-terminal.ts'
import { resolveTaskDeleteTarget } from '../utils/task-delete-target.ts'
import { isRecordMissingError } from '../utils/task-queue-state.ts'
import { confirmTaskDeletion } from '../task-delete-confirm.ts'
import { reportCredentialFatal } from '../stores/credential-fatal-alert.ts'
import type { TaskItemView } from '../components/tasks/types'
/**
@@ -53,7 +54,11 @@ export interface LiveTaskHistoryItem {
/** 批量进度响应的公共形状 */
export interface LiveTaskProgressDetail<TItem extends LiveTaskHistoryItem> {
task?: { id?: number; status?: string }
/**
* 任务摘要。`errorMessage` 与 `error` 都取:两个模块的 summary 都带任务级 errorMessage,
* 而行级 error 在「整批都没有可导出字段」时才是唯一的那句话(凭据判死两处都会写)。
*/
task?: { id?: number; status?: string; errorMessage?: string; error?: string }
items?: TItem[]
}
@@ -441,6 +446,9 @@ export function useLiveTaskBoard<T extends LiveTaskHistoryItem>(
mergeHistoryItem(item)
}
if (isTerminalTaskStatus(task.status)) {
// 凭据不可自愈(欠费/套餐到期/未配置代理)时后端已把任务判死:这里弹一次,
// 说清去哪一处改。判据与去重在各自纯函数里,非致命文案不会弹(2026-11-12 用户口径)。
reportCredentialFatal(task.id, item?.error || task.errorMessage || task.error)
removePollingTask(task.id)
shouldRefreshDashboard = true
if (options.addPendingAfterFinalStatus(task, item)) addPendingFileTask(task.id)
@@ -0,0 +1,111 @@
/**
* 「凭据不可自愈 ⇒ 任务已中断」的全局公告队列(**零框架依赖**,`node --test` 可直测)。
*
* 为什么是队列而不是每页各弹一次:五个特性各自轮询,同一个任务在切换页面/重进时会被反复
* 报到终态(`useLiveTaskBoard` 与各 Tab 都在终态分支里调)。一次故障弹五个窗口是噪声,
* 用户真正需要的是「一条说清去改哪」。
*
* 去重口径按 `(taskId, kind)`:同一任务同一档只弹一次(重进页面、重复轮询都吃掉),
* 但用户重试后又因为**另一档**失败时必须再弹——那是要去改另一处的动作。
*
* 队列不落 localStorage:公告是「这一次会话里的这次故障」,刷新页面后任务本身已是终态,
* 历史列表里的错误文案一直在,不需要再弹。
*/
import {
credentialFatalNotice,
type CredentialFatalKind,
type CredentialFatalNotice,
} from '../utils/credential-fatal-notice.ts'
export interface QueuedCredentialFatalNotice {
taskId: number
notice: CredentialFatalNotice
}
const pending: QueuedCredentialFatalNotice[] = []
const reported = new Set<string>()
const listeners = new Set<() => void>()
/** 一次会话里见过的任务数上界:长驻客户端不刷新时不让这个集合无限长。 */
const MAX_REMEMBERED = 500
function rememberKey(taskId: number, kind: CredentialFatalKind): string {
return `${taskId}:${kind}`
}
function notify(): void {
// 订阅方必须同步、不可抛(本仓唯一订阅者是 `CredentialFatalAlert.vue` 的
// `() => void drain()`):这里刻意不套 try/catch —— 吞掉订阅方异常正是棘轮点名的
// 「静默 catch」,而弹窗这件事漏掉一次就是用户看不到故障原因
listeners.forEach((listener) => listener())
}
/**
* 报告一条任务终态文案:命中「不可自愈」才入队。
*
* @returns true=本次真的入队(交付弹窗),false=不致命或这一任务这一档已经报过
*/
export function reportCredentialFatal(taskId: number, message: string | null | undefined): boolean {
if (!Number.isFinite(taskId) || taskId <= 0) return false
const notice = credentialFatalNotice(message)
if (!notice) return false
const key = rememberKey(taskId, notice.kind)
if (reported.has(key)) return false
reported.add(key)
if (reported.size > MAX_REMEMBERED) {
// Set 保留插入序:先扔最老的那一批,够用且无额外记账
const overflow = reported.size - MAX_REMEMBERED
let dropped = 0
for (const stale of reported) {
if (dropped >= overflow) break
reported.delete(stale)
dropped += 1
}
}
pending.push({ taskId, notice })
notify()
return true
}
/**
* 轻量进度里没有错误文案(白名单刻意瘦)时用:先按 `(taskId, kind)` 判重避免白发请求,
* 再取一次重文案补报。取不到就当没发生——网络抖动不该弹窗。
*/
export async function reportCredentialFatalAfterFetch(
taskId: number,
fetcher: () => Promise<string | null | undefined>,
): Promise<boolean> {
if (!Number.isFinite(taskId) || taskId <= 0) return false
const known = Array.from(reported).some((key) => key.startsWith(`${taskId}:`))
// 已报过一次就不再多打一次请求;但同一任务换档失败的情形只能靠取文案才发现,
// 因此只在**完全没有**该任务记录时短路
if (known) return false
// 取不到文案就当没发生(网络抖动不该弹窗):用 .catch 归一到「没有」,
// 不写成空 catch 块——静默 catch 棘轮连这一处也数
const message = await fetcher().catch(() => null)
return reportCredentialFatal(taskId, message)
}
/** 取队首(弹窗组件一次只展示一条)。 */
export function takeCredentialFatal(): QueuedCredentialFatalNotice | null {
return pending.shift() ?? null
}
/** 队列长度(弹窗组件据此决定还要不要继续取)。 */
export function credentialFatalQueueLength(): number {
return pending.length
}
export function subscribeCredentialFatal(listener: () => void): () => void {
listeners.add(listener)
return () => {
listeners.delete(listener)
}
}
/** 仅测试用:清空队列与去重记忆。 */
export function __resetCredentialFatalAlertForTest(): void {
pending.length = 0
reported.clear()
listeners.clear()
}
@@ -0,0 +1,170 @@
/**
* 「凭据不可自愈 ⇒ 任务已中断」的界面判据(纯函数,零 vue、零 `@/` 别名)。
*
* 单独成文件与本仓 `llm-balance-text.ts` / `proxy-balance-alert.ts` 同一理由:判据要能被
* `node --test` 直接钉住。这两档的错法都是「安静地不弹」——欠费时用户以为任务还在跑,
* 实际上是客户端在按次付费买出口 IP、每一行都必然失败。
*
* **与后端 `CredentialFatalClassifier` 是同一套口径的两份实现**(后端判终态、前端判弹窗)。
* 两边必须同形:新增/删除任一档位要两边一起改,否则会出现「任务已判死但界面不弹」
* (用户只看到一行消失)或「界面弹了但其实还在跑」(拿抖动陪葬)的错位。
*/
export type CredentialFatalKind = 'llm_balance' | 'proxy' | 'key_invalid'
export interface CredentialFatalNotice {
kind: CredentialFatalKind
title: string
body: string
}
/** 后端写进终态文案里的那两句指引(`CredentialFatalClassifier.guidance`)里独有的字样。 */
const TERMINAL_SENTENCE = '任务已终止'
const PROXY_TERMINAL_HINT = '代理 IP'
/**
* 可自愈的供应商状态:先判这一档,命中就**不弹**。
*
* 顺序不能反:青果「没有可用的空闲通道」的原文里带着「套餐到期」字样(它在解释为什么拿不到
* 通道),先判欠费就会把一次约 3 分钟就自愈的占用报成"去充值"。后端同一条顺序(铁律 25②)。
*/
const SELF_HEALING_MARKERS = [
'no_available_channel',
'没有可用的空闲通道',
'channel_busy',
'通道被占',
'通道已满',
'冷却',
'cooldown',
'稍后重试',
'timeout',
'timed out',
'超时',
'too many requests',
'rate limited',
'限流',
'bad gateway',
'service unavailable',
'gateway timeout',
'connection refused',
'连接被拒绝',
'不可达',
'unreachable',
'页面无效',
'风控墙',
'人机验证',
]
/** 代理侧「不修外部条件就永远失败」:没配置、套餐耗尽、提取链接/密钥不可用。 */
const PROXY_MARKERS = [
'未配置代理',
'代理地址为空',
'代理链接为空',
'代理',
'提取链接',
'提取分钟数',
'青果',
'qg.net',
'jikip',
'极客',
'套餐',
'invalid_key',
'unavailable_key',
'key_block',
'api_auth_deny',
'access_deny',
]
/** LLM 侧余额/额度类。 */
const LLM_BALANCE_MARKERS = [
'insufficient_user_quota',
'insufficient_quota',
'insufficient balance',
'insufficient_funds',
'wallet balance insufficient',
'quota exceeded',
'预扣费额度',
'余额欠费',
'欠费',
'额度不足',
'余额不足',
]
/** LLM 侧密钥类(与余额分开:用户要做的动作不同——换密钥而不是充值)。 */
const LLM_KEY_MARKERS = [
'密钥无效',
'密钥失效',
'密钥已失效',
'无效的密钥',
'密钥不可用',
'invalid api key',
'invalid_api_key',
'api key 无效',
'apikey 无效',
'unauthorized',
'http 401',
]
function hit(haystack: string, markers: readonly string[]): boolean {
return markers.some((marker) => haystack.includes(marker))
}
/**
* 文案 → 该不该弹、弹哪一档。不可自愈返回公告,其余(含查不出、可自愈、无凭据字样)返回 null。
*
* 判据刻意不认裸 `429/502/503/504`:上游欠费的原文里带账户号与余额(`用户[151502]`),
* 按数字子串判会把一次正常限流当成欠费弹出来。
*/
export function credentialFatalNotice(message: string | null | undefined): CredentialFatalNotice | null {
const raw = (message ?? '').trim()
if (!raw) return null
const text = raw.toLowerCase()
// 后端已经判死并写了指引句:这句话本身就足够定性,先认它(比逐词猜稳)
if (raw.includes(TERMINAL_SENTENCE)) {
return raw.includes(PROXY_TERMINAL_HINT) ? proxyNotice() : llmBalanceNotice()
}
if (hit(text, SELF_HEALING_MARKERS)) return null
const proxy = hit(text, PROXY_MARKERS)
const llmKey = hit(text, LLM_KEY_MARKERS)
const llmBalance = hit(text, LLM_BALANCE_MARKERS)
// 代理与 LLM 同时命中时取代理:代理拿不到就一次 LLM 都不会调,让用户先去充 LLM 是白跑一趟
if (proxy) return proxyNotice()
if (llmKey) return keyInvalidNotice()
if (llmBalance) return llmBalanceNotice()
return null
}
export function proxyNotice(): CredentialFatalNotice {
return {
kind: 'proxy',
title: '任务已中断:代理 IP 不可用',
body:
'任务已经停止,剩下的采集与检测不再继续——否则每一行都要再买一次出口 IP,而结果依然拿不到。\n\n'
+ '请到「密钥设置 → 代理设置」检查提取链接是否已填写、套餐是否到期、余额是否充足;'
+ '处理好之后重新发起任务。这不是你上传的表格有问题。',
}
}
export function llmBalanceNotice(): CredentialFatalNotice {
return {
kind: 'llm_balance',
title: '任务已中断:LLM 额度不足',
body:
'任务已经停止,后面的行不再送检测——额度不够时每一行都会失败,继续跑只会让你等更久。\n\n'
+ '请到「密钥设置 → LLM 密钥」充值或换一把可用的密钥,处理好之后重新发起任务。'
+ '这不是你上传的表格有问题。',
}
}
export function keyInvalidNotice(): CredentialFatalNotice {
return {
kind: 'key_invalid',
title: '任务已中断:密钥无效',
body:
'任务已经停止。上游拒绝了这把密钥(失效、被禁用或权限不足),继续跑不可能成功。\n\n'
+ '请到「密钥设置 → LLM 密钥」更新密钥后重新发起任务。这不是你上传的表格有问题。',
}
}