Files
crawler-plugin/admin-frontend-vue/src/pages/records/workbench-client-api.ts
T
huangzd1997 0586df2df0 feat(phase-4): AC-16/17/18 前端登录态与分片上传、后管包体与竞态门
AC-16(S1-F1/S1-F2)
- frontend-vue ensureAuth:清态前先判 isAuthError——弱网/超时/5xx 不再把人踢回登录页;
  http.ts 的 onResponseRejected 给错误打鉴权标记(HTTP 401 与业务 401/4011 都算),
  纯网络错误保留底层文案供调用方区分"断网"与"掉登录";clearLocalSession 导出复用。
- admin 全局错误兜底:main.ts 装 app.config.errorHandler(首屏就崩也接得住),
  window error / unhandledrejection 由 App.vue setup 调 useGlobalErrorReporting() 接线,
  卸载出口在 onBeforeUnmount 摘监听与提示定时器(后管的 timer-cleanup-pairing 尺子要求
  "注册点所在文件找得回反注册 + 卸载钩子",故接线必须在组件作用域,不在 main.ts)。
  上报体只带 kind/message/stack/route/ts 并过脱敏(Bearer、JWT 三段式、query 里疑似
  token/key/secret 的取值一律打码),凭据零容忍;服务端新增
  /api/admin/client-errors(requireAdmin,字段截断 2000 后 WARN 落日志,不落库)。

