API/src/interface/site-adapter.interface.ts

import {
   CreateReviewDTO,
   UpdateReviewDTO,
   UnifiedMediaDTO,
   UnifiedOrderDTO,
   UnifiedProductDTO,
   UnifiedReviewDTO,
   UnifiedSubscriptionDTO,
   UnifiedCustomerDTO,
   UnifiedWebhookDTO,
   UnifiedWebhookPaginationDTO,
   CreateWebhookDTO,
   UpdateWebhookDTO,
   CreateVariationDTO,
   UpdateVariationDTO,
   UnifiedProductVariationDTO,
   UnifiedVariationPaginationDTO,
} from '../dto/site-api.dto';
import { UnifiedPaginationDTO, UnifiedSearchParamsDTO } from '../dto/api.dto';
import { BatchOperationDTO, BatchOperationResultDTO } from '../dto/batch.dto';

export interface ISiteAdapter {
   // ========== 客户映射方法 ==========
   /**
    * 将平台客户数据转换为统一客户数据格式
    * @param data 平台特定客户数据
    * @returns 统一客户数据格式
    */
   mapPlatformToUnifiedCustomer(data: any): UnifiedCustomerDTO;

   /**
    * 将统一客户数据格式转换为平台客户数据
    * @param data 统一客户数据格式
    * @returns 平台特定客户数据
    */
   mapUnifiedToPlatformCustomer(data: Partial<UnifiedCustomerDTO>): any;

   /**
    * 获取单个客户
    */
   getCustomer(where: Partial<Pick<UnifiedCustomerDTO, 'id' | 'email' | 'phone'>>): Promise<UnifiedCustomerDTO>;

   /**
    * 获取客户列表
    */
   getCustomers(params: UnifiedSearchParamsDTO): Promise<UnifiedPaginationDTO<UnifiedCustomerDTO>>;

   /**
    * 获取所有客户
    */
   getAllCustomers(params?: UnifiedSearchParamsDTO): Promise<UnifiedCustomerDTO[]>;

   /**
    * 创建客户
    */
   createCustomer(data: Partial<UnifiedCustomerDTO>): Promise<UnifiedCustomerDTO>;

   /**
    * 更新客户
    */
   updateCustomer(where: Partial<Pick<UnifiedCustomerDTO, 'id' | 'email' | 'phone'>>, data: Partial<UnifiedCustomerDTO>): Promise<UnifiedCustomerDTO>;

   /**
    * 删除客户
    */
   deleteCustomer(where: Partial<Pick<UnifiedCustomerDTO, 'id' | 'email' | 'phone'>>): Promise<boolean>;

   /**
    * 批量处理客户
    */
   batchProcessCustomers?(data: BatchOperationDTO): Promise<BatchOperationResultDTO>;

   // ========== 媒体映射方法 ==========
   /**
    * 将平台媒体数据转换为统一媒体数据格式
    * @param data 平台特定媒体数据
    * @returns 统一媒体数据格式
    */
   mapPlatformToUnifiedMedia(data: any): UnifiedMediaDTO;

   /**
    * 将统一媒体数据格式转换为平台媒体数据
    * @param data 统一媒体数据格式
    * @returns 平台特定媒体数据
    */
   mapUnifiedToPlatformMedia(data: Partial<UnifiedMediaDTO>): any;

   /**
    * 获取媒体列表
    */
   getMedia(params: UnifiedSearchParamsDTO): Promise<UnifiedPaginationDTO<UnifiedMediaDTO>>;

   /**
    * 获取所有媒体
    */
   getAllMedia(params?: UnifiedSearchParamsDTO): Promise<UnifiedMediaDTO[]>;

   /**
    * 创建媒体
    */
   createMedia(file: any): Promise<UnifiedMediaDTO>;

   // ========== 订单映射方法 ==========
   /**
    * 将平台订单数据转换为统一订单数据格式
    * @param data 平台特定订单数据
    * @returns 统一订单数据格式
    */
   mapPlatformToUnifiedOrder(data: any): UnifiedOrderDTO;

   /**
    * 将统一订单数据格式转换为平台订单数据
    * @param data 统一订单数据格式
    * @returns 平台特定订单数据
    */
   mapUnifiedToPlatformOrder(data: Partial<UnifiedOrderDTO>): any;

