feat(@vben/web-antd): 客户画像页面与二级抽屉

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

@@ -0,0 +1,210 @@
+/**
+ * 文件职责：客户管理列表与画像 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 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,
+  });
+}