From a6bc6b80b37ed4cd9994dacf3002c504c50ee830 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:43:24 +0800
Subject: [PATCH] =?UTF-8?q?task-139(=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=E8=A1=A5=E5=85=85=E7=89=88?=
 =?UTF-8?q?=E6=9C=AC=E6=8E=A5=E5=8F=A3=E5=85=AC=E5=BC=80=E5=A5=91=E7=BA=A6?=
 =?UTF-8?q?=E5=9B=9E=E5=BD=92=E5=A4=B9=E5=85=B7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增 public-version-contract.ts：/api/version(/latest) 字段与空语义匹配夹具。

TDD: task-139.test.ts 8 用例 RED→GREEN。
---
 .../pages/records/public-version-contract.ts  | 24 +++++++++
 admin-frontend-vue/tests/task-139.test.ts     | 52 +++++++++++++++++++
 2 files changed, 76 insertions(+)
 create mode 100644 admin-frontend-vue/src/pages/records/public-version-contract.ts
 create mode 100644 admin-frontend-vue/tests/task-139.test.ts

diff --git a/admin-frontend-vue/src/pages/records/public-version-contract.ts b/admin-frontend-vue/src/pages/records/public-version-contract.ts
new file mode 100644
index 00000000..544f36f5
--- /dev/null
+++ b/admin-frontend-vue/src/pages/records/public-version-contract.ts
@@ -0,0 +1,24 @@
+/** 客户端公开版本接口回归契约（任务 139，细则见 09 模块）：字段名/空语义固定夹具；纯逻辑。 */
+
+/** 公开接口契约键：/api/version {version,desc,url}；/api/version/latest {version,file_url}。 */
+export function publicContractKeys(): string[] {
+  return ['version', 'desc', 'url', 'file_url']
+}
+
+function hasOwn(record: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(record, key)
+}
+
+/** 最新版本契约：顶层必须带 version 与 file_url(允许 null/空串)，且不被 success 信封包裹。 */
+export function matchesPublicLatestContract(payload: unknown): boolean {
+  if (!payload || typeof payload !== 'object') return false
+  const record = payload as Record<string, unknown>
+  return hasOwn(record, 'version') && hasOwn(record, 'file_url') && !hasOwn(record, 'success')
+}
+
+/** 基础版本契约：顶层必须带 version、desc、url，不被 success 信封包裹。 */
+export function matchesPublicVersionContract(payload: unknown): boolean {
+  if (!payload || typeof payload !== 'object') return false
+  const record = payload as Record<string, unknown>
+  return hasOwn(record, 'version') && hasOwn(record, 'desc') && hasOwn(record, 'url') && !hasOwn(record, 'success')
+}
diff --git a/admin-frontend-vue/tests/task-139.test.ts b/admin-frontend-vue/tests/task-139.test.ts
new file mode 100644
index 00000000..03a8ec0e
--- /dev/null
+++ b/admin-frontend-vue/tests/task-139.test.ts
@@ -0,0 +1,52 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readSource } from './helpers.ts'
+import {
+  matchesPublicLatestContract,
+  matchesPublicVersionContract,
+  publicContractKeys,
+} from '../src/pages/records/public-version-contract.ts'
+
+test('test_task_139_public_contract_normal_primary_path', () => {
+  // 正常主路径：最新版本负载满足公开契约键。
+  assert.equal(matchesPublicLatestContract({ version: '1.0.46', file_url: 'https://a.zip' }), true)
+  assert.equal(matchesPublicVersionContract({ version: '1.0.0', desc: 'x', url: 'https://a' }), true)
+})
+
+test('test_task_139_public_contract_normal_variant_input', () => {
+  // 正常变体：允许空语义(null/空串)。
+  assert.equal(matchesPublicLatestContract({ version: null, file_url: null }), true)
+  assert.equal(matchesPublicLatestContract({ version: '', file_url: '' }), true)
+})
+
+test('test_task_139_public_contract_repeated_is_idempotent', () => {
+  // 正常重复：键集合稳定。
+  assert.deepEqual(publicContractKeys(), publicContractKeys())
+})
+
+test('test_task_139_public_contract_boundary_empty_input', () => {
+  // 边界空值：非对象不满足契约。
+  assert.equal(matchesPublicLatestContract(null), false)
+})
+
+test('test_task_139_public_contract_boundary_single_item', () => {
+  // 边界单元素：缺失 file_url 不满足。
+  assert.equal(matchesPublicLatestContract({ version: '1.0.0' }), false)
+})
+
+test('test_task_139_public_contract_boundary_limit_or_missing_field', () => {
+  // 边界上限/缺字段：多余字段不影响契约匹配。
+  assert.equal(matchesPublicLatestContract({ version: '1', file_url: 'u', extra: 1 }), true)
+})
+
+test('test_task_139_public_contract_invalid_input_rejected', () => {
+  // 异常输入：不把 /api/admin/version 上传响应当成公开契约。
+  assert.equal(matchesPublicLatestContract({ success: true, data: { version: 'x', file_url: 'u' } }), false)
+})
+
+test('test_task_139_public_contract_dependency_failure_returns_actionable_message', () => {
+  // 依赖失败/可操作：契约纯逻辑、无框架/http。
+  const mod = readSource('src/pages/records/public-version-contract.ts')
+  assert.equal(/axios|http\.|vue/.test(mod), false, '契约保持纯逻辑')
+  assert.match(mod, /file_url/)
+})