   /**
    * 将统一订单创建参数转换为平台订单创建参数
    * @param data 统一订单创建参数
    * @returns 平台订单创建参数
    */
   mapCreateOrderParams(data: Partial<UnifiedOrderDTO>): any;

   /**
    * 将统一订单更新参数转换为平台订单更新参数
    * @param data 统一订单更新参数
    * @returns 平台订单更新参数
    */
   mapUpdateOrderParams(data: Partial<UnifiedOrderDTO>): any;

   /**
    * 获取单个订单
    */
   getOrder(where: Partial<Pick<UnifiedOrderDTO, 'id'>>): Promise<UnifiedOrderDTO>;

   /**
    * 获取订单列表
    */
   getOrders(params: UnifiedSearchParamsDTO): Promise<UnifiedPaginationDTO<UnifiedOrderDTO>>;

   /**
    * 获取所有订单
    */
   getAllOrders(params?: UnifiedSearchParamsDTO): Promise<UnifiedOrderDTO[]>;

   /**
    * 获取订单总数
    */
   countOrders(params: Record<string, any>): Promise<number>;

   /**
    * 创建订单
    */
   createOrder(data: Partial<UnifiedOrderDTO>): Promise<UnifiedOrderDTO>;

   /**
    * 更新订单
    */
   updateOrder(where: Partial<Pick<UnifiedOrderDTO, 'id'>>, data: Partial<UnifiedOrderDTO>): Promise<boolean>;

   /**
    * 删除订单
    */
   deleteOrder(where: Partial<Pick<UnifiedOrderDTO, 'id'>>): Promise<boolean>;

   /**
    * 获取订单备注
    */
   getOrderNotes(orderId: string | number): Promise<any[]>;

   /**
    * 创建订单备注
    */
   createOrderNote(orderId: string | number, data: any): Promise<any>;

   /**
    * 取消订单履行
    */
   cancelFulfillment(orderId: string | number, data: {
      reason?: string;
      shipment_id?: string;
   }): Promise<any>;

   /**
    * 获取订单履行信息
    */
   getOrderFulfillments(orderId: string | number): Promise<any[]>;

   /**
    * 创建订单履行信息
    */
   createOrderFulfillment(orderId: string | number, data: {
      tracking_number: string;
      shipping_provider: string;
      shipping_method?: string;
      status?: string;
      date_created?: string;
      items?: Array<{
         order_item_id: number;
         quantity: number;
      }>;
   }): Promise<any>;

   /**
    * 更新订单履行信息
    */
   updateOrderFulfillment(orderId: string | number, fulfillmentId: string, data: {
      tracking_number?: string;
      shipping_provider?: string;
      shipping_method?: string;
      status?: string;
      date_created?: string;
      items?: Array<{
         order_item_id: number;
         quantity: number;
      }>;
   }): Promise<any>;

   /**
    * 删除订单履行信息
    */
   deleteOrderFulfillment(orderId: string | number, fulfillmentId: string): Promise<boolean>;

   /**
    * 批量处理订单
    */
   batchProcessOrders?(data: BatchOperationDTO): Promise<BatchOperationResultDTO>;

   // ========== 产品映射方法 ==========
   /**
    * 将平台产品数据转换为统一产品数据格式
    * @param data 平台特定产品数据
    * @returns 统一产品数据格式
    */
   mapPlatformToUnifiedProduct(data: any): UnifiedProductDTO;

   /**
    * 将统一产品数据格式转换为平台产品数据
    * @param data 统一产品数据格式
    * @returns 平台特定产品数据
    */
   mapUnifiedToPlatformProduct(data: Partial<UnifiedProductDTO>): any;

   /**
    * 将统一产品创建参数转换为平台产品创建参数
    * @param data 统一产品创建参数
    * @returns 平台产品创建参数
    */
   mapCreateProductParams(data: Partial<UnifiedProductDTO>): any;

   /**
    * 将统一产品更新参数转换为平台产品更新参数
    * @param data 统一产品更新参数
    * @returns 平台产品更新参数
    */
   mapUpdateProductParams(data: Partial<UnifiedProductDTO>): any;

