task-121(记录与版本中心): 定义历史记录 DTO

新增 src/pages/records/history-dto.ts：历史记录类型/分页筛选归一与 snake 查询序列化，历史页与版本/公开接口分离。 TDD: task-121.test.ts 8 用例先 RED 后 GREEN。
2026-09-05 17:29:53 +08:00
parent 818eed0cb5
commit 467c72efb4
2 changed files with 163 additions and 0 deletions
@@ -0,0 +1,89 @@
+/** 历史生成记录 DTO（任务 121）：列表筛选/分页归一与类型边界；与 Java ImageHistoryController
+ * snake 契约对齐；历史页与后台版本/公开版本接口分离。纯逻辑。 */
+
+export const HISTORY_DEFAULT_PAGE_SIZE = 15
+export const HISTORY_MIN_PAGE = 1
+export const HISTORY_MAX_PAGE_SIZE = 200
+
+/** 历史记录面板类型(保留字符串，由后端 panel_type 决定)。 */
+export type HistoryRecordType = string
+
+export interface HistoryRecordItem {
+  id: number
+  userId: number | null
+  username: string
+  createdAt: string
+  panelType: HistoryRecordType
+  originalUrls: string[]
+  resultUrls: string[]
+  longImageUrl: string
+  params: Record<string, unknown>
+}
+
+export interface HistoryPageResult {
+  items: HistoryRecordItem[]
+  total: number
+  page: number
+  pageSize: number
+}
+
+export interface HistoryListParams {
+  page: number
+  pageSize: number
+  userId?: number | null
+  timeStart?: string
+  timeEnd?: string
+}
+
+export interface HistoryListQuery {
+  page: number
+  page_size: number
+  user_id?: number
+  time_start?: string
+  time_end?: string
+}
+
+function finiteInt(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? Math.floor(value) : null
+}
+
+function positiveIdOrNull(value: unknown): number | null {
+  const id = finiteInt(value)
+  return id === null || id < 1 ? null : id
+}
+
+function textOrUndefined(value: unknown): string | undefined {
+  const text = typeof value === 'string' ? value.trim() : ''
+  return text || undefined
+}
+
+/** 归一历史筛选/分页：页码下限 1、页大小 1..上限。 */
+export function normalizeHistoryParams(raw: Partial<HistoryListParams>): HistoryListParams {
+  const page = Math.max(finiteInt(raw.page) ?? HISTORY_MIN_PAGE, HISTORY_MIN_PAGE)
+  const rawSize = finiteInt(raw.pageSize)
+  const pageSize =
+    rawSize === null || rawSize < HISTORY_MIN_PAGE
+      ? HISTORY_DEFAULT_PAGE_SIZE
+      : Math.min(rawSize, HISTORY_MAX_PAGE_SIZE)
+  return {
+    page,
+    pageSize,
+    userId: positiveIdOrNull(raw.userId),
+    timeStart: textOrUndefined(raw.timeStart),
+    timeEnd: textOrUndefined(raw.timeEnd),
+  }
+}
+
+/** 前端状态 → Java 查询参数(snake，仅下发非空)。 */
+export function toHistoryListQuery(params: HistoryListParams): HistoryListQuery {
+  const query: HistoryListQuery = { page: params.page, page_size: params.pageSize }
+  if (params.userId != null) query.user_id = params.userId
+  if (params.timeStart) query.time_start = params.timeStart
+  if (params.timeEnd) query.time_end = params.timeEnd
+  return query
+}
+
+/** 无数据历史分页缺省值。 */
+export function emptyHistoryPage(): HistoryPageResult {
+  return { items: [], total: 0, page: HISTORY_MIN_PAGE, pageSize: HISTORY_DEFAULT_PAGE_SIZE }
+}
@@ -0,0 +1,74 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readSource } from './helpers.ts'
+import {
+  HISTORY_DEFAULT_PAGE_SIZE,
+  emptyHistoryPage,
+  normalizeHistoryParams,
+  toHistoryListQuery,
+} from '../src/pages/records/history-dto.ts'
+
+test('test_task_121_history_dto_normal_primary_path', () => {
+  // 正常主路径：历史筛选归一并序列化为 snake 查询参数。
+  const params = normalizeHistoryParams({ page: 2, pageSize: 20, userId: 3, timeStart: '2026-01-01 00:00:00', timeEnd: '2026-01-31 23:59:59' })
+  assert.equal(params.page, 2)
+  const query = toHistoryListQuery(params)
+  assert.equal(query.page, 2)
+  assert.equal(query.page_size, 20)
+  assert.equal(query.user_id, 3)
+  assert.equal(query.time_start, '2026-01-01 00:00:00')
+  assert.equal(query.time_end, '2026-01-31 23:59:59')
+})
+
+test('test_task_121_history_dto_normal_variant_input', () => {
+  // 正常变体：仅时间起始筛选；空 userId 不下发。
+  const query = toHistoryListQuery(normalizeHistoryParams({ page: 1, pageSize: 15, userId: null, timeStart: '2026-02-01' }))
+  assert.equal('user_id' in query, false)
+  assert.equal(query.time_start, '2026-02-01')
+})
+
+test('test_task_121_history_dto_repeated_is_idempotent', () => {
+  // 正常重复：归一不改输入、结果稳定。
+  const input = { page: 1, pageSize: 15, timeStart: ' a ' }
+  assert.deepEqual(normalizeHistoryParams(input), normalizeHistoryParams(input))
+  assert.equal((input as { timeStart: string }).timeStart, ' a ')
+})
+
+test('test_task_121_history_dto_boundary_empty_input', () => {
+  // 边界空值：空入参回默认分页。
+  const params = normalizeHistoryParams({})
+  assert.equal(params.page, 1)
+  assert.equal(params.pageSize, HISTORY_DEFAULT_PAGE_SIZE)
+  assert.equal(params.userId, null)
+})
+
+test('test_task_121_history_dto_boundary_single_item', () => {
+  // 边界单元素：单记录空结果 DTO 结构完整。
+  const page = emptyHistoryPage()
+  assert.deepEqual(page.items, [])
+  assert.equal(page.total, 0)
+  assert.equal(page.page, 1)
+})
+
+test('test_task_121_history_dto_boundary_limit_or_missing_field', () => {
+  // 边界上限/缺字段：页码/页大小钳制；非法 userId 忽略。
+  const params = normalizeHistoryParams({ page: 0, pageSize: 999, userId: -1 })
+  assert.equal(params.page, 1)
+  assert.equal(params.pageSize, 200)
+  assert.equal(params.userId, null)
+})
+
+test('test_task_121_history_dto_invalid_input_rejected', () => {
+  // 异常输入：NaN 回默认。
+  const params = normalizeHistoryParams({ page: Number.NaN, pageSize: Number.NaN })
+  assert.equal(params.page, 1)
+  assert.equal(params.pageSize, HISTORY_DEFAULT_PAGE_SIZE)
+})
+
+test('test_task_121_history_dto_dependency_failure_returns_actionable_message', () => {
+  // 依赖失败/可操作：DTO 纯逻辑、无框架/http；历史页与版本/公开接口分离。
+  const mod = readSource('src/pages/records/history-dto.ts')
+  assert.equal(/axios|http\.|vue/.test(mod), false, '历史 DTO 保持纯逻辑')
+  assert.match(mod, /HistoryRecord/)
+  assert.match(mod, /page_size/)
+})