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 }
+}