TakeoutSaaS.TenantUI/apps/web-antd/src/api/customer/index.ts

/**
 * 文件职责：客户管理列表与画像 API 契约定义。
 */
import { requestClient } from '#/api/request';

/** 客户标签筛选值。 */
export type CustomerTagFilter =
  | 'active'
  | 'all'
  | 'churn'
  | 'dormant'
  | 'high_value'
  | 'new_customer';

/** 客户下单次数筛选值。 */
export type CustomerOrderCountRangeFilter =
  | 'all'
  | 'once'
  | 'six_to_ten'
  | 'ten_plus'
  | 'two_to_five';

/** 客户注册周期筛选值。 */
export type CustomerRegisterPeriodFilter = '7d' | '30d' | '90d' | 'all';

/** 客户列表筛选参数。 */
export interface CustomerListFilterQuery {
  keyword?: string;
  orderCountRange?: CustomerOrderCountRangeFilter;
  registerPeriod?: CustomerRegisterPeriodFilter;
  storeId: string;
  tag?: CustomerTagFilter;
}

/** 客户列表分页参数。 */
export interface CustomerListQuery extends CustomerListFilterQuery {
  page: number;
  pageSize: number;
}

/** 客户标签。 */
export interface CustomerTagDto {
  code: string;
  label: string;
  tone: string;
}

/** 客户列表行。 */
export interface CustomerListItemDto {
  avatarColor: string;
  avatarText: string;
  averageAmount: number;
  customerKey: string;
  isDimmed: boolean;
  lastOrderAt: string;
  name: string;
  orderCount: number;
  orderCountBarPercent: number;
  phoneMasked: string;
  tags: CustomerTagDto[];
  totalAmount: number;
}

/** 客户列表结果。 */
export interface CustomerListResultDto {
  items: CustomerListItemDto[];
  page: number;
  pageSize: number;
  total: number;
}

/** 客户列表统计。 */
export interface CustomerListStatsDto {
  activeCustomers: number;
  averageAmountLast30Days: number;
  monthlyGrowthRatePercent: number;
  monthlyNewCustomers: number;
  totalCustomers: number;
}

/** 客户消费偏好。 */
export interface CustomerPreferenceDto {
  averageDeliveryDistance: string;
  preferredCategories: string[];
  preferredDelivery: string;
  preferredOrderPeaks: string;
  preferredPaymentMethod: string;
}

/** 客户常购商品。 */
export interface CustomerTopProductDto {
  count: number;
  productName: string;
  proportionPercent: number;
  rank: number;
}

/** 客户趋势点。 */
export interface CustomerTrendPointDto {
  amount: number;
  label: string;
}

/** 客户最近订单。 */
export interface CustomerRecentOrderDto {
  amount: number;
  deliveryType: string;
  itemsSummary: string;
  orderNo: string;
  orderedAt: string;
  status: string;
}

/** 客户会员摘要。 */
export interface CustomerMemberSummaryDto {
  growthValue: number;
  isMember: boolean;
  joinedAt: string;
  pointsBalance: number;
  tierName: string;
}

/** 客户详情（一级抽屉）。 */
export interface CustomerDetailDto {
  averageAmount: number;
  customerKey: string;
  firstOrderAt: string;
  member: CustomerMemberSummaryDto;
  name: string;
  phoneMasked: string;
  preference: CustomerPreferenceDto;
  recentOrders: CustomerRecentOrderDto[];
  registeredAt: string;
  repurchaseRatePercent: number;
  source: string;
  tags: CustomerTagDto[];
  topProducts: CustomerTopProductDto[];
  totalAmount: number;
  totalOrders: number;
  trend: CustomerTrendPointDto[];
}

/** 客户画像（一级抽屉内二级抽屉）。 */
export interface CustomerProfileDto {
  averageAmount: number;
  averageOrderIntervalDays: number;
  customerKey: string;
  firstOrderAt: string;
  member: CustomerMemberSummaryDto;
  name: string;
  phoneMasked: string;
  preference: CustomerPreferenceDto;
  recentOrders: CustomerRecentOrderDto[];
  registeredAt: string;
  repurchaseRatePercent: number;
  source: string;
  tags: CustomerTagDto[];
  topProducts: CustomerTopProductDto[];
  totalAmount: number;
  totalOrders: number;
  trend: CustomerTrendPointDto[];
}

/** 客户导出回执。 */
export interface CustomerExportDto {
  fileContentBase64: string;
  fileName: string;
  totalCount: number;
}

/** 客户分析周期筛选值。 */
export type CustomerAnalysisPeriodFilter = '7d' | '30d' | '90d' | '365d';

/** 客户分析趋势点。 */
export interface CustomerAnalysisTrendPointDto {
  label: string;
  value: number;
}

/** 客户分析新老客构成项。 */
export interface CustomerAnalysisCompositionItemDto {
  count: number;
  label: string;
  percent: number;
  segmentCode: string;
  tone: string;
}

/** 客单价分布项。 */
export interface CustomerAnalysisAmountDistributionItemDto {
  count: number;
  label: string;
  percent: number;
  segmentCode: string;
}

/** RFM 分层单元。 */
export interface CustomerAnalysisRfmCellDto {
  count: number;
  label: string;
  segmentCode: string;
  tone: string;
}

/** RFM 分层行。 */
export interface CustomerAnalysisRfmRowDto {
  cells: CustomerAnalysisRfmCellDto[];
  label: string;
}

/** 客户分析 Top 客户。 */
export interface CustomerAnalysisTopCustomerDto {
  averageAmount: number;
  customerKey: string;
  lastOrderAt: string;
  name: string;
  orderCount: number;
  phoneMasked: string;
  rank: number;
  tags: CustomerTagDto[];
  totalAmount: number;
}

