From 1d983158770119df6d4f6eab6771049a4934a132 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=BB=84=E8=87=AA=E8=BE=BE?= <980324341@qq.com>
Date: Sat, 5 Sep 2026 17:33:42 +0800
Subject: [PATCH] =?UTF-8?q?task-126(=E8=AE=B0=E5=BD=95=E4=B8=8E=E7=89=88?=
 =?UTF-8?q?=E6=9C=AC=E4=B8=AD=E5=BF=83):=20=E5=AE=9A=E4=B9=89=E8=BD=AF?=
 =?UTF-8?q?=E4=BB=B6=E7=89=88=E6=9C=AC=20DTO?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增 version-dto.ts：软件版本行类型与版本号归一；后台/公开接口分离。

TDD: task-126.test.ts 8 用例 RED→GREEN。
---
 .../src/pages/records/version-dto.ts          | 26 +++++++++
 admin-frontend-vue/tests/task-126.test.ts     | 55 +++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 admin-frontend-vue/src/pages/records/version-dto.ts
 create mode 100644 admin-frontend-vue/tests/task-126.test.ts

diff --git a/admin-frontend-vue/src/pages/records/version-dto.ts b/admin-frontend-vue/src/pages/records/version-dto.ts
new file mode 100644
index 00000000..a907b1f2
--- /dev/null
+++ b/admin-frontend-vue/src/pages/records/version-dto.ts
@@ -0,0 +1,26 @@
+/** 软件版本 DTO（任务 126）：客户端软件版本行类型与版本号归一；后台版本与公开接口分离，纯逻辑。 */
+
+/** 客户端软件版本行(GET /api/admin/versions data.items，Java SoftwareVersionEntity snake)。 */
+export interface SoftwareVersionItem {
+  id: number
+  version: string
+  fileUrl: string
+  createdAt: string
+}
+
+export interface SoftwareVersionList {
+  items: SoftwareVersionItem[]
+}
+
+export function emptySoftwareVersionList(): SoftwareVersionList {
+  return { items: [] }
+}
+
+/** 版本号归一：去首尾空白；空白视为空。 */
+export function normalizeVersionString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+export function isNonEmptyVersion(value: string): boolean {
+  return normalizeVersionString(value).length > 0
+}
diff --git a/admin-frontend-vue/tests/task-126.test.ts b/admin-frontend-vue/tests/task-126.test.ts
new file mode 100644
index 00000000..de7fd619
--- /dev/null
+++ b/admin-frontend-vue/tests/task-126.test.ts
@@ -0,0 +1,55 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readSource } from './helpers.ts'
+import {
+  emptySoftwareVersionList,
+  isNonEmptyVersion,
+  normalizeVersionString,
+} from '../src/pages/records/version-dto.ts'
+
+test('test_task_126_software_version_dto_normal_primary_path', () => {
+  // 正常主路径：版本号归一与空列表缺省。
+  assert.equal(normalizeVersionString(' 1.0.46 '), '1.0.46')
+  assert.equal(isNonEmptyVersion('1.0.46'), true)
+  assert.deepEqual(emptySoftwareVersionList(), { items: [] })
+})
+
+test('test_task_126_software_version_dto_normal_variant_input', () => {
+  // 正常变体：多段版本号保留。
+  assert.equal(normalizeVersionString('1.2.3-beta.1'), '1.2.3-beta.1')
+})
+
+test('test_task_126_software_version_dto_repeated_is_idempotent', () => {
+  // 正常重复：归一稳定、不改输入。
+  const v = ' 1.0.0 '
+  assert.equal(normalizeVersionString(v), normalizeVersionString(v))
+  assert.equal(v, ' 1.0.0 ')
+})
+
+test('test_task_126_software_version_dto_boundary_empty_input', () => {
+  // 边界空值：空白版本号视为空。
+  assert.equal(normalizeVersionString('   '), '')
+  assert.equal(isNonEmptyVersion(''), false)
+})
+
+test('test_task_126_software_version_dto_boundary_single_item', () => {
+  // 边界单元素：单版本号可比较空格无关。
+  assert.equal(isNonEmptyVersion(normalizeVersionString('v1')), true)
+})
+
+test('test_task_126_software_version_dto_boundary_limit_or_missing_field', () => {
+  // 边界上限/缺字段：非字符串输入按空处理。
+  assert.equal(normalizeVersionString(null as unknown as string), '')
+})
+
+test('test_task_126_software_version_dto_invalid_input_rejected', () => {
+  // 异常输入：非法字符版本号仍作为字符串保留(不做语义强校验)。
+  assert.equal(normalizeVersionString('a.b'), 'a.b')
+})
+
+test('test_task_126_software_version_dto_dependency_failure_returns_actionable_message', () => {
+  // 依赖失败/可操作：DTO 纯逻辑、无框架/http。
+  const mod = readSource('src/pages/records/version-dto.ts')
+  assert.equal(/axios|http\.|vue/.test(mod), false, '版本 DTO 保持纯逻辑')
+  assert.match(mod, /SoftwareVersion/)
+})