   /**
    * 获取单个产品
    */
   getProduct(where: Partial<Pick<UnifiedProductDTO, 'id' | 'sku'>>): Promise<UnifiedProductDTO>;

   /**
    * 获取产品列表
    */
   getProducts(params: UnifiedSearchParamsDTO): Promise<UnifiedPaginationDTO<UnifiedProductDTO>>;

   /**
    * 获取所有产品
    */
   getAllProducts(params?: UnifiedSearchParamsDTO): Promise<UnifiedProductDTO[]>;

   /**
    * 创建产品
    */
   createProduct(data: Partial<UnifiedProductDTO>): Promise<UnifiedProductDTO>;

   /**
    * 更新产品
    */
   updateProduct(where: Partial<Pick<UnifiedProductDTO, 'id' | 'sku'>>, data: Partial<UnifiedProductDTO>): Promise<boolean>;

   /**
    * 删除产品
    */
   deleteProduct(where: Partial<Pick<UnifiedProductDTO, 'id' | 'sku'>>): Promise<boolean>;

   /**
    * 批量处理产品
    */
   batchProcessProducts?(data: BatchOperationDTO): Promise<BatchOperationResultDTO>;

   // ========== 评论映射方法 ==========
   /**
    * 将平台评论数据转换为统一评论数据格式
    * @param data 平台特定评论数据
    * @returns 统一评论数据格式
    */
   mapPlatformToUnifiedReview(data: any): UnifiedReviewDTO;

   /**
    * 将统一评论数据格式转换为平台评论数据
    * @param data 统一评论数据格式
    * @returns 平台特定评论数据
    */
   mapUnifiedToPlatformReview(data: Partial<UnifiedReviewDTO>): any;

   /**
    * 将统一评论创建参数转换为平台评论创建参数
    * @param data 统一评论创建参数
    * @returns 平台评论创建参数
    */
   mapCreateReviewParams(data: CreateReviewDTO): any;

   /**
    * 将统一评论更新参数转换为平台评论更新参数
    * @param data 统一评论更新参数
    * @returns 平台评论更新参数
    */
   mapUpdateReviewParams(data: UpdateReviewDTO): any;

   /**
    * 获取评论列表
    */
   getReviews(params: UnifiedSearchParamsDTO): Promise<UnifiedPaginationDTO<UnifiedReviewDTO>>;

   /**
    * 获取所有评论
    */
   getAllReviews(params?: UnifiedSearchParamsDTO): Promise<UnifiedReviewDTO[]>;

   /**
    * 创建评论
    */
   createReview(data: CreateReviewDTO): Promise<UnifiedReviewDTO>;

   /**
    * 更新评论
    */
   updateReview(where: Partial<Pick<UnifiedReviewDTO, 'id'>>, data: UpdateReviewDTO): Promise<UnifiedReviewDTO>;

   /**
    * 删除评论
    */
   deleteReview(where: Partial<Pick<UnifiedReviewDTO, 'id'>>): Promise<boolean>;

   // ========== 订阅映射方法 ==========
   /**
    * 将平台订阅数据转换为统一订阅数据格式
    * @param data 平台特定订阅数据
    * @returns 统一订阅数据格式
    */
   mapPlatformToUnifiedSubscription(data: any): UnifiedSubscriptionDTO;

   /**
    * 将统一订阅数据格式转换为平台订阅数据
    * @param data 统一订阅数据格式
    * @returns 平台特定订阅数据
    */
   mapUnifiedToPlatformSubscription(data: Partial<UnifiedSubscriptionDTO>): any;

   /**
    * 获取订阅列表
    */
   getSubscriptions(params: UnifiedSearchParamsDTO): Promise<UnifiedPaginationDTO<UnifiedSubscriptionDTO>>;

   /**
    * 获取所有订阅
    */
   getAllSubscriptions(params?: UnifiedSearchParamsDTO): Promise<UnifiedSubscriptionDTO[]>;

   // ========== 产品变体映射方法 ==========
   /**
    * 将平台产品变体数据转换为统一产品变体数据格式
    * @param data 平台特定产品变体数据
    * @returns 统一产品变体数据格式
    */
   mapPlatformToUnifiedVariation(data: any): UnifiedProductVariationDTO;