/** 客户分析总览。 */
export interface CustomerAnalysisOverviewDto {
  activeCustomers: number;
  activeRatePercent: number;
  amountDistribution: CustomerAnalysisAmountDistributionItemDto[];
  averageLifetimeValue: number;
  composition: CustomerAnalysisCompositionItemDto[];
  growthRatePercent: number;
  growthTrend: CustomerAnalysisTrendPointDto[];
  newCustomers: number;
  newCustomersDailyAverage: number;
  periodCode: CustomerAnalysisPeriodFilter;
  periodDays: number;
  rfmRows: CustomerAnalysisRfmRowDto[];
  topCustomers: CustomerAnalysisTopCustomerDto[];
  totalCustomers: number;
}

/** 客群明细分群编码。 */
export type CustomerAnalysisSegmentCode =
  | 'active_new'
  | 'active_recent'
  | 'all'
  | 'amount_0_30'
  | 'amount_30_60'
  | 'amount_60_100'
  | 'amount_100_150'
  | 'amount_150_plus'
  | 'churn'
  | 'dormant'
  | 'high_value_top'
  | 'repeat_loyal'
  | `rfm_r${1 | 2 | 3}c${1 | 2 | 3 | 4}`
  | (string & {});

/** 客群明细行。 */
export interface CustomerAnalysisSegmentListItemDto {
  avatarColor: string;
  avatarText: string;
  averageAmount: number;
  customerKey: string;
  isDimmed: boolean;
  isMember: boolean;
  lastOrderAt: string;
  memberTierName: string;
  name: string;
  orderCount: number;
  phoneMasked: string;
  registeredAt: string;
  tags: CustomerTagDto[];
  totalAmount: number;
}

/** 客群明细结果。 */
export interface CustomerAnalysisSegmentListResultDto {
  items: CustomerAnalysisSegmentListItemDto[];
  page: number;
  pageSize: number;
  segmentCode: string;
  segmentDescription: string;
  segmentTitle: string;
  totalCount: number;
}

/** 客户分析会员详情。 */
export interface CustomerMemberDetailDto {
  averageAmount: number;
  customerKey: string;
  lastOrderAt: string;
  member: CustomerMemberSummaryDto;
  name: string;
  phoneMasked: string;
  recentOrders: CustomerRecentOrderDto[];
  registeredAt: string;
  repurchaseRatePercent: number;
  source: string;
  tags: CustomerTagDto[];
  totalAmount: number;
  totalOrders: number;
}

/** 客户分析基础查询参数。 */
export interface CustomerAnalysisBaseQuery {
  period?: CustomerAnalysisPeriodFilter;
  storeId: string;
}

/** 客群明细查询参数。 */
export interface CustomerAnalysisSegmentListQuery extends CustomerAnalysisBaseQuery {
  keyword?: string;
  page: number;
  pageSize: number;
  segmentCode: CustomerAnalysisSegmentCode;
}

/** 查询客户列表。 */
export async function getCustomerListApi(params: CustomerListQuery) {
  return requestClient.get<CustomerListResultDto>('/customer/list/list', {
    params,
  });
}

/** 查询客户列表统计。 */
export async function getCustomerListStatsApi(params: CustomerListFilterQuery) {
  return requestClient.get<CustomerListStatsDto>('/customer/list/stats', {
    params,
  });
}

/** 查询客户详情。 */
export async function getCustomerDetailApi(params: {
  customerKey: string;
  storeId: string;
}) {
  return requestClient.get<CustomerDetailDto>('/customer/list/detail', {
    params,
  });
}

/** 查询客户画像。 */
export async function getCustomerProfileApi(params: {
  customerKey: string;
  storeId: string;
}) {
  return requestClient.get<CustomerProfileDto>('/customer/list/profile', {
    params,
  });
}

/** 导出客户列表 CSV。 */
export async function exportCustomerCsvApi(params: CustomerListFilterQuery) {
  return requestClient.get<CustomerExportDto>('/customer/list/export', {
    params,
  });
}

/** 查询客户分析总览。 */
export async function getCustomerAnalysisOverviewApi(
  params: CustomerAnalysisBaseQuery,
) {
  return requestClient.get<CustomerAnalysisOverviewDto>(
    '/customer/analysis/overview',
    {
      params,
    },
  );
}

/** 查询客群明细分页。 */
export async function getCustomerAnalysisSegmentListApi(
  params: CustomerAnalysisSegmentListQuery,
) {
  return requestClient.get<CustomerAnalysisSegmentListResultDto>(
    '/customer/analysis/segment/list',
    {
      params,
    },
  );
}

/** 查询客户分析会员详情。 */
export async function getCustomerMemberDetailApi(params: {
  customerKey: string;
  storeId: string;
}) {
  return requestClient.get<CustomerMemberDetailDto>(
    '/customer/analysis/member/detail',
    {
      params,
    },
  );
}

/** 查询客户分析客户详情。 */
export async function getCustomerAnalysisDetailApi(params: {
  customerKey: string;
  storeId: string;
}) {
  return requestClient.get<CustomerDetailDto>('/customer/analysis/detail', {
    params,
  });
}

/** 查询客户分析客户画像。 */
export async function getCustomerAnalysisProfileApi(params: {
  customerKey: string;
  storeId: string;
}) {
  return requestClient.get<CustomerProfileDto>('/customer/analysis/profile', {
    params,
  });
}

/** 导出客户分析 CSV。 */
export async function exportCustomerAnalysisCsvApi(
  params: CustomerAnalysisBaseQuery,
) {
  return requestClient.get<CustomerExportDto>('/customer/analysis/export', {
    params,
  });
}