Files
crawler-plugin/admin-frontend-vue/src/pages/records/workbench-client-api.ts
T
huangzd1997 a5e390750b refactor(slim-r3): 删除零引用死模块——keywordshare/debug/PublicWorkbenchClientVersion 三线 40 件
Project-Slimming 第三轮收尾执行(用户拍板「零引用的也都要删除」):
定谳依据=6.4 天生产访问日志零流量(970 万行单遍对撞,26 UNIQUE 前缀防撞车)
+四树代码零引用(后端类名/包名/字符串、admin、用户端、app_client 全扫)
+V163 建菜单→V165 撤菜单的历史链(功能入口 10 月底已下线,Controller 成孤儿)。

删除(40 件):
- modules/keywordshare 整模块 31 类+4 mapper XML+KeywordShareServiceTest
  (后管 V165 已撤菜单、app_client 同步链 kw_share_api 亦无调用方;
  biz_keyword_share 等表按「已应用迁移不可回改」保留在库)
- modules/debug 2 支控制器(/debug/request-info、/debug/task-recovery/*)
- workbenchclient/controller/PublicWorkbenchClientVersionController
  (/api/workbench-client/version/latest:app_client 实际走 /api/version/latest,
  admin 侧仅文案引用,无任何真实调用方)
- config/KeywordShareSyncProperties(唯一消费方 KeywordShareService 同批删)

同步编辑:
- AdminApiGuardFilter:摘 DEBUG_PREFIX 前缀(常量/javadoc/审计日志块/requiresCredential/
  guardedPrefixes 五处);ApiGuardCoverageAuditor:METHOD_GUARDED_PATHS 摘 /api/keyword-share
- PropertiesConfig 摘 KeywordShareSyncProperties.class;application.yml 与
  application-local.example.yml 摘 keyword-share-sync 段与两个 env
- 台账两处扣减:XML_SELECT_TOTAL 114→103(11 select)、XML_STATEMENT_TOTAL 164→147
  (11 select+4 insert+1 delete);MigratedSqlEquivalenceTest.NOT_MIGRATED 摘 12 条点名
  (tsv 基准账本零 KeywordShare 行,LEDGER_ROWS/LEDGER_SELECTS 不动)
- PendingPhase5ReadPathTest 摘 P1-B2(RAND 断言随 XML 删);ApiGuardCoverageAuditorTest
  前缀总数 25→24;AdminApiGuardFilterTest 摘 4 支 /debug 用例与 2 条边界 URI
- admin:workbench-client-api 死常量、页面头注释与 page-hint、operation-guides 指南文案
  摘被删端点字样;align-workbench-client.test 摘 3 条对应断言

零行为影响:全部删除件在 6.4 天窗口内零流量;守卫过滤器行为对现存前缀不变
(/api/admin、用户态、自助清单原样)。
2026-11-16 12:18:05 +08:00

248 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'
/** 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
}
}