   /**
    * 将统一产品变体数据格式转换为平台产品变体数据
    * @param data 统一产品变体数据格式
    * @returns 平台特定产品变体数据
    */
   mapUnifiedToPlatformVariation(data: Partial<UnifiedProductVariationDTO>): any;

   /**
    * 将统一产品变体创建参数转换为平台产品变体创建参数
    * @param data 统一产品变体创建参数
    * @returns 平台产品变体创建参数
    */
   mapCreateVariationParams(data: CreateVariationDTO): any;

   /**
    * 将统一产品变体更新参数转换为平台产品变体更新参数
    * @param data 统一产品变体更新参数
    * @returns 平台产品变体更新参数
    */
   mapUpdateVariationParams(data: UpdateVariationDTO): any;

   /**
    * 获取单个产品变体
    */
   getVariation(productId: string | number, variationId: string | number): Promise<UnifiedProductVariationDTO>;

   /**
    * 获取产品变体列表
    */
   getVariations(productId: string | number, params: UnifiedSearchParamsDTO): Promise<UnifiedVariationPaginationDTO>;

   /**
    * 获取所有产品变体
    */
   getAllVariations(productId: string | number, params?: UnifiedSearchParamsDTO): Promise<UnifiedProductVariationDTO[]>;

   /**
    * 创建产品变体
    */
   createVariation(productId: string | number, data: CreateVariationDTO): Promise<UnifiedProductVariationDTO>;

   /**
    * 更新产品变体
    */
   updateVariation(productId: string | number, variationId: string | number, data: UpdateVariationDTO): Promise<UnifiedProductVariationDTO>;

   /**
    * 删除产品变体
    */
   deleteVariation(productId: string | number, variationId: string | number): Promise<boolean>;

   // ========== Webhook映射方法 ==========
   /**
    * 将平台Webhook数据转换为统一Webhook数据格式
    * @param data 平台特定Webhook数据
    * @returns 统一Webhook数据格式
    */
   mapPlatformToUnifiedWebhook(data: any): UnifiedWebhookDTO;

   /**
    * 将统一Webhook数据格式转换为平台Webhook数据
    * @param data 统一Webhook数据格式
    * @returns 平台特定Webhook数据
    */
   mapUnifiedToPlatformWebhook(data: Partial<UnifiedWebhookDTO>): any;

   /**
    * 将统一Webhook创建参数转换为平台Webhook创建参数
    * @param data 统一Webhook创建参数
    * @returns 平台Webhook创建参数
    */
   mapCreateWebhookParams(data: CreateWebhookDTO): any;

   /**
    * 将统一Webhook更新参数转换为平台Webhook更新参数
    * @param data 统一Webhook更新参数
    * @returns 平台Webhook更新参数
    */
   mapUpdateWebhookParams(data: UpdateWebhookDTO): any;

   /**
    * 获取单个webhook
    */
   getWebhook(where: Partial<Pick<UnifiedWebhookDTO, 'id'>>): Promise<UnifiedWebhookDTO>;

   /**
    * 获取webhooks列表
    */
   getWebhooks(params: UnifiedSearchParamsDTO): Promise<UnifiedWebhookPaginationDTO>;

   /**
    * 获取所有webhooks
    */
   getAllWebhooks(params?: UnifiedSearchParamsDTO): Promise<UnifiedWebhookDTO[]>;

   /**
    * 创建webhook
    */
   createWebhook(data: CreateWebhookDTO): Promise<UnifiedWebhookDTO>;

   /**
    * 更新webhook
    */
   updateWebhook(where: Partial<Pick<UnifiedWebhookDTO, 'id'>>, data: UpdateWebhookDTO): Promise<UnifiedWebhookDTO>;

   /**
    * 删除webhook
    */
   deleteWebhook(where: Partial<Pick<UnifiedWebhookDTO, 'id'>>): Promise<boolean>;

   // ========== 站点/其他方法 ==========
   /**
    * 获取站点链接列表
    */
   getLinks(): Promise<Array<{ title: string, url: string }>>;
}