/**
 * [MOCK-001] DataSource抽象接口定义
 * 所有数据源必须实现此接口
 * AI注意: 这是抽象层，不涉及具体实现
 * 
 * @module types/datasource
 * @author AI-Frontend-Team
 * @created 2026-03-19
 */

/**
 * 通用DataSource接口
 * 定义了标准CRUD操作
 */
export interface IDataSource<T, QueryParams = any, CreateInput = Partial<T>, UpdateInput = Partial<T>> {
  /**
   * 查询列表
   * @param params 查询参数
   * @returns 数据列表
   */
  list(params?: QueryParams): Promise<T[]>;

  /**
   * 获取详情
   * @param id 数据ID
   * @returns 单条数据或null
   */
  detail(id: string): Promise<T | null>;

  /**
   * 创建数据
   * @param data 创建数据
   * @returns 创建后的数据
   */
  create(data: CreateInput): Promise<T>;

  /**
   * 更新数据
   * @param id 数据ID
   * @param data 更新数据
   * @returns 更新后的数据
   */
  update(id: string, data: UpdateInput): Promise<T>;

  /**
   * 删除数据
   * @param id 数据ID
   */
  delete(id: string): Promise<void>;
}

/**
 * 分页查询结果
 */
export interface PaginatedResult<T> {
  /** 数据列表 */
  items: T[];
  /** 总条数 */
  total: number;
  /** 当前页 */
  page: number;
  /** 每页条数 */
  pageSize: number;
  /** 总页数 */
  totalPages: number;
}

/**
 * 分页DataSource接口
 * 继承IDataSource，增加分页查询能力
 */
export interface IPaginatedDataSource<T, QueryParams = any, CreateInput = Partial<T>, UpdateInput = Partial<T>>
  extends Omit<IDataSource<T, QueryParams, CreateInput, UpdateInput>, 'list'> {
  /**
   * 分页查询
   * @param params 查询参数
   * @returns 分页结果
   */
  list(params?: QueryParams): Promise<PaginatedResult<T>>;

  /**
   * 获取所有数据（不分页）
   * @param params 查询参数
   * @returns 数据列表
   */
  listAll(params?: QueryParams): Promise<T[]>;
}

// ============================================
// 证书模块查询参数
// ============================================

export interface CertificateQueryParams {
  /** 状态筛选 */
  status?: string;
  /** 类型筛选 */
  type?: string;
  /** 关键词搜索 */
  keyword?: string;
  /** 当前页 */
  page?: number;
  /** 每页条数 */
  pageSize?: number;
}

// ============================================
// 产品模块查询参数
// ============================================

export interface ProductQueryParams {
  /** 关键词搜索 */
  keyword?: string;
  /** 分类筛选 */
  category?: string;
  /** 状态筛选 */
  status?: string;
  /** 平台筛选 */
  platform?: string;
  /** 当前页 */
  page?: number;
  /** 每页条数 */
  pageSize?: number;
}

// ============================================
// 订单模块查询参数
// ============================================

export interface OrderQueryParams {
  /** 订单状态 */
  status?: string;
  /** 平台筛选 */
  platform?: string;
  /** 店铺ID */
  shopId?: string;
  /** 开始日期 */
  startDate?: string;
  /** 结束日期 */
  endDate?: string;
  /** 关键词搜索 */
  keyword?: string;
  /** 当前页 */
  page?: number;
  /** 每页条数 */
  pageSize?: number;
}

// ============================================
// 用户模块查询参数
// ============================================

export interface UserQueryParams {
  /** 关键词搜索 */
  keyword?: string;
  /** 角色筛选 */
  role?: string;
  /** 状态筛选 */
  status?: string;
  /** 当前页 */
  page?: number;
  /** 每页条数 */
  pageSize?: number;
}

// ============================================
// 库存模块查询参数
// ============================================

export interface InventoryQueryParams {
  /** 仓库ID */
  warehouseId?: string;
  /** 产品ID */
  productId?: string;
  /** 库存状态 */
  stockStatus?: 'normal' | 'low' | 'out';
  /** 关键词搜索 */
  keyword?: string;
  /** 当前页 */
  page?: number;
  /** 每页条数 */
  pageSize?: number;
}

// ============================================
// Mock标记类型
// ============================================

/**
 * Mock数据源标记接口
 * 用于类型识别和调试
 */
export interface IMockDataSource {
  /** Mock标记 */
  readonly __MOCK__: true;
  /** Mock数据源名称 */
  readonly __MOCK_NAME__: string;
}

/**
 * 判断是否为Mock数据源
 */
export function isMockDataSource<T>(source: IDataSource<T>): source is IDataSource<T> & IMockDataSource {
  return '__MOCK__' in source && (source as any).__MOCK__ === true;
}
