API/src/dto/api.dto.ts

import { ApiProperty } from '@midwayjs/swagger';
import { Rule, RuleType } from '@midwayjs/validate';

export class UnifiedPaginationDTO<T> {
  // 分页DTO用于承载统一分页信息与列表数据
  @ApiProperty({ description: '列表数据' })
  items: T[];

  @ApiProperty({ description: '总数', example: 100 })
  total: number;

  @ApiProperty({ description: '当前页', example: 1 })
  page: number;

  @ApiProperty({ description: '每页数量', example: 20 })
  per_page: number;

  @ApiProperty({ description: '总页数', example: 5 })
  totalPages: number;
}


export class UnifiedSearchParamsDTO<Where=Record<string, any>>  {
  // 统一查询参数DTO用于承载分页与筛选与排序参数
  @ApiProperty({ description: '页码', example: 1, required: false })
  page?: number;

  @ApiProperty({ description: '每页数量', example: 20, required: false })
  per_page?: number;
  
  @ApiProperty({ description: '查询时间范围开始', example: '2023-01-01T00:00:00Z', required: false })
  after?: string;
  
  @ApiProperty({ description: '查询时间范围结束', example: '2023-01-01T23:59:59Z', required: false })
  before?: string;
 
  @ApiProperty({ description: '搜索关键词', required: false })
  search?: string;

  @ApiProperty({
    description: '过滤条件对象', 
    type: 'any', // FIXME 这里是因为 openapit2ts 会将 where 变成 undefined 所以有嵌套对象时先不指定类型 
    required: false,
  })
  where?: Where;

  @ApiProperty({
    description: '排序对象,例如 { "sku": "desc" }',
    type: 'any', // FIXME 这里是因为 openapit2ts 会将 where 变成 undefined 所以有嵌套对象时先不指定类型 
    required: false,
  })
  orderBy?: Record<string, 'asc' | 'desc'> | string;
}

/**
 * 批量操作错误项
 */
export interface BatchErrorItem {
  // 错误项标识(可以是ID、邮箱等)
  identifier: string;
  // 错误信息
  error: string;
}

/**
 * 批量操作结果基础接口
 */
export interface BatchOperationResult {
  // 总处理数量
  total: number;
  // 成功处理数量
  processed: number;
  // 创建数量
  created?: number;
  // 更新数量
  updated?: number;
  // 删除数量
  deleted?: number;
  // 跳过的数量(如数据已存在或无需处理)
  skipped?: number;
  // 错误列表
  errors: BatchErrorItem[];
}

/**
 * 同步操作结果接口
 */
export class SyncOperationResult implements BatchOperationResult {
  total: number;
  processed: number;
  created?: number;
  updated?: number;
  deleted?: number;
  skipped?: number;
  errors: BatchErrorItem[];
  // 同步成功数量
  synced: number;
}

/**
 * 批量操作错误项DTO
 */
export class BatchErrorItemDTO {
  @ApiProperty({ description: '错误项标识(如ID、邮箱等)', type: String })
  @Rule(RuleType.string().required())
  identifier: string;

  @ApiProperty({ description: '错误信息', type: String })
  @Rule(RuleType.string().required())
  error: string;
}

/**
 * 批量操作结果基础DTO
 */
export class BatchOperationResultDTO {
  @ApiProperty({ description: '总处理数量', type: Number })
  total: number;

  @ApiProperty({ description: '成功处理数量', type: Number })
  processed: number;

  @ApiProperty({ description: '创建数量', type: Number, required: false })
  created?: number;

  @ApiProperty({ description: '更新数量', type: Number, required: false })
  updated?: number;

  @ApiProperty({ description: '删除数量', type: Number, required: false })
  deleted?: number;

  @ApiProperty({ description: '跳过的数量', type: Number, required: false })
  skipped?: number;

  @ApiProperty({ description: '错误列表', type: [BatchErrorItemDTO] })
  errors: BatchErrorItemDTO[];
}

/**
 * 同步操作结果DTO
 */
export class SyncOperationResultDTO extends BatchOperationResultDTO {
  @ApiProperty({ description: '同步成功数量', type: Number })
  synced: number;
}

/**
 * 同步参数DTO
 */
export class SyncParamsDTO {
  @ApiProperty({ description: '页码', type: Number, required: false, default: 1 })
  @Rule(RuleType.number().integer().min(1).optional())
  page?: number = 1;

  @ApiProperty({ description: '每页数量', type: Number, required: false, default: 100 })
  @Rule(RuleType.number().integer().min(1).max(1000).optional())
  pageSize?: number = 100;

  @ApiProperty({ description: '开始时间', type: String, required: false })
  @Rule(RuleType.string().optional())
  startDate?: string;

  @ApiProperty({ description: '结束时间', type: String, required: false })
  @Rule(RuleType.string().optional())
  endDate?: string;

  @ApiProperty({ description: '强制同步(忽略缓存)', type: Boolean, required: false, default: false })
  @Rule(RuleType.boolean().optional())
  force?: boolean = false;
}

/**
 * 批量查询DTO
 */
export class BatchQueryDTO {
  @ApiProperty({ description: 'ID列表', type: [String, Number] })
  @Rule(RuleType.array().items(RuleType.alternatives().try(RuleType.string(), RuleType.number())).required())
  ids: Array<string | number>;

  @ApiProperty({ description: '包含关联数据', type: Boolean, required: false, default: false })
  @Rule(RuleType.boolean().optional())
  includeRelations?: boolean = false;
}

/**
 * 批量操作结果类(泛型支持)
 */
export class BatchOperationResultDTOGeneric<T> extends BatchOperationResultDTO {
  @ApiProperty({ description: '操作成功的数据列表', type: Array })
  data?: T[];
}

/**
 * 同步操作结果类(泛型支持)
 */
export class SyncOperationResultDTOGeneric<T> extends SyncOperationResultDTO {
  @ApiProperty({ description: '同步成功的数据列表', type: Array })
  data?: T[];
}