/** * 桌面端「指定版本更新」纯逻辑:解析公开版本列表、按版本去重排序、 * 判定目标版本相对本机是升级 / 同版 / 回退。 * * 数据源:GET /api/version/list(公开接口,字段口径同管理端 /api/admin/versions)。 * 回退(older)是本功能允许的显式操作,但**必须给出明确文案**,不得静默降级 * (背景见 version-compare 的"不引导降级"约定:自动检测不提示降级,手动指定除外)。 */ import { compareVersions, normVersion } from './version-compare.ts' /** 公开版本列表项(同一版本重复上传时只保留最新一条记录) */ export interface ClientVersionItem { /** web_config 记录 id */ id?: number | string /** 版本号(已归一化,不带 v 前缀) */ version: string /** 安装包公开下载直链 */ fileUrl: string /** 发布记录时间(yyyy-MM-dd HH:mm,接口原样透传) */ createdAt: string } /** 目标版本相对本机的类型:更新 / 同版本 / 回退 / 本机版本未知 */ export type TargetVersionKind = 'newer' | 'same' | 'older' | 'unknown' function pickString(value: unknown): string { if (value === null || value === undefined) return '' return String(value).trim() } /** * 解析 /api/version/list 响应。 * * - 无版本号或无下载直链的行直接丢弃(选了也装不了); * - 同一版本重复上传会有多行,只保留先出现的一条(接口按 created_at 倒序,即最新记录); * - 最终按版本号从高到低排序:列表是给人挑的,版本序比发布时间序直观 * (旧版本重新上传会让它在接口里排到最前,但版本号仍然是低的)。 */ export function parseVersionList(data: unknown): ClientVersionItem[] { const record = (data ?? {}) as Record const rawItems = Array.isArray(record.items) ? record.items : Array.isArray(data) ? (data as unknown[]) : [] const byVersion = new Map() for (const raw of rawItems) { if (!raw || typeof raw !== 'object') continue const row = raw as Record const version = normVersion(row.version) const fileUrl = pickString(row.file_url ?? row.fileUrl) const createdAt = pickString(row.created_at ?? row.createdAt) if (!version || !fileUrl) continue if (byVersion.has(version)) continue byVersion.set(version, { id: row.id as number | string | undefined, version, fileUrl, createdAt, }) } return [...byVersion.values()].sort((a, b) => compareVersions(b.version, a.version)) } /** 判定目标版本相对本机版本的类型;本机版本拿不到(旧客户端无版本桥)时为 unknown。 */ export function classifyTargetVersion(current: string, target: string): TargetVersionKind { const local = normVersion(current) const remote = normVersion(target) if (!local || !remote) return 'unknown' const diff = compareVersions(remote, local) if (diff > 0) return 'newer' if (diff < 0) return 'older' return 'same' } /** 目标版本提示/确认文案(同版与回退必须说清楚,避免用户以为在升级)。 */ export function describeTargetVersion(kind: TargetVersionKind, current: string, target: string): string { switch (kind) { case 'older': return `v${target} 低于当前版本 v${current},属于回退操作,请确认线上问题确实由新版引起。` case 'same': return `与当前版本相同(v${current}),将重新下载并安装。` case 'newer': return `将从 v${current} 更新到 v${target}。` default: return `将安装 v${target}(未读到本机版本,无法比较新旧)。` } }