AC-17(S1-F3)
- 后端新增分片通道 ChunkedUploadService(init/part/status/complete/abort):8MB/片、
  同片重复上传幂等覆盖、流式拼装复算 sha256、超限与缺片直接拒绝、24h 过期回收;
  FileUploadController 暴露 /api/files/chunk/**,LocalFileStorageService 加
  saveTempFileFromFile(同一套扩展名黑名单与 fileKey 索引);三键显式写进 application.yml
  (不进"只在代码默认值里"的名单)。
- 工作台安装包 93MB:WorkbenchClientPackageService 走同一分片通道转存 client 桶
  (objectKey 写进会话 purpose,拼装时逐字匹配,防借分片接口覆盖已发布包),
  confirm 失败带 cleanupUnconfirmedObject 补偿清理未登记对象;后管 ≤64MB 仍直传预签名 PUT。
- 用户端 upload.ts:大文件分片 + 逐片重试 + 进度回调,超时按体积给(不再固定 120s);
  断点探测失败不再静默按"全缺"重传(catch-silence 棘轮因此一格没涨,blocks 300→301 已记名)。

AC-18(P1-F1/P1-F2/P1-F4/S1-F4)
- 后管 manualChunks 摘掉 element-plus(按需引入已在 src/plugins/element.ts 生效):
  实测构建产物已无 element-plus 独立 chunk,index.html 只 modulepreload vue 块。
- UsersPage/DeviceLogsPage 接 createLatestRequestGate,旧响应不再覆盖新页;
  用户端新增 useServerTablePaging(只驻留当前页 + 自带竞态门 + 失败给原因),
  挂载用例 3 例钉住"翻页重取/旧响应作废/失败可见"。
- DeliveryVideoWorkspace 两处轮询接 document.visibilityState,隐藏标签页暂停。

激活 Phase 0 预置契约 7 例(用户端 5 + 后管 5,共 12 例;其中 AC-16 后管两支按"接线在组件作用域"
的口径改写并把判据加强到反注册配对 + 根组件接线,见蓝图 §5)。
门禁读数:后端 mvn -o test-compile rc=0,CatchSilenceRatchetTest 9 例绿(total 1034→1045、
notRethrow 585→591、logOnly 182→188 逐处记名,EMPTY 未涨)、ChunkedUploadServiceTest 8 例、
WorkbenchClientPackageServiceTest 21 例、ClientErrorReportControllerTest 4 例;后管 1848 例 +
mount 33 例 + vue-tsc + build 全绿;用户端 955 例 + mount 30 例 + vue-tsc + build 全绿。
真机:OssWorkbenchClientLiveVerificationTest 以线上 MinIO 实测 PUT→stat→sha256→presign→删除
全链 1 例绿(凭据只走环境变量,不落任何文件)。

⚠ 按 pathspec 只圈本轮文件:application.yml 用索引手术只提交分片三键那一格,他人
「PENDING 不再按 2 小时判死」的 StaleTaskRepairService/ClientTaskPullSpi/application.yml
注释件与 useLiveTaskBoard/BrandAppearancePatentTab/task-delete-target 四件在飞改动
原样留在工作树未提交。
2026-10-29 13:47:21 +08:00

251 lines
11 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/** 工作台客户端包接口适配:列表 / 直传预签名 / 分片上传 / 确认 / 删除。 */
import axios from 'axios'
import { http, unwrap } from '@/api/http'
import {
parseWorkbenchClientPackageList,
parseWorkbenchClientPackageUpload,
} from './workbench-client-model.ts'
import type { WorkbenchClientPackageItem, WorkbenchClientPackageList } from './workbench-client-dto.ts'
export const WORKBENCH_CLIENT_PACKAGES_ENDPOINT = '/api/admin/workbench-client/packages'
export const WORKBENCH_CLIENT_PACKAGE_ENDPOINT = '/api/admin/workbench-client/package'
export const WORKBENCH_CLIENT_PRESIGN_ENDPOINT = `${WORKBENCH_CLIENT_PACKAGE_ENDPOINT}/presign`
export const WORKBENCH_CLIENT_CONFIRM_ENDPOINT = `${WORKBENCH_CLIENT_PACKAGE_ENDPOINT}/confirm`
export const WORKBENCH_CLIENT_DELETE_ENDPOINT = `${WORKBENCH_CLIENT_PACKAGE_ENDPOINT}/delete`
/** 分片通道(S1-F3/AC-17):init/complete/abort 在工作台端点,分片体走通用 /api/files/chunk。 */
export const WORKBENCH_CLIENT_CHUNK_INIT_ENDPOINT = `${WORKBENCH_CLIENT_PACKAGE_ENDPOINT}/chunk/init`
export const WORKBENCH_CLIENT_CHUNK_COMPLETE_ENDPOINT = `${WORKBENCH_CLIENT_PACKAGE_ENDPOINT}/chunk/complete`
export const WORKBENCH_CLIENT_CHUNK_ENDPOINT = `${WORKBENCH_CLIENT_PACKAGE_ENDPOINT}/chunk`
/** confirm 失败的补偿清理:只删"已转存未登记"的对象(已登记后端拒绝)。 */
export const WORKBENCH_CLIENT_UNCONFIRMED_OBJECT_ENDPOINT = `${WORKBENCH_CLIENT_PACKAGE_ENDPOINT}/object`
export const FILES_CHUNK_ENDPOINT = '/api/files/chunk'
/** 客户端自动更新契约(后管页面不直接调用):GET 返回 {version,file_url,sha256,...}。 */
export const WORKBENCH_CLIENT_PUBLIC_LATEST_ENDPOINT = '/api/workbench-client/version/latest'
/** MinIO 直传专用实例:不带 cookie、不挂 401 跳登录拦截器;大 zip 给足超时。 */
const directPut = axios.create({ timeout: 600_000, withCredentials: false })
/** 单片大小:8MB——93MB 包 ≈ 12 片,一片失败只重传 8MB,不再从 0 重来。 */
export const UPLOAD_PART_SIZE = 8 * 1024 * 1024
/** ≤64MB 仍走单次预签名直传(链路最短);再大改分片(S1-F3)。 */
export const DIRECT_PUT_MAX_BYTES = 64 * 1024 * 1024
/** 每片重试次数(不含首次):弱网下一片抖一下不必整单作废。 */
const PART_RETRY_LIMIT = 2
export async function fetchWorkbenchClientPackages(): Promise<WorkbenchClientPackageList> {
const { data } = await http.get<unknown>(WORKBENCH_CLIENT_PACKAGES_ENDPOINT)
return parseWorkbenchClientPackageList(data)
}
export interface WorkbenchClientUploadTarget {
objectKey: string
uploadUrl: string
fileUrl: string
version: string
fileName: string
}
/** 第一步:向后端申请直传 PUT 预签名地址(登录会话签发,默认 1 小时有效)。 */
export async function requestWorkbenchClientPresign(
fileName: string,
version: string,
): Promise<WorkbenchClientUploadTarget> {
const { data } = await http.post<unknown>(WORKBENCH_CLIENT_PRESIGN_ENDPOINT, null, {
params: { file_name: fileName, version },
})
const core = (unwrap(data) ?? {}) as Record<string, unknown>
const uploadUrl = typeof core.upload_url === 'string' ? core.upload_url : ''
const objectKey = typeof core.object_key === 'string' ? core.object_key : ''
if (!uploadUrl || !objectKey) {
throw new Error('后端未返回直传地址,请重试')
}
return {
objectKey,
uploadUrl,
fileUrl: typeof core.file_url === 'string' ? core.file_url : '',
version: typeof core.version === 'string' ? core.version : version.trim(),
fileName: typeof core.file_name === 'string' ? core.file_name : fileName,
}
}
/** 第三步:直传完成后通知后端核对对象、复算 sha256 并落库(data.item 为新记录行)。 */
export async function confirmWorkbenchClientPackage(
objectKey: string,
fileName: string,
version: string,
): Promise<WorkbenchClientPackageItem | null> {
// confirm 要服务端流式复算最多 512MB 的 sha256;默认 30s 会在慢 MinIO/跨地域回源时
// 先超时,而服务端可能已经落库——管理员重试会得到「已登记」的错位(CR-08)。
const { data } = await http.post<unknown>(WORKBENCH_CLIENT_CONFIRM_ENDPOINT, null, {
params: { object_key: objectKey, file_name: fileName, version },
timeout: 600_000,
})
return parseWorkbenchClientPackageUpload(data)
}
/**
* confirm 失败后的补偿清理:删除"已转存但未登记"的对象。
* 后端对已登记对象会拒绝清理(防止误删线上正在用的包),失败不覆盖原始错误。
* 返回是否确实清理成功——调用方据此决定报错文案是"可重传"还是"先刷新核对"。
*/
async function deleteUnconfirmedPackageObject(objectKey: string): Promise<boolean> {
try {
await http.delete(WORKBENCH_CLIENT_UNCONFIRMED_OBJECT_ENDPOINT, {
params: { object_key: objectKey },
})
return true
} catch {
return false
}
}
/**
* confirm 失败后的补偿清理(分片链):删会话 + 尽力删未登记对象。
*/
async function cleanupUnconfirmedPackage(uploadId: string, objectKey: string): Promise<void> {
try {
await http.delete(`${WORKBENCH_CLIENT_CHUNK_ENDPOINT}/${encodeURIComponent(uploadId)}`, {
params: objectKey ? { object_key: objectKey } : {},
})
} catch {
// 尽力而为:清理失败只说明残留等人工处置,不能替原始错误改口
}
}
/** 按 id 批量删除客户端包(后端会顺带清理无引用对象的 MinIO 包体);返回实际删除行数。 */
export async function deleteWorkbenchClientPackages(ids: number[]): Promise<number> {
if (!ids.length) return 0
const { data } = await http.post<unknown>(WORKBENCH_CLIENT_DELETE_ENDPOINT, ids)
const core = (unwrap(data) ?? {}) as Record<string, unknown>
return typeof core.deleted === 'number' ? core.deleted : ids.length
}
/** 单次预签名 PUT 直传(≤DIRECT_PUT_MAX_BYTES 的短链路)。 */
async function directPutUpload(
file: Blob,
target: WorkbenchClientUploadTarget,
onProgress?: (percent: number) => void,
): Promise<void> {
await directPut.put(target.uploadUrl, file, {
headers: { 'Content-Type': 'application/octet-stream' },
onUploadProgress: (event) => {
if (!onProgress) return
const total = event.total || 0
onProgress(total > 0 ? Math.min(Math.round((event.loaded / total) * 100), 100) : 0)
},
})
}
/**
* 分片上传(S1-F3/AC-17):整包切成 partSize 片逐片 POST,每片独立重试;
* 开传前先查已到片号——上一次断掉的会话可以直接续传(后端保留 24h)。
* 这一问失败不静默按「全缺」重传:93MB 的包问不到续传点就说明链路已经不对了,
* 当场报错让人重来,也比闷头把整包再传一遍便宜。
*/
async function chunkedUpload(
file: Blob,
uploadId: string,
totalParts: number,
onProgress?: (percent: number) => void,
): Promise<void> {
const { data } = await http.get<unknown>(`${FILES_CHUNK_ENDPOINT}/${encodeURIComponent(uploadId)}`)
const core = (unwrap(data) ?? {}) as Record<string, unknown>
const done = new Set<number>(
(Array.isArray(core.uploaded_parts) ? core.uploaded_parts : []).map((index) => Number(index)),
)
const report = (partial: number) => {
if (!onProgress) return
const loaded = done.size * UPLOAD_PART_SIZE + partial
onProgress(Math.min(Math.round((loaded / file.size) * 100), 99))
}
for (let index = 0; index < totalParts; index += 1) {
if (done.has(index)) {
report(0)
continue
}
const blob = file.slice(index * UPLOAD_PART_SIZE, Math.min(file.size, (index + 1) * UPLOAD_PART_SIZE))
let lastError: unknown = null
for (let attempt = 0; attempt <= PART_RETRY_LIMIT; attempt += 1) {
const form = new FormData()
form.append('file', blob, `part-${index}`)
try {
await http.post(`${FILES_CHUNK_ENDPOINT}/${encodeURIComponent(uploadId)}/part/${index}`, form, {
headers: { 'Content-Type': 'multipart/form-data' },
timeout: 300_000,
onUploadProgress: (event) => report(Math.min(event.loaded || 0, blob.size)),
})
done.add(index)
lastError = null
break
} catch (error) {
lastError = error
}
}
if (lastError) {
throw lastError instanceof Error ? lastError : new Error(`第 ${index} 片上传失败`)
}
}
if (onProgress) onProgress(100)
}
/**
* 上传客户端包:≤64MB 走浏览器直传预签名 PUT;大包走后端分片通道(每片可重试/续传,
* 服务端拼装后转存 client 桶)。两条链最后都收敛到 confirm:服务端复算 sha256、
* 凭据扫描、版本唯一性登记。confirm 失败清理未登记对象,不留孤儿。
*/
export async function uploadWorkbenchClientPackage(
file: Blob,
fileName: string,
version: string,
onProgress?: (percent: number) => void,
): Promise<WorkbenchClientPackageItem | null> {
if (file.size <= DIRECT_PUT_MAX_BYTES) {
const target = await requestWorkbenchClientPresign(fileName, version)
await directPutUpload(file, target, onProgress)
try {
return await confirmWorkbenchClientPackage(target.objectKey, target.fileName, target.version)
} catch (error) {
// confirm 失败先 cleanup 未登记对象再报错;服务端若已登记会拒绝清理(CR-08 幂等窗口),
// 那种情况保留原错误文案引导"先刷新列表",不冒充已处置。
const cleaned = await deleteUnconfirmedPackageObject(target.objectKey)
const reason = error instanceof Error ? error.message : String(error)
if (cleaned) {
throw new Error(`安装包已上传但登记未完成(${reason})。未登记对象已清理,可直接重新上传。`)
}
throw new Error(`安装包已上传,但确认未完成(${reason})。请先刷新列表确认,不要立即重复上传。`)
}
}
const totalParts = Math.max(1, Math.ceil(file.size / UPLOAD_PART_SIZE))
const { data } = await http.post<unknown>(WORKBENCH_CLIENT_CHUNK_INIT_ENDPOINT, null, {
params: { file_name: fileName, version, total_parts: totalParts, total_bytes: file.size },
})
const core = (unwrap(data) ?? {}) as Record<string, unknown>
const uploadId = typeof core.upload_id === 'string' ? core.upload_id : ''
const objectKey = typeof core.object_key === 'string' ? core.object_key : ''
if (!uploadId || !objectKey) {
throw new Error('后端未返回分片会话,请重试')
}
const confirmedName = typeof core.file_name === 'string' ? core.file_name : fileName
const confirmedVersion = typeof core.version === 'string' ? core.version : version
let assembled = false
try {
await chunkedUpload(file, uploadId, totalParts, onProgress)
await http.post(WORKBENCH_CLIENT_CHUNK_COMPLETE_ENDPOINT, null, {
params: { upload_id: uploadId, object_key: objectKey, file_name: confirmedName, version: confirmedVersion },
timeout: 600_000,
})
assembled = true
return await confirmWorkbenchClientPackage(objectKey, confirmedName, confirmedVersion)
} catch (error) {
await cleanupUnconfirmedPackage(uploadId, objectKey)
const reason = error instanceof Error ? error.message : String(error)
if (assembled) {
throw new Error(`安装包已转存但登记未完成(${reason})。未登记对象已清理,可直接重新上传。`)
}
throw error
}
}