Merge pull request 'feat(finance): 财务概览页面模块 1:1 还原' (#8) from feature/finance-overview-1to1 into main

feat(@vben/web-antd): implement finance business report module

.gitea/workflows/deploy.yml

@@ -0,0 +1,71 @@
+name: Build and Deploy TenantUI
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-and-deploy:
+    runs-on: host
+    steps:
+      - name: Checkout code
+        run: |
+          set -e
+          cd /opt/deploy/tenantui || mkdir -p /opt/deploy/tenantui
+          cd /opt/deploy/tenantui
+
+          # 如果已有仓库就 pull，否则 clone
+          if [ -d ".git" ]; then
+            git fetch origin main
+            git reset --hard origin/main
+            git clean -fd
+          else
+            git clone --branch main ssh://git@git.laosankeji.com:2222/msumshk/TakeoutSaaS.TenantUI.git .
+          fi
+
+      - name: Build on host
+        run: |
+          set -e
+          cd /opt/deploy/tenantui
+
+          # 1. 保证 pnpm 可用（兼容没有 corepack 的 runner）
+          if ! command -v pnpm >/dev/null 2>&1; then
+            if command -v corepack >/dev/null 2>&1; then
+              corepack enable
+              corepack prepare pnpm@10.28.2 --activate
+            elif command -v npm >/dev/null 2>&1; then
+              npm install -g pnpm@10.28.2
+            else
+              echo "ERROR: corepack/npm 均不可用，请在 runner 安装 Node.js 20+"
+              exit 1
+            fi
+          fi
+
+          pnpm --version
+          pnpm install --frozen-lockfile
+          VITE_GLOB_API_URL=https://api-tenant-dev.laosankeji.com/api/tenant/v1 pnpm exec turbo run build --filter=@vben/web-antd...
+
+          rm -rf publish/web-antd-dist
+          mkdir -p publish
+          cp -r apps/web-antd/dist publish/web-antd-dist
+
+      - name: Build Docker image
+        run: |
+          set -e
+          cd /opt/deploy/tenantui
+          docker build -t takeoutsaas-tenantui:latest -f scripts/deploy/Dockerfile.runtime .
+
+      - name: Deploy container
+        run: |
+          docker stop tenantui || true
+          docker rm tenantui || true
+          docker run -d \
+            --name tenantui \
+            --restart unless-stopped \
+            -p 8010:8080 \
+            takeoutsaas-tenantui:latest
+
+      - name: Clean up old images
+        run: |
+          docker image prune -f

apps/web-antd/.env

@@ -6,3 +6,6 @@ VITE_APP_NAMESPACE=vben-web-antd
 
 # 对store进行加密的密钥，在将store持久化到localStorage时会使用该密钥进行加密
 VITE_APP_STORE_SECURE_KEY=please-replace-me-with-your-own-key
+
+# 腾讯地图 WebGL JS SDK Key
+VITE_TENCENT_MAP_KEY=DGIBZ-YUM64-5ONUT-F4RIA-MPUP2-XFFXZ

apps/web-antd/.env.development

@@ -12,6 +12,9 @@ VITE_TENANT_ID=806357433394921472
 # 是否开启 Nitro Mock服务，true 为开启，false 为关闭
 VITE_NITRO_MOCK=false
 
+# 是否开启商品分类管理 mock（默认 false，分类管理强制走真实 API）
+VITE_MOCK_PRODUCT_CATEGORY=false
+
 # 是否打开 devtools，true 为打开，false 为关闭
 VITE_DEVTOOLS=false
 

apps/web-antd/.env.production

@@ -1,7 +1,7 @@
 VITE_BASE=/
 
 # 接口地址
-VITE_GLOB_API_URL=https://mock-napi.vben.pro/api
+VITE_GLOB_API_URL=https://api-tenant.laosankeji.com/api/tenant/v1
 
 # 是否开启压缩，可以设置为 none, brotli, gzip
 VITE_COMPRESS=none

apps/web-antd/package.json

@@ -26,6 +26,7 @@
     "#/*": "./src/*"
   },
   "dependencies": {
+    "@microsoft/signalr": "catalog:",
     "@vben/access": "workspace:*",
     "@vben/common-ui": "workspace:*",
     "@vben/constants": "workspace:*",

apps/web-antd/public/sounds/README.md

@@ -0,0 +1,5 @@
+Sound placeholder files:
+- new-order.mp3: 新订单提示音（需替换为实际音频文件）
+- urge.mp3: 催单提示音（需替换为实际音频文件）
+
+请将实际的 MP3 音频文件放置到此目录下。

apps/web-antd/src/api/core/auth.ts

@@ -1,3 +1,5 @@
+import type { RequestClientConfig } from '@vben/request';
+
 import { baseRequestClient, requestClient } from '#/api/request';
 
 export namespace AuthApi {
@@ -53,10 +55,14 @@ export async function loginApi(data: AuthApi.LoginParams) {
 /**
  * 刷新accessToken
  */
-export async function refreshTokenApi(data: AuthApi.RefreshTokenParams) {
+export async function refreshTokenApi(
+  data: AuthApi.RefreshTokenParams,
+  config?: RequestClientConfig,
+) {
   return baseRequestClient.post<AuthApi.ApiResponse<AuthApi.LoginResult>>(
     '/auth/refresh',
     data,
+    config,
   );
 }
 

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

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

apps/web-antd/src/api/files.ts

@@ -0,0 +1,44 @@
+import { requestClient } from '#/api/request';
+
+export type UploadFileType =
+  | 'business_license'
+  | 'dish_image'
+  | 'merchant_logo'
+  | 'other'
+  | 'review_image'
+  | 'user_avatar';
+
+export interface FileUploadResponse {
+  fileName?: null | string;
+  fileSize: number;
+  url?: null | string;
+}
+
+const TENANT_STORAGE_KEY = 'sys-tenant-id';
+const DEV_TENANT_ID = import.meta.env.DEV ? import.meta.env.VITE_TENANT_ID : '';
+
+function resolveTenantId() {
+  const hostname = window.location.hostname;
+  const hostnameParts = hostname.split('.').filter(Boolean);
+  const isIpAddress = /^\d+\.\d+\.\d+\.\d+$/.test(hostname);
+  const subdomainTenantId =
+    hostnameParts.length > 2 && !isIpAddress ? hostnameParts[0] : '';
+  const storageTenantId = localStorage.getItem(TENANT_STORAGE_KEY) || '';
+  return subdomainTenantId || storageTenantId || DEV_TENANT_ID || '';
+}
+
+export async function uploadTenantFileApi(
+  file: File,
+  type: UploadFileType = 'other',
+) {
+  const tenantId = resolveTenantId();
+  if (!tenantId) {
+    throw new Error('缺少租户标识');
+  }
+
+  return requestClient.upload<FileUploadResponse>('/files/upload', {
+    file,
+    tenantId: String(tenantId),
+    type,
+  });
+}

apps/web-antd/src/api/finance/cost.ts

@@ -0,0 +1,143 @@
+/**
+ * 文件职责：财务中心成本管理 API 契约与请求封装。
+ */
+import { requestClient } from '#/api/request';
+
+/** 成本统计维度。 */
+export type FinanceCostDimension = 'store' | 'tenant';
+
+/** 成本分类编码。 */
+export type FinanceCostCategoryCode = 'fixed' | 'food' | 'labor' | 'packaging';
+
+/** 成本作用域查询参数。 */
+export interface FinanceCostScopeQuery {
+  dimension?: FinanceCostDimension;
+  month?: string;
+  storeId?: string;
+}
+
+/** 成本明细项。 */
+export interface FinanceCostEntryDetailDto {
+  amount: number;
+  itemId?: string;
+  itemName: string;
+  quantity?: number;
+  sortOrder: number;
+  unitPrice?: number;
+}
+
+/** 成本分类数据。 */
+export interface FinanceCostEntryCategoryDto {
+  category: FinanceCostCategoryCode;
+  categoryText: string;
+  items: FinanceCostEntryDetailDto[];
+  percentage: number;
+  totalAmount: number;
+}
+
+/** 成本录入数据。 */
+export interface FinanceCostEntryDto {
+  categories: FinanceCostEntryCategoryDto[];
+  costRate: number;
+  dimension: FinanceCostDimension;
+  month: string;
+  monthRevenue: number;
+  storeId?: string;
+  totalCost: number;
+}
+
+/** 保存成本明细项请求。 */
+export interface SaveFinanceCostDetailPayload {
+  amount: number;
+  itemId?: string;
+  itemName: string;
+  quantity?: number;
+  sortOrder: number;
+  unitPrice?: number;
+}
+
+/** 保存成本分类请求。 */
+export interface SaveFinanceCostCategoryPayload {
+  category: FinanceCostCategoryCode;
+  items: SaveFinanceCostDetailPayload[];
+  totalAmount: number;
+}
+
+/** 保存成本录入请求。 */
+export interface SaveFinanceCostEntryPayload extends FinanceCostScopeQuery {
+  categories: SaveFinanceCostCategoryPayload[];
+}
+
+/** 成本分析统计卡。 */
+export interface FinanceCostAnalysisStatsDto {
+  averageCostPerPaidOrder: number;
+  foodCostRate: number;
+  monthOnMonthChangeRate: number;
+  paidOrderCount: number;
+  revenue: number;
+  totalCost: number;
+}
+
+/** 成本趋势点。 */
+export interface FinanceCostTrendPointDto {
+  costRate: number;
+  month: string;
+  revenue: number;
+  totalCost: number;
+}
+
+/** 成本构成项。 */
+export interface FinanceCostCompositionDto {
+  amount: number;
+  category: FinanceCostCategoryCode;
+  categoryText: string;
+  percentage: number;
+}
+
+/** 成本明细表行。 */
+export interface FinanceCostMonthlyDetailRowDto {
+  costRate: number;
+  fixedAmount: number;
+  foodAmount: number;
+  laborAmount: number;
+  month: string;
+  packagingAmount: number;
+  totalCost: number;
+}
+
+/** 成本分析数据。 */
+export interface FinanceCostAnalysisDto {
+  composition: FinanceCostCompositionDto[];
+  detailRows: FinanceCostMonthlyDetailRowDto[];
+  dimension: FinanceCostDimension;
+  month: string;
+  stats: FinanceCostAnalysisStatsDto;
+  storeId?: string;
+  trend: FinanceCostTrendPointDto[];
+}
+
+/** 查询成本录入数据。 */
+export async function getFinanceCostEntryApi(params: FinanceCostScopeQuery) {
+  return requestClient.get<FinanceCostEntryDto>('/finance/cost/entry', {
+    params,
+  });
+}
+
+/** 保存成本录入数据。 */
+export async function saveFinanceCostEntryApi(
+  payload: SaveFinanceCostEntryPayload,
+) {
+  return requestClient.post<FinanceCostEntryDto>(
+    '/finance/cost/entry/save',
+    payload,
+  );
+}
+
+/** 查询成本分析数据。 */
+export async function getFinanceCostAnalysisApi(
+  params: FinanceCostScopeQuery & { trendMonthCount?: number },
+) {
+  return requestClient.get<FinanceCostAnalysisDto>('/finance/cost/analysis', {
+    params,
+  });
+}

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

@@ -0,0 +1,9 @@
+/**
+ * 文件职责：财务中心 API 聚合导出。
+ */
+export * from './cost';
+export * from './invoice';
+export * from './overview';
+export * from './report';
+export * from './settlement';
+export * from './transaction';

apps/web-antd/src/api/finance/invoice.ts

@@ -0,0 +1,206 @@
+/**
+ * 文件职责：财务中心发票管理 API 契约与请求封装。
+ */
+import { requestClient } from '#/api/request';
+
+/** 发票状态筛选值。 */
+export type FinanceInvoiceStatusFilter = 'all' | 'issued' | 'pending' | 'voided';
+
+/** 发票类型筛选值。 */
+export type FinanceInvoiceTypeFilter = 'all' | 'normal' | 'special';
+
+/** 发票设置详情。 */
+export interface FinanceInvoiceSettingDto {
+  autoIssueMaxAmount: number;
+  bankAccount?: string;
+  bankName?: string;
+  companyName: string;
+  enableAutoIssue: boolean;
+  enableElectronicNormalInvoice: boolean;
+  enableElectronicSpecialInvoice: boolean;
+  registeredAddress?: string;
+  registeredPhone?: string;
+  taxpayerNumber: string;
+}
+
+/** 保存发票设置请求。 */
+export interface SaveFinanceInvoiceSettingPayload
+  extends FinanceInvoiceSettingDto {}
+
+/** 发票记录列表查询参数。 */
+export interface FinanceInvoiceRecordListQuery {
+  endDate?: string;
+  invoiceType?: Exclude<FinanceInvoiceTypeFilter, 'all'>;
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  startDate?: string;
+  status?: Exclude<FinanceInvoiceStatusFilter, 'all'>;
+}
+
+/** 发票统计结果。 */
+export interface FinanceInvoiceStatsDto {
+  currentMonthIssuedAmount: number;
+  currentMonthIssuedCount: number;
+  pendingCount: number;
+  voidedCount: number;
+}
+
+/** 发票记录列表项。 */
+export interface FinanceInvoiceRecordListItemDto {
+  amount: number;
+  applicantName: string;
+  appliedAt: string;
+  companyName: string;
+  invoiceNo: string;
+  invoiceType: string;
+  invoiceTypeText: string;
+  orderNo: string;
+  recordId: string;
+  status: string;
+  statusText: string;
+}
+
+/** 发票记录分页结果。 */
+export interface FinanceInvoiceRecordListResultDto {
+  items: FinanceInvoiceRecordListItemDto[];
+  page: number;
+  pageSize: number;
+  stats: FinanceInvoiceStatsDto;
+  totalCount: number;
+}
+
+/** 发票记录详情。 */
+export interface FinanceInvoiceRecordDetailDto {
+  amount: number;
+  applicantName: string;
+  appliedAt: string;
+  applyRemark?: string;
+  companyName: string;
+  contactEmail?: string;
+  contactPhone?: string;
+  invoiceNo: string;
+  invoiceType: string;
+  invoiceTypeText: string;
+  issueRemark?: string;
+  issuedAt?: string;
+  issuedByUserId?: string;
+  orderNo: string;
+  recordId: string;
+  status: string;
+  statusText: string;
+  taxpayerNumber?: string;
+  voidReason?: string;
+  voidedAt?: string;
+  voidedByUserId?: string;
+}
+
+/** 发票开票请求。 */
+export interface FinanceInvoiceIssuePayload {
+  contactEmail?: string;
+  issueRemark?: string;
+  recordId: string;
+}
+
+/** 发票开票结果。 */
+export interface FinanceInvoiceIssueResultDto {
+  amount: number;
+  companyName: string;
+  contactEmail?: string;
+  invoiceNo: string;
+  issuedAt: string;
+  recordId: string;
+  status: string;
+  statusText: string;
+}
+
+/** 发票作废请求。 */
+export interface FinanceInvoiceVoidPayload {
+  recordId: string;
+  voidReason: string;
+}
+
+/** 发票申请请求。 */
+export interface FinanceInvoiceApplyPayload {
+  amount: number;
+  applicantName: string;
+  appliedAt?: string;
+  applyRemark?: string;
+  companyName: string;
+  contactEmail?: string;
+  contactPhone?: string;
+  invoiceType: Exclude<FinanceInvoiceTypeFilter, 'all'>;
+  orderNo: string;
+  taxpayerNumber?: string;
+}
+
+/** 查询发票设置。 */
+export async function getFinanceInvoiceSettingDetailApi() {
+  return requestClient.get<FinanceInvoiceSettingDto>(
+    '/finance/invoice/settings/detail',
+  );
+}
+
+/** 保存发票设置。 */
+export async function saveFinanceInvoiceSettingApi(
+  payload: SaveFinanceInvoiceSettingPayload,
+) {
+  return requestClient.post<FinanceInvoiceSettingDto>(
+    '/finance/invoice/settings/save',
+    payload,
+  );
+}
+
+/** 查询发票记录列表。 */
+export async function getFinanceInvoiceRecordListApi(
+  params: FinanceInvoiceRecordListQuery,
+) {
+  return requestClient.get<FinanceInvoiceRecordListResultDto>(
+    '/finance/invoice/record/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询发票记录详情。 */
+export async function getFinanceInvoiceRecordDetailApi(params: {
+  recordId: string;
+}) {
+  return requestClient.get<FinanceInvoiceRecordDetailDto>(
+    '/finance/invoice/record/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 执行发票开票。 */
+export async function issueFinanceInvoiceRecordApi(
+  payload: FinanceInvoiceIssuePayload,
+) {
+  return requestClient.post<FinanceInvoiceIssueResultDto>(
+    '/finance/invoice/record/issue',
+    payload,
+  );
+}
+
+/** 执行发票作废。 */
+export async function voidFinanceInvoiceRecordApi(
+  payload: FinanceInvoiceVoidPayload,
+) {
+  return requestClient.post<FinanceInvoiceRecordDetailDto>(
+    '/finance/invoice/record/void',
+    payload,
+  );
+}
+
+/** 发起发票申请。 */
+export async function applyFinanceInvoiceRecordApi(
+  payload: FinanceInvoiceApplyPayload,
+) {
+  return requestClient.post<FinanceInvoiceRecordDetailDto>(
+    '/finance/invoice/record/apply',
+    payload,
+  );
+}

apps/web-antd/src/api/finance/overview.ts

@@ -0,0 +1,122 @@
+/**
+ * 文件职责：财务概览 API 契约与请求封装。
+ */
+import { requestClient } from '#/api/request';
+
+/** 财务概览维度。 */
+export type FinanceOverviewDimension = 'store' | 'tenant';
+
+/** 趋势周期值。 */
+export type FinanceOverviewTrendRange = '7' | '30';
+
+/** 财务概览查询参数。 */
+export interface FinanceOverviewDashboardQuery {
+  dimension: FinanceOverviewDimension;
+  storeId?: string;
+}
+
+/** KPI 卡片数据。 */
+export interface FinanceOverviewKpiCardDto {
+  amount: number;
+  changeRate: number;
+  compareAmount: number;
+  compareLabel: string;
+  trend: 'down' | 'flat' | 'up';
+}
+
+/** 收入趋势点。 */
+export interface FinanceOverviewIncomeTrendPointDto {
+  amount: number;
+  date: string;
+  dateLabel: string;
+}
+
+/** 收入趋势数据。 */
+export interface FinanceOverviewIncomeTrendDto {
+  last30Days: FinanceOverviewIncomeTrendPointDto[];
+  last7Days: FinanceOverviewIncomeTrendPointDto[];
+}
+
+/** 利润趋势点。 */
+export interface FinanceOverviewProfitTrendPointDto {
+  costAmount: number;
+  date: string;
+  dateLabel: string;
+  netProfitAmount: number;
+  revenueAmount: number;
+}
+
+/** 利润趋势数据。 */
+export interface FinanceOverviewProfitTrendDto {
+  last30Days: FinanceOverviewProfitTrendPointDto[];
+  last7Days: FinanceOverviewProfitTrendPointDto[];
+}
+
+/** 收入构成项。 */
+export interface FinanceOverviewIncomeCompositionItemDto {
+  amount: number;
+  channel: 'delivery' | 'dine_in' | 'pickup';
+  channelText: string;
+  percentage: number;
+}
+
+/** 收入构成数据。 */
+export interface FinanceOverviewIncomeCompositionDto {
+  items: FinanceOverviewIncomeCompositionItemDto[];
+  totalAmount: number;
+}
+
+/** 成本构成项。 */
+export interface FinanceOverviewCostCompositionItemDto {
+  amount: number;
+  category: 'fixed' | 'food' | 'labor' | 'packaging' | 'platform';
+  categoryText: string;
+  percentage: number;
+}
+
+/** 成本构成数据。 */
+export interface FinanceOverviewCostCompositionDto {
+  items: FinanceOverviewCostCompositionItemDto[];
+  totalAmount: number;
+}
+
+/** TOP 商品项。 */
+export interface FinanceOverviewTopProductItemDto {
+  percentage: number;
+  productName: string;
+  rank: number;
+  revenueAmount: number;
+  salesQuantity: number;
+}
+
+/** TOP 商品排行。 */
+export interface FinanceOverviewTopProductDto {
+  items: FinanceOverviewTopProductItemDto[];
+  periodDays: number;
+}
+
+/** 财务概览驾驶舱数据。 */
+export interface FinanceOverviewDashboardDto {
+  actualReceived: FinanceOverviewKpiCardDto;
+  costComposition: FinanceOverviewCostCompositionDto;
+  dimension: FinanceOverviewDimension;
+  incomeComposition: FinanceOverviewIncomeCompositionDto;
+  incomeTrend: FinanceOverviewIncomeTrendDto;
+  netIncome: FinanceOverviewKpiCardDto;
+  profitTrend: FinanceOverviewProfitTrendDto;
+  refundAmount: FinanceOverviewKpiCardDto;
+  storeId?: string;
+  todayRevenue: FinanceOverviewKpiCardDto;
+  topProducts: FinanceOverviewTopProductDto;
+  withdrawableBalance: FinanceOverviewKpiCardDto;
+}
+
+/** 查询财务概览驾驶舱。 */
+export async function getFinanceOverviewDashboardApi(
+  params: FinanceOverviewDashboardQuery,
+) {
+  return requestClient.get<FinanceOverviewDashboardDto>(
+    '/finance/overview/dashboard',
+    { params },
+  );
+}

apps/web-antd/src/api/finance/report.ts

@@ -0,0 +1,156 @@
+/**
+ * 文件职责：财务中心经营报表 API 契约与请求封装。
+ */
+import { requestClient } from '#/api/request';
+
+/** 报表周期筛选值。 */
+export type FinanceBusinessReportPeriodType = 'daily' | 'monthly' | 'weekly';
+
+/** 经营报表状态值。 */
+export type FinanceBusinessReportStatus =
+  | 'failed'
+  | 'queued'
+  | 'running'
+  | 'succeeded';
+
+/** 经营报表列表查询参数。 */
+export interface FinanceBusinessReportListQuery {
+  page: number;
+  pageSize: number;
+  periodType?: FinanceBusinessReportPeriodType;
+  storeId: string;
+}
+
+/** 经营报表详情查询参数。 */
+export interface FinanceBusinessReportDetailQuery {
+  reportId: string;
+  storeId: string;
+}
+
+/** 经营报表批量导出查询参数。 */
+export interface FinanceBusinessReportBatchExportQuery {
+  page: number;
+  pageSize: number;
+  periodType?: FinanceBusinessReportPeriodType;
+  storeId: string;
+}
+
+/** 经营报表列表行。 */
+export interface FinanceBusinessReportListItemDto {
+  averageOrderValue: number;
+  canDownload: boolean;
+  costTotalAmount: number;
+  dateText: string;
+  netProfitAmount: number;
+  orderCount: number;
+  profitRatePercent: number;
+  refundRatePercent: number;
+  reportId: string;
+  revenueAmount: number;
+  status: FinanceBusinessReportStatus;
+  statusText: string;
+}
+
+/** 经营报表列表结果。 */
+export interface FinanceBusinessReportListResultDto {
+  items: FinanceBusinessReportListItemDto[];
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+/** 经营报表 KPI 项。 */
+export interface FinanceBusinessReportKpiDto {
+  key: string;
+  label: string;
+  momChangeRate: number;
+  valueText: string;
+  yoyChangeRate: number;
+}
+
+/** 经营报表明细项。 */
+export interface FinanceBusinessReportBreakdownItemDto {
+  amount: number;
+  key: string;
+  label: string;
+  ratioPercent: number;
+}
+
+/** 经营报表详情。 */
+export interface FinanceBusinessReportDetailDto {
+  costBreakdowns: FinanceBusinessReportBreakdownItemDto[];
+  incomeBreakdowns: FinanceBusinessReportBreakdownItemDto[];
+  kpis: FinanceBusinessReportKpiDto[];
+  periodType: FinanceBusinessReportPeriodType;
+  reportId: string;
+  status: FinanceBusinessReportStatus;
+  statusText: string;
+  title: string;
+}
+
+/** 经营报表导出结果。 */
+export interface FinanceBusinessReportExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 查询经营报表列表。 */
+export async function getFinanceBusinessReportListApi(
+  params: FinanceBusinessReportListQuery,
+) {
+  return requestClient.get<FinanceBusinessReportListResultDto>(
+    '/finance/report/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询经营报表详情。 */
+export async function getFinanceBusinessReportDetailApi(
+  params: FinanceBusinessReportDetailQuery,
+) {
+  return requestClient.get<FinanceBusinessReportDetailDto>(
+    '/finance/report/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 导出经营报表 PDF。 */
+export async function exportFinanceBusinessReportPdfApi(
+  params: FinanceBusinessReportDetailQuery,
+) {
+  return requestClient.get<FinanceBusinessReportExportDto>(
+    '/finance/report/export/pdf',
+    {
+      params,
+    },
+  );
+}
+
+/** 导出经营报表 Excel。 */
+export async function exportFinanceBusinessReportExcelApi(
+  params: FinanceBusinessReportDetailQuery,
+) {
+  return requestClient.get<FinanceBusinessReportExportDto>(
+    '/finance/report/export/excel',
+    {
+      params,
+    },
+  );
+}
+
+/** 批量导出经营报表（ZIP）。 */
+export async function exportFinanceBusinessReportBatchApi(
+  params: FinanceBusinessReportBatchExportQuery,
+) {
+  return requestClient.get<FinanceBusinessReportExportDto>(
+    '/finance/report/export/batch',
+    {
+      params,
+    },
+  );
+}

apps/web-antd/src/api/finance/settlement.ts

@@ -0,0 +1,137 @@
+/**
+ * 文件职责：财务中心到账查询 API 契约与请求封装。
+ */
+import { requestClient } from '#/api/request';
+
+/** 到账渠道筛选值。 */
+export type FinanceSettlementChannelFilter = 'alipay' | 'all' | 'wechat';
+
+/** 到账查询筛选参数。 */
+export interface FinanceSettlementFilterQuery {
+  channel?: FinanceSettlementChannelFilter;
+  endDate?: string;
+  startDate?: string;
+  storeId: string;
+}
+
+/** 到账查询列表参数。 */
+export interface FinanceSettlementListQuery extends FinanceSettlementFilterQuery {
+  page: number;
+  pageSize: number;
+}
+
+/** 到账统计结果。 */
+export interface FinanceSettlementStatsDto {
+  currentMonthArrivedAmount: number;
+  currentMonthTransactionCount: number;
+  todayArrivedAmount: number;
+  yesterdayArrivedAmount: number;
+}
+
+/** 到账账户信息。 */
+export interface FinanceSettlementAccountDto {
+  alipayPidMasked: string;
+  bankAccountName: string;
+  bankAccountNoMasked: string;
+  bankName: string;
+  settlementPeriodText: string;
+  wechatMerchantNoMasked: string;
+}
+
+/** 到账列表行。 */
+export interface FinanceSettlementListItemDto {
+  arrivedAmount: number;
+  arrivedDate: string;
+  channel: 'alipay' | 'wechat';
+  channelText: string;
+  transactionCount: number;
+}
+
+/** 到账列表结果。 */
+export interface FinanceSettlementListResultDto {
+  items: FinanceSettlementListItemDto[];
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+/** 到账明细查询参数。 */
+export interface FinanceSettlementDetailQuery {
+  arrivedDate: string;
+  channel: 'alipay' | 'wechat';
+  storeId: string;
+}
+
+/** 到账明细行。 */
+export interface FinanceSettlementDetailItemDto {
+  amount: number;
+  orderNo: string;
+  paidAt: string;
+}
+
+/** 到账明细结果。 */
+export interface FinanceSettlementDetailResultDto {
+  items: FinanceSettlementDetailItemDto[];
+}
+
+/** 到账导出结果。 */
+export interface FinanceSettlementExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 查询到账统计。 */
+export async function getFinanceSettlementStatsApi(params: {
+  storeId: string;
+}) {
+  return requestClient.get<FinanceSettlementStatsDto>(
+    '/finance/settlement/stats',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询到账账户信息。 */
+export async function getFinanceSettlementAccountApi() {
+  return requestClient.get<FinanceSettlementAccountDto>(
+    '/finance/settlement/account',
+  );
+}
+
+/** 查询到账列表。 */
+export async function getFinanceSettlementListApi(
+  params: FinanceSettlementListQuery,
+) {
+  return requestClient.get<FinanceSettlementListResultDto>(
+    '/finance/settlement/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询到账明细。 */
+export async function getFinanceSettlementDetailApi(
+  params: FinanceSettlementDetailQuery,
+) {
+  return requestClient.get<FinanceSettlementDetailResultDto>(
+    '/finance/settlement/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 导出到账汇总 CSV。 */
+export async function exportFinanceSettlementCsvApi(
+  params: FinanceSettlementFilterQuery,
+) {
+  return requestClient.get<FinanceSettlementExportDto>(
+    '/finance/settlement/export',
+    {
+      params,
+    },
+  );
+}

apps/web-antd/src/api/finance/transaction.ts

@@ -0,0 +1,159 @@
+/**
+ * 文件职责：财务中心交易流水 API 契约与请求封装。
+ */
+import { requestClient } from '#/api/request';
+
+/** 交易类型筛选值。 */
+export type FinanceTransactionTypeFilter =
+  | 'all'
+  | 'income'
+  | 'point_redeem'
+  | 'refund'
+  | 'stored_card_recharge';
+
+/** 交易渠道筛选值。 */
+export type FinanceTransactionChannelFilter =
+  | 'all'
+  | 'delivery'
+  | 'dine_in'
+  | 'pickup';
+
+/** 交易支付方式筛选值。 */
+export type FinanceTransactionPaymentFilter =
+  | 'alipay'
+  | 'all'
+  | 'balance'
+  | 'card'
+  | 'cash'
+  | 'wechat';
+
+/** 交易流水筛选参数。 */
+export interface FinanceTransactionFilterQuery {
+  channel?: FinanceTransactionChannelFilter;
+  endDate?: string;
+  keyword?: string;
+  paymentMethod?: FinanceTransactionPaymentFilter;
+  startDate?: string;
+  storeId: string;
+  type?: FinanceTransactionTypeFilter;
+}
+
+/** 交易流水列表查询参数。 */
+export interface FinanceTransactionListQuery extends FinanceTransactionFilterQuery {
+  page: number;
+  pageSize: number;
+}
+
+/** 交易流水列表行。 */
+export interface FinanceTransactionListItemDto {
+  amount: number;
+  channel: string;
+  isIncome: boolean;
+  occurredAt: string;
+  orderNo?: string;
+  paymentMethod: string;
+  remark: string;
+  transactionId: string;
+  transactionNo: string;
+  type: string;
+  typeText: string;
+}
+
+/** 交易流水列表结果。 */
+export interface FinanceTransactionListResultDto {
+  items: FinanceTransactionListItemDto[];
+  page: number;
+  pageIncomeAmount: number;
+  pageRefundAmount: number;
+  pageSize: number;
+  total: number;
+}
+
+/** 交易流水统计结果。 */
+export interface FinanceTransactionStatsDto {
+  totalCount: number;
+  totalIncome: number;
+  totalRefund: number;
+}
+
+/** 交易流水详情。 */
+export interface FinanceTransactionDetailDto {
+  amount: number;
+  arrivedAmount?: number;
+  channel: string;
+  customerName: string;
+  customerPhone: string;
+  giftAmount?: number;
+  memberMobileMasked?: string;
+  memberName?: string;
+  occurredAt: string;
+  orderNo?: string;
+  paymentMethod: string;
+  pointBalanceAfterChange?: number;
+  pointChangeAmount?: number;
+  rechargeAmount?: number;
+  refundNo?: string;
+  refundReason?: string;
+  remark: string;
+  storeId: string;
+  transactionId: string;
+  transactionNo: string;
+  type: string;
+  typeText: string;
+}
+
+/** 交易流水导出结果。 */
+export interface FinanceTransactionExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 查询交易流水列表。 */
+export async function getFinanceTransactionListApi(
+  params: FinanceTransactionListQuery,
+) {
+  return requestClient.get<FinanceTransactionListResultDto>(
+    '/finance/transaction/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询交易流水统计。 */
+export async function getFinanceTransactionStatsApi(
+  params: FinanceTransactionFilterQuery,
+) {
+  return requestClient.get<FinanceTransactionStatsDto>(
+    '/finance/transaction/stats',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询交易流水详情。 */
+export async function getFinanceTransactionDetailApi(params: {
+  storeId: string;
+  transactionId: string;
+}) {
+  return requestClient.get<FinanceTransactionDetailDto>(
+    '/finance/transaction/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 导出交易流水 CSV。 */
+export async function exportFinanceTransactionCsvApi(
+  params: FinanceTransactionFilterQuery,
+) {
+  return requestClient.get<FinanceTransactionExportDto>(
+    '/finance/transaction/export',
+    {
+      params,
+    },
+  );
+}

apps/web-antd/src/api/marketing/calendar.ts

@@ -0,0 +1,133 @@
+/**
+ * 文件职责：营销中心营销日历 API 与 DTO 定义。
+ */
+import { requestClient } from '#/api/request';
+
+/** 总览查询参数。 */
+export interface MarketingCalendarOverviewQuery {
+  month: number;
+  storeId: string;
+  year: number;
+}
+
+/** 日期头。 */
+export interface MarketingCalendarDayDto {
+  day: number;
+  isToday: boolean;
+  isWeekend: boolean;
+}
+
+/** 图例。 */
+export interface MarketingCalendarLegendDto {
+  color: string;
+  label: string;
+  type: string;
+}
+
+/** 顶部统计。 */
+export interface MarketingCalendarStatsDto {
+  estimatedDiscountAmount: number;
+  maxConcurrentCount: number;
+  ongoingCount: number;
+  totalActivityCount: number;
+}
+
+/** 活动条。 */
+export interface MarketingCalendarActivityBarDto {
+  barId: string;
+  endDay: number;
+  isDimmed: boolean;
+  isMilestone: boolean;
+  label: string;
+  startDay: number;
+}
+
+/** 详情字段。 */
+export interface MarketingCalendarDetailFieldDto {
+  label: string;
+  value: string;
+}
+
+/** 活动详情。 */
+export interface MarketingCalendarActivityDetailDto {
+  description: string;
+  fields: MarketingCalendarDetailFieldDto[];
+  moduleName: string;
+}
+
+/** 活动。 */
+export interface MarketingCalendarActivityDto {
+  activityId: string;
+  bars: MarketingCalendarActivityBarDto[];
+  calendarType: string;
+  color: string;
+  detail: MarketingCalendarActivityDetailDto;
+  displayStatus: string;
+  endDate: string;
+  estimatedDiscountAmount: number;
+  isDimmed: boolean;
+  name: string;
+  sourceId: string;
+  sourceType: string;
+  startDate: string;
+  summary: string;
+}
+
+/** 冲突活动摘要。 */
+export interface MarketingCalendarConflictActivityDto {
+  activityId: string;
+  calendarType: string;
+  color: string;
+  displayStatus: string;
+  name: string;
+  summary: string;
+}
+
+/** 冲突区间。 */
+export interface MarketingCalendarConflictDto {
+  activities: MarketingCalendarConflictActivityDto[];
+  activityCount: number;
+  activityIds: string[];
+  conflictId: string;
+  endDay: number;
+  maxConcurrentCount: number;
+  startDay: number;
+}
+
+/** 冲突横幅。 */
+export interface MarketingCalendarConflictBannerDto {
+  activityCount: number;
+  conflictCount: number;
+  conflictId: string;
+  endDay: number;
+  maxConcurrentCount: number;
+  startDay: number;
+}
+
+/** 营销日历总览。 */
+export interface MarketingCalendarOverviewDto {
+  activities: MarketingCalendarActivityDto[];
+  conflictBanner: MarketingCalendarConflictBannerDto | null;
+  conflicts: MarketingCalendarConflictDto[];
+  days: MarketingCalendarDayDto[];
+  legends: MarketingCalendarLegendDto[];
+  month: string;
+  monthEndDate: string;
+  monthStartDate: string;
+  monthValue: number;
+  stats: MarketingCalendarStatsDto;
+  todayDay: number;
+  year: number;
+}
+
+/** 查询营销日历总览。 */
+export async function getMarketingCalendarOverviewApi(
+  params: MarketingCalendarOverviewQuery,
+) {
+  return requestClient.get<MarketingCalendarOverviewDto>(
+    '/marketing/calendar/overview',
+    {
+      params,
+    },
+  );
+}

apps/web-antd/src/api/marketing/flash-sale.ts

@@ -0,0 +1,266 @@
+/**
+ * 文件职责：营销中心限时折扣 API 与 DTO 定义。
+ * 1. 维护限时折扣列表、详情、保存、状态切换、删除和选品契约。
+ */
+import { requestClient } from '#/api/request';
+
+/** 活动展示状态。 */
+export type MarketingFlashSaleDisplayStatus = 'ended' | 'ongoing' | 'upcoming';
+
+/** 活动编辑状态。 */
+export type MarketingFlashSaleEditorStatus = 'active' | 'completed';
+
+/** 活动周期。 */
+export type MarketingFlashSaleCycleType = 'once' | 'recurring';
+
+/** 周期日期模式。 */
+export type MarketingFlashSaleRecurringDateMode = 'fixed' | 'long_term';
+
+/** 适用渠道。 */
+export type MarketingFlashSaleChannel = 'delivery' | 'dine_in' | 'pickup';
+
+/** 商品状态。 */
+export type MarketingFlashSaleProductStatus =
+  | 'off_shelf'
+  | 'on_sale'
+  | 'sold_out';
+
+/** 限时折扣商品。 */
+export interface MarketingFlashSaleProductDto {
+  categoryId: string;
+  categoryName: string;
+  discountPrice: number;
+  name: string;
+  originalPrice: number;
+  perUserLimit: null | number;
+  productId: string;
+  soldCount: number;
+  spuCode: string;
+  status: MarketingFlashSaleProductStatus;
+}
+
+/** 活动指标。 */
+export interface MarketingFlashSaleMetricsDto {
+  activitySalesCount: number;
+  discountTotalAmount: number;
+  loopedWeeks: number;
+  monthlyDiscountSalesCount: number;
+}
+
+/** 列表查询参数。 */
+export interface MarketingFlashSaleListQuery {
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  status?: '' | MarketingFlashSaleDisplayStatus;
+  storeId?: string;
+}
+
+/** 详情查询参数。 */
+export interface MarketingFlashSaleDetailQuery {
+  activityId: string;
+  storeId: string;
+}
+
+/** 保存请求。 */
+export interface SaveMarketingFlashSaleDto {
+  channels: MarketingFlashSaleChannel[];
+  cycleType: MarketingFlashSaleCycleType;
+  endDate?: string;
+  id?: string;
+  metrics?: MarketingFlashSaleMetricsDto;
+  name: string;
+  perUserLimit: null | number;
+  products: Array<{
+    discountPrice: number;
+    perUserLimit: null | number;
+    productId: string;
+  }>;
+  recurringDateMode: MarketingFlashSaleRecurringDateMode;
+  startDate?: string;
+  storeId: string;
+  storeIds: string[];
+  timeEnd?: string;
+  timeStart?: string;
+  weekDays: number[];
+}
+
+/** 状态修改请求。 */
+export interface ChangeMarketingFlashSaleStatusDto {
+  activityId: string;
+  status: MarketingFlashSaleEditorStatus;
+  storeId: string;
+}
+
+/** 删除请求。 */
+export interface DeleteMarketingFlashSaleDto {
+  activityId: string;
+  storeId: string;
+}
+
+/** 列表统计。 */
+export interface MarketingFlashSaleStatsDto {
+  monthlyDiscountSalesCount: number;
+  ongoingCount: number;
+  participatingProductCount: number;
+  totalCount: number;
+}
+
+/** 列表项。 */
+export interface MarketingFlashSaleListItemDto {
+  channels: MarketingFlashSaleChannel[];
+  cycleType: MarketingFlashSaleCycleType;
+  displayStatus: MarketingFlashSaleDisplayStatus;
+  endDate?: string;
+  id: string;
+  isDimmed: boolean;
+  metrics: MarketingFlashSaleMetricsDto;
+  name: string;
+  perUserLimit: null | number;
+  products: MarketingFlashSaleProductDto[];
+  recurringDateMode: MarketingFlashSaleRecurringDateMode;
+  startDate?: string;
+  status: MarketingFlashSaleEditorStatus;
+  storeIds: string[];
+  timeEnd?: string;
+  timeStart?: string;
+  updatedAt: string;
+  weekDays: number[];
+}
+
+/** 列表结果。 */
+export interface MarketingFlashSaleListResultDto {
+  items: MarketingFlashSaleListItemDto[];
+  page: number;
+  pageSize: number;
+  stats: MarketingFlashSaleStatsDto;
+  total: number;
+}
+
+/** 详情数据。 */
+export interface MarketingFlashSaleDetailDto {
+  channels: MarketingFlashSaleChannel[];
+  cycleType: MarketingFlashSaleCycleType;
+  displayStatus: MarketingFlashSaleDisplayStatus;
+  endDate?: string;
+  id: string;
+  metrics: MarketingFlashSaleMetricsDto;
+  name: string;
+  perUserLimit: null | number;
+  products: MarketingFlashSaleProductDto[];
+  recurringDateMode: MarketingFlashSaleRecurringDateMode;
+  startDate?: string;
+  status: MarketingFlashSaleEditorStatus;
+  storeIds: string[];
+  timeEnd?: string;
+  timeStart?: string;
+  updatedAt: string;
+  weekDays: number[];
+}
+
+/** 选品分类查询参数。 */
+export interface MarketingFlashSalePickerCategoryQuery {
+  storeId: string;
+}
+
+/** 选品分类项。 */
+export interface MarketingFlashSalePickerCategoryItemDto {
+  id: string;
+  name: string;
+  productCount: number;
+}
+
+/** 选品商品查询参数。 */
+export interface MarketingFlashSalePickerProductQuery {
+  categoryId?: string;
+  keyword?: string;
+  limit?: number;
+  storeId: string;
+}
+
+/** 选品商品项。 */
+export interface MarketingFlashSalePickerProductItemDto {
+  categoryId: string;
+  categoryName: string;
+  id: string;
+  name: string;
+  price: number;
+  spuCode: string;
+  status: MarketingFlashSaleProductStatus;
+  stock: number;
+}
+
+/** 获取列表。 */
+export async function getMarketingFlashSaleListApi(
+  params: MarketingFlashSaleListQuery,
+) {
+  return requestClient.get<MarketingFlashSaleListResultDto>(
+    '/marketing/flash-sale/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 获取详情。 */
+export async function getMarketingFlashSaleDetailApi(
+  params: MarketingFlashSaleDetailQuery,
+) {
+  return requestClient.get<MarketingFlashSaleDetailDto>(
+    '/marketing/flash-sale/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存活动。 */
+export async function saveMarketingFlashSaleApi(
+  data: SaveMarketingFlashSaleDto,
+) {
+  return requestClient.post<MarketingFlashSaleDetailDto>(
+    '/marketing/flash-sale/save',
+    data,
+  );
+}
+
+/** 修改状态。 */
+export async function changeMarketingFlashSaleStatusApi(
+  data: ChangeMarketingFlashSaleStatusDto,
+) {
+  return requestClient.post<MarketingFlashSaleDetailDto>(
+    '/marketing/flash-sale/status',
+    data,
+  );
+}
+
+/** 删除活动。 */
+export async function deleteMarketingFlashSaleApi(
+  data: DeleteMarketingFlashSaleDto,
+) {
+  return requestClient.post('/marketing/flash-sale/delete', data);
+}
+
+/** 获取选品分类。 */
+export async function getMarketingFlashSalePickerCategoriesApi(
+  params: MarketingFlashSalePickerCategoryQuery,
+) {
+  return requestClient.get<MarketingFlashSalePickerCategoryItemDto[]>(
+    '/marketing/flash-sale/picker/categories',
+    {
+      params,
+    },
+  );
+}
+
+/** 获取选品商品。 */
+export async function getMarketingFlashSalePickerProductsApi(
+  params: MarketingFlashSalePickerProductQuery,
+) {
+  return requestClient.get<MarketingFlashSalePickerProductItemDto[]>(
+    '/marketing/flash-sale/picker/products',
+    {
+      params,
+    },
+  );
+}

apps/web-antd/src/api/marketing/full-reduction.ts

@@ -0,0 +1,240 @@
+/**
+ * 文件职责：营销中心满减活动 API 与 DTO 定义。
+ * 1. 维护满减活动列表、详情、保存、状态切换与删除契约。
+ */
+import { requestClient } from '#/api/request';
+
+/** 活动类型。 */
+export type MarketingFullReductionActivityType =
+  | 'gift'
+  | 'reduce'
+  | 'second_half';
+
+/** 展示状态。 */
+export type MarketingFullReductionDisplayStatus =
+  | 'ended'
+  | 'ongoing'
+  | 'upcoming';
+
+/** 编辑状态。 */
+export type MarketingFullReductionEditorStatus = 'active' | 'completed';
+
+/** 适用渠道。 */
+export type MarketingFullReductionChannel = 'delivery' | 'dine_in' | 'pickup';
+
+/** 门店范围。 */
+export type MarketingFullReductionStoreScopeMode = 'all' | 'stores';
+
+/** 商品范围。 */
+export type MarketingFullReductionScopeType = 'all' | 'category' | 'product';
+
+/** 满赠赠品类型。 */
+export type MarketingFullReductionGiftScopeType = 'same_lowest' | 'specified';
+
+/** 第二份折扣类型。 */
+export type MarketingFullReductionSecondHalfDiscountType =
+  | 'free'
+  | 'half'
+  | 'seventy'
+  | 'sixty';
+
+/** 满减阶梯规则。 */
+export interface MarketingFullReductionTierRuleDto {
+  meetAmount: number;
+  reduceAmount: number;
+}
+
+/** 商品范围规则。 */
+export interface MarketingFullReductionScopeRuleDto {
+  categoryIds: string[];
+  productIds: string[];
+  scopeType: MarketingFullReductionScopeType;
+}
+
+/** 满赠规则。 */
+export interface MarketingFullReductionGiftRuleDto {
+  applicableScope: MarketingFullReductionScopeRuleDto;
+  buyQuantity: number;
+  giftQuantity: number;
+  giftScope: MarketingFullReductionScopeRuleDto;
+  giftScopeType: MarketingFullReductionGiftScopeType;
+}
+
+/** 第二份半价规则。 */
+export interface MarketingFullReductionSecondHalfRuleDto {
+  applicableScope: MarketingFullReductionScopeRuleDto;
+  discountType: MarketingFullReductionSecondHalfDiscountType;
+}
+
+/** 活动指标。 */
+export interface MarketingFullReductionMetricsDto {
+  attachRateIncreasePercent: number;
+  averageTicketIncrease: number;
+  discountTotalAmount: number;
+  drivenSalesAmount: number;
+  giftedCount: number;
+  monthlyDrivenSalesAmount: number;
+  participatingOrderCount: number;
+  ticketIncreaseAmount: number;
+}
+
+/** 列表查询参数。 */
+export interface MarketingFullReductionListQuery {
+  activityType?: '' | MarketingFullReductionActivityType;
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  status?: '' | MarketingFullReductionDisplayStatus;
+  storeId?: string;
+}
+
+/** 详情查询参数。 */
+export interface MarketingFullReductionDetailQuery {
+  activityId: string;
+  storeId: string;
+}
+
+/** 保存请求。 */
+export interface SaveMarketingFullReductionDto {
+  activityType: MarketingFullReductionActivityType;
+  channels: MarketingFullReductionChannel[];
+  description?: string;
+  endDate: string;
+  giftRule?: MarketingFullReductionGiftRuleDto;
+  id?: string;
+  metrics?: MarketingFullReductionMetricsDto;
+  name: string;
+  reduceTiers: MarketingFullReductionTierRuleDto[];
+  scopeStoreId: string;
+  secondHalfRule?: MarketingFullReductionSecondHalfRuleDto;
+  stackWithCoupon: boolean;
+  startDate: string;
+  storeId: string;
+  storeIds?: string[];
+  storeScopeMode: MarketingFullReductionStoreScopeMode;
+}
+
+/** 状态修改请求。 */
+export interface ChangeMarketingFullReductionStatusDto {
+  activityId: string;
+  status: MarketingFullReductionEditorStatus;
+  storeId: string;
+}
+
+/** 删除请求。 */
+export interface DeleteMarketingFullReductionDto {
+  activityId: string;
+  storeId: string;
+}
+
+/** 统计数据。 */
+export interface MarketingFullReductionStatsDto {
+  averageTicketIncrease: number;
+  monthlyDrivenSalesAmount: number;
+  ongoingCount: number;
+  totalCount: number;
+}
+
+/** 列表项。 */
+export interface MarketingFullReductionListItemDto {
+  activityType: MarketingFullReductionActivityType;
+  channels: MarketingFullReductionChannel[];
+  description?: string;
+  displayStatus: MarketingFullReductionDisplayStatus;
+  endDate: string;
+  giftRule?: MarketingFullReductionGiftRuleDto;
+  id: string;
+  isDimmed: boolean;
+  metrics: MarketingFullReductionMetricsDto;
+  name: string;
+  reduceTiers: MarketingFullReductionTierRuleDto[];
+  scopeStoreId: string;
+  secondHalfRule?: MarketingFullReductionSecondHalfRuleDto;
+  stackWithCoupon: boolean;
+  startDate: string;
+  storeIds: string[];
+  storeScopeMode: MarketingFullReductionStoreScopeMode;
+  updatedAt: string;
+}
+
+/** 列表结果。 */
+export interface MarketingFullReductionListResultDto {
+  items: MarketingFullReductionListItemDto[];
+  page: number;
+  pageSize: number;
+  stats: MarketingFullReductionStatsDto;
+  total: number;
+}
+
+/** 详情数据。 */
+export interface MarketingFullReductionDetailDto {
+  activityType: MarketingFullReductionActivityType;
+  channels: MarketingFullReductionChannel[];
+  description?: string;
+  displayStatus: MarketingFullReductionDisplayStatus;
+  endDate: string;
+  giftRule?: MarketingFullReductionGiftRuleDto;
+  id: string;
+  metrics: MarketingFullReductionMetricsDto;
+  name: string;
+  reduceTiers: MarketingFullReductionTierRuleDto[];
+  scopeStoreId: string;
+  secondHalfRule?: MarketingFullReductionSecondHalfRuleDto;
+  stackWithCoupon: boolean;
+  startDate: string;
+  status: MarketingFullReductionEditorStatus;
+  storeIds: string[];
+  storeScopeMode: MarketingFullReductionStoreScopeMode;
+  updatedAt: string;
+}
+
+/** 获取列表。 */
+export async function getMarketingFullReductionListApi(
+  params: MarketingFullReductionListQuery,
+) {
+  return requestClient.get<MarketingFullReductionListResultDto>(
+    '/marketing/full-reduction/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 获取详情。 */
+export async function getMarketingFullReductionDetailApi(
+  params: MarketingFullReductionDetailQuery,
+) {
+  return requestClient.get<MarketingFullReductionDetailDto>(
+    '/marketing/full-reduction/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存活动。 */
+export async function saveMarketingFullReductionApi(
+  data: SaveMarketingFullReductionDto,
+) {
+  return requestClient.post<MarketingFullReductionDetailDto>(
+    '/marketing/full-reduction/save',
+    data,
+  );
+}
+
+/** 修改状态。 */
+export async function changeMarketingFullReductionStatusApi(
+  data: ChangeMarketingFullReductionStatusDto,
+) {
+  return requestClient.post<MarketingFullReductionDetailDto>(
+    '/marketing/full-reduction/status',
+    data,
+  );
+}
+
+/** 删除活动。 */
+export async function deleteMarketingFullReductionApi(
+  data: DeleteMarketingFullReductionDto,
+) {
+  return requestClient.post('/marketing/full-reduction/delete', data);
+}

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

@@ -0,0 +1,191 @@
+/**
+ * 文件职责：营销中心 API 与 DTO 定义。
+ * 1. 维护优惠券列表、详情、保存、状态切换与删除契约。
+ */
+import { requestClient } from '#/api/request';
+
+/** 优惠券类型。 */
+export type MarketingCouponType = 'amount_off' | 'discount' | 'free_delivery';
+
+/** 列表展示状态。 */
+export type MarketingCouponDisplayStatus =
+  | 'disabled'
+  | 'ended'
+  | 'ongoing'
+  | 'upcoming';
+
+/** 编辑状态。 */
+export type MarketingCouponEditorStatus = 'disabled' | 'enabled';
+
+/** 有效期类型。 */
+export type MarketingCouponValidityType = 'days' | 'fixed';
+
+/** 适用渠道。 */
+export type MarketingCouponChannel = 'delivery' | 'dine_in' | 'pickup';
+
+/** 门店范围模式。 */
+export type MarketingCouponStoreScopeMode = 'all' | 'stores';
+
+/** 优惠券列表查询。 */
+export interface MarketingCouponListQuery {
+  couponType?: '' | MarketingCouponType;
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  status?: '' | MarketingCouponDisplayStatus;
+  storeId: string;
+}
+
+/** 优惠券详情查询。 */
+export interface MarketingCouponDetailQuery {
+  couponId: string;
+  storeId: string;
+}
+
+/** 保存优惠券请求。 */
+export interface SaveMarketingCouponDto {
+  channels: MarketingCouponChannel[];
+  couponType: MarketingCouponType;
+  id?: string;
+  minimumSpend: null | number;
+  name: string;
+  perUserLimit: null | number;
+  relativeValidDays: null | number;
+  status: MarketingCouponEditorStatus;
+  storeId: string;
+  storeIds?: string[];
+  storeScopeMode: MarketingCouponStoreScopeMode;
+  totalQuantity: number;
+  validFrom: null | string;
+  validTo: null | string;
+  validityType: MarketingCouponValidityType;
+  value: number;
+}
+
+/** 修改状态请求。 */
+export interface ChangeMarketingCouponStatusDto {
+  couponId: string;
+  status: MarketingCouponEditorStatus;
+  storeId: string;
+}
+
+/** 删除请求。 */
+export interface DeleteMarketingCouponDto {
+  couponId: string;
+  storeId: string;
+}
+
+/** 统计数据。 */
+export interface MarketingCouponStatsDto {
+  claimedCount: number;
+  ongoingCount: number;
+  redeemRate: number;
+  redeemedCount: number;
+  totalCount: number;
+}
+
+/** 列表项。 */
+export interface MarketingCouponListItemDto {
+  channels: MarketingCouponChannel[];
+  claimedQuantity: number;
+  couponType: MarketingCouponType;
+  displayStatus: MarketingCouponDisplayStatus;
+  id: string;
+  isDimmed: boolean;
+  minimumSpend: null | number;
+  name: string;
+  perUserLimit: null | number;
+  redeemedQuantity: number;
+  relativeValidDays: null | number;
+  storeIds: string[];
+  storeScopeMode: MarketingCouponStoreScopeMode;
+  totalQuantity: number;
+  updatedAt: string;
+  validFrom: null | string;
+  validTo: null | string;
+  value: number;
+}
+
+/** 列表结果。 */
+export interface MarketingCouponListResultDto {
+  items: MarketingCouponListItemDto[];
+  page: number;
+  pageSize: number;
+  stats: MarketingCouponStatsDto;
+  total: number;
+}
+
+/** 详情数据。 */
+export interface MarketingCouponDetailDto {
+  channels: MarketingCouponChannel[];
+  claimedQuantity: number;
+  couponType: MarketingCouponType;
+  id: string;
+  minimumSpend: null | number;
+  name: string;
+  perUserLimit: null | number;
+  relativeValidDays: null | number;
+  status: MarketingCouponEditorStatus;
+  storeIds: string[];
+  storeScopeMode: MarketingCouponStoreScopeMode;
+  totalQuantity: number;
+  updatedAt: string;
+  validFrom: null | string;
+  validTo: null | string;
+  validityType: MarketingCouponValidityType;
+  value: number;
+}
+
+/** 获取优惠券列表。 */
+export async function getMarketingCouponListApi(
+  params: MarketingCouponListQuery,
+) {
+  return requestClient.get<MarketingCouponListResultDto>(
+    '/marketing/coupon/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 获取优惠券详情。 */
+export async function getMarketingCouponDetailApi(
+  params: MarketingCouponDetailQuery,
+) {
+  return requestClient.get<MarketingCouponDetailDto>(
+    '/marketing/coupon/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存优惠券。 */
+export async function saveMarketingCouponApi(data: SaveMarketingCouponDto) {
+  return requestClient.post<MarketingCouponDetailDto>(
+    '/marketing/coupon/save',
+    data,
+  );
+}
+
+/** 修改优惠券状态。 */
+export async function changeMarketingCouponStatusApi(
+  data: ChangeMarketingCouponStatusDto,
+) {
+  return requestClient.post<MarketingCouponDetailDto>(
+    '/marketing/coupon/status',
+    data,
+  );
+}
+
+/** 删除优惠券。 */
+export async function deleteMarketingCouponApi(data: DeleteMarketingCouponDto) {
+  return requestClient.post('/marketing/coupon/delete', data);
+}
+
+export * from './calendar';
+export * from './flash-sale';
+export * from './full-reduction';
+export * from './new-customer';
+export * from './punch-card';
+export * from './seckill';

apps/web-antd/src/api/marketing/new-customer.ts

@@ -0,0 +1,213 @@
+/**
+ * 文件职责：营销中心新客有礼 API 与 DTO 定义。
+ * 1. 维护新客有礼详情、配置保存、邀请记录分页与写入契约。
+ */
+import { requestClient } from '#/api/request';
+
+/** 礼包类型。 */
+export type MarketingNewCustomerGiftType = 'coupon' | 'direct';
+
+/** 券场景。 */
+export type MarketingNewCustomerCouponScene = 'invitee' | 'inviter' | 'welcome';
+
+/** 券类型。 */
+export type MarketingNewCustomerCouponType =
+  | 'amount_off'
+  | 'discount'
+  | 'free_shipping';
+
+/** 分享渠道。 */
+export type MarketingNewCustomerShareChannel =
+  | 'moments'
+  | 'sms'
+  | 'wechat_friend';
+
+/** 邀请订单状态。 */
+export type MarketingNewCustomerInviteOrderStatus = 'ordered' | 'pending_order';
+
+/** 邀请奖励状态。 */
+export type MarketingNewCustomerInviteRewardStatus = 'issued' | 'pending';
+
+/** 优惠券规则。 */
+export interface MarketingNewCustomerCouponRuleDto {
+  couponType: MarketingNewCustomerCouponType;
+  id: string;
+  minimumSpend: null | number;
+  scene: MarketingNewCustomerCouponScene;
+  sortOrder: number;
+  validDays: number;
+  value: null | number;
+}
+
+/** 新客有礼设置。 */
+export interface MarketingNewCustomerSettingsDto {
+  directMinimumSpend: null | number;
+  directReduceAmount: null | number;
+  giftEnabled: boolean;
+  giftType: MarketingNewCustomerGiftType;
+  inviteEnabled: boolean;
+  inviteeCoupons: MarketingNewCustomerCouponRuleDto[];
+  inviterCoupons: MarketingNewCustomerCouponRuleDto[];
+  shareChannels: MarketingNewCustomerShareChannel[];
+  storeId: string;
+  updatedAt: string;
+  welcomeCoupons: MarketingNewCustomerCouponRuleDto[];
+}
+
+/** 统计数据。 */
+export interface MarketingNewCustomerStatsDto {
+  firstOrderConversionRate: number;
+  firstOrderedCount: number;
+  giftClaimRate: number;
+  giftClaimedCount: number;
+  monthlyGrowthCount: number;
+  monthlyGrowthRatePercent: number;
+  monthlyNewCustomers: number;
+}
+
+/** 邀请记录。 */
+export interface MarketingNewCustomerInviteRecordDto {
+  id: string;
+  inviteeName: string;
+  inviteTime: string;
+  inviterName: string;
+  orderStatus: MarketingNewCustomerInviteOrderStatus;
+  rewardIssuedAt: null | string;
+  rewardStatus: MarketingNewCustomerInviteRewardStatus;
+  sourceChannel?: string;
+}
+
+/** 邀请记录分页。 */
+export interface MarketingNewCustomerInviteRecordListResultDto {
+  items: MarketingNewCustomerInviteRecordDto[];
+  page: number;
+  pageSize: number;
+  totalCount: number;
+}
+
+/** 新客有礼详情。 */
+export interface MarketingNewCustomerDetailDto {
+  inviteRecords: MarketingNewCustomerInviteRecordListResultDto;
+  settings: MarketingNewCustomerSettingsDto;
+  stats: MarketingNewCustomerStatsDto;
+}
+
+/** 新客有礼详情查询。 */
+export interface MarketingNewCustomerDetailQuery {
+  recordPage?: number;
+  recordPageSize?: number;
+  storeId: string;
+}
+
+/** 邀请记录查询。 */
+export interface MarketingNewCustomerInviteRecordListQuery {
+  page: number;
+  pageSize: number;
+  storeId: string;
+}
+
+/** 保存券规则项。 */
+export interface SaveMarketingNewCustomerCouponRuleDto {
+  couponType: MarketingNewCustomerCouponType;
+  minimumSpend: null | number;
+  validDays: number;
+  value: null | number;
+}
+
+/** 保存新客有礼配置请求。 */
+export interface SaveMarketingNewCustomerSettingsDto {
+  directMinimumSpend: null | number;
+  directReduceAmount: null | number;
+  giftEnabled: boolean;
+  giftType: MarketingNewCustomerGiftType;
+  inviteEnabled: boolean;
+  inviteeCoupons: SaveMarketingNewCustomerCouponRuleDto[];
+  inviterCoupons: SaveMarketingNewCustomerCouponRuleDto[];
+  shareChannels: MarketingNewCustomerShareChannel[];
+  storeId: string;
+  welcomeCoupons: SaveMarketingNewCustomerCouponRuleDto[];
+}
+
+/** 写入邀请记录请求。 */
+export interface WriteMarketingNewCustomerInviteRecordDto {
+  inviteeName: string;
+  inviteTime: string;
+  inviterName: string;
+  orderStatus: MarketingNewCustomerInviteOrderStatus;
+  rewardIssuedAt: null | string;
+  rewardStatus: MarketingNewCustomerInviteRewardStatus;
+  sourceChannel?: string;
+  storeId: string;
+}
+
+/** 新客成长记录。 */
+export interface MarketingNewCustomerGrowthRecordDto {
+  customerKey: string;
+  customerName?: string;
+  firstOrderAt: null | string;
+  giftClaimedAt: null | string;
+  id: string;
+  registeredAt: string;
+  sourceChannel?: string;
+}
+
+/** 写入成长记录请求。 */
+export interface WriteMarketingNewCustomerGrowthRecordDto {
+  customerKey: string;
+  customerName?: string;
+  firstOrderAt: null | string;
+  giftClaimedAt: null | string;
+  registeredAt: string;
+  sourceChannel?: string;
+  storeId: string;
+}
+
+/** 获取新客有礼详情。 */
+export async function getMarketingNewCustomerDetailApi(
+  params: MarketingNewCustomerDetailQuery,
+) {
+  return requestClient.get<MarketingNewCustomerDetailDto>(
+    '/marketing/new-customer/detail',
+    { params },
+  );
+}
+
+/** 保存新客有礼配置。 */
+export async function saveMarketingNewCustomerSettingsApi(
+  data: SaveMarketingNewCustomerSettingsDto,
+) {
+  return requestClient.post<MarketingNewCustomerSettingsDto>(
+    '/marketing/new-customer/save',
+    data,
+  );
+}
+
+/** 获取邀请记录分页。 */
+export async function getMarketingNewCustomerInviteRecordListApi(
+  params: MarketingNewCustomerInviteRecordListQuery,
+) {
+  return requestClient.get<MarketingNewCustomerInviteRecordListResultDto>(
+    '/marketing/new-customer/invite-record/list',
+    { params },
+  );
+}
+
+/** 写入邀请记录。 */
+export async function writeMarketingNewCustomerInviteRecordApi(
+  data: WriteMarketingNewCustomerInviteRecordDto,
+) {
+  return requestClient.post<MarketingNewCustomerInviteRecordDto>(
+    '/marketing/new-customer/invite-record/write',
+    data,
+  );
+}
+
+/** 写入成长记录。 */
+export async function writeMarketingNewCustomerGrowthRecordApi(
+  data: WriteMarketingNewCustomerGrowthRecordDto,
+) {
+  return requestClient.post<MarketingNewCustomerGrowthRecordDto>(
+    '/marketing/new-customer/growth-record/write',
+    data,
+  );
+}

apps/web-antd/src/api/marketing/punch-card.ts

@@ -0,0 +1,334 @@
+/**
+ * 文件职责：营销中心次卡管理 API 与 DTO 定义。
+ * 1. 维护次卡列表、详情、保存、状态、删除、使用记录及导出契约。
+ */
+import { requestClient } from '#/api/request';
+
+/** 次卡状态。 */
+export type MarketingPunchCardStatus = 'disabled' | 'enabled';
+
+/** 有效期类型。 */
+export type MarketingPunchCardValidityType = 'days' | 'range';
+
+/** 适用范围类型。 */
+export type MarketingPunchCardScopeType =
+  | 'all'
+  | 'category'
+  | 'product'
+  | 'tag';
+
+/** 使用模式。 */
+export type MarketingPunchCardUsageMode = 'cap' | 'free';
+
+/** 过期策略。 */
+export type MarketingPunchCardExpireStrategy = 'invalidate' | 'refund';
+
+/** 使用记录展示状态。 */
+export type MarketingPunchCardUsageDisplayStatus =
+  | 'almost_used_up'
+  | 'expired'
+  | 'normal'
+  | 'used_up';
+
+/** 使用记录筛选状态。 */
+export type MarketingPunchCardUsageFilterStatus =
+  | 'expired'
+  | 'normal'
+  | 'used_up';
+
+/** 次卡范围。 */
+export interface MarketingPunchCardScopeDto {
+  categoryIds: string[];
+  productIds: string[];
+  scopeType: MarketingPunchCardScopeType;
+  tagIds: string[];
+}
+
+/** 次卡模板统计。 */
+export interface MarketingPunchCardStatsDto {
+  activeInUseCount: number;
+  onSaleCount: number;
+  totalRevenueAmount: number;
+  totalSoldCount: number;
+}
+
+/** 次卡列表项。 */
+export interface MarketingPunchCardListItemDto {
+  activeCount: number;
+  coverImageUrl?: string;
+  dailyLimit: null | number;
+  id: string;
+  isDimmed: boolean;
+  name: string;
+  originalPrice: null | number;
+  revenueAmount: number;
+  salePrice: number;
+  scopeType: MarketingPunchCardScopeType;
+  soldCount: number;
+  status: MarketingPunchCardStatus;
+  totalTimes: number;
+  updatedAt: string;
+  usageCapAmount: null | number;
+  usageMode: MarketingPunchCardUsageMode;
+  validitySummary: string;
+}
+
+/** 次卡列表结果。 */
+export interface MarketingPunchCardListResultDto {
+  items: MarketingPunchCardListItemDto[];
+  page: number;
+  pageSize: number;
+  stats: MarketingPunchCardStatsDto;
+  totalCount: number;
+}
+
+/** 次卡详情。 */
+export interface MarketingPunchCardDetailDto {
+  activeCount: number;
+  allowTransfer: boolean;
+  coverImageUrl?: string;
+  dailyLimit: null | number;
+  description?: string;
+  expireStrategy: MarketingPunchCardExpireStrategy;
+  id: string;
+  name: string;
+  notifyChannels: string[];
+  originalPrice: null | number;
+  perOrderLimit: null | number;
+  perUserPurchaseLimit: null | number;
+  revenueAmount: number;
+  salePrice: number;
+  scope: MarketingPunchCardScopeDto;
+  soldCount: number;
+  status: MarketingPunchCardStatus;
+  storeId: string;
+  totalTimes: number;
+  updatedAt: string;
+  usageCapAmount: null | number;
+  usageMode: MarketingPunchCardUsageMode;
+  validityDays: null | number;
+  validityType: MarketingPunchCardValidityType;
+  validFrom: null | string;
+  validTo: null | string;
+}
+
+/** 保存次卡请求。 */
+export interface SaveMarketingPunchCardDto {
+  allowTransfer: boolean;
+  coverImageUrl?: string;
+  dailyLimit: null | number;
+  description?: string;
+  expireStrategy: MarketingPunchCardExpireStrategy;
+  id?: string;
+  name: string;
+  notifyChannels: string[];
+  originalPrice: null | number;
+  perOrderLimit: null | number;
+  perUserPurchaseLimit: null | number;
+  salePrice: number;
+  scopeCategoryIds: string[];
+  scopeProductIds: string[];
+  scopeTagIds: string[];
+  scopeType: MarketingPunchCardScopeType;
+  storeId: string;
+  totalTimes: number;
+  usageCapAmount: null | number;
+  usageMode: MarketingPunchCardUsageMode;
+  validityDays: null | number;
+  validityType: MarketingPunchCardValidityType;
+  validFrom: null | string;
+  validTo: null | string;
+}
+
+/** 修改状态请求。 */
+export interface ChangeMarketingPunchCardStatusDto {
+  punchCardId: string;
+  status: MarketingPunchCardStatus;
+  storeId: string;
+}
+
+/** 删除次卡请求。 */
+export interface DeleteMarketingPunchCardDto {
+  punchCardId: string;
+  storeId: string;
+}
+
+/** 次卡列表查询。 */
+export interface MarketingPunchCardListQuery {
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  status?: '' | MarketingPunchCardStatus;
+  storeId: string;
+}
+
+/** 次卡详情查询。 */
+export interface MarketingPunchCardDetailQuery {
+  punchCardId: string;
+  storeId: string;
+}
+
+/** 使用记录统计。 */
+export interface MarketingPunchCardUsageStatsDto {
+  expiringSoonCount: number;
+  monthUsedCount: number;
+  todayUsedCount: number;
+}
+
+/** 次卡选项。 */
+export interface MarketingPunchCardTemplateOptionDto {
+  name: string;
+  templateId: string;
+}
+
+/** 使用记录项。 */
+export interface MarketingPunchCardUsageRecordDto {
+  displayStatus: MarketingPunchCardUsageDisplayStatus;
+  extraPayAmount: null | number;
+  id: string;
+  memberName: string;
+  memberPhoneMasked: string;
+  productName: string;
+  punchCardId: string;
+  punchCardInstanceId: string;
+  punchCardName: string;
+  recordNo: string;
+  remainingTimesAfterUse: number;
+  totalTimes: number;
+  usedAt: string;
+  usedTimes: number;
+}
+
+/** 使用记录列表结果。 */
+export interface MarketingPunchCardUsageRecordListResultDto {
+  items: MarketingPunchCardUsageRecordDto[];
+  page: number;
+  pageSize: number;
+  stats: MarketingPunchCardUsageStatsDto;
+  templateOptions: MarketingPunchCardTemplateOptionDto[];
+  totalCount: number;
+}
+
+/** 使用记录查询参数。 */
+export interface MarketingPunchCardUsageRecordListQuery {
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  punchCardId?: string;
+  status?: '' | MarketingPunchCardUsageFilterStatus;
+  storeId: string;
+}
+
+/** 使用记录导出参数。 */
+export interface ExportMarketingPunchCardUsageRecordQuery {
+  keyword?: string;
+  punchCardId?: string;
+  status?: '' | MarketingPunchCardUsageFilterStatus;
+  storeId: string;
+}
+
+/** 使用记录导出回执。 */
+export interface MarketingPunchCardUsageRecordExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 写入使用记录请求。 */
+export interface WriteMarketingPunchCardUsageRecordDto {
+  extraPayAmount: null | number;
+  memberName?: string;
+  memberPhoneMasked?: string;
+  productName: string;
+  punchCardId: string;
+  punchCardInstanceId?: string;
+  punchCardInstanceNo?: string;
+  storeId: string;
+  usedAt?: string;
+  usedTimes: number;
+}
+
+/** 查询次卡列表。 */
+export async function getMarketingPunchCardListApi(
+  params: MarketingPunchCardListQuery,
+) {
+  return requestClient.get<MarketingPunchCardListResultDto>(
+    '/marketing/punch-card/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询次卡详情。 */
+export async function getMarketingPunchCardDetailApi(
+  params: MarketingPunchCardDetailQuery,
+) {
+  return requestClient.get<MarketingPunchCardDetailDto>(
+    '/marketing/punch-card/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存次卡。 */
+export async function saveMarketingPunchCardApi(
+  data: SaveMarketingPunchCardDto,
+) {
+  return requestClient.post<MarketingPunchCardDetailDto>(
+    '/marketing/punch-card/save',
+    data,
+  );
+}
+
+/** 修改次卡状态。 */
+export async function changeMarketingPunchCardStatusApi(
+  data: ChangeMarketingPunchCardStatusDto,
+) {
+  return requestClient.post<MarketingPunchCardDetailDto>(
+    '/marketing/punch-card/status',
+    data,
+  );
+}
+
+/** 删除次卡。 */
+export async function deleteMarketingPunchCardApi(
+  data: DeleteMarketingPunchCardDto,
+) {
+  return requestClient.post('/marketing/punch-card/delete', data);
+}
+
+/** 查询使用记录。 */
+export async function getMarketingPunchCardUsageRecordListApi(
+  params: MarketingPunchCardUsageRecordListQuery,
+) {
+  return requestClient.get<MarketingPunchCardUsageRecordListResultDto>(
+    '/marketing/punch-card/usage-record/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 导出使用记录。 */
+export async function exportMarketingPunchCardUsageRecordApi(
+  params: ExportMarketingPunchCardUsageRecordQuery,
+) {
+  return requestClient.get<MarketingPunchCardUsageRecordExportDto>(
+    '/marketing/punch-card/usage-record/export',
+    {
+      params,
+    },
+  );
+}
+
+/** 写入使用记录。 */
+export async function writeMarketingPunchCardUsageRecordApi(
+  data: WriteMarketingPunchCardUsageRecordDto,
+) {
+  return requestClient.post<MarketingPunchCardUsageRecordDto>(
+    '/marketing/punch-card/usage-record/write',
+    data,
+  );
+}

apps/web-antd/src/api/marketing/seckill.ts

@@ -0,0 +1,271 @@
+/**
+ * 文件职责：营销中心秒杀活动 API 与 DTO 定义。
+ * 1. 维护秒杀活动列表、详情、保存、状态切换、删除与选品契约。
+ */
+import { requestClient } from '#/api/request';
+
+/** 活动展示状态。 */
+export type MarketingSeckillDisplayStatus = 'ended' | 'ongoing' | 'upcoming';
+
+/** 活动编辑状态。 */
+export type MarketingSeckillEditorStatus = 'active' | 'completed';
+
+/** 秒杀活动类型。 */
+export type MarketingSeckillActivityType = 'hourly' | 'timed';
+
+/** 适用渠道。 */
+export type MarketingSeckillChannel = 'delivery' | 'dine_in' | 'pickup';
+
+/** 商品状态。 */
+export type MarketingSeckillProductStatus =
+  | 'off_shelf'
+  | 'on_sale'
+  | 'sold_out';
+
+/** 场次。 */
+export interface MarketingSeckillSessionDto {
+  durationMinutes: number;
+  startTime: string;
+}
+
+/** 秒杀商品。 */
+export interface MarketingSeckillProductDto {
+  categoryId: string;
+  categoryName: string;
+  name: string;
+  originalPrice: number;
+  perUserLimit: null | number;
+  productId: string;
+  seckillPrice: number;
+  soldCount: number;
+  spuCode: string;
+  status: MarketingSeckillProductStatus;
+  stockLimit: number;
+}
+
+/** 活动指标。 */
+export interface MarketingSeckillMetricsDto {
+  conversionRate: number;
+  dealCount: number;
+  monthlySeckillSalesCount: number;
+  participantCount: number;
+}
+
+/** 列表查询参数。 */
+export interface MarketingSeckillListQuery {
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  status?: '' | MarketingSeckillDisplayStatus;
+  storeId?: string;
+}
+
+/** 详情查询参数。 */
+export interface MarketingSeckillDetailQuery {
+  activityId: string;
+  storeId: string;
+}
+
+/** 保存请求。 */
+export interface SaveMarketingSeckillDto {
+  activityType: MarketingSeckillActivityType;
+  channels: MarketingSeckillChannel[];
+  endDate?: string;
+  id?: string;
+  metrics?: MarketingSeckillMetricsDto;
+  name: string;
+  perUserLimit: null | number;
+  preheatEnabled: boolean;
+  preheatHours: null | number;
+  products: Array<{
+    perUserLimit: null | number;
+    productId: string;
+    seckillPrice: number;
+    stockLimit: number;
+  }>;
+  sessions: MarketingSeckillSessionDto[];
+  startDate?: string;
+  storeId: string;
+  timeEnd?: string;
+  timeStart?: string;
+}
+
+/** 状态修改请求。 */
+export interface ChangeMarketingSeckillStatusDto {
+  activityId: string;
+  status: MarketingSeckillEditorStatus;
+  storeId: string;
+}
+
+/** 删除请求。 */
+export interface DeleteMarketingSeckillDto {
+  activityId: string;
+  storeId: string;
+}
+
+/** 列表统计。 */
+export interface MarketingSeckillStatsDto {
+  conversionRate: number;
+  monthlySeckillSalesCount: number;
+  ongoingCount: number;
+  totalCount: number;
+}
+
+/** 列表项。 */
+export interface MarketingSeckillListItemDto {
+  activityType: MarketingSeckillActivityType;
+  channels: MarketingSeckillChannel[];
+  displayStatus: MarketingSeckillDisplayStatus;
+  endDate?: string;
+  id: string;
+  isDimmed: boolean;
+  metrics: MarketingSeckillMetricsDto;
+  name: string;
+  perUserLimit: null | number;
+  preheatEnabled: boolean;
+  preheatHours: null | number;
+  products: MarketingSeckillProductDto[];
+  sessions: MarketingSeckillSessionDto[];
+  startDate?: string;
+  status: MarketingSeckillEditorStatus;
+  storeIds: string[];
+  timeEnd?: string;
+  timeStart?: string;
+  updatedAt: string;
+}
+
+/** 列表结果。 */
+export interface MarketingSeckillListResultDto {
+  items: MarketingSeckillListItemDto[];
+  page: number;
+  pageSize: number;
+  stats: MarketingSeckillStatsDto;
+  total: number;
+}
+
+/** 详情数据。 */
+export interface MarketingSeckillDetailDto {
+  activityType: MarketingSeckillActivityType;
+  channels: MarketingSeckillChannel[];
+  displayStatus: MarketingSeckillDisplayStatus;
+  endDate?: string;
+  id: string;
+  metrics: MarketingSeckillMetricsDto;
+  name: string;
+  perUserLimit: null | number;
+  preheatEnabled: boolean;
+  preheatHours: null | number;
+  products: MarketingSeckillProductDto[];
+  sessions: MarketingSeckillSessionDto[];
+  startDate?: string;
+  status: MarketingSeckillEditorStatus;
+  storeIds: string[];
+  timeEnd?: string;
+  timeStart?: string;
+  updatedAt: string;
+}
+
+/** 选品分类查询参数。 */
+export interface MarketingSeckillPickerCategoryQuery {
+  storeId: string;
+}
+
+/** 选品分类项。 */
+export interface MarketingSeckillPickerCategoryItemDto {
+  id: string;
+  name: string;
+  productCount: number;
+}
+
+/** 选品商品查询参数。 */
+export interface MarketingSeckillPickerProductQuery {
+  categoryId?: string;
+  keyword?: string;
+  limit?: number;
+  storeId: string;
+}
+
+/** 选品商品项。 */
+export interface MarketingSeckillPickerProductItemDto {
+  categoryId: string;
+  categoryName: string;
+  id: string;
+  name: string;
+  price: number;
+  spuCode: string;
+  status: MarketingSeckillProductStatus;
+  stock: number;
+}
+
+/** 获取列表。 */
+export async function getMarketingSeckillListApi(
+  params: MarketingSeckillListQuery,
+) {
+  return requestClient.get<MarketingSeckillListResultDto>(
+    '/marketing/seckill/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 获取详情。 */
+export async function getMarketingSeckillDetailApi(
+  params: MarketingSeckillDetailQuery,
+) {
+  return requestClient.get<MarketingSeckillDetailDto>(
+    '/marketing/seckill/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存活动。 */
+export async function saveMarketingSeckillApi(data: SaveMarketingSeckillDto) {
+  return requestClient.post<MarketingSeckillDetailDto>(
+    '/marketing/seckill/save',
+    data,
+  );
+}
+
+/** 修改状态。 */
+export async function changeMarketingSeckillStatusApi(
+  data: ChangeMarketingSeckillStatusDto,
+) {
+  return requestClient.post<MarketingSeckillDetailDto>(
+    '/marketing/seckill/status',
+    data,
+  );
+}
+
+/** 删除活动。 */
+export async function deleteMarketingSeckillApi(
+  data: DeleteMarketingSeckillDto,
+) {
+  return requestClient.post('/marketing/seckill/delete', data);
+}
+
+/** 获取选品分类。 */
+export async function getMarketingSeckillPickerCategoriesApi(
+  params: MarketingSeckillPickerCategoryQuery,
+) {
+  return requestClient.get<MarketingSeckillPickerCategoryItemDto[]>(
+    '/marketing/seckill/picker/categories',
+    {
+      params,
+    },
+  );
+}
+
+/** 获取选品商品。 */
+export async function getMarketingSeckillPickerProductsApi(
+  params: MarketingSeckillPickerProductQuery,
+) {
+  return requestClient.get<MarketingSeckillPickerProductItemDto[]>(
+    '/marketing/seckill/picker/products',
+    {
+      params,
+    },
+  );
+}

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

@@ -0,0 +1,287 @@
+/**
+ * 文件职责：会员中心会员管理 API 契约定义。
+ */
+import { requestClient } from '#/api/request';
+
+/** 会员列表筛选参数。 */
+export interface MemberListFilterQuery {
+  keyword?: string;
+  storeId: string;
+  tierId?: string;
+}
+
+/** 会员列表分页参数。 */
+export interface MemberListQuery extends MemberListFilterQuery {
+  page: number;
+  pageSize: number;
+}
+
+/** 会员列表行。 */
+export interface MemberListItemDto {
+  avatarColor: string;
+  avatarText: string;
+  isDormant: boolean;
+  lastOrderAt: string;
+  memberId: string;
+  mobileMasked: string;
+  name: string;
+  orderCount: number;
+  pointsBalance: number;
+  storedBalance: number;
+  tierColorHex: string;
+  tierId?: string;
+  tierName: string;
+  totalAmount: number;
+}
+
+/** 会员列表结果。 */
+export interface MemberListResultDto {
+  items: MemberListItemDto[];
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+/** 会员列表统计。 */
+export interface MemberListStatsDto {
+  activeMembers: number;
+  dormantMembers: number;
+  monthlyNewMembers: number;
+  totalMembers: number;
+}
+
+/** 最近订单。 */
+export interface MemberRecentOrderDto {
+  amount: number;
+  orderNo: string;
+  orderedAt: string;
+  statusText: string;
+}
+
+/** 会员详情。 */
+export interface MemberDetailDto {
+  avatarColor: string;
+  avatarText: string;
+  averageAmount: number;
+  joinedAt: string;
+  memberId: string;
+  mobileMasked: string;
+  name: string;
+  orderCount: number;
+  pointsBalance: number;
+  recentOrders: MemberRecentOrderDto[];
+  storedBalance: number;
+  storedGiftBalance: number;
+  storedRechargeBalance: number;
+  tags: string[];
+  tierColorHex: string;
+  tierId?: string;
+  tierName: string;
+  totalAmount: number;
+}
+
+/** 会员导出回执。 */
+export interface MemberExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 会员等级列表项。 */
+export interface MemberTierListItemDto {
+  canDelete: boolean;
+  colorHex: string;
+  conditionText: string;
+  iconKey: string;
+  isDefault: boolean;
+  memberCount: number;
+  name: string;
+  perks: string[];
+  sortOrder: number;
+  tierId: string;
+}
+
+/** 升降级规则。 */
+export interface MemberTierRuleDto {
+  downgradeWindowDays: number;
+  upgradeAmountThreshold?: number;
+  upgradeOrderCountThreshold?: number;
+  upgradeRuleType: 'amount' | 'both' | 'count' | 'none';
+}
+
+/** 折扣权益。 */
+export interface MemberTierDiscountBenefitDto {
+  discountRate?: number;
+  enabled: boolean;
+}
+
+/** 积分倍率权益。 */
+export interface MemberTierPointMultiplierBenefitDto {
+  enabled: boolean;
+  multiplier?: number;
+}
+
+/** 生日特权。 */
+export interface MemberTierBirthdayBenefitDto {
+  couponTemplateIds: string[];
+  doublePointsEnabled: boolean;
+  enabled: boolean;
+}
+
+/** 每月赠券。 */
+export interface MemberTierMonthlyCouponBenefitDto {
+  couponTemplateIds: string[];
+  enabled: boolean;
+  grantDay: number;
+}
+
+/** 免配送费权益。 */
+export interface MemberTierFreeDeliveryBenefitDto {
+  enabled: boolean;
+  monthlyFreeTimes: number;
+}
+
+/** 等级权益。 */
+export interface MemberTierBenefitsDto {
+  birthday: MemberTierBirthdayBenefitDto;
+  discount: MemberTierDiscountBenefitDto;
+  exclusiveServiceEnabled: boolean;
+  freeDelivery: MemberTierFreeDeliveryBenefitDto;
+  monthlyCoupon: MemberTierMonthlyCouponBenefitDto;
+  pointMultiplier: MemberTierPointMultiplierBenefitDto;
+  priorityDeliveryEnabled: boolean;
+}
+
+/** 等级详情。 */
+export interface MemberTierDetailDto {
+  benefits: MemberTierBenefitsDto;
+  canDelete: boolean;
+  colorHex: string;
+  iconKey: string;
+  isDefault: boolean;
+  name: string;
+  rule: MemberTierRuleDto;
+  sortOrder: number;
+  tierId?: string;
+}
+
+/** 保存等级请求。 */
+export interface SaveMemberTierPayload {
+  benefits: MemberTierBenefitsDto;
+  colorHex: string;
+  iconKey: string;
+  isDefault: boolean;
+  name: string;
+  rule: MemberTierRuleDto;
+  sortOrder: number;
+  tierId?: string;
+}
+
+/** 会员日配置。 */
+export interface MemberDaySettingDto {
+  extraDiscountRate: number;
+  isEnabled: boolean;
+  weekday: number;
+}
+
+/** 优惠券选择项。 */
+export interface MemberCouponPickerItemDto {
+  couponTemplateId: string;
+  couponType: string;
+  displayText: string;
+  minimumSpend?: number;
+  name: string;
+  value: number;
+}
+
+/** 查询会员列表。 */
+export async function getMemberListApi(params: MemberListQuery) {
+  return requestClient.get<MemberListResultDto>('/member/list/list', {
+    params,
+  });
+}
+
+/** 查询会员列表统计。 */
+export async function getMemberListStatsApi(params: MemberListFilterQuery) {
+  return requestClient.get<MemberListStatsDto>('/member/list/stats', {
+    params,
+  });
+}
+
+/** 查询会员详情。 */
+export async function getMemberDetailApi(params: {
+  memberId: string;
+  storeId: string;
+}) {
+  return requestClient.get<MemberDetailDto>('/member/list/detail', {
+    params,
+  });
+}
+
+/** 保存会员标签。 */
+export async function saveMemberTagsApi(payload: {
+  memberId: string;
+  storeId?: string;
+  tags: string[];
+}) {
+  return requestClient.post('/member/list/tags', payload);
+}
+
+/** 导出会员 CSV。 */
+export async function exportMemberCsvApi(params: MemberListFilterQuery) {
+  return requestClient.get<MemberExportDto>('/member/list/export', {
+    params,
+  });
+}
+
+/** 查询会员等级列表。 */
+export async function getMemberTierListApi() {
+  return requestClient.get<MemberTierListItemDto[]>('/member/tier/list');
+}
+
+/** 查询会员等级详情。 */
+export async function getMemberTierDetailApi(params: { tierId?: string }) {
+  return requestClient.get<MemberTierDetailDto>('/member/tier/detail', {
+    params,
+  });
+}
+
+/** 保存会员等级。 */
+export async function saveMemberTierApi(payload: SaveMemberTierPayload) {
+  return requestClient.post<MemberTierDetailDto>('/member/tier/save', payload);
+}
+
+/** 删除会员等级。 */
+export async function deleteMemberTierApi(payload: { tierId: string }) {
+  return requestClient.post('/member/tier/delete', payload);
+}
+
+/** 查询会员日配置。 */
+export async function getMemberDaySettingApi() {
+  return requestClient.get<MemberDaySettingDto>('/member/tier/day-setting');
+}
+
+/** 保存会员日配置。 */
+export async function saveMemberDaySettingApi(payload: MemberDaySettingDto) {
+  return requestClient.post<MemberDaySettingDto>(
+    '/member/tier/day-setting',
+    payload,
+  );
+}
+
+/** 查询优惠券选择器列表。 */
+export async function getMemberCouponPickerApi(params: {
+  keyword?: string;
+  storeId?: string;
+}) {
+  return requestClient.get<MemberCouponPickerItemDto[]>(
+    '/member/tier/coupon-picker',
+    {
+      params,
+    },
+  );
+}
+
+export * from './message-reach';
+export * from './points-mall';
+export * from './stored-card';

apps/web-antd/src/api/member/message-reach.ts

@@ -0,0 +1,283 @@
+/**
+ * 文件职责：会员消息触达模块 API 契约定义。
+ */
+import { requestClient } from '#/api/request';
+
+/** 消息状态。 */
+export type MemberMessageReachStatus =
+  | 'draft'
+  | 'failed'
+  | 'pending'
+  | 'sending'
+  | 'sent';
+
+/** 消息渠道。 */
+export type MemberMessageReachChannel = 'inapp' | 'sms' | 'wechat-mini';
+
+/** 目标人群类型。 */
+export type MemberMessageAudienceType = 'all' | 'tag';
+
+/** 发送时间类型。 */
+export type MemberMessageScheduleType = 'immediate' | 'scheduled';
+
+/** 模板分类。 */
+export type MemberMessageTemplateCategory = 'marketing' | 'notice' | 'recall';
+
+/** 页面统计。 */
+export interface MemberMessageReachStatsDto {
+  conversionRate: number;
+  monthlySentCount: number;
+  openRate: number;
+  reachMemberCount: number;
+}
+
+/** 消息列表查询。 */
+export interface MemberMessageReachListQuery {
+  channel?: MemberMessageReachChannel;
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  status?: MemberMessageReachStatus;
+}
+
+/** 消息列表项。 */
+export interface MemberMessageReachListItemDto {
+  audienceText: string;
+  channels: MemberMessageReachChannel[];
+  conversionRate: number;
+  estimatedReachCount: number;
+  messageId: string;
+  openRate: number;
+  scheduledAt?: string;
+  sentAt?: string;
+  status: MemberMessageReachStatus;
+  title: string;
+}
+
+/** 消息列表结果。 */
+export interface MemberMessageReachListResultDto {
+  items: MemberMessageReachListItemDto[];
+  page: number;
+  pageSize: number;
+  totalCount: number;
+}
+
+/** 收件明细。 */
+export interface MemberMessageReachRecipientDto {
+  channel: MemberMessageReachChannel;
+  convertedAt?: string;
+  errorMessage?: string;
+  memberId: string;
+  mobile?: string;
+  openId?: string;
+  readAt?: string;
+  sentAt?: string;
+  status: 'failed' | 'pending' | 'sent';
+}
+
+/** 消息详情。 */
+export interface MemberMessageReachDetailDto {
+  audienceTags: string[];
+  audienceText: string;
+  audienceType: MemberMessageAudienceType;
+  channels: MemberMessageReachChannel[];
+  content: string;
+  conversionRate: number;
+  convertedCount: number;
+  estimatedReachCount: number;
+  lastError?: string;
+  messageId: string;
+  openRate: number;
+  readCount: number;
+  recipients: MemberMessageReachRecipientDto[];
+  scheduleType: MemberMessageScheduleType;
+  scheduledAt?: string;
+  sentAt?: string;
+  sentCount: number;
+  status: MemberMessageReachStatus;
+  templateId?: string;
+  title: string;
+}
+
+/** 保存消息请求。 */
+export interface SaveMemberMessageReachPayload {
+  audienceTags: string[];
+  audienceType: MemberMessageAudienceType;
+  channels: MemberMessageReachChannel[];
+  content: string;
+  messageId?: string;
+  scheduleType: MemberMessageScheduleType;
+  scheduledAt?: string;
+  storeId?: string;
+  submitAction: 'draft' | 'send';
+  templateId?: string;
+  title: string;
+}
+
+/** 删除消息请求。 */
+export interface DeleteMemberMessageReachPayload {
+  messageId: string;
+}
+
+/** 调度元信息。 */
+export interface MemberMessageDispatchMetaDto {
+  hangfireJobId?: string;
+  messageId: string;
+  scheduleType: MemberMessageScheduleType;
+  scheduledAt?: string;
+  status: MemberMessageReachStatus;
+}
+
+/** 目标估算请求。 */
+export interface EstimateMemberMessageAudiencePayload {
+  audienceType: MemberMessageAudienceType;
+  tags: string[];
+}
+
+/** 目标估算响应。 */
+export interface MemberMessageAudienceEstimateDto {
+  reachCount: number;
+}
+
+/** 模板列表查询。 */
+export interface MemberMessageTemplateListQuery {
+  category?: MemberMessageTemplateCategory;
+  keyword?: string;
+  page: number;
+  pageSize: number;
+}
+
+/** 模板 DTO。 */
+export interface MemberMessageTemplateDto {
+  category: MemberMessageTemplateCategory;
+  content: string;
+  lastUsedAt?: string;
+  name: string;
+  templateId: string;
+  usageCount: number;
+}
+
+/** 模板列表结果。 */
+export interface MemberMessageTemplateListResultDto {
+  items: MemberMessageTemplateDto[];
+  page: number;
+  pageSize: number;
+  totalCount: number;
+}
+
+/** 保存模板请求。 */
+export interface SaveMemberMessageTemplatePayload {
+  category: MemberMessageTemplateCategory;
+  content: string;
+  name: string;
+  templateId?: string;
+}
+
+/** 删除模板请求。 */
+export interface DeleteMemberMessageTemplatePayload {
+  templateId: string;
+}
+
+/** 查询页面统计。 */
+export async function getMemberMessageReachStatsApi(params?: {
+  storeId?: string;
+}) {
+  return requestClient.get<MemberMessageReachStatsDto>(
+    '/member/message-reach/stats',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询消息列表。 */
+export async function getMemberMessageReachListApi(
+  params: MemberMessageReachListQuery,
+) {
+  return requestClient.get<MemberMessageReachListResultDto>(
+    '/member/message-reach/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询消息详情。 */
+export async function getMemberMessageReachDetailApi(params: {
+  messageId: string;
+}) {
+  return requestClient.get<MemberMessageReachDetailDto>(
+    '/member/message-reach/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存消息。 */
+export async function saveMemberMessageReachApi(
+  payload: SaveMemberMessageReachPayload,
+) {
+  return requestClient.post<MemberMessageDispatchMetaDto>(
+    '/member/message-reach/save',
+    payload,
+  );
+}
+
+/** 删除消息。 */
+export async function deleteMemberMessageReachApi(
+  payload: DeleteMemberMessageReachPayload,
+) {
+  return requestClient.post('/member/message-reach/delete', payload);
+}
+
+/** 估算触达人数。 */
+export async function estimateMemberMessageAudienceApi(
+  payload: EstimateMemberMessageAudiencePayload,
+) {
+  return requestClient.post<MemberMessageAudienceEstimateDto>(
+    '/member/message-reach/audience/estimate',
+    payload,
+  );
+}
+
+/** 查询模板列表。 */
+export async function getMemberMessageTemplateListApi(
+  params: MemberMessageTemplateListQuery,
+) {
+  return requestClient.get<MemberMessageTemplateListResultDto>(
+    '/member/message-reach/template/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询模板详情。 */
+export async function getMemberMessageTemplateDetailApi(params: {
+  templateId: string;
+}) {
+  return requestClient.get<MemberMessageTemplateDto>(
+    '/member/message-reach/template/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存模板。 */
+export async function saveMemberMessageTemplateApi(
+  payload: SaveMemberMessageTemplatePayload,
+) {
+  return requestClient.post<MemberMessageTemplateDto>(
+    '/member/message-reach/template/save',
+    payload,
+  );
+}
+
+/** 删除模板。 */
+export async function deleteMemberMessageTemplateApi(
+  payload: DeleteMemberMessageTemplatePayload,
+) {
+  return requestClient.post('/member/message-reach/template/delete', payload);
+}

apps/web-antd/src/api/member/points-mall.ts

@@ -0,0 +1,372 @@
+/**
+ * 文件职责：会员中心积分商城 API 契约定义。
+ */
+import { requestClient } from '#/api/request';
+
+/** 兑换类型。 */
+export type MemberPointMallRedeemType = 'coupon' | 'physical' | 'product';
+
+/** 兑换方式。 */
+export type MemberPointMallExchangeType = 'mixed' | 'points';
+
+/** 商品状态。 */
+export type MemberPointMallProductStatus = 'disabled' | 'enabled';
+
+/** 积分有效期模式。 */
+export type MemberPointMallExpiryMode = 'permanent' | 'yearly_clear';
+
+/** 通知渠道。 */
+export type MemberPointMallNotifyChannel = 'in_app' | 'sms';
+
+/** 实物领取方式。 */
+export type MemberPointMallPickupMethod = 'delivery' | 'store_pickup';
+
+/** 兑换记录状态。 */
+export type MemberPointMallRecordStatus =
+  | 'canceled'
+  | 'completed'
+  | 'issued'
+  | 'pending_pickup';
+
+/** 核销方式。 */
+export type MemberPointMallVerifyMethod = 'manual' | 'scan';
+
+/** 规则详情查询。 */
+export interface MemberPointMallRuleDetailQuery {
+  storeId: string;
+}
+
+/** 规则模型。 */
+export interface MemberPointMallRuleDto {
+  consumeAmountPerStep: number;
+  consumeRewardPointsPerStep: number;
+  expiryMode: MemberPointMallExpiryMode;
+  isConsumeRewardEnabled: boolean;
+  isRegisterRewardEnabled: boolean;
+  isReviewRewardEnabled: boolean;
+  isSigninRewardEnabled: boolean;
+  registerRewardPoints: number;
+  reviewRewardPoints: number;
+  signinRewardPoints: number;
+  storeId: string;
+}
+
+/** 规则统计。 */
+export interface MemberPointMallRuleStatsDto {
+  pointMembers: number;
+  redeemRate: number;
+  redeemedPoints: number;
+  totalIssuedPoints: number;
+}
+
+/** 规则详情结果。 */
+export interface MemberPointMallRuleDetailResultDto {
+  rule: MemberPointMallRuleDto;
+  stats: MemberPointMallRuleStatsDto;
+}
+
+/** 保存规则。 */
+export type SaveMemberPointMallRulePayload = MemberPointMallRuleDto;
+
+/** 商品列表查询。 */
+export interface MemberPointMallProductListQuery {
+  keyword?: string;
+  status?: MemberPointMallProductStatus;
+  storeId: string;
+}
+
+/** 商品详情查询。 */
+export interface MemberPointMallProductDetailQuery {
+  pointMallProductId: string;
+  storeId: string;
+}
+
+/** 商品模型。 */
+export interface MemberPointMallProductDto {
+  cashAmount: number;
+  couponTemplateId?: string;
+  description?: string;
+  exchangeType: MemberPointMallExchangeType;
+  imageUrl?: string;
+  name: string;
+  notifyChannels: MemberPointMallNotifyChannel[];
+  perMemberLimit?: number;
+  physicalName?: string;
+  pickupMethod?: MemberPointMallPickupMethod;
+  pointMallProductId: string;
+  productId?: string;
+  redeemType: MemberPointMallRedeemType;
+  redeemTypeText: string;
+  redeemedCount: number;
+  requiredPoints: number;
+  status: MemberPointMallProductStatus;
+  statusText: string;
+  stockAvailable: number;
+  stockTotal: number;
+  storeId: string;
+  updatedAt: string;
+}
+
+/** 商品列表结果。 */
+export interface MemberPointMallProductListResultDto {
+  items: MemberPointMallProductDto[];
+}
+
+/** 保存商品。 */
+export interface SaveMemberPointMallProductPayload {
+  cashAmount: number;
+  couponTemplateId?: string;
+  description?: string;
+  exchangeType: MemberPointMallExchangeType;
+  imageUrl?: string;
+  name: string;
+  notifyChannels: MemberPointMallNotifyChannel[];
+  perMemberLimit?: number;
+  physicalName?: string;
+  pickupMethod?: MemberPointMallPickupMethod;
+  pointMallProductId?: string;
+  productId?: string;
+  redeemType: MemberPointMallRedeemType;
+  requiredPoints: number;
+  status: MemberPointMallProductStatus;
+  stockTotal: number;
+  storeId: string;
+}
+
+/** 修改商品状态。 */
+export interface ChangeMemberPointMallProductStatusPayload {
+  pointMallProductId: string;
+  status: MemberPointMallProductStatus;
+  storeId: string;
+}
+
+/** 删除商品。 */
+export interface DeleteMemberPointMallProductPayload {
+  pointMallProductId: string;
+  storeId: string;
+}
+
+/** 记录列表查询。 */
+export interface MemberPointMallRecordListQuery {
+  endDate?: string;
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  redeemType?: MemberPointMallRedeemType;
+  startDate?: string;
+  status?: MemberPointMallRecordStatus;
+  storeId: string;
+}
+
+/** 记录详情查询。 */
+export interface MemberPointMallRecordDetailQuery {
+  recordId: string;
+  storeId: string;
+}
+
+/** 记录模型。 */
+export interface MemberPointMallRecordDto {
+  cashAmount: number;
+  exchangeType: MemberPointMallExchangeType;
+  issuedAt?: string;
+  memberId: string;
+  memberMobileMasked: string;
+  memberName: string;
+  pointMallProductId: string;
+  productName: string;
+  recordId: string;
+  recordNo: string;
+  redeemedAt: string;
+  redeemType: MemberPointMallRedeemType;
+  redeemTypeText: string;
+  status: MemberPointMallRecordStatus;
+  statusText: string;
+  usedPoints: number;
+  verifiedAt?: string;
+}
+
+/** 记录详情。 */
+export interface MemberPointMallRecordDetailDto extends MemberPointMallRecordDto {
+  verifyMethod?: MemberPointMallVerifyMethod;
+  verifyMethodText?: string;
+  verifyRemark?: string;
+  verifiedBy?: string;
+}
+
+/** 记录统计。 */
+export interface MemberPointMallRecordStatsDto {
+  currentMonthUsedPoints: number;
+  pendingPhysicalCount: number;
+  todayRedeemCount: number;
+}
+
+/** 记录分页结果。 */
+export interface MemberPointMallRecordListResultDto {
+  items: MemberPointMallRecordDto[];
+  page: number;
+  pageSize: number;
+  stats: MemberPointMallRecordStatsDto;
+  totalCount: number;
+}
+
+/** 导出记录查询。 */
+export interface ExportMemberPointMallRecordQuery {
+  endDate?: string;
+  keyword?: string;
+  redeemType?: MemberPointMallRedeemType;
+  startDate?: string;
+  status?: MemberPointMallRecordStatus;
+  storeId: string;
+}
+
+/** 导出结果。 */
+export interface MemberPointMallRecordExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 写入记录请求。 */
+export interface WriteMemberPointMallRecordPayload {
+  memberId: string;
+  pointMallProductId: string;
+  redeemedAt?: string;
+  storeId: string;
+}
+
+/** 核销记录请求。 */
+export interface VerifyMemberPointMallRecordPayload {
+  recordId: string;
+  storeId: string;
+  verifyMethod: MemberPointMallVerifyMethod;
+  verifyRemark?: string;
+}
+
+/** 查询规则详情。 */
+export async function getMemberPointMallRuleDetailApi(
+  params: MemberPointMallRuleDetailQuery,
+) {
+  return requestClient.get<MemberPointMallRuleDetailResultDto>(
+    '/member/points-mall/rule/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存规则。 */
+export async function saveMemberPointMallRuleApi(
+  payload: SaveMemberPointMallRulePayload,
+) {
+  return requestClient.post<MemberPointMallRuleDto>(
+    '/member/points-mall/rule/save',
+    payload,
+  );
+}
+
+/** 查询商品列表。 */
+export async function getMemberPointMallProductListApi(
+  params: MemberPointMallProductListQuery,
+) {
+  return requestClient.get<MemberPointMallProductListResultDto>(
+    '/member/points-mall/product/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询商品详情。 */
+export async function getMemberPointMallProductDetailApi(
+  params: MemberPointMallProductDetailQuery,
+) {
+  return requestClient.get<MemberPointMallProductDto>(
+    '/member/points-mall/product/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存商品。 */
+export async function saveMemberPointMallProductApi(
+  payload: SaveMemberPointMallProductPayload,
+) {
+  return requestClient.post<MemberPointMallProductDto>(
+    '/member/points-mall/product/save',
+    payload,
+  );
+}
+
+/** 修改商品状态。 */
+export async function changeMemberPointMallProductStatusApi(
+  payload: ChangeMemberPointMallProductStatusPayload,
+) {
+  return requestClient.post<MemberPointMallProductDto>(
+    '/member/points-mall/product/status',
+    payload,
+  );
+}
+
+/** 删除商品。 */
+export async function deleteMemberPointMallProductApi(
+  payload: DeleteMemberPointMallProductPayload,
+) {
+  return requestClient.post('/member/points-mall/product/delete', payload);
+}
+
+/** 查询兑换记录。 */
+export async function getMemberPointMallRecordListApi(
+  params: MemberPointMallRecordListQuery,
+) {
+  return requestClient.get<MemberPointMallRecordListResultDto>(
+    '/member/points-mall/record/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 查询兑换记录详情。 */
+export async function getMemberPointMallRecordDetailApi(
+  params: MemberPointMallRecordDetailQuery,
+) {
+  return requestClient.get<MemberPointMallRecordDetailDto>(
+    '/member/points-mall/record/detail',
+    {
+      params,
+    },
+  );
+}
+
+/** 导出兑换记录。 */
+export async function exportMemberPointMallRecordApi(
+  params: ExportMemberPointMallRecordQuery,
+) {
+  return requestClient.get<MemberPointMallRecordExportDto>(
+    '/member/points-mall/record/export',
+    {
+      params,
+    },
+  );
+}
+
+/** 写入兑换记录。 */
+export async function writeMemberPointMallRecordApi(
+  payload: WriteMemberPointMallRecordPayload,
+) {
+  return requestClient.post<MemberPointMallRecordDto>(
+    '/member/points-mall/record/write',
+    payload,
+  );
+}
+
+/** 核销兑换记录。 */
+export async function verifyMemberPointMallRecordApi(
+  payload: VerifyMemberPointMallRecordPayload,
+) {
+  return requestClient.post<MemberPointMallRecordDetailDto>(
+    '/member/points-mall/record/verify',
+    payload,
+  );
+}

apps/web-antd/src/api/member/stored-card.ts

@@ -0,0 +1,205 @@
+/**
+ * 文件职责：会员中心储值卡 API 与 DTO 定义。
+ */
+import { requestClient } from '#/api/request';
+
+/** 储值卡方案状态。 */
+export type MemberStoredCardPlanStatus = 'disabled' | 'enabled';
+
+/** 储值卡充值支付方式。 */
+export type MemberStoredCardPaymentMethod =
+  | 'alipay'
+  | 'balance'
+  | 'card'
+  | 'cash'
+  | 'unknown'
+  | 'wechat';
+
+/** 储值卡方案列表查询。 */
+export interface MemberStoredCardPlanListQuery {
+  storeId: string;
+}
+
+/** 储值卡方案统计。 */
+export interface MemberStoredCardPlanStatsDto {
+  currentMonthRechargeAmount: number;
+  rechargeMemberCount: number;
+  totalGiftAmount: number;
+  totalRechargeAmount: number;
+}
+
+/** 储值卡方案项。 */
+export interface MemberStoredCardPlanDto {
+  arrivedAmount: number;
+  giftAmount: number;
+  planId: string;
+  rechargeAmount: number;
+  rechargeCount: number;
+  sortOrder: number;
+  status: MemberStoredCardPlanStatus;
+  totalRechargeAmount: number;
+}
+
+/** 储值卡方案列表结果。 */
+export interface MemberStoredCardPlanListResultDto {
+  items: MemberStoredCardPlanDto[];
+  stats: MemberStoredCardPlanStatsDto;
+}
+
+/** 保存储值卡方案请求。 */
+export interface SaveMemberStoredCardPlanPayload {
+  giftAmount: number;
+  planId?: string;
+  rechargeAmount: number;
+  sortOrder: number;
+  status: MemberStoredCardPlanStatus;
+  storeId: string;
+}
+
+/** 修改储值卡方案状态请求。 */
+export interface ChangeMemberStoredCardPlanStatusPayload {
+  planId: string;
+  status: MemberStoredCardPlanStatus;
+  storeId: string;
+}
+
+/** 删除储值卡方案请求。 */
+export interface DeleteMemberStoredCardPlanPayload {
+  planId: string;
+  storeId: string;
+}
+
+/** 充值记录列表查询。 */
+export interface MemberStoredCardRechargeRecordListQuery {
+  endDate?: string;
+  keyword?: string;
+  page: number;
+  pageSize: number;
+  startDate?: string;
+  storeId: string;
+}
+
+/** 储值卡充值记录项。 */
+export interface MemberStoredCardRechargeRecordDto {
+  arrivedAmount: number;
+  giftAmount: number;
+  memberId: string;
+  memberMobileMasked: string;
+  memberName: string;
+  paymentMethod: MemberStoredCardPaymentMethod;
+  paymentMethodText: string;
+  planId?: string;
+  rechargedAt: string;
+  rechargeAmount: number;
+  recordId: string;
+  recordNo: string;
+  remark?: string;
+}
+
+/** 储值卡充值记录分页结果。 */
+export interface MemberStoredCardRechargeRecordListResultDto {
+  items: MemberStoredCardRechargeRecordDto[];
+  page: number;
+  pageSize: number;
+  totalCount: number;
+}
+
+/** 储值卡充值记录导出查询。 */
+export interface ExportMemberStoredCardRechargeRecordQuery {
+  endDate?: string;
+  keyword?: string;
+  startDate?: string;
+  storeId: string;
+}
+
+/** 储值卡充值记录导出结果。 */
+export interface MemberStoredCardRechargeRecordExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 写入储值卡充值记录请求。 */
+export interface WriteMemberStoredCardRechargeRecordPayload {
+  giftAmount: number;
+  memberId: string;
+  paymentMethod: Exclude<MemberStoredCardPaymentMethod, 'unknown'>;
+  planId?: string;
+  rechargedAt?: string;
+  rechargeAmount: number;
+  remark?: string;
+  storeId: string;
+}
+
+/** 查询储值卡方案列表。 */
+export async function getMemberStoredCardPlanListApi(
+  params: MemberStoredCardPlanListQuery,
+) {
+  return requestClient.get<MemberStoredCardPlanListResultDto>(
+    '/member/stored-card/plan/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 保存储值卡方案。 */
+export async function saveMemberStoredCardPlanApi(
+  payload: SaveMemberStoredCardPlanPayload,
+) {
+  return requestClient.post<MemberStoredCardPlanDto>(
+    '/member/stored-card/plan/save',
+    payload,
+  );
+}
+
+/** 修改储值卡方案状态。 */
+export async function changeMemberStoredCardPlanStatusApi(
+  payload: ChangeMemberStoredCardPlanStatusPayload,
+) {
+  return requestClient.post<MemberStoredCardPlanDto>(
+    '/member/stored-card/plan/status',
+    payload,
+  );
+}
+
+/** 删除储值卡方案。 */
+export async function deleteMemberStoredCardPlanApi(
+  payload: DeleteMemberStoredCardPlanPayload,
+) {
+  return requestClient.post('/member/stored-card/plan/delete', payload);
+}
+
+/** 查询储值卡充值记录。 */
+export async function getMemberStoredCardRechargeRecordListApi(
+  params: MemberStoredCardRechargeRecordListQuery,
+) {
+  return requestClient.get<MemberStoredCardRechargeRecordListResultDto>(
+    '/member/stored-card/record/list',
+    {
+      params,
+    },
+  );
+}
+
+/** 导出储值卡充值记录。 */
+export async function exportMemberStoredCardRechargeRecordApi(
+  params: ExportMemberStoredCardRechargeRecordQuery,
+) {
+  return requestClient.get<MemberStoredCardRechargeRecordExportDto>(
+    '/member/stored-card/record/export',
+    {
+      params,
+    },
+  );
+}
+
+/** 写入储值卡充值记录。 */
+export async function writeMemberStoredCardRechargeRecordApi(
+  payload: WriteMemberStoredCardRechargeRecordPayload,
+) {
+  return requestClient.post<MemberStoredCardRechargeRecordDto>(
+    '/member/stored-card/record/write',
+    payload,
+  );
+}

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

@@ -1,5 +1,6 @@
 import type {
   ContractStatus,
+  GeoLocationStatus,
   MerchantDocumentStatus,
   MerchantDocumentType,
   MerchantStatus,
@@ -51,6 +52,22 @@ export interface MerchantDetailDto {
   legalRepresentative?: string;
   /** 注册地址 */
   registeredAddress?: string;
+  /** 所在省份 */
+  province?: string;
+  /** 所在城市 */
+  city?: string;
+  /** 所在区县 */
+  district?: string;
+  /** 商户经度 */
+  longitude?: null | number;
+  /** 商户纬度 */
+  latitude?: null | number;
+  /** 地理定位状态 */
+  geoStatus?: GeoLocationStatus;
+  /** 地理定位失败原因 */
+  geoFailReason?: string;
+  /** 地理定位成功时间 */
+  geoUpdatedAt?: null | string;
   /** 联系电话 */
   contactPhone?: string;
   /** 联系邮箱 */
@@ -196,3 +213,8 @@ export interface UpdateMerchantDto {
 export async function updateMerchantInfoApi(data: UpdateMerchantDto) {
   return requestClient.post('/merchant/update', data);
 }
+
+/** 手动重试当前商户地理定位 */
+export async function retryMerchantGeocodeApi() {
+  return requestClient.post('/merchant/geocode/retry');
+}

apps/web-antd/src/api/order-hall/index.ts

@@ -0,0 +1,100 @@
+/**
+ * 文件职责：订单大厅（看板）接口与类型定义。
+ */
+import { requestClient } from '#/api/request';
+
+/** 订单看板卡片。 */
+export interface OrderBoardCard {
+  acceptedAt?: null | string;
+  channel: number;
+  createdAt: string;
+  customerName?: null | string;
+  customerPhone?: null | string;
+  deliveryType: number;
+  id: string;
+  isUrged: boolean;
+  itemsSummary?: null | string;
+  orderNo: string;
+  paidAmount: number;
+  queueNumber?: null | string;
+  readyAt?: null | string;
+  status: number;
+  storeId: string;
+  tableNo?: null | string;
+  urgeCount: number;
+}
+
+/** 订单看板结果（四列）。 */
+export interface OrderBoardResult {
+  completed: OrderBoardCard[];
+  delivering: OrderBoardCard[];
+  making: OrderBoardCard[];
+  pending: OrderBoardCard[];
+}
+
+/** 订单看板统计。 */
+export interface OrderBoardStats {
+  completedCount: number;
+  deliveringCount: number;
+  makingCount: number;
+  pendingCount: number;
+  todayTotal: number;
+}
+
+/** 获取完整看板数据。 */
+export async function getOrderBoardApi(params: {
+  channel?: string;
+  storeId: string;
+}) {
+  return requestClient.get<OrderBoardResult>('/order-board/board', { params });
+}
+
+/** 获取看板统计。 */
+export async function getOrderBoardStatsApi(params: { storeId: string }) {
+  return requestClient.get<OrderBoardStats>('/order-board/stats', { params });
+}
+
+/** 重连补偿拉取。 */
+export async function getPendingSinceApi(params: {
+  since: string;
+  storeId: string;
+}) {
+  return requestClient.get<OrderBoardCard[]>('/order-board/pending-since', {
+    params,
+  });
+}
+
+/** 接单。 */
+export async function acceptOrderApi(orderId: string) {
+  return requestClient.post<OrderBoardCard>(
+    `/order-board/${orderId}/accept`,
+    {},
+  );
+}
+
+/** 拒单。 */
+export async function rejectOrderApi(
+  orderId: string,
+  data: { reason: string },
+) {
+  return requestClient.post<OrderBoardCard>(
+    `/order-board/${orderId}/reject`,
+    data,
+  );
+}
+
+/** 出餐完成。 */
+export async function completePreparationApi(orderId: string) {
+  return requestClient.post<OrderBoardCard>(
+    `/order-board/${orderId}/complete-preparation`,
+    {},
+  );
+}
+
+/** 确认送达/取餐。 */
+export async function confirmDeliveryApi(orderId: string) {
+  return requestClient.post<OrderBoardCard>(
+    `/order-board/${orderId}/confirm-delivery`,
+    {},
+  );
+}

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

@@ -0,0 +1,140 @@
+/**
+ * 文件职责：订单管理（全部订单）接口与类型定义。
+ */
+import { requestClient } from '#/api/request';
+
+/** 全部订单状态筛选值。 */
+export type OrderAllStatusFilter =
+  | 'all'
+  | 'cancelled'
+  | 'completed'
+  | 'delivering'
+  | 'making'
+  | 'pending'
+  | 'pickup'
+  | 'refunded';
+
+/** 全部订单渠道筛选值。 */
+export type OrderAllChannelFilter = 'all' | 'delivery' | 'dine_in' | 'pickup';
+
+/** 全部订单支付方式筛选值。 */
+export type OrderAllPaymentFilter =
+  | 'alipay'
+  | 'all'
+  | 'balance'
+  | 'card'
+  | 'cash'
+  | 'wechat';
+
+/** 全部订单筛选参数。 */
+export interface OrderAllFilterQuery {
+  channel?: OrderAllChannelFilter;
+  endDate?: string;
+  keyword?: string;
+  paymentMethod?: OrderAllPaymentFilter;
+  startDate?: string;
+  status?: OrderAllStatusFilter;
+  storeId: string;
+}
+
+/** 全部订单列表查询参数。 */
+export interface OrderAllListQuery extends OrderAllFilterQuery {
+  page: number;
+  pageSize: number;
+}
+
+/** 全部订单列表行。 */
+export interface OrderAllListItemDto {
+  amount: number;
+  channel: string;
+  customer: string;
+  isDimmed: boolean;
+  itemsSummary: string;
+  orderNo: string;
+  orderedAt: string;
+  status: string;
+}
+
+/** 全部订单列表结果。 */
+export interface OrderAllListResultDto {
+  items: OrderAllListItemDto[];
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+/** 全部订单统计。 */
+export interface OrderAllStatsDto {
+  averageAmount: number;
+  refundCount: number;
+  totalAmount: number;
+  totalOrders: number;
+}
+
+/** 全部订单详情商品行。 */
+export interface OrderAllDetailItemDto {
+  name: string;
+  quantity: number;
+  spec: string;
+  subTotal: number;
+  unitPrice: number;
+}
+
+/** 全部订单详情时间线。 */
+export interface OrderAllTimelineDto {
+  label: string;
+  time: string;
+}
+
+/** 全部订单详情。 */
+export interface OrderAllDetailDto {
+  channel: string;
+  customerAddress: string;
+  customerName: string;
+  customerPhone: string;
+  deliveryFee: number;
+  discountAmount: number;
+  finishedAt?: null | string;
+  items: OrderAllDetailItemDto[];
+  itemsAmount: number;
+  orderNo: string;
+  orderedAt: string;
+  paidAmount: number;
+  paidAt?: null | string;
+  paymentMethod: string;
+  remark: string;
+  status: string;
+  timeline: OrderAllTimelineDto[];
+}
+
+/** 全部订单导出回执。 */
+export interface OrderAllExportDto {
+  fileContentBase64: string;
+  fileName: string;
+  totalCount: number;
+}
+
+/** 查询全部订单列表。 */
+export async function getOrderAllListApi(params: OrderAllListQuery) {
+  return requestClient.get<OrderAllListResultDto>('/order/all/list', {
+    params,
+  });
+}
+
+/** 查询全部订单统计。 */
+export async function getOrderAllStatsApi(params: OrderAllFilterQuery) {
+  return requestClient.get<OrderAllStatsDto>('/order/all/stats', { params });
+}
+
+/** 查询全部订单详情。 */
+export async function getOrderAllDetailApi(params: {
+  orderNo: string;
+  storeId: string;
+}) {
+  return requestClient.get<OrderAllDetailDto>('/order/all/detail', { params });
+}
+
+/** 导出全部订单 CSV。 */
+export async function exportOrderAllCsvApi(params: OrderAllFilterQuery) {
+  return requestClient.get<OrderAllExportDto>('/order/all/export', { params });
+}

apps/web-antd/src/api/request.ts

@@ -20,10 +20,16 @@ import { useAuthStore } from '#/store';
 import { refreshTokenApi } from './core';
 
 const { apiURL } = useAppConfig(import.meta.env, import.meta.env.PROD);
-const TENANT_HEADER_KEY = 'X-Tenant-Id';
+const TENANT_ID_HEADER_KEY = 'X-Tenant-Id';
+const TENANT_CODE_HEADER_KEY = 'X-Tenant-Code';
 const TENANT_STORAGE_KEY = 'sys-tenant-id';
 const DEV_TENANT_ID = import.meta.env.DEV ? import.meta.env.VITE_TENANT_ID : '';
 
+interface TenantHeaderPayload {
+  tenantCode?: string;
+  tenantId?: string;
+}
+
 function getHeaderValue(headers: any, key: string) {
   if (!headers) {
     return '';
@@ -49,16 +55,31 @@ function setHeaderValue(headers: any, key: string, value: string) {
   headers[key] = value;
 }
 
-function resolveTenantId() {
+function resolveTenantHeaderPayload(): TenantHeaderPayload {
   const hostname = window.location.hostname;
   const hostnameParts = hostname.split('.').filter(Boolean);
   const isIpAddress = /^\d+\.\d+\.\d+\.\d+$/.test(hostname);
-  const subdomainTenantId =
+  const subdomainTenant =
     hostnameParts.length > 2 && !isIpAddress ? hostnameParts[0] : '';
 
-  const storageTenantId = localStorage.getItem(TENANT_STORAGE_KEY) || '';
+  if (subdomainTenant) {
+    if (/^\d+$/.test(subdomainTenant)) {
+      return { tenantId: subdomainTenant };
+    }
 
-  return subdomainTenantId || storageTenantId || DEV_TENANT_ID || '';
+    return { tenantCode: subdomainTenant };
+  }
+
+  const storageTenantId = localStorage.getItem(TENANT_STORAGE_KEY) || '';
+  if (storageTenantId) {
+    return { tenantId: storageTenantId };
+  }
+
+  if (DEV_TENANT_ID) {
+    return { tenantId: DEV_TENANT_ID };
+  }
+
+  return {};
 }
 
 function createRequestClient(baseURL: string, options?: RequestClientOptions) {
@@ -96,11 +117,30 @@ function createRequestClient(baseURL: string, options?: RequestClientOptions) {
       throw new Error('refresh token is required');
     }
 
-    const resp = await refreshTokenApi({
+    const headers: Record<string, string> = {
-      refreshToken: currentRefreshToken,
+      'Accept-Language': preferences.app.locale,
-    });
+    };
+    const { tenantCode, tenantId } = resolveTenantHeaderPayload();
+    if (tenantCode) {
+      headers[TENANT_CODE_HEADER_KEY] = tenantCode;
+    } else if (tenantId) {
+      headers[TENANT_ID_HEADER_KEY] = tenantId;
+    }
 
-    const tokenData = resp?.data;
+    const resp = await refreshTokenApi(
+      {
+        refreshToken: currentRefreshToken,
+      },
+      {
+        headers,
+      },
+    );
+
+    const responseBody = (resp as any)?.data ?? resp;
+    const tokenData =
+      responseBody?.accessToken || responseBody?.refreshToken
+        ? responseBody
+        : responseBody?.data;
     const newAccessToken = tokenData?.accessToken;
     const newRefreshToken = tokenData?.refreshToken ?? currentRefreshToken;
 
@@ -128,11 +168,20 @@ function createRequestClient(baseURL: string, options?: RequestClientOptions) {
       }
       setHeaderValue(config.headers, 'Accept-Language', preferences.app.locale);
 
-      const headerTenantId = getHeaderValue(config.headers, TENANT_HEADER_KEY);
+      const headerTenantId = getHeaderValue(
-      if (!headerTenantId) {
+        config.headers,
-        const tenantId = resolveTenantId();
+        TENANT_ID_HEADER_KEY,
-        if (tenantId) {
+      );
-          setHeaderValue(config.headers, TENANT_HEADER_KEY, String(tenantId));
+      const headerTenantCode = getHeaderValue(
+        config.headers,
+        TENANT_CODE_HEADER_KEY,
+      );
+      if (!headerTenantId && !headerTenantCode) {
+        const { tenantCode, tenantId } = resolveTenantHeaderPayload();
+        if (tenantCode) {
+          setHeaderValue(config.headers, TENANT_CODE_HEADER_KEY, tenantCode);
+        } else if (tenantId) {
+          setHeaderValue(config.headers, TENANT_ID_HEADER_KEY, tenantId);
         }
       }
 

apps/web-antd/src/api/store-delivery/index.ts

@@ -45,8 +45,9 @@ export interface DeliveryGeneralSettingsDto {
 
 /** 门店配送设置聚合 */
 export interface StoreDeliverySettingsDto {
-  generalSettings: DeliveryGeneralSettingsDto;
+  generalSettings: DeliveryGeneralSettingsDto | null;
-  mode: DeliveryMode;
+  isConfigured: boolean;
+  mode: DeliveryMode | null;
   /** 半径配送中心点纬度 */
   radiusCenterLatitude: null | number;
   /** 半径配送中心点经度 */
@@ -57,7 +58,17 @@ export interface StoreDeliverySettingsDto {
 }
 
 /** 保存配送设置参数 */
-export type SaveStoreDeliverySettingsParams = StoreDeliverySettingsDto;
+export interface SaveStoreDeliverySettingsParams {
+  generalSettings: DeliveryGeneralSettingsDto;
+  mode: DeliveryMode;
+  /** 半径配送中心点纬度 */
+  radiusCenterLatitude: null | number;
+  /** 半径配送中心点经度 */
+  radiusCenterLongitude: null | number;
+  polygonZones: PolygonZoneDto[];
+  radiusTiers: RadiusTierDto[];
+  storeId: string;
+}
 
 /** 复制配送设置参数 */
 export interface CopyStoreDeliverySettingsParams {

apps/web-antd/src/api/store-dinein/index.ts

@@ -44,7 +44,8 @@ export interface DineInTableDto {
 /** 门店堂食设置聚合 */
 export interface StoreDineInSettingsDto {
   areas: DineInAreaDto[];
-  basicSettings: DineInBasicSettingsDto;
+  basicSettings: DineInBasicSettingsDto | null;
+  isConfigured: boolean;
   storeId: string;
   tables: DineInTableDto[];
 }

apps/web-antd/src/api/store-fees/index.ts

@@ -46,6 +46,34 @@ export interface StoreOtherFeesDto {
 export interface StoreFeesSettingsDto {
   /** 基础配送费 */
   baseDeliveryFee: number;
+  /** 平台服务费率（%） */
+  platformServiceRate: number;
+  /** 固定包装费 */
+  fixedPackagingFee: number;
+  /** 免配送费门槛，空值表示关闭 */
+  freeDeliveryThreshold: null | number;
+  /** 起送金额 */
+  minimumOrderAmount: number;
+  /** 其他费用 */
+  otherFees: StoreOtherFeesDto;
+  /** 按订单包装费模式 */
+  orderPackagingFeeMode: OrderPackagingFeeMode;
+  /** 包装费模式 */
+  packagingFeeMode: PackagingFeeMode;
+  /** 包装费阶梯 */
+  packagingFeeTiers: PackagingFeeTierDto[];
+  /** 是否已配置 */
+  isConfigured: boolean;
+  /** 门店 ID */
+  storeId: string;
+}
+
+/** 保存费用设置参数 */
+export interface SaveStoreFeesSettingsParams {
+  /** 基础配送费 */
+  baseDeliveryFee: number;
+  /** 平台服务费率（%） */
+  platformServiceRate: number;
   /** 固定包装费 */
   fixedPackagingFee: number;
   /** 免配送费门槛，空值表示关闭 */
@@ -64,8 +92,13 @@ export interface StoreFeesSettingsDto {
   storeId: string;
 }
 
-/** 保存费用设置参数 */
+/** 保存包装费收取方式参数 */
-export type SaveStoreFeesSettingsParams = StoreFeesSettingsDto;
+export interface SaveStoreFeesModeParams {
+  /** 包装费模式 */
+  packagingFeeMode: PackagingFeeMode;
+  /** 门店 ID */
+  storeId: string;
+}
 
 /** 复制费用设置参数 */
 export interface CopyStoreFeesSettingsParams {
@@ -87,6 +120,11 @@ export async function saveStoreFeesSettingsApi(
   return requestClient.post<StoreFeesSettingsDto>('/store/fees/save', data);
 }
 
+/** 保存包装费收取方式 */
+export async function saveStoreFeesModeApi(data: SaveStoreFeesModeParams) {
+  return requestClient.post('/store/fees/mode/save', data);
+}
+
 /** 复制费用设置到其他门店 */
 export async function copyStoreFeesSettingsApi(
   data: CopyStoreFeesSettingsParams,

apps/web-antd/src/api/store-pickup/index.ts

@@ -71,10 +71,11 @@ export interface PickupPreviewDayDto {
 
 /** 门店自提设置聚合 */
 export interface StorePickupSettingsDto {
-  basicSettings: PickupBasicSettingsDto;
+  basicSettings: null | PickupBasicSettingsDto;
   bigSlots: PickupSlotDto[];
-  fineRule: PickupFineRuleDto;
+  fineRule: null | PickupFineRuleDto;
-  mode: PickupMode;
+  isConfigured: boolean;
+  mode: null | PickupMode;
   previewDays: PickupPreviewDayDto[];
   storeId: string;
 }
@@ -100,6 +101,12 @@ export interface SavePickupFineRuleParams {
   storeId: string;
 }
 
+/** 保存自提模式参数 */
+export interface SavePickupModeParams {
+  mode: PickupMode;
+  storeId: string;
+}
+
 /** 复制自提设置参数 */
 export interface CopyStorePickupSettingsParams {
   sourceStoreId: string;
@@ -130,6 +137,11 @@ export async function savePickupFineRuleApi(data: SavePickupFineRuleParams) {
   return requestClient.post('/store/pickup/fine-rule/save', data);
 }
 
+/** 保存自提模式 */
+export async function savePickupModeApi(data: SavePickupModeParams) {
+  return requestClient.post('/store/pickup/mode/save', data);
+}
+
 /** 复制到其他门店 */
 export async function copyStorePickupSettingsApi(
   data: CopyStorePickupSettingsParams,

apps/web-antd/src/api/store-staff/index.ts

@@ -58,9 +58,11 @@ export interface StaffScheduleDto {
 
 /** 门店排班聚合 */
 export interface StoreStaffScheduleDto {
+  isScheduleConfigured: boolean;
+  isTemplateConfigured: boolean;
   schedules: StaffScheduleDto[];
   storeId: string;
-  templates: StoreShiftTemplatesDto;
+  templates: null | StoreShiftTemplatesDto;
   weekStartDate: string;
 }
 

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

@@ -1,4 +1,5 @@
 import type {
+  GeoLocationStatus,
   ServiceType,
   StoreAuditStatus,
   StoreBusinessStatus,
@@ -22,6 +23,22 @@ export interface StoreListItemDto {
   managerName: string;
   /** 门店地址 */
   address: string;
+  /** 所在省份 */
+  province?: string;
+  /** 所在城市 */
+  city?: string;
+  /** 所在区县 */
+  district?: string;
+  /** 门店经度 */
+  longitude?: null | number;
+  /** 门店纬度 */
+  latitude?: null | number;
+  /** 地理定位状态 */
+  geoStatus?: GeoLocationStatus;
+  /** 地理定位失败原因 */
+  geoFailReason?: string;
+  /** 地理定位成功时间 */
+  geoUpdatedAt?: null | string;
   /** 门店封面图 */
   coverImage?: string;
   /** 营业状态 */
@@ -117,3 +134,8 @@ export async function toggleStoreBusinessStatusApi(
 ) {
   return requestClient.post('/store/toggle-business-status', data);
 }
+
+/** 手动重试门店地理定位 */
+export async function retryStoreGeocodeApi(storeId: string) {
+  return requestClient.post(`/store/${storeId}/geocode/retry`);
+}

apps/web-antd/src/enums/merchantEnum.ts

@@ -60,3 +60,9 @@ export enum MerchantAuditAction {
   Unknown = 0,
   Update = 2,
 }
+
+export enum GeoLocationStatus {
+  Failed = 2,
+  Pending = 0,
+  Success = 1,
+}

apps/web-antd/src/enums/storeEnum.ts

@@ -10,12 +10,12 @@ export enum StoreBusinessStatus {
 
 /** 门店审核状态 */
 export enum StoreAuditStatus {
+  /** 已通过 */
+  Approved = 2,
   /** 草稿 */
   Draft = 0,
   /** 待审核 */
   Pending = 1,
-  /** 已通过 */
-  Approved = 2,
   /** 已拒绝 */
   Rejected = 3,
 }
@@ -29,3 +29,13 @@ export enum ServiceType {
   /** 到店自提 */
   Pickup = 2,
 }
+
+/** 地理定位状态 */
+export enum GeoLocationStatus {
+  /** 定位失败 */
+  Failed = 2,
+  /** 待定位 */
+  Pending = 0,
+  /** 定位成功 */
+  Success = 1,
+}

apps/web-antd/src/hooks/useSignalR.ts

@@ -0,0 +1,121 @@
+/**
+ * 文件职责：SignalR 连接管理 Hook，提供自动重连、事件订阅、断线补偿能力。
+ */
+import type { HubConnection } from '@microsoft/signalr';
+
+import { ref } from 'vue';
+
+import { useAppConfig } from '@vben/hooks';
+import { useAccessStore } from '@vben/stores';
+
+import {
+  HubConnectionBuilder,
+  HubConnectionState,
+  LogLevel,
+} from '@microsoft/signalr';
+
+/** SignalR Hook 配置。 */
+export interface UseSignalROptions {
+  /** 重连后的补偿回调（传入断线时间戳）。 */
+  onReconnected?: (lastDisconnectedAt: Date) => void;
+  /** 连接关闭回调。 */
+  onClose?: (error?: Error) => void;
+}
+
+/** SignalR 连接管理 Hook。 */
+export function useSignalR(options?: UseSignalROptions) {
+  const isConnected = ref(false);
+  let connection: HubConnection | null = null;
+  let lastDisconnectedAt: Date | null = null;
+
+  // 1. 构建 Hub URL（从 apiURL 去掉 /api/tenant/v1 后缀）
+  function buildHubUrl(): string {
+    const { apiURL } = useAppConfig(import.meta.env, import.meta.env.PROD);
+    const base = apiURL.replace(/\/api\/tenant\/v\d+\/?$/, '');
+    return `${base}/hubs/order-board`;
+  }
+
+  // 2. 获取 JWT Token
+  function getAccessToken(): string {
+    const accessStore = useAccessStore();
+    return accessStore.accessToken || '';
+  }
+
+  // 3. 建立连接
+  async function connect(storeId?: string): Promise<void> {
+    if (connection?.state === HubConnectionState.Connected) {
+      return;
+    }
+
+    const hubUrl = storeId
+      ? `${buildHubUrl()}?storeId=${storeId}`
+      : buildHubUrl();
+
+    connection = new HubConnectionBuilder()
+      .withUrl(hubUrl, {
+        accessTokenFactory: () => getAccessToken(),
+      })
+      .withAutomaticReconnect([0, 2000, 5000, 10_000, 30_000])
+      .configureLogging(LogLevel.Warning)
+      .build();
+
+    // 4. 重连成功回调
+    connection.onreconnecting(() => {
+      isConnected.value = false;
+      lastDisconnectedAt = new Date();
+    });
+
+    connection.onreconnected(() => {
+      isConnected.value = true;
+      if (lastDisconnectedAt && options?.onReconnected) {
+        options.onReconnected(lastDisconnectedAt);
+      }
+      lastDisconnectedAt = null;
+    });
+
+    // 5. 连接关闭回调
+    connection.onclose((error) => {
+      isConnected.value = false;
+      lastDisconnectedAt = new Date();
+      options?.onClose?.(error ?? undefined);
+    });
+
+    await connection.start();
+    isConnected.value = true;
+  }
+
+  // 6. 断开连接
+  async function disconnect(): Promise<void> {
+    if (connection) {
+      await connection.stop();
+      connection = null;
+      isConnected.value = false;
+    }
+  }
+
+  // 7. 订阅事件
+  function on<T = unknown>(event: string, callback: (data: T) => void): void {
+    connection?.on(event, callback);
+  }
+
+  // 8. 取消订阅
+  function off(event: string): void {
+    connection?.off(event);
+  }
+
+  // 9. 调用 Hub 方法
+  async function invoke(method: string, ...args: unknown[]): Promise<void> {
+    if (connection?.state === HubConnectionState.Connected) {
+      await connection.invoke(method, ...args);
+    }
+  }
+
+  return {
+    isConnected,
+    connect,
+    disconnect,
+    on,
+    off,
+    invoke,
+  };
+}

apps/web-antd/src/main.ts

@@ -28,6 +28,8 @@ async function initApplication() {
     app: {
       accessMode: 'backend',
       defaultHomePath: '/dashboard/console',
+      enableRefreshToken: true,
+      loginExpiredMode: 'modal',
     },
   });
 

apps/web-antd/src/mock/index.ts

@@ -1,5 +1,11 @@
-// Mock 数据入口，仅在开发环境下使用
+// Mock 数据入口，仅在开发环境下使用。
-// 门店模块已切换真实 TenantApi，此处仅保留其他业务的 mock。
+// 默认关闭商品相关 mock；需要时可通过环境变量显式开启。
-import './product';
+if (import.meta.env.VITE_MOCK_PRODUCT === 'true') {
+  void import('./product');
+  console.warn('[Mock] 已启用商品列表 Mock 数据');
+}
 
-console.warn('[Mock] 非门店模块 Mock 数据已启用');
+if (import.meta.env.VITE_MOCK_PRODUCT_EXTENSIONS === 'true') {
+  void import('./product-extensions');
+  console.warn('[Mock] 已启用商品扩展模块 Mock 数据');
+}

apps/web-antd/src/mock/product.ts

@@ -0,0 +1,883 @@
+import Mock from 'mockjs';
+
+/** 文件职责：商品管理页面 Mock 接口。 */
+interface MockRequestOptions {
+  body: null | string;
+  type: string;
+  url: string;
+}
+
+type ProductStatus = 'off_shelf' | 'on_sale' | 'sold_out';
+type ProductKind = 'combo' | 'single';
+type ProductSoldoutMode = 'permanent' | 'timed' | 'today';
+type ShelfMode = 'draft' | 'now' | 'scheduled';
+type BatchActionType =
+  | 'batch_delete'
+  | 'batch_off'
+  | 'batch_on'
+  | 'batch_soldout';
+
+interface CategorySeed {
+  id: string;
+  name: string;
+  sort: number;
+}
+
+interface ProductSeed {
+  categoryId: string;
+  defaultKind?: ProductKind;
+  name: string;
+  price: number;
+  subtitle: string;
+  tags?: string[];
+}
+
+interface ProductRecord {
+  categoryId: string;
+  description: string;
+  id: string;
+  imageUrl: string;
+  kind: ProductKind;
+  name: string;
+  notifyManager: boolean;
+  originalPrice: null | number;
+  price: number;
+  recoverAt: null | string;
+  remainStock: number;
+  salesMonthly: number;
+  soldoutMode: null | ProductSoldoutMode;
+  soldoutReason: string;
+  spuCode: string;
+  status: ProductStatus;
+  stock: number;
+  storeId: string;
+  subtitle: string;
+  syncToPlatform: boolean;
+  tags: string[];
+  timedOnShelfAt: null | string;
+  updatedAt: string;
+}
+
+interface ProductStoreState {
+  nextSeq: number;
+  products: ProductRecord[];
+}
+
+const CATEGORY_SEEDS: CategorySeed[] = [
+  { id: 'cat-hot', name: '热销推荐', sort: 1 },
+  { id: 'cat-main', name: '主食', sort: 2 },
+  { id: 'cat-snack', name: '小吃凉菜', sort: 3 },
+  { id: 'cat-soup', name: '汤羹粥品', sort: 4 },
+  { id: 'cat-drink', name: '饮品', sort: 5 },
+  { id: 'cat-alcohol', name: '酒水', sort: 6 },
+  { id: 'cat-combo', name: '套餐', sort: 7 },
+];
+
+const PRODUCT_SEEDS: ProductSeed[] = [
+  {
+    categoryId: 'cat-main',
+    name: '宫保鸡丁',
+    price: 32,
+    subtitle: '经典川菜，香辣可口',
+    tags: ['招牌'],
+  },
+  {
+    categoryId: 'cat-main',
+    name: '鱼香肉丝',
+    price: 28,
+    subtitle: '酸甜开胃，佐饭佳选',
+    tags: ['必点'],
+  },
+  {
+    categoryId: 'cat-main',
+    name: '麻婆豆腐',
+    price: 22,
+    subtitle: '麻辣鲜香，口感细腻',
+    tags: ['辣'],
+  },
+  {
+    categoryId: 'cat-main',
+    name: '蛋炒饭',
+    price: 15,
+    subtitle: '粒粒分明，锅气十足',
+  },
+  {
+    categoryId: 'cat-main',
+    name: '红烧排骨',
+    price: 42,
+    subtitle: '酱香浓郁，肉质软烂',
+    tags: ['招牌'],
+  },
+  {
+    categoryId: 'cat-main',
+    name: '土豆烧牛腩',
+    price: 38,
+    subtitle: '软糯入味，牛腩足量',
+  },
+  {
+    categoryId: 'cat-main',
+    name: '黑椒牛柳意面',
+    price: 36,
+    subtitle: '西式风味，黑椒浓香',
+    tags: ['新品'],
+  },
+  {
+    categoryId: 'cat-main',
+    name: '照烧鸡腿饭',
+    price: 27,
+    subtitle: '日式酱香，鸡腿多汁',
+  },
+  {
+    categoryId: 'cat-snack',
+    name: '蒜香鸡翅',
+    price: 24,
+    subtitle: '外酥里嫩，蒜香扑鼻',
+    tags: ['热卖'],
+  },
+  {
+    categoryId: 'cat-snack',
+    name: '香辣薯条',
+    price: 12,
+    subtitle: '酥脆爽口，轻微辣感',
+  },
+  {
+    categoryId: 'cat-snack',
+    name: '凉拌黄瓜',
+    price: 10,
+    subtitle: '爽脆开胃，解腻优选',
+  },
+  {
+    categoryId: 'cat-snack',
+    name: '口水鸡',
+    price: 26,
+    subtitle: '麻香鲜辣，肉质嫩滑',
+    tags: ['辣'],
+  },
+  {
+    categoryId: 'cat-snack',
+    name: '椒盐玉米',
+    price: 14,
+    subtitle: '外脆内甜，老少皆宜',
+  },
+  {
+    categoryId: 'cat-soup',
+    name: '酸辣汤',
+    price: 18,
+    subtitle: '开胃暖身，酸辣平衡',
+  },
+  {
+    categoryId: 'cat-soup',
+    name: '番茄蛋花汤',
+    price: 16,
+    subtitle: '清爽酸甜，营养丰富',
+  },
+  {
+    categoryId: 'cat-soup',
+    name: '皮蛋瘦肉粥',
+    price: 19,
+    subtitle: '米香浓郁，口感顺滑',
+  },
+  {
+    categoryId: 'cat-soup',
+    name: '海带排骨汤',
+    price: 21,
+    subtitle: '汤鲜味美，口感醇厚',
+  },
+  {
+    categoryId: 'cat-drink',
+    name: '柠檬气泡水',
+    price: 9,
+    subtitle: '清爽解腻，微甜口感',
+    tags: ['新品'],
+  },
+  {
+    categoryId: 'cat-drink',
+    name: '冰粉',
+    price: 8,
+    subtitle: '夏日必备，冰凉清甜',
+    tags: ['限时'],
+  },
+  {
+    categoryId: 'cat-drink',
+    name: '酸梅汤',
+    price: 11,
+    subtitle: '古法熬制，酸甜适中',
+  },
+  {
+    categoryId: 'cat-drink',
+    name: '杨枝甘露',
+    price: 16,
+    subtitle: '果香浓郁，奶香顺滑',
+    tags: ['推荐'],
+  },
+  {
+    categoryId: 'cat-drink',
+    name: '鲜榨橙汁',
+    price: 13,
+    subtitle: '现榨现卖，清新自然',
+  },
+  {
+    categoryId: 'cat-alcohol',
+    name: '青岛啤酒 500ml',
+    price: 12,
+    subtitle: '经典口感，冰镇更佳',
+  },
+  {
+    categoryId: 'cat-alcohol',
+    name: '哈尔滨啤酒 500ml',
+    price: 11,
+    subtitle: '麦香清爽，口感顺滑',
+  },
+  {
+    categoryId: 'cat-alcohol',
+    name: '乌苏啤酒 620ml',
+    price: 15,
+    subtitle: '劲爽畅饮，聚餐优选',
+    tags: ['热卖'],
+  },
+  {
+    categoryId: 'cat-combo',
+    defaultKind: 'combo',
+    name: '双人午市套餐',
+    price: 69,
+    subtitle: '两荤一素+汤+饮料',
+    tags: ['套餐'],
+  },
+  {
+    categoryId: 'cat-combo',
+    defaultKind: 'combo',
+    name: '单人畅享套餐',
+    price: 39,
+    subtitle: '主食+小吃+饮品',
+    tags: ['套餐'],
+  },
+  {
+    categoryId: 'cat-combo',
+    defaultKind: 'combo',
+    name: '家庭四人餐',
+    price: 168,
+    subtitle: '经典大份组合，聚会优选',
+    tags: ['套餐', '招牌'],
+  },
+  {
+    categoryId: 'cat-hot',
+    name: '招牌牛肉饭',
+    price: 34,
+    subtitle: '高人气单品，复购率高',
+    tags: ['热销'],
+  },
+  {
+    categoryId: 'cat-hot',
+    name: '经典鸡排饭',
+    price: 26,
+    subtitle: '酥脆鸡排，份量十足',
+    tags: ['热销'],
+  },
+  {
+    categoryId: 'cat-hot',
+    name: '藤椒鸡腿饭',
+    price: 29,
+    subtitle: '麻香清爽，口味独特',
+    tags: ['推荐'],
+  },
+  {
+    categoryId: 'cat-hot',
+    name: '番茄牛腩饭',
+    price: 33,
+    subtitle: '酸甜开胃，牛腩软烂',
+  },
+  {
+    categoryId: 'cat-hot',
+    name: '椒麻鸡拌面',
+    price: 24,
+    subtitle: '清爽拌面，椒麻上头',
+    tags: ['新品'],
+  },
+];
+
+const productStoreMap = new Map<string, ProductStoreState>();
+const ENABLE_PRODUCT_CATEGORY_MOCK =
+  import.meta.env.VITE_MOCK_PRODUCT_CATEGORY === 'true';
+
+/** 解析 URL 查询参数。 */
+function parseUrlParams(url: string) {
+  const parsed = new URL(url, 'http://localhost');
+  const params: Record<string, string> = {};
+  parsed.searchParams.forEach((value, key) => {
+    params[key] = value;
+  });
+  return params;
+}
+
+/** 解析请求体 JSON。 */
+function parseBody(options: MockRequestOptions) {
+  if (!options.body) return {};
+  try {
+    return JSON.parse(options.body) as Record<string, unknown>;
+  } catch (error) {
+    console.error('[mock-product] parseBody error:', error);
+    return {};
+  }
+}
+
+/** 统一 yyyy-MM-dd HH:mm:ss。 */
+function toDateTimeText(date: Date) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  const hour = String(date.getHours()).padStart(2, '0');
+  const minute = String(date.getMinutes()).padStart(2, '0');
+  const second = String(date.getSeconds()).padStart(2, '0');
+  return `${year}-${month}-${day} ${hour}:${minute}:${second}`;
+}
+
+/** 归一化数值输入。 */
+function normalizeNumber(value: unknown, fallback = 0, min = 0) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, parsed);
+}
+
+/** 归一化正整数。 */
+function normalizeInt(value: unknown, fallback = 0, min = 0) {
+  return Math.floor(normalizeNumber(value, fallback, min));
+}
+
+/** 归一化文本。 */
+function normalizeText(value: unknown, fallback = '') {
+  const text = String(value ?? '').trim();
+  return text || fallback;
+}
+
+/** 归一化状态。 */
+function normalizeStatus(
+  value: unknown,
+  fallback: ProductStatus,
+): ProductStatus {
+  const next = String(value || '');
+  if (next === 'on_sale' || next === 'off_shelf' || next === 'sold_out') {
+    return next;
+  }
+  return fallback;
+}
+
+/** 归一化商品类型。 */
+function normalizeKind(value: unknown, fallback: ProductKind): ProductKind {
+  const next = String(value || '');
+  return next === 'combo' || next === 'single' ? next : fallback;
+}
+
+/** 归一化沽清模式。 */
+function normalizeSoldoutMode(
+  value: unknown,
+  fallback: ProductSoldoutMode,
+): ProductSoldoutMode {
+  const next = String(value || '');
+  if (next === 'today' || next === 'timed' || next === 'permanent') return next;
+  return fallback;
+}
+
+/** 标准化标签列表。 */
+function normalizeTags(value: unknown) {
+  if (!Array.isArray(value)) return [];
+  return [
+    ...new Set(
+      value
+        .map((item) => String(item || '').trim())
+        .filter(Boolean)
+        .slice(0, 8),
+    ),
+  ];
+}
+
+/** 查找分类名。 */
+function getCategoryName(categoryId: string) {
+  return (
+    CATEGORY_SEEDS.find((item) => item.id === categoryId)?.name ??
+    CATEGORY_SEEDS[0]?.name ??
+    '未分类'
+  );
+}
+
+/** 生成默认商品池。 */
+function createDefaultProducts(storeId: string): ProductRecord[] {
+  const now = new Date();
+  const list: ProductRecord[] = [];
+  let seq = 1;
+  for (const seed of PRODUCT_SEEDS) {
+    const statusSeed = seq % 9;
+    let status: ProductStatus = 'on_sale';
+    if (statusSeed === 0) {
+      status = 'sold_out';
+    } else if (statusSeed === 4 || statusSeed === 7) {
+      status = 'off_shelf';
+    }
+
+    let stock = 20 + (seq % 120);
+    if (status === 'sold_out') {
+      stock = 0;
+    } else if (status === 'off_shelf') {
+      stock = 12 + (seq % 20);
+    }
+    const price = Number(seed.price.toFixed(2));
+    const originalPrice =
+      seq % 3 === 0 ? Number((price + (3 + (seq % 8))).toFixed(2)) : null;
+    const createdAt = new Date(now);
+    createdAt.setDate(now.getDate() - (seq % 30));
+    list.push({
+      id: `prd-${storeId}-${String(seq).padStart(4, '0')}`,
+      storeId,
+      spuCode: `SPU2024${String(1000 + seq).padStart(5, '0')}`,
+      name: seed.name,
+      subtitle: seed.subtitle,
+      description: `${seed.name}，${seed.subtitle}。`,
+      categoryId: seed.categoryId,
+      kind: seed.defaultKind ?? 'single',
+      price,
+      originalPrice,
+      stock,
+      salesMonthly: 15 + ((seq * 17) % 260),
+      tags: seed.tags ? [...seed.tags] : [],
+      status,
+      soldoutMode: status === 'sold_out' ? 'today' : null,
+      remainStock: stock,
+      recoverAt: null,
+      soldoutReason: status === 'sold_out' ? '食材用完' : '',
+      syncToPlatform: true,
+      notifyManager: false,
+      timedOnShelfAt: null,
+      imageUrl: '',
+      updatedAt: toDateTimeText(createdAt),
+    });
+    seq += 1;
+  }
+  return list;
+}
+
+/** 创建默认门店状态。 */
+function createDefaultState(storeId: string): ProductStoreState {
+  const products = createDefaultProducts(storeId);
+  return {
+    products,
+    nextSeq: products.length + 1,
+  };
+}
+
+/** 确保门店状态存在。 */
+function ensureStoreState(storeId = '') {
+  const key = storeId || 'default';
+  let state = productStoreMap.get(key);
+  if (!state) {
+    state = createDefaultState(key);
+    productStoreMap.set(key, state);
+  }
+  return state;
+}
+
+/** 构建分类结果（全量口径，不受筛选影响）。 */
+function buildCategoryList(products: ProductRecord[]) {
+  const countMap = new Map<string, number>();
+  for (const item of products) {
+    countMap.set(item.categoryId, (countMap.get(item.categoryId) ?? 0) + 1);
+  }
+  return CATEGORY_SEEDS.toSorted((a, b) => a.sort - b.sort).map((category) => ({
+    id: category.id,
+    name: category.name,
+    sort: category.sort,
+    productCount: countMap.get(category.id) ?? 0,
+  }));
+}
+
+/** 列表项映射。 */
+function toListItem(product: ProductRecord) {
+  return {
+    id: product.id,
+    spuCode: product.spuCode,
+    name: product.name,
+    subtitle: product.subtitle,
+    categoryId: product.categoryId,
+    categoryName: getCategoryName(product.categoryId),
+    kind: product.kind,
+    price: product.price,
+    originalPrice: product.originalPrice,
+    stock: product.stock,
+    salesMonthly: product.salesMonthly,
+    tags: [...product.tags],
+    status: product.status,
+    soldoutMode: product.soldoutMode,
+    imageUrl: product.imageUrl,
+  };
+}
+
+/** 详情映射。 */
+function toDetailItem(product: ProductRecord) {
+  return {
+    ...toListItem(product),
+    description: product.description,
+    remainStock: product.remainStock,
+    soldoutReason: product.soldoutReason,
+    recoverAt: product.recoverAt,
+    syncToPlatform: product.syncToPlatform,
+    notifyManager: product.notifyManager,
+  };
+}
+
+/** 创建商品 ID。 */
+function createProductId(storeId: string, seq: number) {
+  return `prd-${storeId}-${String(seq).padStart(4, '0')}`;
+}
+
+/** 创建 SPU 编码。 */
+function createSpuCode(seq: number) {
+  return `SPU2026${String(10_000 + seq).slice(-5)}`;
+}
+
+/** 解析上架方式。 */
+function resolveStatusByShelfMode(
+  mode: ShelfMode,
+  fallback: ProductStatus,
+): ProductStatus {
+  if (mode === 'now') return 'on_sale';
+  if (mode === 'draft' || mode === 'scheduled') return 'off_shelf';
+  return fallback;
+}
+
+/** 获取商品分类（默认走真实 TenantApi，需手动开启才启用 mock）。 */
+if (ENABLE_PRODUCT_CATEGORY_MOCK) {
+  Mock.mock(
+    /\/product\/category\/list(?:\?|$)/,
+    'get',
+    (options: MockRequestOptions) => {
+      const params = parseUrlParams(options.url);
+      const storeId = String(params.storeId || '');
+      const state = ensureStoreState(storeId);
+      return {
+        code: 200,
+        data: buildCategoryList(state.products),
+      };
+    },
+  );
+}
+
+/** 获取商品列表。 */
+Mock.mock(/\/product\/list(?:\?|$)/, 'get', (options: MockRequestOptions) => {
+  const params = parseUrlParams(options.url);
+  const storeId = String(params.storeId || '');
+  const state = ensureStoreState(storeId);
+
+  const categoryId = String(params.categoryId || '').trim();
+  const keyword = String(params.keyword || '')
+    .trim()
+    .toLowerCase();
+  const status = normalizeStatus(params.status, 'on_sale');
+  const kind = normalizeKind(params.kind, 'single');
+  const hasStatus = Boolean(params.status);
+  const hasKind = Boolean(params.kind);
+
+  const page = Math.max(1, normalizeInt(params.page, 1, 1));
+  const pageSize = Math.max(
+    1,
+    Math.min(200, normalizeInt(params.pageSize, 12, 1)),
+  );
+
+  const filtered = state.products.filter((item) => {
+    if (categoryId && item.categoryId !== categoryId) return false;
+    if (keyword) {
+      const hit =
+        item.name.toLowerCase().includes(keyword) ||
+        item.spuCode.toLowerCase().includes(keyword);
+      if (!hit) return false;
+    }
+    if (hasStatus && item.status !== status) return false;
+    if (hasKind && item.kind !== kind) return false;
+    return true;
+  });
+
+  const ordered = filtered.toSorted((a, b) =>
+    b.updatedAt.localeCompare(a.updatedAt),
+  );
+  const start = (page - 1) * pageSize;
+  const items = ordered.slice(start, start + pageSize);
+  return {
+    code: 200,
+    data: {
+      items: items.map((item) => toListItem(item)),
+      total: ordered.length,
+      page,
+      pageSize,
+    },
+  };
+});
+
+/** 获取商品详情。 */
+Mock.mock(/\/product\/detail(?:\?|$)/, 'get', (options: MockRequestOptions) => {
+  const params = parseUrlParams(options.url);
+  const storeId = String(params.storeId || '');
+  const productId = String(params.productId || '');
+  const state = ensureStoreState(storeId);
+  const product = state.products.find((item) => item.id === productId);
+  if (!product) {
+    return {
+      code: 404,
+      data: null,
+      message: '商品不存在',
+    };
+  }
+  return {
+    code: 200,
+    data: toDetailItem(product),
+  };
+});
+
+/** 保存商品（新增/编辑）。 */
+Mock.mock(/\/product\/save/, 'post', (options: MockRequestOptions) => {
+  const body = parseBody(options);
+  const storeId = normalizeText(body.storeId);
+  if (!storeId) {
+    return { code: 400, data: null, message: '门店不能为空' };
+  }
+  const state = ensureStoreState(storeId);
+
+  const id = normalizeText(body.id);
+  const shelfMode = normalizeText(body.shelfMode, 'now') as ShelfMode;
+  const existingIndex = state.products.findIndex((item) => item.id === id);
+  const fallbackStatus =
+    existingIndex === -1 ? 'on_sale' : state.products[existingIndex]?.status;
+  const statusFromBody = normalizeStatus(
+    body.status,
+    fallbackStatus || 'on_sale',
+  );
+  const nextStatus = resolveStatusByShelfMode(shelfMode, statusFromBody);
+  const categoryId = normalizeText(
+    body.categoryId,
+    CATEGORY_SEEDS[0]?.id ?? 'cat-main',
+  );
+
+  const existingProduct =
+    existingIndex === -1 ? null : state.products[existingIndex];
+  const baseProduct: ProductRecord = existingProduct
+    ? { ...existingProduct }
+    : {
+        id: createProductId(storeId, state.nextSeq),
+        storeId,
+        spuCode: createSpuCode(state.nextSeq),
+        name: '',
+        subtitle: '',
+        description: '',
+        categoryId,
+        kind: 'single',
+        price: 0,
+        originalPrice: null,
+        stock: 0,
+        salesMonthly: 0,
+        tags: [],
+        status: 'off_shelf',
+        soldoutMode: null,
+        remainStock: 0,
+        recoverAt: null,
+        soldoutReason: '',
+        syncToPlatform: true,
+        notifyManager: false,
+        timedOnShelfAt: null,
+        imageUrl: '',
+        updatedAt: toDateTimeText(new Date()),
+      };
+
+  baseProduct.name = normalizeText(body.name, baseProduct.name);
+  baseProduct.subtitle = normalizeText(body.subtitle, baseProduct.subtitle);
+  baseProduct.description = normalizeText(
+    body.description,
+    baseProduct.description || `${baseProduct.name}，${baseProduct.subtitle}`,
+  );
+  baseProduct.categoryId = CATEGORY_SEEDS.some((item) => item.id === categoryId)
+    ? categoryId
+    : baseProduct.categoryId;
+  baseProduct.kind = normalizeKind(body.kind, baseProduct.kind);
+  baseProduct.price = Number(
+    normalizeNumber(body.price, baseProduct.price, 0).toFixed(2),
+  );
+  const originalPrice = normalizeNumber(body.originalPrice, -1, 0);
+  baseProduct.originalPrice =
+    originalPrice > 0 ? Number(originalPrice.toFixed(2)) : null;
+  baseProduct.stock = normalizeInt(body.stock, baseProduct.stock, 0);
+  baseProduct.tags = normalizeTags(body.tags);
+  baseProduct.status = nextStatus;
+  baseProduct.soldoutMode = nextStatus === 'sold_out' ? 'today' : null;
+  baseProduct.recoverAt = null;
+  baseProduct.soldoutReason = nextStatus === 'sold_out' ? '库存售罄' : '';
+  baseProduct.remainStock = baseProduct.stock;
+  baseProduct.syncToPlatform = true;
+  baseProduct.notifyManager = false;
+  baseProduct.timedOnShelfAt =
+    shelfMode === 'scheduled' ? normalizeText(body.timedOnShelfAt) : null;
+  baseProduct.updatedAt = toDateTimeText(new Date());
+
+  if (!baseProduct.name) {
+    return {
+      code: 400,
+      data: null,
+      message: '商品名称不能为空',
+    };
+  }
+
+  if (existingIndex === -1) {
+    state.products.unshift(baseProduct);
+    state.nextSeq += 1;
+  } else {
+    state.products.splice(existingIndex, 1, baseProduct);
+  }
+
+  return {
+    code: 200,
+    data: toDetailItem(baseProduct),
+  };
+});
+
+/** 删除商品。 */
+Mock.mock(/\/product\/delete/, 'post', (options: MockRequestOptions) => {
+  const body = parseBody(options);
+  const storeId = normalizeText(body.storeId);
+  const productId = normalizeText(body.productId);
+  if (!storeId || !productId) {
+    return { code: 400, data: null, message: '参数不完整' };
+  }
+  const state = ensureStoreState(storeId);
+  state.products = state.products.filter((item) => item.id !== productId);
+  return { code: 200, data: null };
+});
+
+/** 修改商品状态。 */
+Mock.mock(
+  /\/product\/status\/change/,
+  'post',
+  (options: MockRequestOptions) => {
+    const body = parseBody(options);
+    const storeId = normalizeText(body.storeId);
+    const productId = normalizeText(body.productId);
+    if (!storeId || !productId) {
+      return { code: 400, data: null, message: '参数不完整' };
+    }
+    const state = ensureStoreState(storeId);
+    const product = state.products.find((item) => item.id === productId);
+    if (!product) return { code: 404, data: null, message: '商品不存在' };
+
+    const nextStatus = normalizeStatus(body.status, product.status);
+    product.status = nextStatus;
+    if (nextStatus === 'sold_out') {
+      product.soldoutMode = 'today';
+      product.soldoutReason = product.soldoutReason || '库存售罄';
+      product.remainStock = 0;
+      product.stock = 0;
+    } else {
+      product.soldoutMode = null;
+      product.recoverAt = null;
+      product.soldoutReason = '';
+    }
+    product.updatedAt = toDateTimeText(new Date());
+    return { code: 200, data: toListItem(product) };
+  },
+);
+
+/** 商品沽清。 */
+Mock.mock(/\/product\/soldout/, 'post', (options: MockRequestOptions) => {
+  const body = parseBody(options);
+  const storeId = normalizeText(body.storeId);
+  const productId = normalizeText(body.productId);
+  if (!storeId || !productId) {
+    return { code: 400, data: null, message: '参数不完整' };
+  }
+  const state = ensureStoreState(storeId);
+  const product = state.products.find((item) => item.id === productId);
+  if (!product) return { code: 404, data: null, message: '商品不存在' };
+
+  const mode = normalizeSoldoutMode(body.mode, 'today');
+  const remainStock = normalizeInt(body.remainStock, 0, 0);
+  product.status = 'sold_out';
+  product.soldoutMode = mode;
+  product.remainStock = remainStock;
+  product.stock = remainStock;
+  product.soldoutReason = normalizeText(body.reason);
+  product.recoverAt = mode === 'timed' ? normalizeText(body.recoverAt) : null;
+  product.syncToPlatform = Boolean(body.syncToPlatform);
+  product.notifyManager = Boolean(body.notifyManager);
+  product.updatedAt = toDateTimeText(new Date());
+  return { code: 200, data: toDetailItem(product) };
+});
+
+/** 批量商品动作。 */
+Mock.mock(/\/product\/batch/, 'post', (options: MockRequestOptions) => {
+  const body = parseBody(options);
+  const storeId = normalizeText(body.storeId);
+  const action = normalizeText(body.action) as BatchActionType;
+  const productIds = Array.isArray(body.productIds)
+    ? body.productIds.map((item) => String(item || '').trim()).filter(Boolean)
+    : [];
+
+  if (!storeId || productIds.length === 0) {
+    return {
+      code: 400,
+      data: null,
+      message: '批量操作参数不完整',
+    };
+  }
+
+  const state = ensureStoreState(storeId);
+  const idSet = new Set(productIds);
+  const targets = state.products.filter((item) => idSet.has(item.id));
+  let successCount = 0;
+
+  if (action === 'batch_delete') {
+    const before = state.products.length;
+    state.products = state.products.filter((item) => !idSet.has(item.id));
+    successCount = before - state.products.length;
+  } else {
+    for (const item of targets) {
+      switch (action) {
+        case 'batch_off': {
+          item.status = 'off_shelf';
+          item.soldoutMode = null;
+          item.recoverAt = null;
+          item.soldoutReason = '';
+
+          break;
+        }
+        case 'batch_on': {
+          item.status = 'on_sale';
+          item.soldoutMode = null;
+          item.recoverAt = null;
+          item.soldoutReason = '';
+
+          break;
+        }
+        case 'batch_soldout': {
+          item.status = 'sold_out';
+          item.soldoutMode = normalizeSoldoutMode(body.mode, 'today');
+          item.remainStock = normalizeInt(body.remainStock, 0, 0);
+          item.stock = item.remainStock;
+          item.soldoutReason = normalizeText(body.reason);
+          item.recoverAt =
+            item.soldoutMode === 'timed' ? normalizeText(body.recoverAt) : null;
+          item.syncToPlatform = Boolean(body.syncToPlatform ?? true);
+          item.notifyManager = Boolean(body.notifyManager ?? false);
+
+          break;
+        }
+        // No default
+      }
+      item.updatedAt = toDateTimeText(new Date());
+      successCount += 1;
+    }
+  }
+
+  const totalCount = productIds.length;
+  const failedCount = Math.max(totalCount - successCount, 0);
+  return {
+    code: 200,
+    data: {
+      action,
+      totalCount,
+      successCount,
+      failedCount,
+    },
+  };
+});

apps/web-antd/src/preferences.ts

@@ -10,6 +10,8 @@ export const overridesPreferences = defineOverridesPreferences({
   app: {
     accessMode: 'backend',
     defaultHomePath: '/dashboard/console',
+    enableRefreshToken: true,
+    loginExpiredMode: 'modal',
     name: import.meta.env.VITE_APP_TITLE,
   },
   theme: {

apps/web-antd/src/router/access.ts

@@ -1,6 +1,7 @@
 import type {
   ComponentRecordType,
   GenerateMenuAndRoutesOptions,
+  RouteRecordStringComponent,
 } from '@vben/types';
 
 import { generateAccessible } from '@vben/access';
@@ -14,6 +15,11 @@ import { $t } from '#/locales';
 
 const forbiddenComponent = () => import('#/views/_core/fallback/forbidden.vue');
 
+const PRODUCT_PATH = '/product';
+const PRODUCT_DETAIL_PATH = '/product/detail';
+const PRODUCT_DETAIL_NAME = 'ProductDetail';
+const PRODUCT_LIST_PATH = '/product/list';
+
 async function generateAccess(options: GenerateMenuAndRoutesOptions) {
   const pageMap: ComponentRecordType = import.meta.glob('../views/**/*.vue');
 
@@ -29,7 +35,8 @@ async function generateAccess(options: GenerateMenuAndRoutesOptions) {
         content: `${$t('common.loadingMenu')}...`,
         duration: 1.5,
       });
-      return await getAllMenusApi();
+      const menuList = await getAllMenusApi();
+      return ensureProductDetailRoute(menuList);
     },
     // 可以指定没有权限跳转403页面
     forbiddenComponent,
@@ -39,4 +46,93 @@ async function generateAccess(options: GenerateMenuAndRoutesOptions) {
   });
 }
 
+function ensureProductDetailRoute(
+  routes: RouteRecordStringComponent[],
+): RouteRecordStringComponent[] {
+  const clonedRoutes = cloneMenuRoutes(routes);
+  if (containsRoute(clonedRoutes, PRODUCT_DETAIL_PATH, PRODUCT_DETAIL_NAME)) {
+    return clonedRoutes;
+  }
+
+  const productRoute = findProductRoute(clonedRoutes);
+  if (!productRoute) {
+    return clonedRoutes;
+  }
+
+  const productChildren = [...(productRoute.children ?? [])];
+  const listMeta = productChildren.find(
+    (item) => String(item.path || '').trim() === PRODUCT_LIST_PATH,
+  )?.meta;
+
+  productChildren.push({
+    name: PRODUCT_DETAIL_NAME,
+    path: PRODUCT_DETAIL_PATH,
+    component: '/views/product/detail/index.vue',
+    meta: {
+      ...listMeta,
+      title: '商品详情',
+      hideInMenu: true,
+    },
+  });
+
+  productRoute.children = productChildren;
+  return clonedRoutes;
+}
+
+function cloneMenuRoutes(
+  routes: RouteRecordStringComponent[],
+): RouteRecordStringComponent[] {
+  return routes.map((route) => ({
+    ...route,
+    meta: route.meta ? { ...route.meta } : route.meta,
+    children: route.children ? cloneMenuRoutes(route.children) : undefined,
+  }));
+}
+
+function containsRoute(
+  routes: RouteRecordStringComponent[],
+  path: string,
+  name: string,
+): boolean {
+  for (const route of routes) {
+    const routePath = String(route.path || '').trim();
+    const routeName = String(route.name || '').trim();
+    if (routePath === path || routeName === name) {
+      return true;
+    }
+    if (route.children && containsRoute(route.children, path, name)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function findProductRoute(
+  routes: RouteRecordStringComponent[],
+): null | RouteRecordStringComponent {
+  for (const route of routes) {
+    const routePath = String(route.path || '').trim();
+    const routeName = String(route.name || '').trim();
+    const hasProductListChild = (route.children ?? []).some(
+      (item) => String(item.path || '').trim() === PRODUCT_LIST_PATH,
+    );
+
+    if (
+      routePath === PRODUCT_PATH ||
+      routeName === 'Product' ||
+      hasProductListChild
+    ) {
+      return route;
+    }
+
+    if (route.children) {
+      const nestedMatch = findProductRoute(route.children);
+      if (nestedMatch) {
+        return nestedMatch;
+      }
+    }
+  }
+  return null;
+}
+
 export { generateAccess };

apps/web-antd/src/router/routes/modules/order.ts

@@ -0,0 +1,36 @@
+import type { RouteRecordRaw } from 'vue-router';
+
+/** 文件职责：订单管理模块静态路由。 */
+const routes: RouteRecordRaw[] = [
+  {
+    meta: {
+      icon: 'lucide:receipt-text',
+      order: 15,
+      title: '订单管理',
+    },
+    name: 'Order',
+    path: '/order',
+    children: [
+      {
+        name: 'OrderHall',
+        path: '/order/hall',
+        component: () => import('#/views/order/hall/index.vue'),
+        meta: {
+          icon: 'lucide:layout-dashboard',
+          title: '订单大厅',
+        },
+      },
+      {
+        name: 'OrderAll',
+        path: '/order/list',
+        component: () => import('#/views/order/list/index.vue'),
+        meta: {
+          icon: 'lucide:list-ordered',
+          title: '全部订单',
+        },
+      },
+    ],
+  },
+];
+
+export default routes;

apps/web-antd/src/router/routes/modules/product.ts

@@ -0,0 +1,90 @@
+import type { RouteRecordRaw } from 'vue-router';
+
+/** 文件职责：商品管理模块静态路由。 */
+const routes: RouteRecordRaw[] = [
+  {
+    meta: {
+      icon: 'lucide:package',
+      order: 20,
+      title: '商品管理',
+    },
+    name: 'Product',
+    path: '/product',
+    children: [
+      {
+        name: 'ProductList',
+        path: '/product/list',
+        component: () => import('#/views/product/list/index.vue'),
+        meta: {
+          icon: 'lucide:list',
+          title: '商品列表',
+        },
+      },
+      {
+        name: 'ProductCategory',
+        path: '/product/category',
+        component: () => import('#/views/product/category/index.vue'),
+        meta: {
+          icon: 'lucide:folders',
+          title: '分类管理',
+        },
+      },
+      {
+        name: 'ProductSpecs',
+        path: '/product/specs',
+        component: () => import('#/views/product/specs/index.vue'),
+        meta: {
+          icon: 'lucide:sliders-horizontal',
+          title: '规格做法',
+        },
+      },
+      {
+        name: 'ProductAddons',
+        path: '/product/addons',
+        component: () => import('#/views/product/addons/index.vue'),
+        meta: {
+          icon: 'lucide:plus-square',
+          title: '加料管理',
+        },
+      },
+      {
+        name: 'ProductLabels',
+        path: '/product/labels',
+        component: () => import('#/views/product/labels/index.vue'),
+        meta: {
+          icon: 'lucide:tags',
+          title: '商品标签',
+        },
+      },
+      {
+        name: 'ProductSchedule',
+        path: '/product/schedule',
+        component: () => import('#/views/product/schedule/index.vue'),
+        meta: {
+          icon: 'lucide:calendar-clock',
+          title: '时段供应',
+        },
+      },
+      {
+        name: 'ProductBatchTools',
+        path: '/product/batch',
+        component: () => import('#/views/product/batch/index.vue'),
+        meta: {
+          icon: 'lucide:wand-sparkles',
+          title: '批量工具',
+        },
+      },
+      {
+        name: 'ProductDetail',
+        path: '/product/detail',
+        component: () => import('#/views/product/detail/index.vue'),
+        meta: {
+          hideInMenu: true,
+          title: '商品详情',
+        },
+      },
+    ],
+  },
+];
+
+export default routes;

apps/web-antd/src/views/customer/analysis/components/AmountDistributionCard.vue

@@ -0,0 +1,46 @@
+<script setup lang="ts">
+import type {
+  CustomerAnalysisAmountDistributionItemDto,
+  CustomerAnalysisSegmentCode,
+} from '#/api/customer';
+
+import {
+  formatPercent,
+  resolveDistributionColor,
+} from '../composables/customer-analysis-page/helpers';
+
+interface Props {
+  items: CustomerAnalysisAmountDistributionItemDto[];
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'segment', segmentCode: CustomerAnalysisSegmentCode): void;
+}>();
+</script>
+
+<template>
+  <div class="ca-card">
+    <div class="ca-card-title">客单价分布</div>
+    <button
+      v-for="(item, index) in props.items"
+      :key="item.segmentCode"
+      class="ca-dist-row"
+      type="button"
+      @click="emit('segment', item.segmentCode)"
+    >
+      <span class="ca-dist-label">{{ item.label }}</span>
+      <span class="ca-dist-bar">
+        <span
+          class="ca-dist-bar-inner"
+          :style="{
+            width: `${Math.max(4, Math.min(100, item.percent))}%`,
+            backgroundColor: resolveDistributionColor(index),
+          }"
+        ></span>
+      </span>
+      <span class="ca-dist-val">{{ formatPercent(item.percent) }}</span>
+    </button>
+  </div>
+</template>

apps/web-antd/src/views/customer/analysis/components/AnalysisStatsGrid.vue

@@ -0,0 +1,78 @@
+<script setup lang="ts">
+import type {
+  CustomerAnalysisOverviewDto,
+  CustomerAnalysisSegmentCode,
+} from '#/api/customer';
+
+import {
+  formatCurrency,
+  formatInteger,
+  formatPercent,
+  formatSignedPercent,
+} from '../composables/customer-analysis-page/helpers';
+
+interface Props {
+  overview: CustomerAnalysisOverviewDto;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'segment', segmentCode: CustomerAnalysisSegmentCode): void;
+}>();
+</script>
+
+<template>
+  <div class="ca-stats">
+    <button class="ca-stat" type="button" @click="emit('segment', 'all')">
+      <div class="label">客户总数</div>
+      <div class="val blue">
+        {{ formatInteger(props.overview.totalCustomers) }}
+      </div>
+      <div class="sub">
+        较上周期 {{ formatSignedPercent(props.overview.growthRatePercent) }}
+      </div>
+    </button>
+
+    <button
+      class="ca-stat"
+      type="button"
+      @click="emit('segment', 'active_new')"
+    >
+      <div class="label">本期新增</div>
+      <div class="val green">
+        +{{ formatInteger(props.overview.newCustomers) }}
+      </div>
+      <div class="sub">
+        日均 {{ props.overview.newCustomersDailyAverage }} 人
+      </div>
+    </button>
+
+    <button
+      class="ca-stat"
+      type="button"
+      @click="emit('segment', 'active_recent')"
+    >
+      <div class="label">活跃率</div>
+      <div class="val orange">
+        {{ formatPercent(props.overview.activeRatePercent) }}
+      </div>
+      <div class="sub">
+        {{ formatInteger(props.overview.activeCustomers) }} /
+        {{ formatInteger(props.overview.totalCustomers) }}
+      </div>
+    </button>
+
+    <button
+      class="ca-stat"
+      type="button"
+      @click="emit('segment', 'high_value_top')"
+    >
+      <div class="label">平均客户价值</div>
+      <div class="val">
+        {{ formatCurrency(props.overview.averageLifetimeValue) }}
+      </div>
+      <div class="sub">生命周期价值</div>
+    </button>
+  </div>
+</template>

apps/web-antd/src/views/customer/analysis/components/AnalysisToolbar.vue

@@ -0,0 +1,67 @@
+<script setup lang="ts">
+import type { CustomerAnalysisPeriodFilter } from '#/api/customer';
+
+import { Button, Segmented, Select } from 'ant-design-vue';
+
+import { ANALYSIS_PERIOD_OPTIONS } from '../composables/customer-analysis-page/constants';
+
+interface OptionItem {
+  label: string;
+  value: string;
+}
+
+interface Props {
+  isExporting: boolean;
+  isStoreLoading: boolean;
+  period: CustomerAnalysisPeriodFilter;
+  selectedStoreId: string;
+  storeOptions: OptionItem[];
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'export'): void;
+  (event: 'update:period', value: string): void;
+  (event: 'update:selectedStoreId', value: string): void;
+}>();
+
+function handleStoreChange(value: unknown) {
+  if (typeof value === 'number' || typeof value === 'string') {
+    emit('update:selectedStoreId', String(value));
+    return;
+  }
+
+  emit('update:selectedStoreId', '');
+}
+</script>
+
+<template>
+  <div class="ca-toolbar">
+    <Select
+      class="ca-store-select"
+      :value="props.selectedStoreId"
+      :options="props.storeOptions"
+      placeholder="请选择门店"
+      :loading="props.isStoreLoading"
+      :disabled="props.isStoreLoading || props.storeOptions.length === 0"
+      @update:value="(value) => handleStoreChange(value)"
+    />
+
+    <span class="ca-period-label">统计周期</span>
+    <Segmented
+      class="ca-period-segment"
+      :value="props.period"
+      :options="ANALYSIS_PERIOD_OPTIONS"
+      @change="(value) => emit('update:period', String(value ?? '30d'))"
+    />
+
+    <Button
+      class="ca-export-btn"
+      :loading="props.isExporting"
+      @click="emit('export')"
+    >
+      导出报表
+    </Button>
+  </div>
+</template>

apps/web-antd/src/views/customer/analysis/components/CompositionCard.vue

@@ -0,0 +1,84 @@
+<script setup lang="ts">
+import type {
+  CustomerAnalysisCompositionItemDto,
+  CustomerAnalysisSegmentCode,
+} from '#/api/customer';
+
+import { computed } from 'vue';
+
+import {
+  formatInteger,
+  formatPercent,
+  resolveCompositionToneColor,
+} from '../composables/customer-analysis-page/helpers';
+
+interface Props {
+  items: CustomerAnalysisCompositionItemDto[];
+  totalCustomers: number;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'segment', segmentCode: CustomerAnalysisSegmentCode): void;
+}>();
+
+const donutStyle = computed(() => {
+  if (props.items.length === 0) {
+    return {
+      background: 'conic-gradient(#e5e7eb 0deg 360deg)',
+    };
+  }
+
+  let angle = 0;
+  const parts: string[] = [];
+  for (const item of props.items) {
+    const start = angle;
+    const delta = Math.max(0, Math.min(360, (item.percent / 100) * 360));
+    angle += delta;
+    const end = Math.min(360, angle);
+    parts.push(
+      `${resolveCompositionToneColor(item.tone)} ${start}deg ${end}deg`,
+    );
+  }
+
+  if (angle < 360) {
+    parts.push(`#e5e7eb ${angle}deg 360deg`);
+  }
+
+  return {
+    background: `conic-gradient(${parts.join(',')})`,
+  };
+});
+</script>
+
+<template>
+  <div class="ca-card">
+    <div class="ca-card-title">新老客占比</div>
+    <div class="ca-donut-wrap">
+      <div class="ca-donut" :style="donutStyle">
+        <div class="ca-donut-hole">
+          <div class="num">{{ formatInteger(props.totalCustomers) }}</div>
+          <div class="lbl">总客户</div>
+        </div>
+      </div>
+
+      <div class="ca-legend">
+        <button
+          v-for="item in props.items"
+          :key="item.segmentCode"
+          class="ca-legend-item"
+          type="button"
+          @click="emit('segment', item.segmentCode)"
+        >
+          <span
+            class="ca-legend-dot"
+            :style="{ backgroundColor: resolveCompositionToneColor(item.tone) }"
+          ></span>
+          <span class="ca-legend-label">{{ item.label }}</span>
+          <span class="ca-legend-value">{{ formatPercent(item.percent) }}</span>
+        </button>
+      </div>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/customer/analysis/components/GrowthTrendCard.vue

@@ -0,0 +1,49 @@
+<script setup lang="ts">
+import type {
+  CustomerAnalysisSegmentCode,
+  CustomerAnalysisTrendPointDto,
+} from '#/api/customer';
+
+import { computed } from 'vue';
+
+interface Props {
+  points: CustomerAnalysisTrendPointDto[];
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'segment', segmentCode: CustomerAnalysisSegmentCode): void;
+}>();
+
+const maxValue = computed(() =>
+  Math.max(1, ...(props.points.map((item) => item.value) ?? [1])),
+);
+
+function resolveHeight(value: number) {
+  const ratio = value / maxValue.value;
+  return `${Math.max(14, Math.round(ratio * 96))}px`;
+}
+</script>
+
+<template>
+  <div class="ca-card ca-card-full">
+    <div class="ca-card-title">客户增长趋势</div>
+    <div class="ca-bars">
+      <button
+        v-for="point in props.points"
+        :key="point.label"
+        class="ca-bar-col"
+        type="button"
+        @click="emit('segment', 'active_new')"
+      >
+        <div class="ca-bar-val">{{ point.value }}</div>
+        <div
+          class="ca-bar"
+          :style="{ height: resolveHeight(point.value) }"
+        ></div>
+        <span class="ca-bar-lbl">{{ point.label }}</span>
+      </button>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/customer/analysis/components/MemberDetailDrawer.vue

@@ -0,0 +1,182 @@
+<script setup lang="ts">
+import type { TableProps } from 'ant-design-vue';
+
+import type { CustomerMemberDetailDto } from '#/api/customer';
+
+import { h } from 'vue';
+
+import { Drawer, Empty, Spin, Table, Tag } from 'ant-design-vue';
+
+import {
+  resolveDeliveryTagColor,
+  resolveOrderStatusClass,
+} from '#/views/customer/profile/composables/customer-profile-page/helpers';
+
+import {
+  formatCurrencyWithFraction,
+  formatPercent,
+  resolveAvatarText,
+  resolveTagColor,
+} from '../composables/customer-analysis-page/helpers';
+
+interface Props {
+  detail: CustomerMemberDetailDto | null;
+  loading: boolean;
+  open: boolean;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'close'): void;
+}>();
+
+const orderColumns: TableProps['columns'] = [
+  {
+    title: '时间',
+    dataIndex: 'orderedAt',
+    width: 168,
+  },
+  {
+    title: '订单号',
+    dataIndex: 'orderNo',
+    width: 160,
+  },
+  {
+    title: '商品摘要',
+    dataIndex: 'itemsSummary',
+    ellipsis: true,
+  },
+  {
+    title: '金额',
+    dataIndex: 'amount',
+    width: 110,
+    customRender: ({ text }) => formatCurrencyWithFraction(Number(text || 0)),
+  },
+  {
+    title: '方式',
+    dataIndex: 'deliveryType',
+    width: 90,
+    customRender: ({ text }) =>
+      h(Tag, { color: resolveDeliveryTagColor(String(text ?? '')) }, () =>
+        String(text ?? '--'),
+      ),
+  },
+  {
+    title: '状态',
+    dataIndex: 'status',
+    width: 90,
+    customRender: ({ text }) =>
+      h(
+        'span',
+        {
+          class: [
+            'ca-member-order-status',
+            resolveOrderStatusClass(String(text ?? '')),
+          ],
+        },
+        String(text ?? '--'),
+      ),
+  },
+];
+</script>
+
+<template>
+  <Drawer
+    :open="props.open"
+    width="620"
+    title="会员详情"
+    @close="emit('close')"
+  >
+    <Spin :spinning="props.loading">
+      <template v-if="props.detail">
+        <div class="ca-member-head">
+          <div class="ca-member-avatar">
+            {{ resolveAvatarText(props.detail.name) }}
+          </div>
+          <div class="ca-member-head-main">
+            <div class="ca-member-name-wrap">
+              <span class="ca-member-name">{{ props.detail.name }}</span>
+              <Tag v-if="props.detail.member.isMember" color="purple">
+                {{ props.detail.member.tierName || '会员' }}
+              </Tag>
+            </div>
+            <div class="ca-member-meta">
+              {{ props.detail.phoneMasked }} · 注册于
+              {{ props.detail.registeredAt }}
+            </div>
+            <div class="ca-member-meta">
+              入会 {{ props.detail.member.joinedAt || '--' }} · 来源：{{
+                props.detail.source || '--'
+              }}
+            </div>
+          </div>
+        </div>
+
+        <div class="ca-member-overview">
+          <div class="ca-member-ov-item">
+            <div class="ca-member-ov-val">
+              {{ formatCurrencyWithFraction(props.detail.totalAmount) }}
+            </div>
+            <div class="ca-member-ov-label">累计消费</div>
+          </div>
+          <div class="ca-member-ov-item">
+            <div class="ca-member-ov-val">{{ props.detail.totalOrders }}</div>
+            <div class="ca-member-ov-label">消费次数</div>
+          </div>
+          <div class="ca-member-ov-item">
+            <div class="ca-member-ov-val">
+              {{ formatCurrencyWithFraction(props.detail.averageAmount) }}
+            </div>
+            <div class="ca-member-ov-label">平均客单价</div>
+          </div>
+          <div class="ca-member-ov-item">
+            <div class="ca-member-ov-val">
+              {{ formatPercent(props.detail.repurchaseRatePercent) }}
+            </div>
+            <div class="ca-member-ov-label">复购率</div>
+          </div>
+          <div class="ca-member-ov-item">
+            <div class="ca-member-ov-val">
+              {{ props.detail.member.pointsBalance }}
+            </div>
+            <div class="ca-member-ov-label">积分</div>
+          </div>
+        </div>
+
+        <div class="ca-member-section">
+          <div class="ca-member-section-title">会员标签</div>
+          <div class="ca-member-tag-list">
+            <Tag
+              v-for="tag in props.detail.tags"
+              :key="`${tag.code}-${tag.label}`"
+              :color="resolveTagColor(tag.tone)"
+            >
+              {{ tag.label }}
+            </Tag>
+            <span
+              v-if="props.detail.tags.length === 0"
+              class="ca-member-empty-text"
+            >
+              暂无标签
+            </span>
+          </div>
+        </div>
+
+        <div class="ca-member-section">
+          <div class="ca-member-section-title">最近订单</div>
+          <Table
+            class="ca-member-order-table"
+            row-key="orderNo"
+            size="small"
+            :columns="orderColumns"
+            :data-source="props.detail.recentOrders"
+            :pagination="false"
+          />
+        </div>
+      </template>
+
+      <Empty v-else description="暂无会员详情" />
+    </Spin>
+  </Drawer>
+</template>

apps/web-antd/src/views/customer/analysis/components/RfmMatrixCard.vue

@@ -0,0 +1,54 @@
+<script setup lang="ts">
+import type {
+  CustomerAnalysisRfmRowDto,
+  CustomerAnalysisSegmentCode,
+} from '#/api/customer';
+
+import {
+  formatInteger,
+  resolveRfmCellToneClass,
+} from '../composables/customer-analysis-page/helpers';
+
+interface Props {
+  rows: CustomerAnalysisRfmRowDto[];
+}
+
+defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'segment', segmentCode: CustomerAnalysisSegmentCode): void;
+}>();
+
+const columnLabels = ['高频高额', '高频低额', '低频高额', '低频低额'];
+</script>
+
+<template>
+  <div class="ca-card ca-card-full">
+    <div class="ca-card-title">RFM 客户分层</div>
+    <div class="ca-rfm">
+      <div class="ca-rfm-header"></div>
+      <div
+        v-for="columnLabel in columnLabels"
+        :key="columnLabel"
+        class="ca-rfm-header"
+      >
+        {{ columnLabel }}
+      </div>
+
+      <template v-for="row in rows" :key="row.label">
+        <div class="ca-rfm-label">{{ row.label }}</div>
+        <button
+          v-for="cell in row.cells"
+          :key="cell.segmentCode"
+          class="ca-rfm-cell"
+          :class="resolveRfmCellToneClass(cell.tone)"
+          type="button"
+          @click="emit('segment', cell.segmentCode)"
+        >
+          <div class="ca-rfm-cell-num">{{ formatInteger(cell.count) }}人</div>
+          <div class="ca-rfm-cell-label">{{ cell.label }}</div>
+        </button>
+      </template>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/customer/analysis/components/SegmentDrawer.vue

@@ -0,0 +1,239 @@
+<script setup lang="ts">
+import type { TablePaginationConfig, TableProps } from 'ant-design-vue';
+
+import type {
+  CustomerAnalysisSegmentListItemDto,
+  CustomerAnalysisSegmentListResultDto,
+  CustomerTagDto,
+} from '#/api/customer';
+
+import { h } from 'vue';
+
+import { Button, Drawer, Input, Table, Tag } from 'ant-design-vue';
+
+import {
+  formatCurrencyWithFraction,
+  resolveTagColor,
+} from '../composables/customer-analysis-page/helpers';
+
+interface PaginationState {
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+interface Props {
+  keyword: string;
+  loading: boolean;
+  open: boolean;
+  pagination: PaginationState;
+  result: CustomerAnalysisSegmentListResultDto | null;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'close'): void;
+  (event: 'detail', customerKey: string): void;
+  (event: 'member', customerKey: string): void;
+  (event: 'pageChange', page: number, pageSize: number): void;
+  (event: 'profile', customerKey: string): void;
+  (event: 'search'): void;
+  (event: 'update:keyword', value: string): void;
+}>();
+
+function renderCustomerCell(record: CustomerAnalysisSegmentListItemDto) {
+  return h('div', { class: 'ca-segment-customer' }, [
+    h(
+      'span',
+      {
+        class: 'ca-segment-avatar',
+        style: {
+          background: record.avatarColor || '#1677ff',
+        },
+      },
+      record.avatarText || record.name.slice(0, 1) || '客',
+    ),
+    h('div', { class: 'ca-segment-customer-main' }, [
+      h('div', { class: 'ca-segment-customer-name' }, record.name || '--'),
+      h(
+        'div',
+        { class: 'ca-segment-customer-phone' },
+        record.phoneMasked || '--',
+      ),
+    ]),
+  ]);
+}
+
+function renderTagList(tags: CustomerTagDto[]) {
+  if (tags.length === 0) {
+    return '--';
+  }
+
+  return h(
+    'div',
+    { class: 'ca-segment-tag-list' },
+    tags.map((tag) =>
+      h(
+        Tag,
+        {
+          color: resolveTagColor(tag.tone),
+        },
+        () => tag.label,
+      ),
+    ),
+  );
+}
+
+const columns: TableProps['columns'] = [
+  {
+    title: '客户',
+    dataIndex: 'name',
+    width: 220,
+    customRender: ({ record }) =>
+      renderCustomerCell(record as CustomerAnalysisSegmentListItemDto),
+  },
+  {
+    title: '累计消费',
+    dataIndex: 'totalAmount',
+    width: 120,
+    customRender: ({ text }) => formatCurrencyWithFraction(Number(text || 0)),
+  },
+  {
+    title: '下单次数',
+    dataIndex: 'orderCount',
+    width: 100,
+  },
+  {
+    title: '客单价',
+    dataIndex: 'averageAmount',
+    width: 100,
+    customRender: ({ text }) => formatCurrencyWithFraction(Number(text || 0)),
+  },
+  {
+    title: '最近下单',
+    dataIndex: 'lastOrderAt',
+    width: 120,
+  },
+  {
+    title: '会员等级',
+    dataIndex: 'memberTierName',
+    width: 110,
+    customRender: ({ record }) => {
+      const item = record as CustomerAnalysisSegmentListItemDto;
+      if (!item.isMember) {
+        return '--';
+      }
+      return item.memberTierName || '会员';
+    },
+  },
+  {
+    title: '标签',
+    dataIndex: 'tags',
+    customRender: ({ record }) =>
+      renderTagList((record as CustomerAnalysisSegmentListItemDto).tags),
+  },
+  {
+    title: '操作',
+    key: 'action',
+    width: 160,
+    customRender: ({ record }) => {
+      const item = record as CustomerAnalysisSegmentListItemDto;
+      const actions = [
+        h(
+          Button,
+          {
+            type: 'link',
+            size: 'small',
+            class: 'ca-segment-action',
+            onClick: () => emit('detail', item.customerKey),
+          },
+          () => '详情',
+        ),
+        h(
+          Button,
+          {
+            type: 'link',
+            size: 'small',
+            class: 'ca-segment-action',
+            onClick: () => emit('profile', item.customerKey),
+          },
+          () => '画像',
+        ),
+      ];
+
+      if (item.isMember) {
+        actions.push(
+          h(
+            Button,
+            {
+              type: 'link',
+              size: 'small',
+              class: 'ca-segment-action',
+              onClick: () => emit('member', item.customerKey),
+            },
+            () => '会员',
+          ),
+        );
+      }
+
+      return h('div', { class: 'ca-segment-action-wrap' }, actions);
+    },
+  },
+];
+
+function handleTableChange(next: TablePaginationConfig) {
+  emit('pageChange', Number(next.current || 1), Number(next.pageSize || 10));
+}
+
+function resolveRowClassName(record: CustomerAnalysisSegmentListItemDto) {
+  return record.isDimmed ? 'ca-segment-row-dimmed' : '';
+}
+</script>
+
+<template>
+  <Drawer
+    :open="props.open"
+    width="980"
+    title="客群明细"
+    @close="emit('close')"
+  >
+    <div class="ca-segment-head">
+      <div class="ca-segment-title">
+        {{ props.result?.segmentTitle || '客群明细' }}
+      </div>
+      <div class="ca-segment-desc">
+        {{ props.result?.segmentDescription || '--' }}
+      </div>
+    </div>
+
+    <div class="ca-segment-toolbar">
+      <Input
+        class="ca-segment-search"
+        :value="props.keyword"
+        allow-clear
+        placeholder="搜索姓名 / 手机号"
+        @update:value="(value) => emit('update:keyword', String(value ?? ''))"
+        @press-enter="emit('search')"
+      />
+      <Button type="primary" @click="emit('search')">查询</Button>
+    </div>
+
+    <Table
+      row-key="customerKey"
+      :columns="columns"
+      :data-source="props.result?.items || []"
+      :loading="props.loading"
+      :pagination="{
+        current: props.pagination.page,
+        pageSize: props.pagination.pageSize,
+        total: props.pagination.total,
+        showSizeChanger: false,
+        showTotal: (total: number) => `共 ${total} 条`,
+      }"
+      :row-class-name="resolveRowClassName"
+      class="ca-segment-table"
+      @change="handleTableChange"
+    />
+  </Drawer>
+</template>

apps/web-antd/src/views/customer/analysis/components/TopCustomerTableCard.vue

@@ -0,0 +1,141 @@
+<script setup lang="ts">
+import type { TableProps } from 'ant-design-vue';
+
+import type {
+  CustomerAnalysisSegmentCode,
+  CustomerAnalysisTopCustomerDto,
+  CustomerTagDto,
+} from '#/api/customer';
+
+import { h } from 'vue';
+
+import { Button, Table, Tag } from 'ant-design-vue';
+
+import {
+  formatCurrencyWithFraction,
+  resolveTagColor,
+} from '../composables/customer-analysis-page/helpers';
+
+interface Props {
+  rows: CustomerAnalysisTopCustomerDto[];
+}
+
+defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'detail', customerKey: string): void;
+  (event: 'segment', segmentCode: CustomerAnalysisSegmentCode): void;
+}>();
+
+function renderTagList(tags: CustomerTagDto[]) {
+  if (tags.length === 0) {
+    return '--';
+  }
+
+  return h(
+    'div',
+    { class: 'ca-top-tag-list' },
+    tags.map((tag) =>
+      h(
+        Tag,
+        {
+          color: resolveTagColor(tag.tone),
+        },
+        () => tag.label,
+      ),
+    ),
+  );
+}
+
+const columns: TableProps['columns'] = [
+  {
+    title: '排名',
+    dataIndex: 'rank',
+    width: 70,
+    customRender: ({ text }) =>
+      h('span', { class: 'ca-top-rank' }, String(text ?? '--')),
+  },
+  {
+    title: '客户',
+    dataIndex: 'name',
+    width: 130,
+  },
+  {
+    title: '累计消费',
+    dataIndex: 'totalAmount',
+    width: 120,
+    customRender: ({ text }) =>
+      h(
+        'span',
+        { class: 'ca-top-money' },
+        formatCurrencyWithFraction(Number(text || 0)),
+      ),
+  },
+  {
+    title: '下单次数',
+    dataIndex: 'orderCount',
+    width: 100,
+  },
+  {
+    title: '客单价',
+    dataIndex: 'averageAmount',
+    width: 100,
+    customRender: ({ text }) => formatCurrencyWithFraction(Number(text || 0)),
+  },
+  {
+    title: '最近下单',
+    dataIndex: 'lastOrderAt',
+    width: 110,
+    customRender: ({ text }) => String(text ?? '--').slice(5),
+  },
+  {
+    title: '标签',
+    dataIndex: 'tags',
+    customRender: ({ record }) =>
+      renderTagList((record as CustomerAnalysisTopCustomerDto).tags),
+  },
+  {
+    title: '操作',
+    key: 'action',
+    width: 90,
+    customRender: ({ record }) =>
+      h(
+        Button,
+        {
+          type: 'link',
+          class: 'ca-top-action',
+          onClick: () =>
+            emit(
+              'detail',
+              String((record as CustomerAnalysisTopCustomerDto).customerKey),
+            ),
+        },
+        () => '查看',
+      ),
+  },
+];
+</script>
+
+<template>
+  <div class="ca-card ca-card-full ca-top-card">
+    <div class="ca-card-title-wrap">
+      <div class="ca-card-title">高价值客户 TOP 10</div>
+      <Button
+        type="link"
+        class="ca-top-segment-btn"
+        @click="emit('segment', 'high_value_top')"
+      >
+        查看客群明细
+      </Button>
+    </div>
+
+    <Table
+      row-key="customerKey"
+      size="small"
+      :columns="columns"
+      :data-source="rows"
+      :pagination="false"
+      class="ca-top-table"
+    />
+  </div>
+</template>

apps/web-antd/src/views/customer/analysis/composables/customer-analysis-page/constants.ts

@@ -0,0 +1,43 @@
+import type { OptionItem } from '../../types';
+
+import type {
+  CustomerAnalysisOverviewDto,
+  CustomerAnalysisPeriodFilter,
+  CustomerAnalysisSegmentCode,
+} from '#/api/customer';
+
+/** 客户分析查看权限。 */
+export const CUSTOMER_ANALYSIS_VIEW_PERMISSION =
+  'tenant:customer:analysis:view';
+
+/** 统计周期选项。 */
+export const ANALYSIS_PERIOD_OPTIONS: OptionItem[] = [
+  { label: '近7天', value: '7d' },
+  { label: '近30天', value: '30d' },
+  { label: '近90天', value: '90d' },
+  { label: '近1年', value: '365d' },
+];
+
+/** 默认统计周期。 */
+export const DEFAULT_PERIOD: CustomerAnalysisPeriodFilter = '30d';
+
+/** 默认分群。 */
+export const DEFAULT_SEGMENT_CODE: CustomerAnalysisSegmentCode = 'all';
+
+/** 默认总览数据。 */
+export const EMPTY_OVERVIEW: CustomerAnalysisOverviewDto = {
+  periodCode: DEFAULT_PERIOD,
+  periodDays: 30,
+  totalCustomers: 0,
+  newCustomers: 0,
+  growthRatePercent: 0,
+  newCustomersDailyAverage: 0,
+  activeCustomers: 0,
+  activeRatePercent: 0,
+  averageLifetimeValue: 0,
+  growthTrend: [],
+  composition: [],
+  amountDistribution: [],
+  rfmRows: [],
+  topCustomers: [],
+};

apps/web-antd/src/views/customer/analysis/composables/customer-analysis-page/data-actions.ts

@@ -0,0 +1,94 @@
+import type { Ref } from 'vue';
+
+import type { CustomerAnalysisOverviewDto } from '#/api/customer';
+import type { StoreListItemDto } from '#/api/store';
+
+import { getCustomerAnalysisOverviewApi } from '#/api/customer';
+import { getStoreListApi } from '#/api/store';
+
+import { EMPTY_OVERVIEW } from './constants';
+
+interface DataActionOptions {
+  isOverviewLoading: Ref<boolean>;
+  isStoreLoading: Ref<boolean>;
+  overview: Ref<CustomerAnalysisOverviewDto>;
+  period: Ref<'7d' | '30d' | '90d' | '365d'>;
+  selectedStoreId: Ref<string>;
+  stores: Ref<StoreListItemDto[]>;
+}
+
+/**
+ * 文件职责：客户分析页的数据加载动作。
+ */
+export function createDataActions(options: DataActionOptions) {
+  function resolvePeriodDays(period: '7d' | '30d' | '90d' | '365d'): number {
+    switch (period) {
+      case '7d': {
+        return 7;
+      }
+      case '90d': {
+        return 90;
+      }
+      case '365d': {
+        return 365;
+      }
+      default: {
+        return 30;
+      }
+    }
+  }
+
+  function resetOverview() {
+    options.overview.value = {
+      ...EMPTY_OVERVIEW,
+      periodCode: options.period.value,
+      periodDays: resolvePeriodDays(options.period.value),
+    };
+  }
+
+  async function loadStores() {
+    options.isStoreLoading.value = true;
+    try {
+      const result = await getStoreListApi({ page: 1, pageSize: 200 });
+      options.stores.value = result.items;
+
+      if (result.items.length === 0) {
+        options.selectedStoreId.value = '';
+        resetOverview();
+        return;
+      }
+
+      const matched = result.items.some(
+        (item) => item.id === options.selectedStoreId.value,
+      );
+      if (!matched) {
+        options.selectedStoreId.value = result.items[0]?.id ?? '';
+      }
+    } finally {
+      options.isStoreLoading.value = false;
+    }
+  }
+
+  async function loadOverview() {
+    if (!options.selectedStoreId.value) {
+      resetOverview();
+      return;
+    }
+
+    options.isOverviewLoading.value = true;
+    try {
+      options.overview.value = await getCustomerAnalysisOverviewApi({
+        storeId: options.selectedStoreId.value,
+        period: options.period.value,
+      });
+    } finally {
+      options.isOverviewLoading.value = false;
+    }
+  }
+
+  return {
+    loadOverview,
+    loadStores,
+    resetOverview,
+  };
+}

apps/web-antd/src/views/customer/analysis/composables/customer-analysis-page/drawer-actions.ts

@@ -0,0 +1,84 @@
+import type { Ref } from 'vue';
+
+import type { CustomerDetailDto, CustomerProfileDto } from '#/api/customer';
+
+import {
+  getCustomerAnalysisDetailApi,
+  getCustomerAnalysisProfileApi,
+} from '#/api/customer';
+
+interface DrawerActionOptions {
+  detail: Ref<CustomerDetailDto | null>;
+  isDetailDrawerOpen: Ref<boolean>;
+  isDetailLoading: Ref<boolean>;
+  isProfileDrawerOpen: Ref<boolean>;
+  isProfileLoading: Ref<boolean>;
+  profile: Ref<CustomerProfileDto | null>;
+  selectedStoreId: Ref<string>;
+}
+
+/**
+ * 文件职责：客户分析页客户详情与画像抽屉动作。
+ */
+export function createDrawerActions(options: DrawerActionOptions) {
+  function setDetailDrawerOpen(value: boolean) {
+    options.isDetailDrawerOpen.value = value;
+    if (!value) {
+      options.detail.value = null;
+      options.isProfileDrawerOpen.value = false;
+      options.profile.value = null;
+    }
+  }
+
+  function setProfileDrawerOpen(value: boolean) {
+    options.isProfileDrawerOpen.value = value;
+    if (!value) {
+      options.profile.value = null;
+    }
+  }
+
+  async function openDetail(customerKey: string) {
+    if (!options.selectedStoreId.value || !customerKey) {
+      return;
+    }
+
+    options.isDetailDrawerOpen.value = true;
+    options.detail.value = null;
+    options.isProfileDrawerOpen.value = false;
+    options.profile.value = null;
+    options.isDetailLoading.value = true;
+    try {
+      options.detail.value = await getCustomerAnalysisDetailApi({
+        storeId: options.selectedStoreId.value,
+        customerKey,
+      });
+    } finally {
+      options.isDetailLoading.value = false;
+    }
+  }
+
+  async function openProfile(customerKey: string) {
+    if (!options.selectedStoreId.value || !customerKey) {
+      return;
+    }
+
+    options.isProfileDrawerOpen.value = true;
+    options.profile.value = null;
+    options.isProfileLoading.value = true;
+    try {
+      options.profile.value = await getCustomerAnalysisProfileApi({
+        storeId: options.selectedStoreId.value,
+        customerKey,
+      });
+    } finally {
+      options.isProfileLoading.value = false;
+    }
+  }
+
+  return {
+    openDetail,
+    openProfile,
+    setDetailDrawerOpen,
+    setProfileDrawerOpen,
+  };
+}

apps/web-antd/src/views/customer/analysis/composables/customer-analysis-page/export-actions.ts

@@ -0,0 +1,46 @@
+import type { Ref } from 'vue';
+
+import { message } from 'ant-design-vue';
+
+import { exportCustomerAnalysisCsvApi } from '#/api/customer';
+
+import { downloadBase64File } from './helpers';
+
+interface ExportActionOptions {
+  canExport: Ref<boolean>;
+  isExporting: Ref<boolean>;
+  period: Ref<'7d' | '30d' | '90d' | '365d'>;
+  selectedStoreId: Ref<string>;
+}
+
+/**
+ * 文件职责：客户分析报表导出动作。
+ */
+export function createExportActions(options: ExportActionOptions) {
+  async function handleExport() {
+    if (!options.selectedStoreId.value) {
+      return;
+    }
+
+    if (!options.canExport.value) {
+      message.warning('暂无导出权限');
+      return;
+    }
+
+    options.isExporting.value = true;
+    try {
+      const result = await exportCustomerAnalysisCsvApi({
+        storeId: options.selectedStoreId.value,
+        period: options.period.value,
+      });
+      downloadBase64File(result.fileName, result.fileContentBase64);
+      message.success('客户分析报表导出成功');
+    } finally {
+      options.isExporting.value = false;
+    }
+  }
+
+  return {
+    handleExport,
+  };
+}

apps/web-antd/src/views/customer/analysis/composables/customer-analysis-page/helpers.ts

@@ -0,0 +1,90 @@
+export function formatCurrency(value: number) {
+  return new Intl.NumberFormat('zh-CN', {
+    style: 'currency',
+    currency: 'CNY',
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 2,
+  }).format(Number.isFinite(value) ? value : 0);
+}
+
+export function formatCurrencyWithFraction(value: number) {
+  return new Intl.NumberFormat('zh-CN', {
+    style: 'currency',
+    currency: 'CNY',
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  }).format(Number.isFinite(value) ? value : 0);
+}
+
+export function formatInteger(value: number) {
+  return new Intl.NumberFormat('zh-CN', {
+    maximumFractionDigits: 0,
+  }).format(Number.isFinite(value) ? value : 0);
+}
+
+export function formatPercent(value: number) {
+  if (!Number.isFinite(value)) {
+    return '0%';
+  }
+  return `${value.toFixed(1).replace(/\.0$/, '')}%`;
+}
+
+export function formatSignedPercent(value: number) {
+  const normalized = Number.isFinite(value) ? value : 0;
+  const sign = normalized > 0 ? '+' : '';
+  return `${sign}${formatPercent(normalized)}`;
+}
+
+export function resolveTagColor(tone: string) {
+  if (tone === 'orange') return 'orange';
+  if (tone === 'green') return 'green';
+  if (tone === 'gray') return 'default';
+  if (tone === 'red') return 'red';
+  return 'blue';
+}
+
+export function resolveRfmCellToneClass(tone: string) {
+  if (tone === 'hot') return 'hot';
+  if (tone === 'warm') return 'warm';
+  if (tone === 'cool') return 'cool';
+  return 'cold';
+}
+
+export function resolveCompositionToneColor(tone: string) {
+  if (tone === 'green') return '#52c41a';
+  if (tone === 'orange') return '#fa8c16';
+  if (tone === 'gray') return '#e5e7eb';
+  return '#1677ff';
+}
+
+export function resolveDistributionColor(index: number) {
+  const palette = ['#7fb4ff', '#4a95ff', '#1677ff', '#1061d6', '#0a4eaf'];
+  return palette[Math.max(0, Math.min(index, palette.length - 1))] ?? '#1677ff';
+}
+
+export function resolveAvatarText(name: string) {
+  const normalized = String(name || '').trim();
+  return normalized ? normalized.slice(0, 1) : '客';
+}
+
+function decodeBase64ToBlob(base64: string) {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.codePointAt(index) ?? 0;
+  }
+  return new Blob([bytes], { type: 'text/csv;charset=utf-8;' });
+}
+
+export function downloadBase64File(
+  fileName: string,
+  fileContentBase64: string,
+) {
+  const blob = decodeBase64ToBlob(fileContentBase64);
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+  anchor.href = url;
+  anchor.download = fileName;
+  anchor.click();
+  URL.revokeObjectURL(url);
+}

apps/web-antd/src/views/customer/analysis/composables/customer-analysis-page/member-actions.ts

@@ -0,0 +1,47 @@
+import type { Ref } from 'vue';
+
+import type { CustomerMemberDetailDto } from '#/api/customer';
+
+import { getCustomerMemberDetailApi } from '#/api/customer';
+
+interface MemberActionOptions {
+  detail: Ref<CustomerMemberDetailDto | null>;
+  isMemberDrawerOpen: Ref<boolean>;
+  isMemberLoading: Ref<boolean>;
+  selectedStoreId: Ref<string>;
+}
+
+/**
+ * 文件职责：客户分析页会员详情抽屉动作。
+ */
+export function createMemberActions(options: MemberActionOptions) {
+  function setMemberDrawerOpen(value: boolean) {
+    options.isMemberDrawerOpen.value = value;
+    if (!value) {
+      options.detail.value = null;
+    }
+  }
+
+  async function openMember(customerKey: string) {
+    if (!options.selectedStoreId.value || !customerKey) {
+      return;
+    }
+
+    options.isMemberDrawerOpen.value = true;
+    options.detail.value = null;
+    options.isMemberLoading.value = true;
+    try {
+      options.detail.value = await getCustomerMemberDetailApi({
+        storeId: options.selectedStoreId.value,
+        customerKey,
+      });
+    } finally {
+      options.isMemberLoading.value = false;
+    }
+  }
+
+  return {
+    openMember,
+    setMemberDrawerOpen,
+  };
+}

apps/web-antd/src/views/customer/analysis/composables/customer-analysis-page/segment-actions.ts

@@ -0,0 +1,99 @@
+import type { Ref } from 'vue';
+
+import type {
+  CustomerAnalysisSegmentCode,
+  CustomerAnalysisSegmentListResultDto,
+} from '#/api/customer';
+
+import { getCustomerAnalysisSegmentListApi } from '#/api/customer';
+
+interface SegmentPagination {
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+interface SegmentActionOptions {
+  currentSegmentCode: Ref<CustomerAnalysisSegmentCode>;
+  isSegmentDrawerOpen: Ref<boolean>;
+  isSegmentLoading: Ref<boolean>;
+  keyword: Ref<string>;
+  pagination: SegmentPagination;
+  period: Ref<'7d' | '30d' | '90d' | '365d'>;
+  result: Ref<CustomerAnalysisSegmentListResultDto | null>;
+  selectedStoreId: Ref<string>;
+}
+
+/**
+ * 文件职责：客户分析页客群明细抽屉动作。
+ */
+export function createSegmentActions(options: SegmentActionOptions) {
+  function setSegmentDrawerOpen(value: boolean) {
+    options.isSegmentDrawerOpen.value = value;
+    if (!value) {
+      options.result.value = null;
+      options.keyword.value = '';
+      options.pagination.page = 1;
+      options.pagination.total = 0;
+    }
+  }
+
+  function setSegmentKeyword(value: string) {
+    options.keyword.value = value;
+  }
+
+  async function loadSegmentData() {
+    if (!options.selectedStoreId.value) {
+      options.result.value = null;
+      options.pagination.total = 0;
+      return;
+    }
+
+    options.isSegmentLoading.value = true;
+    try {
+      const result = await getCustomerAnalysisSegmentListApi({
+        storeId: options.selectedStoreId.value,
+        period: options.period.value,
+        segmentCode: options.currentSegmentCode.value,
+        keyword: options.keyword.value.trim() || undefined,
+        page: options.pagination.page,
+        pageSize: options.pagination.pageSize,
+      });
+
+      options.result.value = result;
+      options.pagination.page = result.page;
+      options.pagination.pageSize = result.pageSize;
+      options.pagination.total = result.totalCount;
+    } finally {
+      options.isSegmentLoading.value = false;
+    }
+  }
+
+  async function openSegment(segmentCode: CustomerAnalysisSegmentCode) {
+    options.currentSegmentCode.value = segmentCode;
+    options.keyword.value = '';
+    options.pagination.page = 1;
+    options.isSegmentDrawerOpen.value = true;
+    await loadSegmentData();
+  }
+
+  async function handleSegmentSearch() {
+    options.pagination.page = 1;
+    await loadSegmentData();
+  }
+
+  async function handleSegmentPageChange(page: number, pageSize: number) {
+    options.pagination.page = page;
+    options.pagination.pageSize = pageSize;
+    await loadSegmentData();
+  }
+
+  return {
+    handleSegmentPageChange,
+    handleSegmentSearch,
+    loadSegmentData,
+    openSegment,
+    setSegmentDrawerOpen,
+    setSegmentKeyword,
+  };
+}

apps/web-antd/src/views/customer/analysis/composables/useCustomerAnalysisPage.ts

@@ -0,0 +1,244 @@
+import type {
+  CustomerAnalysisOverviewDto,
+  CustomerAnalysisPeriodFilter,
+  CustomerAnalysisSegmentCode,
+  CustomerAnalysisSegmentListResultDto,
+  CustomerDetailDto,
+  CustomerMemberDetailDto,
+  CustomerProfileDto,
+} from '#/api/customer';
+import type { StoreListItemDto } from '#/api/store';
+
+import { computed, onActivated, onMounted, reactive, ref, watch } from 'vue';
+import { useRouter } from 'vue-router';
+
+import { useAccessStore } from '@vben/stores';
+
+import { createNavigationActions } from '#/views/customer/list/composables/customer-list-page/navigation-actions';
+
+import {
+  CUSTOMER_ANALYSIS_VIEW_PERMISSION,
+  DEFAULT_PERIOD,
+  DEFAULT_SEGMENT_CODE,
+  EMPTY_OVERVIEW,
+} from './customer-analysis-page/constants';
+import { createDataActions } from './customer-analysis-page/data-actions';
+import { createDrawerActions } from './customer-analysis-page/drawer-actions';
+import { createExportActions } from './customer-analysis-page/export-actions';
+import { createMemberActions } from './customer-analysis-page/member-actions';
+import { createSegmentActions } from './customer-analysis-page/segment-actions';
+
+export function useCustomerAnalysisPage() {
+  const accessStore = useAccessStore();
+  const router = useRouter();
+
+  const stores = ref<StoreListItemDto[]>([]);
+  const selectedStoreId = ref('');
+  const isStoreLoading = ref(false);
+
+  const period = ref<CustomerAnalysisPeriodFilter>(DEFAULT_PERIOD);
+  const overview = ref<CustomerAnalysisOverviewDto>({ ...EMPTY_OVERVIEW });
+  const isOverviewLoading = ref(false);
+
+  const segmentResult = ref<CustomerAnalysisSegmentListResultDto | null>(null);
+  const isSegmentDrawerOpen = ref(false);
+  const isSegmentLoading = ref(false);
+  const segmentKeyword = ref('');
+  const currentSegmentCode =
+    ref<CustomerAnalysisSegmentCode>(DEFAULT_SEGMENT_CODE);
+  const segmentPagination = reactive({
+    page: 1,
+    pageSize: 10,
+    total: 0,
+  });
+
+  const detail = ref<CustomerDetailDto | null>(null);
+  const isDetailDrawerOpen = ref(false);
+  const isDetailLoading = ref(false);
+
+  const profile = ref<CustomerProfileDto | null>(null);
+  const isProfileDrawerOpen = ref(false);
+  const isProfileLoading = ref(false);
+
+  const memberDetail = ref<CustomerMemberDetailDto | null>(null);
+  const isMemberDrawerOpen = ref(false);
+  const isMemberLoading = ref(false);
+
+  const isExporting = ref(false);
+
+  const storeOptions = computed(() =>
+    stores.value.map((item) => ({
+      label: item.name,
+      value: item.id,
+    })),
+  );
+
+  const accessCodeSet = computed(
+    () => new Set((accessStore.accessCodes ?? []).map(String)),
+  );
+  const canExport = computed(() =>
+    accessCodeSet.value.has(CUSTOMER_ANALYSIS_VIEW_PERMISSION),
+  );
+
+  const { loadStores, loadOverview, resetOverview } = createDataActions({
+    stores,
+    selectedStoreId,
+    period,
+    overview,
+    isStoreLoading,
+    isOverviewLoading,
+  });
+
+  const {
+    openSegment,
+    loadSegmentData,
+    setSegmentDrawerOpen,
+    setSegmentKeyword,
+    handleSegmentSearch,
+    handleSegmentPageChange,
+  } = createSegmentActions({
+    selectedStoreId,
+    period,
+    currentSegmentCode,
+    keyword: segmentKeyword,
+    result: segmentResult,
+    isSegmentDrawerOpen,
+    isSegmentLoading,
+    pagination: segmentPagination,
+  });
+
+  const { openMember, setMemberDrawerOpen } = createMemberActions({
+    selectedStoreId,
+    detail: memberDetail,
+    isMemberDrawerOpen,
+    isMemberLoading,
+  });
+
+  const { openDetail, openProfile, setDetailDrawerOpen, setProfileDrawerOpen } =
+    createDrawerActions({
+      selectedStoreId,
+      detail,
+      isDetailDrawerOpen,
+      isDetailLoading,
+      profile,
+      isProfileDrawerOpen,
+      isProfileLoading,
+    });
+
+  const { openProfilePage } = createNavigationActions({
+    selectedStoreId,
+    router,
+  });
+
+  const { handleExport } = createExportActions({
+    selectedStoreId,
+    period,
+    isExporting,
+    canExport,
+  });
+
+  function setSelectedStoreId(value: string) {
+    selectedStoreId.value = value;
+  }
+
+  function setPeriod(value: string) {
+    const normalized = (value ||
+      DEFAULT_PERIOD) as CustomerAnalysisPeriodFilter;
+    period.value = normalized;
+  }
+
+  async function openSegmentByCode(segmentCode: CustomerAnalysisSegmentCode) {
+    await openSegment(segmentCode);
+  }
+
+  async function openTopCustomerDetail(customerKey: string) {
+    await openDetail(customerKey);
+  }
+
+  async function openMemberFromDetail(customerKey: string) {
+    await openMember(customerKey);
+  }
+
+  watch(selectedStoreId, async (storeId) => {
+    if (!storeId) {
+      resetOverview();
+      segmentResult.value = null;
+      segmentPagination.total = 0;
+      setDetailDrawerOpen(false);
+      setProfileDrawerOpen(false);
+      setMemberDrawerOpen(false);
+      isSegmentDrawerOpen.value = false;
+      return;
+    }
+
+    await loadOverview();
+    if (isSegmentDrawerOpen.value) {
+      await loadSegmentData();
+    }
+  });
+
+  watch(period, async () => {
+    if (!selectedStoreId.value) {
+      resetOverview();
+      return;
+    }
+
+    await loadOverview();
+    if (isSegmentDrawerOpen.value) {
+      await loadSegmentData();
+    }
+  });
+
+  onMounted(() => {
+    void loadStores();
+  });
+
+  onActivated(() => {
+    if (stores.value.length === 0 || !selectedStoreId.value) {
+      void loadStores();
+    }
+  });
+
+  return {
+    canExport,
+    currentSegmentCode,
+    detail,
+    handleExport,
+    handleSegmentPageChange,
+    handleSegmentSearch,
+    isDetailDrawerOpen,
+    isDetailLoading,
+    isExporting,
+    isMemberDrawerOpen,
+    isMemberLoading,
+    isOverviewLoading,
+    isProfileDrawerOpen,
+    isProfileLoading,
+    isSegmentDrawerOpen,
+    isSegmentLoading,
+    isStoreLoading,
+    memberDetail,
+    openDetail,
+    openMember,
+    openMemberFromDetail,
+    openProfile,
+    openProfilePage,
+    openSegmentByCode,
+    openTopCustomerDetail,
+    overview,
+    period,
+    profile,
+    segmentKeyword,
+    segmentPagination,
+    segmentResult,
+    selectedStoreId,
+    setDetailDrawerOpen,
+    setMemberDrawerOpen,
+    setPeriod,
+    setProfileDrawerOpen,
+    setSegmentDrawerOpen,
+    setSegmentKeyword,
+    setSelectedStoreId,
+    storeOptions,
+  };
+}

apps/web-antd/src/views/customer/analysis/index.vue

@@ -0,0 +1,158 @@
+<script setup lang="ts">
+import { Page } from '@vben/common-ui';
+
+import { Empty, Spin } from 'ant-design-vue';
+
+import CustomerDetailDrawer from '#/views/customer/list/components/CustomerDetailDrawer.vue';
+import CustomerProfileDrawer from '#/views/customer/list/components/CustomerProfileDrawer.vue';
+
+import AmountDistributionCard from './components/AmountDistributionCard.vue';
+import AnalysisStatsGrid from './components/AnalysisStatsGrid.vue';
+import AnalysisToolbar from './components/AnalysisToolbar.vue';
+import CompositionCard from './components/CompositionCard.vue';
+import GrowthTrendCard from './components/GrowthTrendCard.vue';
+import MemberDetailDrawer from './components/MemberDetailDrawer.vue';
+import RfmMatrixCard from './components/RfmMatrixCard.vue';
+import SegmentDrawer from './components/SegmentDrawer.vue';
+import TopCustomerTableCard from './components/TopCustomerTableCard.vue';
+import { useCustomerAnalysisPage } from './composables/useCustomerAnalysisPage';
+
+const {
+  detail,
+  handleExport,
+  handleSegmentPageChange,
+  handleSegmentSearch,
+  isDetailDrawerOpen,
+  isDetailLoading,
+  isExporting,
+  isMemberDrawerOpen,
+  isMemberLoading,
+  isOverviewLoading,
+  isProfileDrawerOpen,
+  isProfileLoading,
+  isSegmentDrawerOpen,
+  isSegmentLoading,
+  isStoreLoading,
+  memberDetail,
+  openDetail,
+  openMember,
+  openMemberFromDetail,
+  openProfile,
+  openProfilePage,
+  openSegmentByCode,
+  openTopCustomerDetail,
+  overview,
+  period,
+  profile,
+  segmentKeyword,
+  segmentPagination,
+  segmentResult,
+  selectedStoreId,
+  setDetailDrawerOpen,
+  setMemberDrawerOpen,
+  setPeriod,
+  setProfileDrawerOpen,
+  setSegmentDrawerOpen,
+  setSegmentKeyword,
+  setSelectedStoreId,
+  storeOptions,
+} = useCustomerAnalysisPage();
+</script>
+
+<template>
+  <Page title="客户分析" content-class="page-customer-analysis">
+    <div class="ca-page">
+      <AnalysisToolbar
+        :selected-store-id="selectedStoreId"
+        :store-options="storeOptions"
+        :is-store-loading="isStoreLoading"
+        :period="period"
+        :is-exporting="isExporting"
+        @update:selected-store-id="setSelectedStoreId"
+        @update:period="setPeriod"
+        @export="handleExport"
+      />
+
+      <div v-if="!selectedStoreId" class="ca-empty">
+        <Empty description="暂无门店，请先创建门店" />
+      </div>
+
+      <Spin v-else :spinning="isOverviewLoading">
+        <AnalysisStatsGrid :overview="overview" @segment="openSegmentByCode" />
+
+        <div class="ca-grid">
+          <GrowthTrendCard
+            :points="overview.growthTrend"
+            @segment="openSegmentByCode"
+          />
+
+          <CompositionCard
+            :items="overview.composition"
+            :total-customers="overview.totalCustomers"
+            @segment="openSegmentByCode"
+          />
+
+          <AmountDistributionCard
+            :items="overview.amountDistribution"
+            @segment="openSegmentByCode"
+          />
+
+          <RfmMatrixCard
+            :rows="overview.rfmRows"
+            @segment="openSegmentByCode"
+          />
+
+          <TopCustomerTableCard
+            :rows="overview.topCustomers"
+            @detail="openTopCustomerDetail"
+            @segment="openSegmentByCode"
+          />
+        </div>
+      </Spin>
+    </div>
+
+    <SegmentDrawer
+      :open="isSegmentDrawerOpen"
+      :loading="isSegmentLoading"
+      :result="segmentResult"
+      :pagination="segmentPagination"
+      :keyword="segmentKeyword"
+      @close="setSegmentDrawerOpen(false)"
+      @update:keyword="setSegmentKeyword"
+      @search="handleSegmentSearch"
+      @page-change="handleSegmentPageChange"
+      @detail="openDetail"
+      @profile="openProfile"
+      @member="openMember"
+    />
+
+    <CustomerDetailDrawer
+      :open="isDetailDrawerOpen"
+      :loading="isDetailLoading"
+      :detail="detail"
+      :show-member-action="true"
+      @close="setDetailDrawerOpen(false)"
+      @profile="openProfile"
+      @profile-page="openProfilePage"
+      @member="openMemberFromDetail"
+    />
+
+    <CustomerProfileDrawer
+      :open="isProfileDrawerOpen"
+      :loading="isProfileLoading"
+      :profile="profile"
+      @close="setProfileDrawerOpen(false)"
+    />
+
+    <MemberDetailDrawer
+      :open="isMemberDrawerOpen"
+      :loading="isMemberLoading"
+      :detail="memberDetail"
+      @close="setMemberDrawerOpen(false)"
+    />
+  </Page>
+</template>
+
+<style lang="less">
+@import './styles/index.less';
+</style>

apps/web-antd/src/views/customer/analysis/styles/base.less

@@ -0,0 +1,35 @@
+.page-customer-analysis {
+  .ant-card {
+    border-radius: 10px;
+  }
+
+  .ant-drawer {
+    .ant-drawer-header {
+      padding: 14px 18px;
+      border-bottom: 1px solid #f0f0f0;
+    }
+
+    .ant-drawer-body {
+      padding: 16px 20px;
+    }
+
+    .ant-drawer-footer {
+      padding: 12px 20px;
+      border-top: 1px solid #f0f0f0;
+    }
+  }
+}
+
+.ca-page {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.ca-empty {
+  padding: 48px 16px;
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 10px;
+  box-shadow: 0 2px 8px rgb(15 23 42 / 6%);
+}

apps/web-antd/src/views/customer/analysis/styles/cards.less

@@ -0,0 +1,327 @@
+.ca-stats {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 12px;
+}
+
+.ca-stat {
+  display: block;
+  padding: 16px 20px;
+  text-align: left;
+  cursor: pointer;
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 10px;
+  box-shadow: 0 2px 8px rgb(15 23 42 / 6%);
+  transition: all 0.2s ease;
+
+  &:hover {
+    box-shadow: 0 6px 14px rgb(15 23 42 / 10%);
+    transform: translateY(-1px);
+  }
+
+  .label {
+    margin-bottom: 6px;
+    font-size: 13px;
+    color: rgb(0 0 0 / 45%);
+  }
+
+  .val {
+    font-size: 24px;
+    font-weight: 700;
+    line-height: 1.2;
+    color: rgb(0 0 0 / 88%);
+
+    &.blue {
+      color: #1677ff;
+    }
+
+    &.green {
+      color: #52c41a;
+    }
+
+    &.orange {
+      color: #fa8c16;
+    }
+  }
+
+  .sub {
+    margin-top: 4px;
+    font-size: 12px;
+    color: rgb(0 0 0 / 45%);
+  }
+}
+
+.ca-bars {
+  display: flex;
+  gap: 6px;
+  align-items: flex-end;
+  height: 140px;
+}
+
+.ca-bar-col {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  gap: 4px;
+  align-items: center;
+  min-width: 0;
+  padding: 0;
+  cursor: pointer;
+  background: transparent;
+  border: none;
+}
+
+.ca-bar-val {
+  width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  font-size: 11px;
+  color: rgb(0 0 0 / 65%);
+  text-align: center;
+  white-space: nowrap;
+}
+
+.ca-bar {
+  width: 100%;
+  background: #1677ff;
+  border-radius: 4px 4px 0 0;
+  opacity: 0.8;
+  transition: all 0.2s ease;
+}
+
+.ca-bar-col:hover .ca-bar {
+  opacity: 1;
+}
+
+.ca-bar-lbl {
+  font-size: 11px;
+  color: rgb(0 0 0 / 45%);
+}
+
+.ca-donut-wrap {
+  display: flex;
+  gap: 24px;
+  align-items: center;
+}
+
+.ca-donut {
+  position: relative;
+  flex-shrink: 0;
+  width: 130px;
+  height: 130px;
+  border-radius: 50%;
+}
+
+.ca-donut-hole {
+  position: absolute;
+  inset: 24px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  background: #fff;
+  border-radius: 50%;
+
+  .num {
+    font-size: 18px;
+    font-weight: 700;
+    color: rgb(0 0 0 / 88%);
+  }
+
+  .lbl {
+    font-size: 11px;
+    color: rgb(0 0 0 / 45%);
+  }
+}
+
+.ca-legend {
+  flex: 1;
+  min-width: 0;
+}
+
+.ca-legend-item {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  width: 100%;
+  padding: 6px 0;
+  text-align: left;
+  cursor: pointer;
+  background: transparent;
+  border: none;
+}
+
+.ca-legend-dot {
+  flex-shrink: 0;
+  width: 10px;
+  height: 10px;
+  border-radius: 3px;
+}
+
+.ca-legend-label {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  font-size: 13px;
+  color: rgb(0 0 0 / 65%);
+  white-space: nowrap;
+}
+
+.ca-legend-value {
+  font-size: 13px;
+  font-weight: 600;
+  color: rgb(0 0 0 / 88%);
+}
+
+.ca-dist-row {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+  width: 100%;
+  padding: 8px 0;
+  text-align: left;
+  cursor: pointer;
+  background: transparent;
+  border: none;
+}
+
+.ca-dist-label {
+  flex-shrink: 0;
+  width: 90px;
+  font-size: 13px;
+  color: rgb(0 0 0 / 65%);
+}
+
+.ca-dist-bar {
+  flex: 1;
+  height: 20px;
+  overflow: hidden;
+  background: #f0f0f0;
+  border-radius: 4px;
+}
+
+.ca-dist-bar-inner {
+  display: inline-flex;
+  height: 100%;
+  border-radius: 4px;
+  transition: all 0.2s ease;
+}
+
+.ca-dist-val {
+  flex-shrink: 0;
+  width: 60px;
+  font-weight: 500;
+  color: rgb(0 0 0 / 88%);
+  text-align: right;
+}
+
+.ca-rfm {
+  display: grid;
+  grid-template-columns: auto repeat(4, minmax(0, 1fr));
+  gap: 2px;
+  font-size: 12px;
+}
+
+.ca-rfm-header {
+  padding: 8px;
+  font-weight: 600;
+  color: #6b7280;
+  text-align: center;
+  background: #f8f9fb;
+}
+
+.ca-rfm-label {
+  padding: 8px 10px;
+  font-weight: 600;
+  color: #6b7280;
+  white-space: nowrap;
+  background: #f8f9fb;
+}
+
+.ca-rfm-cell {
+  padding: 10px 8px;
+  text-align: center;
+  cursor: pointer;
+  border: none;
+  border-radius: 4px;
+  transition: all 0.2s ease;
+
+  &:hover {
+    transform: scale(1.03);
+  }
+
+  &.hot {
+    color: #1677ff;
+    background: rgb(22 119 255 / 18%);
+  }
+
+  &.warm {
+    color: #1677ff;
+    background: rgb(22 119 255 / 10%);
+  }
+
+  &.cool {
+    color: #fa8c16;
+    background: rgb(250 140 22 / 10%);
+  }
+
+  &.cold {
+    color: rgb(0 0 0 / 45%);
+    background: #f8f9fb;
+  }
+}
+
+.ca-rfm-cell-num {
+  font-weight: 600;
+}
+
+.ca-rfm-cell-label {
+  margin-top: 2px;
+  font-size: 11px;
+  opacity: 0.75;
+}
+
+.ca-top-card {
+  overflow: hidden;
+}
+
+.ca-top-segment-btn {
+  padding-inline: 0;
+}
+
+.ca-top-table {
+  .ant-table-thead > tr > th {
+    font-size: 13px;
+    white-space: nowrap;
+    background: #f8f9fb;
+  }
+
+  .ant-table-tbody > tr > td {
+    vertical-align: middle;
+  }
+}
+
+.ca-top-rank {
+  font-weight: 700;
+  color: #1677ff;
+}
+
+.ca-top-money {
+  font-weight: 600;
+}
+
+.ca-top-tag-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+
+  .ant-tag {
+    margin-inline-end: 0;
+  }
+}
+
+.ca-top-action {
+  padding-inline: 0;
+}

apps/web-antd/src/views/customer/analysis/styles/drawer.less

@@ -0,0 +1,229 @@
+.ca-segment-head {
+  margin-bottom: 12px;
+}
+
+.ca-segment-title {
+  font-size: 16px;
+  font-weight: 600;
+  color: rgb(0 0 0 / 88%);
+}
+
+.ca-segment-desc {
+  margin-top: 3px;
+  font-size: 13px;
+  color: rgb(0 0 0 / 45%);
+}
+
+.ca-segment-toolbar {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  margin-bottom: 12px;
+
+  .ca-segment-search {
+    width: 260px;
+  }
+}
+
+.ca-segment-table {
+  .ant-table-thead > tr > th {
+    white-space: nowrap;
+    background: #f8f9fb;
+  }
+
+  .ant-pagination {
+    margin: 14px 0 0;
+  }
+}
+
+.ca-segment-customer {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+}
+
+.ca-segment-avatar {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  font-size: 14px;
+  font-weight: 600;
+  color: #fff;
+  border-radius: 50%;
+}
+
+.ca-segment-customer-main {
+  min-width: 0;
+}
+
+.ca-segment-customer-name {
+  font-weight: 500;
+  color: rgb(0 0 0 / 88%);
+}
+
+.ca-segment-customer-phone {
+  margin-top: 2px;
+  font-size: 12px;
+  color: rgb(0 0 0 / 45%);
+}
+
+.ca-segment-tag-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+
+  .ant-tag {
+    margin-inline-end: 0;
+  }
+}
+
+.ca-segment-action-wrap {
+  display: flex;
+  gap: 4px;
+  align-items: center;
+}
+
+.ca-segment-action {
+  padding-inline: 0;
+}
+
+.ca-segment-row-dimmed td {
+  opacity: 0.55;
+}
+
+.ca-segment-row-dimmed:hover td {
+  opacity: 0.78;
+}
+
+.ca-member-head {
+  display: flex;
+  gap: 14px;
+  align-items: center;
+  padding-bottom: 16px;
+  margin-bottom: 20px;
+  border-bottom: 1px solid #f5f5f5;
+}
+
+.ca-member-avatar {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+  width: 48px;
+  height: 48px;
+  font-size: 18px;
+  font-weight: 600;
+  color: #fff;
+  background: #1677ff;
+  border-radius: 50%;
+}
+
+.ca-member-head-main {
+  min-width: 0;
+}
+
+.ca-member-name-wrap {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.ca-member-name {
+  font-size: 16px;
+  font-weight: 600;
+  color: rgb(0 0 0 / 88%);
+}
+
+.ca-member-meta {
+  margin-top: 3px;
+  font-size: 12px;
+  color: rgb(0 0 0 / 45%);
+}
+
+.ca-member-overview {
+  display: grid;
+  grid-template-columns: repeat(5, minmax(0, 1fr));
+  gap: 10px;
+  margin-bottom: 20px;
+}
+
+.ca-member-ov-item {
+  padding: 12px 8px;
+  text-align: center;
+  background: #f8f9fb;
+  border-radius: 8px;
+}
+
+.ca-member-ov-val {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  font-size: 16px;
+  font-weight: 700;
+  color: rgb(0 0 0 / 88%);
+  white-space: nowrap;
+}
+
+.ca-member-ov-label {
+  margin-top: 4px;
+  font-size: 11px;
+  color: rgb(0 0 0 / 45%);
+}
+
+.ca-member-section {
+  margin-bottom: 20px;
+}
+
+.ca-member-section-title {
+  padding-left: 10px;
+  margin-bottom: 12px;
+  font-size: 15px;
+  font-weight: 600;
+  color: rgb(0 0 0 / 88%);
+  border-left: 3px solid #1677ff;
+}
+
+.ca-member-tag-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+
+  .ant-tag {
+    margin-inline-end: 0;
+  }
+}
+
+.ca-member-empty-text {
+  font-size: 13px;
+  color: rgb(0 0 0 / 45%);
+}
+
+.ca-member-order-table {
+  .ant-table-thead > tr > th {
+    font-size: 12px;
+    white-space: nowrap;
+    background: #f8f9fb;
+  }
+}
+
+.ca-member-order-status {
+  font-weight: 600;
+
+  &.success {
+    color: #52c41a;
+  }
+
+  &.danger {
+    color: #ff4d4f;
+  }
+
+  &.processing {
+    color: #1677ff;
+  }
+
+  &.default {
+    color: rgb(0 0 0 / 65%);
+  }
+}

apps/web-antd/src/views/customer/analysis/styles/index.less

@@ -0,0 +1,9 @@
+@import './base.less';
+@import './layout.less';
+@import './cards.less';
+@import './drawer.less';
+@import '../../list/styles/drawer.less';
+@import '../../profile/styles/card.less';
+@import '../../profile/styles/table.less';
+@import '../../profile/styles/responsive.less';
+@import './responsive.less';

apps/web-antd/src/views/customer/analysis/styles/layout.less

@@ -0,0 +1,71 @@
+.ca-toolbar {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  align-items: center;
+  padding: 12px 14px;
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 10px;
+  box-shadow: 0 2px 8px rgb(15 23 42 / 6%);
+
+  .ca-store-select {
+    width: 220px;
+  }
+
+  .ca-period-label {
+    font-size: 13px;
+    color: rgb(0 0 0 / 65%);
+  }
+
+  .ca-period-segment {
+    .ant-segmented-item {
+      min-width: 64px;
+      text-align: center;
+    }
+  }
+
+  .ca-export-btn {
+    margin-left: auto;
+  }
+}
+
+.ca-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 14px;
+  margin-top: 12px;
+}
+
+.ca-card {
+  padding: 20px;
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 10px;
+  box-shadow: 0 2px 8px rgb(15 23 42 / 6%);
+}
+
+.ca-card-full {
+  grid-column: 1 / -1;
+}
+
+.ca-card-title-wrap {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 12px;
+}
+
+.ca-card-title {
+  padding-left: 10px;
+  margin-bottom: 12px;
+  font-size: 15px;
+  font-weight: 600;
+  color: rgb(0 0 0 / 88%);
+  border-left: 3px solid #1677ff;
+}
+
+.ca-card-title-wrap .ca-card-title {
+  margin-bottom: 0;
+}

apps/web-antd/src/views/customer/analysis/styles/responsive.less

@@ -0,0 +1,68 @@
+@media (max-width: 1600px) {
+  .ca-stats {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .ca-member-overview {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+  }
+}
+
+@media (max-width: 1024px) {
+  .ca-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .ca-card-full {
+    grid-column: auto;
+  }
+
+  .ca-toolbar {
+    .ca-store-select {
+      width: 100%;
+    }
+
+    .ca-export-btn {
+      margin-left: 0;
+    }
+  }
+
+  .ca-segment-toolbar {
+    .ca-segment-search {
+      width: 100%;
+    }
+  }
+}
+
+@media (max-width: 768px) {
+  .ca-stats {
+    grid-template-columns: 1fr;
+  }
+
+  .ca-donut-wrap {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+
+  .ca-member-overview {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .ca-toolbar {
+    .ca-period-label {
+      width: 100%;
+    }
+
+    .ca-period-segment {
+      width: 100%;
+    }
+
+    .ca-export-btn {
+      width: 100%;
+    }
+  }
+
+  .ca-segment-toolbar {
+    flex-wrap: wrap;
+  }
+}

apps/web-antd/src/views/customer/analysis/types.ts

@@ -0,0 +1,42 @@
+import type {
+  CustomerAnalysisOverviewDto,
+  CustomerAnalysisPeriodFilter,
+  CustomerAnalysisSegmentCode,
+  CustomerAnalysisSegmentListResultDto,
+  CustomerDetailDto,
+  CustomerMemberDetailDto,
+  CustomerProfileDto,
+} from '#/api/customer';
+
+export interface OptionItem {
+  label: string;
+  value: string;
+}
+
+export interface CustomerAnalysisPagePagination {
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+export interface CustomerAnalysisPageState {
+  detail: CustomerDetailDto | null;
+  isDetailDrawerOpen: boolean;
+  isDetailLoading: boolean;
+  isExporting: boolean;
+  isMemberDrawerOpen: boolean;
+  isMemberLoading: boolean;
+  isOverviewLoading: boolean;
+  isProfileDrawerOpen: boolean;
+  isProfileLoading: boolean;
+  isSegmentDrawerOpen: boolean;
+  isSegmentLoading: boolean;
+  memberDetail: CustomerMemberDetailDto | null;
+  overview: CustomerAnalysisOverviewDto;
+  pagination: CustomerAnalysisPagePagination;
+  period: CustomerAnalysisPeriodFilter;
+  profile: CustomerProfileDto | null;
+  segmentCode: CustomerAnalysisSegmentCode;
+  segmentKeyword: string;
+  segmentResult: CustomerAnalysisSegmentListResultDto | null;
+}

apps/web-antd/src/views/customer/list/components/CustomerDetailDrawer.vue

@@ -0,0 +1,251 @@
+<script setup lang="ts">
+import type { CustomerDetailDto } from '#/api/customer';
+
+import { computed } from 'vue';
+
+import { Button, Drawer, Empty, Spin, Tag } from 'ant-design-vue';
+
+import {
+  formatCurrency,
+  formatPercent,
+  resolveTagColor,
+} from '../composables/customer-list-page/helpers';
+
+interface Props {
+  detail: CustomerDetailDto | null;
+  loading: boolean;
+  open: boolean;
+  showMemberAction?: boolean;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  showMemberAction: false,
+});
+
+const emit = defineEmits<{
+  (event: 'close'): void;
+  (event: 'member', customerKey: string): void;
+  (event: 'profile', customerKey: string): void;
+  (event: 'profilePage', customerKey: string): void;
+}>();
+
+const trendMaxAmount = computed(() =>
+  Math.max(0, ...(props.detail?.trend.map((item) => item.amount) ?? [])),
+);
+
+function resolveAvatarText() {
+  const name = props.detail?.name || '';
+  return name ? name.slice(0, 1) : '客';
+}
+
+function resolveTrendHeight(amount: number) {
+  if (trendMaxAmount.value <= 0) {
+    return '0px';
+  }
+
+  const ratio = amount / trendMaxAmount.value;
+  return `${Math.max(14, Math.round(ratio * 86))}px`;
+}
+
+function handleOpenProfile() {
+  const customerKey = props.detail?.customerKey || '';
+  if (!customerKey) {
+    return;
+  }
+
+  emit('profile', customerKey);
+}
+
+function handleOpenProfilePage() {
+  const customerKey = props.detail?.customerKey || '';
+  if (!customerKey) {
+    return;
+  }
+
+  emit('profilePage', customerKey);
+}
+
+function handleOpenMember() {
+  const customerKey = props.detail?.customerKey || '';
+  if (!customerKey) {
+    return;
+  }
+
+  emit('member', customerKey);
+}
+</script>
+
+<template>
+  <Drawer
+    :open="props.open"
+    width="560"
+    title="客户详情"
+    @close="emit('close')"
+  >
+    <Spin :spinning="props.loading">
+      <template v-if="props.detail">
+        <div class="cl-detail-head">
+          <div class="cl-detail-avatar">{{ resolveAvatarText() }}</div>
+          <div class="cl-detail-title-wrap">
+            <div class="cl-detail-name">{{ props.detail.name }}</div>
+            <div class="cl-detail-meta">
+              {{ props.detail.phoneMasked }} · 注册于
+              {{ props.detail.registeredAt }}
+            </div>
+          </div>
+          <div class="cl-detail-tags">
+            <Tag
+              v-for="tag in props.detail.tags"
+              :key="`${tag.code}-${tag.label}`"
+              :color="resolveTagColor(tag.tone)"
+            >
+              {{ tag.label }}
+            </Tag>
+          </div>
+        </div>
+
+        <div class="cl-overview-grid">
+          <div class="cl-overview-item">
+            <div class="label">累计下单</div>
+            <div class="value">{{ props.detail.totalOrders }} 次</div>
+          </div>
+          <div class="cl-overview-item">
+            <div class="label">累计消费</div>
+            <div class="value primary">
+              {{ formatCurrency(props.detail.totalAmount) }}
+            </div>
+          </div>
+          <div class="cl-overview-item">
+            <div class="label">复购率</div>
+            <div class="value success">
+              {{ formatPercent(props.detail.repurchaseRatePercent) }}
+            </div>
+          </div>
+          <div class="cl-overview-item">
+            <div class="label">会员等级</div>
+            <div class="value">
+              {{
+                props.detail.member.isMember
+                  ? props.detail.member.tierName || '会员'
+                  : '未入会'
+              }}
+            </div>
+          </div>
+        </div>
+
+        <div class="cl-drawer-section">
+          <div class="cl-drawer-section-title">消费偏好</div>
+
+          <div class="cl-preference-tags">
+            <template
+              v-if="props.detail.preference.preferredCategories.length > 0"
+            >
+              <Tag
+                v-for="category in props.detail.preference.preferredCategories"
+                :key="category"
+                color="blue"
+              >
+                {{ category }}
+              </Tag>
+            </template>
+            <span v-else class="cl-empty-text">暂无偏好品类</span>
+          </div>
+
+          <div class="cl-preference-list">
+            <div class="cl-preference-row">
+              <span>偏好下单时段</span>
+              <span>{{
+                props.detail.preference.preferredOrderPeaks || '--'
+              }}</span>
+            </div>
+            <div class="cl-preference-row">
+              <span>平均客单价</span>
+              <span>{{ formatCurrency(props.detail.averageAmount) }}</span>
+            </div>
+            <div class="cl-preference-row">
+              <span>常用配送方式</span>
+              <span>{{
+                props.detail.preference.preferredDelivery || '--'
+              }}</span>
+            </div>
+          </div>
+        </div>
+
+        <div class="cl-drawer-section">
+          <div class="cl-drawer-section-title">常购商品 TOP5</div>
+          <div class="cl-top-product-list">
+            <template v-if="props.detail.topProducts.length > 0">
+              <div
+                v-for="product in props.detail.topProducts"
+                :key="`${product.rank}-${product.productName}`"
+                class="cl-top-product-item"
+              >
+                <span class="rank">{{ product.rank }}</span>
+                <span class="name">{{ product.productName }}</span>
+                <span class="count">{{ product.count }}次</span>
+              </div>
+            </template>
+            <Empty v-else description="暂无商品偏好" />
+          </div>
+        </div>
+
+        <div class="cl-drawer-section">
+          <div class="cl-drawer-section-title">近6月消费趋势</div>
+          <div v-if="props.detail.trend.length > 0" class="cl-trend-bar-group">
+            <div
+              v-for="point in props.detail.trend"
+              :key="point.label"
+              class="cl-trend-bar-item"
+            >
+              <div class="amount">{{ formatCurrency(point.amount) }}</div>
+              <div
+                class="bar"
+                :style="{ height: resolveTrendHeight(point.amount) }"
+              ></div>
+              <div class="month">{{ point.label }}</div>
+            </div>
+          </div>
+          <Empty v-else description="暂无趋势数据" />
+        </div>
+
+        <div class="cl-drawer-section">
+          <div class="cl-drawer-section-title">最近订单</div>
+          <div
+            v-if="props.detail.recentOrders.length > 0"
+            class="cl-recent-orders"
+          >
+            <div
+              v-for="order in props.detail.recentOrders"
+              :key="order.orderNo"
+              class="cl-recent-order-item"
+            >
+              <div class="left">
+                <div class="summary">{{ order.itemsSummary }}</div>
+                <div class="meta">
+                  {{ order.orderedAt }} · {{ order.deliveryType }}
+                </div>
+              </div>
+              <div class="amount">{{ formatCurrency(order.amount) }}</div>
+            </div>
+          </div>
+          <Empty v-else description="暂无订单记录" />
+        </div>
+      </template>
+      <Empty v-else description="暂无详情" />
+    </Spin>
+
+    <template #footer>
+      <div class="cl-detail-footer">
+        <Button @click="emit('close')">关闭</Button>
+        <Button @click="handleOpenProfilePage">进入画像页</Button>
+        <Button
+          v-if="props.showMemberAction && props.detail?.member.isMember"
+          @click="handleOpenMember"
+        >
+          会员详情
+        </Button>
+        <Button type="primary" @click="handleOpenProfile">查看完整画像</Button>
+      </div>
+    </template>
+  </Drawer>
+</template>

apps/web-antd/src/views/customer/list/components/CustomerFilterBar.vue

@@ -0,0 +1,125 @@
+<script setup lang="ts">
+import { IconifyIcon } from '@vben/icons';
+
+import { Button, Input, Select } from 'ant-design-vue';
+
+import {
+  CUSTOMER_ORDER_COUNT_OPTIONS,
+  CUSTOMER_REGISTER_PERIOD_OPTIONS,
+  CUSTOMER_TAG_OPTIONS,
+} from '../composables/customer-list-page/constants';
+
+interface OptionItem {
+  label: string;
+  value: string;
+}
+
+interface FilterState {
+  keyword: string;
+  orderCountRange: string;
+  registerPeriod: string;
+  tag: string;
+}
+
+interface Props {
+  filters: FilterState;
+  isExporting: boolean;
+  isStoreLoading: boolean;
+  selectedStoreId: string;
+  showExport: boolean;
+  storeOptions: OptionItem[];
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'export'): void;
+  (event: 'reset'): void;
+  (event: 'search'): void;
+  (event: 'update:keyword', value: string): void;
+  (event: 'update:orderCountRange', value: string): void;
+  (event: 'update:registerPeriod', value: string): void;
+  (event: 'update:selectedStoreId', value: string): void;
+  (event: 'update:tag', value: string): void;
+}>();
+
+function handleStoreChange(value: unknown) {
+  if (typeof value === 'number' || typeof value === 'string') {
+    emit('update:selectedStoreId', String(value));
+    return;
+  }
+
+  emit('update:selectedStoreId', '');
+}
+</script>
+
+<template>
+  <div class="cl-toolbar">
+    <Select
+      class="cl-store-select"
+      :value="props.selectedStoreId"
+      placeholder="全部门店"
+      :loading="props.isStoreLoading"
+      :options="props.storeOptions"
+      :disabled="props.isStoreLoading || props.storeOptions.length === 0"
+      @update:value="(value) => handleStoreChange(value)"
+    />
+
+    <Select
+      class="cl-tag-select"
+      :value="props.filters.tag"
+      :options="CUSTOMER_TAG_OPTIONS"
+      @update:value="(value) => emit('update:tag', String(value ?? 'all'))"
+    />
+
+    <Select
+      class="cl-order-count-select"
+      :value="props.filters.orderCountRange"
+      :options="CUSTOMER_ORDER_COUNT_OPTIONS"
+      @update:value="
+        (value) => emit('update:orderCountRange', String(value ?? 'all'))
+      "
+    />
+
+    <Select
+      class="cl-register-period-select"
+      :value="props.filters.registerPeriod"
+      :options="CUSTOMER_REGISTER_PERIOD_OPTIONS"
+      @update:value="
+        (value) => emit('update:registerPeriod', String(value ?? 'all'))
+      "
+    />
+
+    <Input
+      class="cl-search-input"
+      :value="props.filters.keyword"
+      placeholder="搜索客户姓名 / 手机号"
+      allow-clear
+      @update:value="(value) => emit('update:keyword', String(value ?? ''))"
+      @press-enter="emit('search')"
+    >
+      <template #prefix>
+        <IconifyIcon icon="lucide:search" class="cl-search-icon" />
+      </template>
+    </Input>
+
+    <Button class="cl-query-btn" type="primary" @click="emit('search')">
+      查询
+    </Button>
+    <Button class="cl-reset-btn" @click="emit('reset')">重置</Button>
+
+    <div class="cl-toolbar-right">
+      <Button
+        v-if="props.showExport"
+        class="cl-export-btn"
+        :loading="props.isExporting"
+        @click="emit('export')"
+      >
+        <template #icon>
+          <IconifyIcon icon="lucide:download" />
+        </template>
+        导出
+      </Button>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/customer/list/components/CustomerProfileDrawer.vue

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+import type { CustomerProfileDto } from '#/api/customer';
+
+import { Drawer, Empty, Spin } from 'ant-design-vue';
+
+import CustomerProfilePanel from '#/views/customer/profile/components/CustomerProfilePanel.vue';
+
+interface Props {
+  loading: boolean;
+  open: boolean;
+  profile: CustomerProfileDto | null;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'close'): void;
+}>();
+</script>
+
+<template>
+  <Drawer
+    :open="props.open"
+    width="860"
+    title="客户完整画像"
+    @close="emit('close')"
+  >
+    <Spin :spinning="props.loading">
+      <template v-if="props.profile">
+        <CustomerProfilePanel :profile="props.profile" />
+      </template>
+      <Empty v-else description="暂无画像" />
+    </Spin>
+  </Drawer>
+</template>

apps/web-antd/src/views/customer/list/components/CustomerStatsBar.vue

@@ -0,0 +1,56 @@
+<script setup lang="ts">
+import type { CustomerListStatsDto } from '#/api/customer';
+
+import {
+  formatCurrency,
+  formatInteger,
+  formatPercent,
+} from '../composables/customer-list-page/helpers';
+
+interface Props {
+  stats: CustomerListStatsDto;
+}
+
+const props = defineProps<Props>();
+</script>
+
+<template>
+  <div class="cl-stats">
+    <div class="cl-stat-card">
+      <div class="cl-stat-label">客户总数</div>
+      <div class="cl-stat-value blue">
+        {{ formatInteger(props.stats.totalCustomers) }}
+      </div>
+      <div class="cl-stat-sub">累计注册客户</div>
+    </div>
+
+    <div class="cl-stat-card">
+      <div class="cl-stat-label">本月新增</div>
+      <div class="cl-stat-value green">
+        {{ props.stats.monthlyNewCustomers >= 0 ? '+' : ''
+        }}{{ formatInteger(props.stats.monthlyNewCustomers) }}
+      </div>
+      <div class="cl-stat-sub">
+        较上月
+        {{ props.stats.monthlyGrowthRatePercent >= 0 ? '+' : ''
+        }}{{ formatPercent(props.stats.monthlyGrowthRatePercent) }}
+      </div>
+    </div>
+
+    <div class="cl-stat-card">
+      <div class="cl-stat-label">活跃客户</div>
+      <div class="cl-stat-value orange">
+        {{ formatInteger(props.stats.activeCustomers) }}
+      </div>
+      <div class="cl-stat-sub">近30天有下单</div>
+    </div>
+
+    <div class="cl-stat-card">
+      <div class="cl-stat-label">客均消费</div>
+      <div class="cl-stat-value">
+        {{ formatCurrency(props.stats.averageAmountLast30Days) }}
+      </div>
+      <div class="cl-stat-sub">近30天平均</div>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/customer/list/components/CustomerTableCard.vue

@@ -0,0 +1,174 @@
+<script setup lang="ts">
+import type { TablePaginationConfig, TableProps } from 'ant-design-vue';
+
+import type { CustomerListItemDto, CustomerTagDto } from '#/api/customer';
+
+import { h } from 'vue';
+
+import { Button, Table, Tag } from 'ant-design-vue';
+
+import {
+  formatCurrency,
+  resolveTagColor,
+} from '../composables/customer-list-page/helpers';
+
+interface PaginationState {
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+interface Props {
+  loading: boolean;
+  pagination: PaginationState;
+  rows: CustomerListItemDto[];
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'detail', customerKey: string): void;
+  (event: 'pageChange', page: number, pageSize: number): void;
+}>();
+
+function renderCustomerCell(record: CustomerListItemDto) {
+  return h('div', { class: 'cl-customer-cell' }, [
+    h(
+      'span',
+      {
+        class: 'cl-avatar',
+        style: {
+          background: record.avatarColor || '#1677ff',
+        },
+      },
+      record.avatarText || record.name.slice(0, 1) || '客',
+    ),
+    h('div', { class: 'cl-customer-main' }, [
+      h('div', { class: 'cl-customer-name' }, record.name || '--'),
+      h('div', { class: 'cl-customer-phone' }, record.phoneMasked || '--'),
+    ]),
+  ]);
+}
+
+function renderOrderCountCell(record: CustomerListItemDto) {
+  return h('div', { class: 'cl-order-count-cell' }, [
+    h('span', { class: 'cl-order-count-value' }, String(record.orderCount)),
+    h('span', {
+      class: 'cl-order-count-bar',
+      style: {
+        width: `${Math.max(4, Math.min(100, record.orderCountBarPercent))}%`,
+      },
+    }),
+  ]);
+}
+
+function renderTags(tags: CustomerTagDto[]) {
+  if (tags.length === 0) {
+    return '--';
+  }
+
+  return h(
+    'div',
+    { class: 'cl-tag-list' },
+    tags.map((tag) =>
+      h(
+        Tag,
+        {
+          color: resolveTagColor(tag.tone),
+        },
+        () => tag.label,
+      ),
+    ),
+  );
+}
+
+const columns: TableProps['columns'] = [
+  {
+    title: '客户信息',
+    dataIndex: 'name',
+    width: 220,
+    customRender: ({ record }) =>
+      renderCustomerCell(record as CustomerListItemDto),
+  },
+  {
+    title: '下单次数',
+    dataIndex: 'orderCount',
+    width: 170,
+    customRender: ({ record }) =>
+      renderOrderCountCell(record as CustomerListItemDto),
+  },
+  {
+    title: '累计消费',
+    dataIndex: 'totalAmount',
+    width: 130,
+    customRender: ({ text }) =>
+      h('span', { class: 'cl-amount' }, formatCurrency(Number(text || 0))),
+  },
+  {
+    title: '客单价',
+    dataIndex: 'averageAmount',
+    width: 120,
+    customRender: ({ text }) =>
+      h(
+        'span',
+        { class: 'cl-average-amount' },
+        formatCurrency(Number(text || 0)),
+      ),
+  },
+  {
+    title: '最近下单',
+    dataIndex: 'lastOrderAt',
+    width: 130,
+  },
+  {
+    title: '客户标签',
+    dataIndex: 'tags',
+    customRender: ({ record }) =>
+      renderTags((record as CustomerListItemDto).tags),
+  },
+  {
+    title: '操作',
+    key: 'action',
+    width: 90,
+    customRender: ({ record }) =>
+      h(
+        Button,
+        {
+          type: 'link',
+          class: 'cl-detail-action',
+          onClick: () =>
+            emit('detail', String((record as CustomerListItemDto).customerKey)),
+        },
+        () => '查看',
+      ),
+  },
+];
+
+function handleTableChange(next: TablePaginationConfig) {
+  emit('pageChange', Number(next.current || 1), Number(next.pageSize || 10));
+}
+
+function resolveRowClassName(record: CustomerListItemDto) {
+  return record.isDimmed ? 'cl-row-dimmed' : '';
+}
+</script>
+
+<template>
+  <div class="cl-table-card">
+    <Table
+      row-key="customerKey"
+      :columns="columns"
+      :data-source="props.rows"
+      :loading="props.loading"
+      :pagination="{
+        current: props.pagination.page,
+        pageSize: props.pagination.pageSize,
+        total: props.pagination.total,
+        showSizeChanger: false,
+        showTotal: (total: number) => `共 ${total} 条`,
+      }"
+      :row-class-name="resolveRowClassName"
+      @change="handleTableChange"
+    />
+  </div>
+</template>

apps/web-antd/src/views/customer/list/composables/customer-list-page/constants.ts

@@ -0,0 +1,60 @@
+import type { OptionItem } from '../../types';
+
+import type { CustomerListStatsDto } from '#/api/customer';
+import type { CustomerFilterState } from '#/views/customer/list/types';
+
+/**
+ * 文件职责：客户列表页常量与默认值。
+ */
+
+/** 客户列表查看权限。 */
+export const CUSTOMER_LIST_VIEW_PERMISSION = 'tenant:customer:list:view';
+
+/** 客户列表管理权限（导出）。 */
+export const CUSTOMER_LIST_MANAGE_PERMISSION = 'tenant:customer:list:manage';
+
+/** 客户标签筛选项。 */
+export const CUSTOMER_TAG_OPTIONS: OptionItem[] = [
+  { label: '全部标签', value: 'all' },
+  { label: '高价值', value: 'high_value' },
+  { label: '活跃客户', value: 'active' },
+  { label: '沉睡客户', value: 'dormant' },
+  { label: '流失客户', value: 'churn' },
+  { label: '新客户', value: 'new_customer' },
+];
+
+/** 下单次数筛选项。 */
+export const CUSTOMER_ORDER_COUNT_OPTIONS: OptionItem[] = [
+  { label: '全部次数', value: 'all' },
+  { label: '1次', value: 'once' },
+  { label: '2-5次', value: 'two_to_five' },
+  { label: '6-10次', value: 'six_to_ten' },
+  { label: '10次以上', value: 'ten_plus' },
+];
+
+/** 注册周期筛选项。 */
+export const CUSTOMER_REGISTER_PERIOD_OPTIONS: OptionItem[] = [
+  { label: '全部时间', value: 'all' },
+  { label: '最近7天', value: '7d' },
+  { label: '最近30天', value: '30d' },
+  { label: '最近90天', value: '90d' },
+];
+
+/** 默认筛选项。 */
+export function createDefaultFilters(): CustomerFilterState {
+  return {
+    keyword: '',
+    tag: 'all',
+    orderCountRange: 'all',
+    registerPeriod: 'all',
+  };
+}
+
+/** 默认统计值。 */
+export const DEFAULT_STATS: CustomerListStatsDto = {
+  totalCustomers: 0,
+  monthlyNewCustomers: 0,
+  monthlyGrowthRatePercent: 0,
+  activeCustomers: 0,
+  averageAmountLast30Days: 0,
+};

apps/web-antd/src/views/customer/list/composables/customer-list-page/data-actions.ts

@@ -0,0 +1,113 @@
+import type { CustomerFilterState, CustomerPaginationState } from '../../types';
+
+import type { CustomerListItemDto, CustomerListStatsDto } from '#/api/customer';
+import type { StoreListItemDto } from '#/api/store';
+
+import { getCustomerListApi, getCustomerListStatsApi } from '#/api/customer';
+import { getStoreListApi } from '#/api/store';
+
+import { DEFAULT_STATS } from './constants';
+import { buildFilterPayload, buildQueryPayload } from './helpers';
+
+interface DataActionOptions {
+  filters: CustomerFilterState;
+  isListLoading: { value: boolean };
+  isStatsLoading: { value: boolean };
+  isStoreLoading: { value: boolean };
+  pagination: CustomerPaginationState;
+  rows: { value: CustomerListItemDto[] };
+  selectedStoreId: { value: string };
+  stats: CustomerListStatsDto;
+  stores: { value: StoreListItemDto[] };
+}
+
+/**
+ * 文件职责：客户列表页数据加载动作。
+ */
+export function createDataActions(options: DataActionOptions) {
+  function resetStats() {
+    options.stats.totalCustomers = DEFAULT_STATS.totalCustomers;
+    options.stats.monthlyNewCustomers = DEFAULT_STATS.monthlyNewCustomers;
+    options.stats.monthlyGrowthRatePercent =
+      DEFAULT_STATS.monthlyGrowthRatePercent;
+    options.stats.activeCustomers = DEFAULT_STATS.activeCustomers;
+    options.stats.averageAmountLast30Days =
+      DEFAULT_STATS.averageAmountLast30Days;
+  }
+
+  async function loadStores() {
+    options.isStoreLoading.value = true;
+    try {
+      const result = await getStoreListApi({ page: 1, pageSize: 200 });
+      options.stores.value = result.items;
+
+      if (result.items.length === 0) {
+        options.selectedStoreId.value = '';
+        options.rows.value = [];
+        options.pagination.total = 0;
+        resetStats();
+        return;
+      }
+
+      const matched = result.items.some(
+        (item) => item.id === options.selectedStoreId.value,
+      );
+      if (!matched) {
+        options.selectedStoreId.value = result.items[0]?.id ?? '';
+      }
+    } finally {
+      options.isStoreLoading.value = false;
+    }
+  }
+
+  async function loadPageData() {
+    if (!options.selectedStoreId.value) {
+      options.rows.value = [];
+      options.pagination.total = 0;
+      resetStats();
+      return;
+    }
+
+    const queryPayload = buildQueryPayload(
+      options.selectedStoreId.value,
+      options.filters,
+      options.pagination.page,
+      options.pagination.pageSize,
+    );
+    const filterPayload = buildFilterPayload(
+      options.selectedStoreId.value,
+      options.filters,
+    );
+
+    options.isListLoading.value = true;
+    options.isStatsLoading.value = true;
+    try {
+      const [listResult, statsResult] = await Promise.all([
+        getCustomerListApi(queryPayload),
+        getCustomerListStatsApi(filterPayload),
+      ]);
+
+      options.rows.value = listResult.items;
+      options.pagination.total = listResult.total;
+      options.pagination.page = listResult.page;
+      options.pagination.pageSize = listResult.pageSize;
+
+      options.stats.totalCustomers = statsResult.totalCustomers;
+      options.stats.monthlyNewCustomers = statsResult.monthlyNewCustomers;
+      options.stats.monthlyGrowthRatePercent =
+        statsResult.monthlyGrowthRatePercent;
+      options.stats.activeCustomers = statsResult.activeCustomers;
+      options.stats.averageAmountLast30Days =
+        statsResult.averageAmountLast30Days;
+    } finally {
+      options.isListLoading.value = false;
+      options.isStatsLoading.value = false;
+    }
+  }
+
+  return {
+    loadPageData,
+    loadStores,
+    resetStats,
+  };
+}

apps/web-antd/src/views/customer/list/composables/customer-list-page/drawer-actions.ts

@@ -0,0 +1,79 @@
+import type { CustomerDetailDto, CustomerProfileDto } from '#/api/customer';
+
+import { getCustomerDetailApi, getCustomerProfileApi } from '#/api/customer';
+
+interface DrawerActionOptions {
+  detail: { value: CustomerDetailDto | null };
+  isDetailDrawerOpen: { value: boolean };
+  isDetailLoading: { value: boolean };
+  isProfileDrawerOpen: { value: boolean };
+  isProfileLoading: { value: boolean };
+  profile: { value: CustomerProfileDto | null };
+  selectedStoreId: { value: string };
+}
+
+/**
+ * 文件职责：客户详情与画像抽屉动作。
+ */
+export function createDrawerActions(options: DrawerActionOptions) {
+  function setDetailDrawerOpen(value: boolean) {
+    options.isDetailDrawerOpen.value = value;
+    if (!value) {
+      options.detail.value = null;
+      options.isProfileDrawerOpen.value = false;
+      options.profile.value = null;
+    }
+  }
+
+  function setProfileDrawerOpen(value: boolean) {
+    options.isProfileDrawerOpen.value = value;
+    if (!value) {
+      options.profile.value = null;
+    }
+  }
+
+  async function openDetail(customerKey: string) {
+    if (!options.selectedStoreId.value || !customerKey) {
+      return;
+    }
+
+    options.isDetailDrawerOpen.value = true;
+    options.detail.value = null;
+    options.isProfileDrawerOpen.value = false;
+    options.profile.value = null;
+    options.isDetailLoading.value = true;
+    try {
+      options.detail.value = await getCustomerDetailApi({
+        storeId: options.selectedStoreId.value,
+        customerKey,
+      });
+    } finally {
+      options.isDetailLoading.value = false;
+    }
+  }
+
+  async function openProfile(customerKey: string) {
+    if (!options.selectedStoreId.value || !customerKey) {
+      return;
+    }
+
+    options.isProfileDrawerOpen.value = true;
+    options.profile.value = null;
+    options.isProfileLoading.value = true;
+    try {
+      options.profile.value = await getCustomerProfileApi({
+        storeId: options.selectedStoreId.value,
+        customerKey,
+      });
+    } finally {
+      options.isProfileLoading.value = false;
+    }
+  }
+
+  return {
+    openDetail,
+    openProfile,
+    setDetailDrawerOpen,
+    setProfileDrawerOpen,
+  };
+}

apps/web-antd/src/views/customer/list/composables/customer-list-page/export-actions.ts

@@ -0,0 +1,45 @@
+import type { CustomerFilterState } from '../../types';
+
+import { message } from 'ant-design-vue';
+
+import { exportCustomerCsvApi } from '#/api/customer';
+
+import { buildFilterPayload, downloadBase64File } from './helpers';
+
+interface ExportActionOptions {
+  canManage: { value: boolean };
+  filters: CustomerFilterState;
+  isExporting: { value: boolean };
+  selectedStoreId: { value: string };
+}
+
+/**
+ * 文件职责：客户列表导出动作。
+ */
+export function createExportActions(options: ExportActionOptions) {
+  async function handleExport() {
+    if (!options.selectedStoreId.value) {
+      return;
+    }
+
+    if (!options.canManage.value) {
+      message.warning('暂无导出权限');
+      return;
+    }
+
+    options.isExporting.value = true;
+    try {
+      const result = await exportCustomerCsvApi(
+        buildFilterPayload(options.selectedStoreId.value, options.filters),
+      );
+      downloadBase64File(result.fileName, result.fileContentBase64);
+      message.success(`导出成功，共 ${result.totalCount} 条记录`);
+    } finally {
+      options.isExporting.value = false;
+    }
+  }
+
+  return {
+    handleExport,
+  };
+}

apps/web-antd/src/views/customer/list/composables/customer-list-page/filter-actions.ts

@@ -0,0 +1,63 @@
+import type { CustomerFilterState, CustomerPaginationState } from '../../types';
+
+import { createDefaultFilters } from './constants';
+
+interface FilterActionOptions {
+  filters: CustomerFilterState;
+  loadPageData: () => Promise<void>;
+  pagination: CustomerPaginationState;
+}
+
+/**
+ * 文件职责：客户列表筛选与分页动作。
+ */
+export function createFilterActions(options: FilterActionOptions) {
+  function setTag(value: string) {
+    options.filters.tag = (value || 'all') as CustomerFilterState['tag'];
+  }
+
+  function setOrderCountRange(value: string) {
+    options.filters.orderCountRange = (value ||
+      'all') as CustomerFilterState['orderCountRange'];
+  }
+
+  function setRegisterPeriod(value: string) {
+    options.filters.registerPeriod = (value ||
+      'all') as CustomerFilterState['registerPeriod'];
+  }
+
+  function setKeyword(value: string) {
+    options.filters.keyword = value;
+  }
+
+  async function handleSearch() {
+    options.pagination.page = 1;
+    await options.loadPageData();
+  }
+
+  async function handleReset() {
+    const defaults = createDefaultFilters();
+    options.filters.keyword = defaults.keyword;
+    options.filters.tag = defaults.tag;
+    options.filters.orderCountRange = defaults.orderCountRange;
+    options.filters.registerPeriod = defaults.registerPeriod;
+    options.pagination.page = 1;
+    await options.loadPageData();
+  }
+
+  async function handlePageChange(page: number, pageSize: number) {
+    options.pagination.page = page;
+    options.pagination.pageSize = pageSize;
+    await options.loadPageData();
+  }
+
+  return {
+    handlePageChange,
+    handleReset,
+    handleSearch,
+    setKeyword,
+    setOrderCountRange,
+    setRegisterPeriod,
+    setTag,
+  };
+}

apps/web-antd/src/views/customer/list/composables/customer-list-page/helpers.ts

@@ -0,0 +1,105 @@
+import type {
+  CustomerFilterQueryPayload,
+  CustomerFilterState,
+  CustomerListQueryPayload,
+} from '../../types';
+
+import type {
+  CustomerOrderCountRangeFilter,
+  CustomerRegisterPeriodFilter,
+  CustomerTagFilter,
+} from '#/api/customer';
+
+function normalizeTag(tag: CustomerTagFilter): CustomerTagFilter | undefined {
+  return tag === 'all' ? undefined : tag;
+}
+
+function normalizeOrderCountRange(
+  orderCountRange: CustomerOrderCountRangeFilter,
+): CustomerOrderCountRangeFilter | undefined {
+  return orderCountRange === 'all' ? undefined : orderCountRange;
+}
+
+function normalizeRegisterPeriod(
+  registerPeriod: CustomerRegisterPeriodFilter,
+): CustomerRegisterPeriodFilter | undefined {
+  return registerPeriod === 'all' ? undefined : registerPeriod;
+}
+
+export function buildFilterPayload(
+  storeId: string,
+  filters: CustomerFilterState,
+): CustomerFilterQueryPayload {
+  return {
+    storeId,
+    keyword: filters.keyword.trim() || undefined,
+    tag: normalizeTag(filters.tag),
+    orderCountRange: normalizeOrderCountRange(filters.orderCountRange),
+    registerPeriod: normalizeRegisterPeriod(filters.registerPeriod),
+  };
+}
+
+export function buildQueryPayload(
+  storeId: string,
+  filters: CustomerFilterState,
+  page: number,
+  pageSize: number,
+): CustomerListQueryPayload {
+  return {
+    ...buildFilterPayload(storeId, filters),
+    page,
+    pageSize,
+  };
+}
+
+export function formatCurrency(value: number) {
+  return new Intl.NumberFormat('zh-CN', {
+    style: 'currency',
+    currency: 'CNY',
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  }).format(Number.isFinite(value) ? value : 0);
+}
+
+export function formatInteger(value: number) {
+  return new Intl.NumberFormat('zh-CN', {
+    maximumFractionDigits: 0,
+  }).format(Number.isFinite(value) ? value : 0);
+}
+
+export function formatPercent(value: number) {
+  if (!Number.isFinite(value)) {
+    return '0%';
+  }
+  return `${value.toFixed(1).replace(/\.0$/, '')}%`;
+}
+
+function decodeBase64ToBlob(base64: string) {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.codePointAt(index) ?? 0;
+  }
+  return new Blob([bytes], { type: 'text/csv;charset=utf-8;' });
+}
+
+export function downloadBase64File(
+  fileName: string,
+  fileContentBase64: string,
+) {
+  const blob = decodeBase64ToBlob(fileContentBase64);
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+  anchor.href = url;
+  anchor.download = fileName;
+  anchor.click();
+  URL.revokeObjectURL(url);
+}
+
+export function resolveTagColor(tone: string) {
+  if (tone === 'orange') return 'orange';
+  if (tone === 'green') return 'green';
+  if (tone === 'gray') return 'default';
+  if (tone === 'red') return 'red';
+  return 'blue';
+}

apps/web-antd/src/views/customer/list/composables/customer-list-page/navigation-actions.ts

@@ -0,0 +1,33 @@
+import type { Router } from 'vue-router';
+
+interface NavigationActionOptions {
+  router: Router;
+  selectedStoreId: { value: string };
+}
+
+/**
+ * 文件职责：客户列表页导航动作。
+ */
+export function createNavigationActions(options: NavigationActionOptions) {
+  function openProfilePage(customerKey: string) {
+    if (!customerKey) {
+      return;
+    }
+
+    const query: Record<string, string> = {
+      customerKey,
+    };
+    if (options.selectedStoreId.value) {
+      query.storeId = options.selectedStoreId.value;
+    }
+
+    void options.router.push({
+      path: '/customer/profile',
+      query,
+    });
+  }
+
+  return {
+    openProfilePage,
+  };
+}

apps/web-antd/src/views/customer/list/composables/useCustomerListPage.ts

@@ -0,0 +1,183 @@
+import type {
+  CustomerDetailDto,
+  CustomerListItemDto,
+  CustomerProfileDto,
+} from '#/api/customer';
+import type { StoreListItemDto } from '#/api/store';
+
+/**
+ * 文件职责：客户列表页面状态与动作编排。
+ */
+import { computed, onActivated, onMounted, reactive, ref, watch } from 'vue';
+import { useRouter } from 'vue-router';
+
+import { useAccessStore } from '@vben/stores';
+
+import {
+  createDefaultFilters,
+  CUSTOMER_LIST_MANAGE_PERMISSION,
+  DEFAULT_STATS,
+} from './customer-list-page/constants';
+import { createDataActions } from './customer-list-page/data-actions';
+import { createDrawerActions } from './customer-list-page/drawer-actions';
+import { createExportActions } from './customer-list-page/export-actions';
+import { createFilterActions } from './customer-list-page/filter-actions';
+import { createNavigationActions } from './customer-list-page/navigation-actions';
+
+export function useCustomerListPage() {
+  const accessStore = useAccessStore();
+  const router = useRouter();
+
+  const stores = ref<StoreListItemDto[]>([]);
+  const selectedStoreId = ref('');
+  const isStoreLoading = ref(false);
+
+  const filters = reactive(createDefaultFilters());
+  const rows = ref<CustomerListItemDto[]>([]);
+  const pagination = reactive({
+    page: 1,
+    pageSize: 10,
+    total: 0,
+  });
+
+  const stats = reactive({ ...DEFAULT_STATS });
+  const isListLoading = ref(false);
+  const isStatsLoading = ref(false);
+
+  const detail = ref<CustomerDetailDto | null>(null);
+  const isDetailDrawerOpen = ref(false);
+  const isDetailLoading = ref(false);
+
+  const profile = ref<CustomerProfileDto | null>(null);
+  const isProfileDrawerOpen = ref(false);
+  const isProfileLoading = ref(false);
+
+  const isExporting = ref(false);
+
+  const storeOptions = computed(() =>
+    stores.value.map((item) => ({
+      label: item.name,
+      value: item.id,
+    })),
+  );
+
+  const accessCodeSet = computed(
+    () => new Set((accessStore.accessCodes ?? []).map(String)),
+  );
+  const canManage = computed(() =>
+    accessCodeSet.value.has(CUSTOMER_LIST_MANAGE_PERMISSION),
+  );
+
+  const { loadPageData, loadStores, resetStats } = createDataActions({
+    stores,
+    selectedStoreId,
+    filters,
+    rows,
+    pagination,
+    stats,
+    isStoreLoading,
+    isListLoading,
+    isStatsLoading,
+  });
+
+  const {
+    handlePageChange,
+    handleReset,
+    handleSearch,
+    setKeyword,
+    setOrderCountRange,
+    setRegisterPeriod,
+    setTag,
+  } = createFilterActions({
+    filters,
+    pagination,
+    loadPageData,
+  });
+
+  const { openDetail, openProfile, setDetailDrawerOpen, setProfileDrawerOpen } =
+    createDrawerActions({
+      selectedStoreId,
+      detail,
+      isDetailDrawerOpen,
+      isDetailLoading,
+      profile,
+      isProfileDrawerOpen,
+      isProfileLoading,
+    });
+
+  const { handleExport } = createExportActions({
+    selectedStoreId,
+    filters,
+    isExporting,
+    canManage,
+  });
+
+  const { openProfilePage } = createNavigationActions({
+    selectedStoreId,
+    router,
+  });
+
+  function setSelectedStoreId(value: string) {
+    selectedStoreId.value = value;
+  }
+
+  watch(selectedStoreId, async (storeId) => {
+    if (!storeId) {
+      rows.value = [];
+      pagination.total = 0;
+      detail.value = null;
+      profile.value = null;
+      isDetailDrawerOpen.value = false;
+      isProfileDrawerOpen.value = false;
+      resetStats();
+      return;
+    }
+
+    pagination.page = 1;
+    await loadPageData();
+  });
+
+  onMounted(() => {
+    void loadStores();
+  });
+
+  onActivated(() => {
+    if (stores.value.length === 0 || !selectedStoreId.value) {
+      void loadStores();
+    }
+  });
+
+  return {
+    canManage,
+    detail,
+    filters,
+    handleExport,
+    handlePageChange,
+    handleReset,
+    handleSearch,
+    isDetailDrawerOpen,
+    isDetailLoading,
+    isExporting,
+    isListLoading,
+    isProfileDrawerOpen,
+    isProfileLoading,
+    isStatsLoading,
+    isStoreLoading,
+    openDetail,
+    openProfile,
+    openProfilePage,
+    pagination,
+    profile,
+    rows,
+    selectedStoreId,
+    setDetailDrawerOpen,
+    setKeyword,
+    setOrderCountRange,
+    setProfileDrawerOpen,
+    setRegisterPeriod,
+    setSelectedStoreId,
+    setTag,
+    stats,
+    storeOptions,
+  };
+}

apps/web-antd/src/views/customer/list/index.vue

@@ -0,0 +1,96 @@
+<script setup lang="ts">
+import { Page } from '@vben/common-ui';
+
+import CustomerDetailDrawer from './components/CustomerDetailDrawer.vue';
+import CustomerFilterBar from './components/CustomerFilterBar.vue';
+import CustomerProfileDrawer from './components/CustomerProfileDrawer.vue';
+import CustomerStatsBar from './components/CustomerStatsBar.vue';
+import CustomerTableCard from './components/CustomerTableCard.vue';
+import { useCustomerListPage } from './composables/useCustomerListPage';
+
+const {
+  canManage,
+  detail,
+  filters,
+  handleExport,
+  handlePageChange,
+  handleReset,
+  handleSearch,
+  isDetailDrawerOpen,
+  isDetailLoading,
+  isExporting,
+  isListLoading,
+  isProfileDrawerOpen,
+  isProfileLoading,
+  isStoreLoading,
+  openDetail,
+  openProfile,
+  openProfilePage,
+  pagination,
+  profile,
+  rows,
+  selectedStoreId,
+  setDetailDrawerOpen,
+  setKeyword,
+  setOrderCountRange,
+  setProfileDrawerOpen,
+  setRegisterPeriod,
+  setSelectedStoreId,
+  setTag,
+  stats,
+  storeOptions,
+} = useCustomerListPage();
+</script>
+
+<template>
+  <Page title="客户列表" content-class="page-customer-list">
+    <div class="cl-page">
+      <CustomerFilterBar
+        :selected-store-id="selectedStoreId"
+        :store-options="storeOptions"
+        :is-store-loading="isStoreLoading"
+        :filters="filters"
+        :show-export="canManage"
+        :is-exporting="isExporting"
+        @update:selected-store-id="setSelectedStoreId"
+        @update:tag="setTag"
+        @update:order-count-range="setOrderCountRange"
+        @update:register-period="setRegisterPeriod"
+        @update:keyword="setKeyword"
+        @search="handleSearch"
+        @reset="handleReset"
+        @export="handleExport"
+      />
+
+      <CustomerStatsBar :stats="stats" />
+
+      <CustomerTableCard
+        :rows="rows"
+        :loading="isListLoading"
+        :pagination="pagination"
+        @page-change="handlePageChange"
+        @detail="openDetail"
+      />
+    </div>
+
+    <CustomerDetailDrawer
+      :open="isDetailDrawerOpen"
+      :loading="isDetailLoading"
+      :detail="detail"
+      @close="setDetailDrawerOpen(false)"
+      @profile="openProfile"
+      @profile-page="openProfilePage"
+    />
+
+    <CustomerProfileDrawer
+      :open="isProfileDrawerOpen"
+      :loading="isProfileLoading"
+      :profile="profile"
+      @close="setProfileDrawerOpen(false)"
+    />
+  </Page>
+</template>
+
+<style lang="less">
+@import './styles/index.less';
+</style>

apps/web-antd/src/views/customer/list/styles/base.less

@@ -0,0 +1,11 @@
+.page-customer-list {
+  .ant-card {
+    border-radius: 10px;
+  }
+}
+
+.cl-page {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}

apps/web-antd/src/views/customer/list/styles/drawer.less

@@ -0,0 +1,537 @@
+.page-customer-list {
+  .ant-drawer {
+    .ant-drawer-header {
+      padding: 14px 18px;
+      border-bottom: 1px solid #f0f0f0;
+    }
+
+    .ant-drawer-body {
+      padding: 16px 20px;
+    }
+
+    .ant-drawer-footer {
+      padding: 12px 20px;
+      border-top: 1px solid #f0f0f0;
+    }
+  }
+}
+
+.cl-detail-head {
+  display: flex;
+  gap: 14px;
+  align-items: center;
+  margin-bottom: 20px;
+}
+
+.cl-detail-avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 52px;
+  height: 52px;
+  font-size: 20px;
+  font-weight: 600;
+  color: #fff;
+  background: #1677ff;
+  border-radius: 50%;
+}
+
+.cl-detail-title-wrap {
+  min-width: 0;
+}
+
+.cl-detail-name {
+  font-size: 16px;
+  font-weight: 600;
+  color: rgb(0 0 0 / 88%);
+}
+
+.cl-detail-meta {
+  margin-top: 2px;
+  font-size: 13px;
+  color: rgb(0 0 0 / 45%);
+}
+
+.cl-detail-tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+  margin-left: auto;
+
+  .ant-tag {
+    margin-inline-end: 0;
+  }
+}
+
+.cl-overview-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 10px;
+  margin-bottom: 22px;
+}
+
+.cl-overview-item {
+  padding: 12px;
+  text-align: center;
+  background: #f8f9fb;
+  border-radius: 8px;
+
+  .label {
+    font-size: 12px;
+    color: rgb(0 0 0 / 45%);
+  }
+
+  .value {
+    margin-top: 4px;
+    font-size: 20px;
+    font-weight: 700;
+    color: rgb(0 0 0 / 88%);
+
+    &.primary {
+      color: #1677ff;
+    }
+
+    &.success {
+      color: #52c41a;
+    }
+  }
+}
+
+.cl-drawer-section {
+  margin-bottom: 22px;
+}
+
+.cl-drawer-section-title {
+  padding-left: 10px;
+  margin-bottom: 12px;
+  font-size: 15px;
+  font-weight: 600;
+  color: rgb(0 0 0 / 88%);
+  border-left: 3px solid #1677ff;
+}
+
+.cl-preference-tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin-bottom: 12px;
+
+  .ant-tag {
+    margin-inline-end: 0;
+  }
+
+  .cl-empty-text {
+    font-size: 13px;
+    color: rgb(0 0 0 / 45%);
+  }
+}
+
+.cl-preference-list {
+  font-size: 13px;
+}
+
+.cl-preference-row {
+  display: flex;
+  justify-content: space-between;
+  padding: 6px 0;
+  color: rgb(0 0 0 / 65%);
+
+  span:last-child {
+    max-width: 62%;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    font-weight: 500;
+    color: rgb(0 0 0 / 88%);
+    text-align: right;
+    white-space: nowrap;
+  }
+}
+
+.cl-top-product-list {
+  min-height: 42px;
+}
+
+.cl-top-product-item {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+  padding: 8px 0;
+  font-size: 13px;
+  border-bottom: 1px solid #f3f4f6;
+
+  &:last-child {
+    border-bottom: none;
+  }
+
+  .rank {
+    width: 20px;
+    color: rgb(0 0 0 / 45%);
+    text-align: center;
+  }
+
+  .name {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    color: rgb(0 0 0 / 88%);
+    white-space: nowrap;
+  }
+
+  .count {
+    color: rgb(0 0 0 / 65%);
+  }
+}
+
+.cl-trend-bar-group {
+  display: flex;
+  gap: 8px;
+  align-items: flex-end;
+  height: 116px;
+}
+
+.cl-trend-bar-item {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  gap: 4px;
+  align-items: center;
+  min-width: 0;
+
+  .amount {
+    width: 100%;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    font-size: 10px;
+    color: rgb(0 0 0 / 45%);
+    text-align: center;
+    white-space: nowrap;
+  }
+
+  .bar {
+    width: 100%;
+    background: #1677ff;
+    border-radius: 4px 4px 0 0;
+    opacity: 0.78;
+  }
+
+  .month {
+    font-size: 11px;
+    color: rgb(0 0 0 / 45%);
+  }
+}
+
+.cl-recent-orders {
+  font-size: 13px;
+}
+
+.cl-recent-order-item {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+  justify-content: space-between;
+  padding: 10px 0;
+  border-bottom: 1px solid #f3f4f6;
+
+  &:last-child {
+    border-bottom: none;
+  }
+
+  .left {
+    flex: 1;
+    min-width: 0;
+  }
+
+  .summary {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    font-weight: 500;
+    color: rgb(0 0 0 / 88%);
+    white-space: nowrap;
+  }
+
+  .meta {
+    margin-top: 2px;
+    font-size: 12px;
+    color: rgb(0 0 0 / 45%);
+  }
+
+  .amount {
+    flex-shrink: 0;
+    font-weight: 600;
+    color: rgb(0 0 0 / 88%);
+    white-space: nowrap;
+  }
+}
+
+.cl-detail-footer {
+  display: flex;
+  gap: 8px;
+  justify-content: flex-end;
+}
+
+.cl-profile-head {
+  display: flex;
+  gap: 16px;
+  align-items: center;
+  padding: 4px 0 16px;
+  margin-bottom: 16px;
+  border-bottom: 1px solid #f0f0f0;
+}
+
+.cl-profile-avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 56px;
+  height: 56px;
+  font-size: 22px;
+  font-weight: 700;
+  color: #fff;
+  background: #3b82f6;
+  border-radius: 50%;
+}
+
+.cl-profile-title-wrap {
+  min-width: 0;
+}
+
+.cl-profile-name {
+  font-size: 18px;
+  font-weight: 700;
+  color: rgb(0 0 0 / 88%);
+}
+
+.cl-profile-meta {
+  margin-top: 4px;
+  font-size: 13px;
+  color: rgb(0 0 0 / 45%);
+}
+
+.cl-profile-tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+  margin-left: auto;
+
+  .ant-tag {
+    margin-inline-end: 0;
+  }
+}
+
+.cl-profile-kpis {
+  display: grid;
+  grid-template-columns: repeat(5, minmax(0, 1fr));
+  gap: 12px;
+  margin-bottom: 16px;
+}
+
+.cl-profile-kpi {
+  padding: 14px 10px;
+  text-align: center;
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 10px;
+
+  .num {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    font-size: 20px;
+    font-weight: 700;
+    color: rgb(0 0 0 / 88%);
+    white-space: nowrap;
+
+    &.blue {
+      color: #1677ff;
+    }
+
+    &.success {
+      color: #52c41a;
+    }
+  }
+
+  .lbl {
+    margin-top: 4px;
+    font-size: 12px;
+    color: rgb(0 0 0 / 45%);
+  }
+}
+
+.cl-profile-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 14px;
+}
+
+.cl-profile-card {
+  padding: 18px 20px;
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 10px;
+
+  &.full {
+    grid-column: 1 / -1;
+  }
+}
+
+.cl-profile-card-title {
+  padding-left: 10px;
+  margin-bottom: 14px;
+  font-size: 15px;
+  font-weight: 600;
+  color: rgb(0 0 0 / 88%);
+  border-left: 3px solid #1677ff;
+}
+
+.cl-profile-pref-row {
+  display: flex;
+  gap: 10px;
+  justify-content: space-between;
+  padding: 10px 0;
+  font-size: 13px;
+  border-bottom: 1px solid #f3f4f6;
+
+  &:last-child {
+    border-bottom: none;
+  }
+
+  .label {
+    color: rgb(0 0 0 / 65%);
+  }
+
+  .value {
+    max-width: 66%;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    font-weight: 500;
+    color: rgb(0 0 0 / 88%);
+    text-align: right;
+    white-space: nowrap;
+  }
+}
+
+.cl-profile-top-list {
+  min-height: 48px;
+}
+
+.cl-profile-top-item {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+  padding: 8px 0;
+  font-size: 13px;
+  border-bottom: 1px solid #f3f4f6;
+
+  &:last-child {
+    border-bottom: none;
+  }
+
+  .name {
+    width: 110px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    color: rgb(0 0 0 / 88%);
+    white-space: nowrap;
+  }
+
+  .bar {
+    display: inline-flex;
+    flex: 1;
+    height: 6px;
+    overflow: hidden;
+    background: #f0f0f0;
+    border-radius: 3px;
+  }
+
+  .bar-inner {
+    display: inline-flex;
+    height: 100%;
+    background: #1677ff;
+    border-radius: 3px;
+  }
+
+  .count {
+    width: 42px;
+    color: rgb(0 0 0 / 65%);
+    text-align: right;
+  }
+}
+
+.cl-profile-top-rank {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+  font-size: 11px;
+  font-weight: 700;
+  border-radius: 50%;
+
+  &.gold {
+    color: #d97706;
+    background: #fef3c7;
+  }
+
+  &.silver {
+    color: #6b7280;
+    background: #f3f4f6;
+  }
+}
+
+.cl-profile-trend-bars {
+  display: flex;
+  gap: 8px;
+  align-items: flex-end;
+  height: 126px;
+}
+
+.cl-profile-trend-bar-col {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  gap: 4px;
+  align-items: center;
+  min-width: 0;
+
+  .bar-val {
+    width: 100%;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    font-size: 10px;
+    color: rgb(0 0 0 / 45%);
+    text-align: center;
+    white-space: nowrap;
+  }
+
+  .bar {
+    width: 100%;
+    background: #1677ff;
+    border-radius: 4px 4px 0 0;
+    opacity: 0.8;
+  }
+
+  .bar-lbl {
+    font-size: 11px;
+    color: rgb(0 0 0 / 45%);
+  }
+}
+
+.cl-profile-order-status {
+  font-weight: 600;
+
+  &.success {
+    color: #52c41a;
+  }
+
+  &.danger {
+    color: #ff4d4f;
+  }
+
+  &.processing {
+    color: #1677ff;
+  }
+
+  &.default {
+    color: rgb(0 0 0 / 65%);
+  }
+}

apps/web-antd/src/views/customer/list/styles/index.less

@@ -0,0 +1,8 @@
+@import './base.less';
+@import './layout.less';
+@import './table.less';
+@import './drawer.less';
+@import '../../profile/styles/card.less';
+@import '../../profile/styles/table.less';
+@import '../../profile/styles/responsive.less';
+@import './responsive.less';

apps/web-antd/src/views/customer/list/styles/layout.less

@@ -0,0 +1,112 @@
+.cl-toolbar {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  align-items: center;
+  padding: 12px 14px;
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 10px;
+  box-shadow: 0 2px 8px rgb(15 23 42 / 6%);
+
+  .cl-store-select {
+    width: 220px;
+  }
+
+  .cl-tag-select {
+    width: 140px;
+  }
+
+  .cl-order-count-select {
+    width: 140px;
+  }
+
+  .cl-register-period-select {
+    width: 140px;
+  }
+
+  .cl-search-input {
+    width: 220px;
+  }
+
+  .cl-toolbar-right {
+    margin-left: auto;
+  }
+
+  .cl-search-icon {
+    width: 14px;
+    height: 14px;
+    color: rgb(0 0 0 / 45%);
+  }
+
+  .cl-query-btn,
+  .cl-reset-btn,
+  .cl-export-btn {
+    display: inline-flex;
+    gap: 4px;
+    align-items: center;
+    height: 32px;
+  }
+
+  .ant-select-selector,
+  .ant-input,
+  .ant-input-affix-wrapper {
+    height: 32px;
+    font-size: 13px;
+  }
+
+  .ant-input-affix-wrapper .ant-input {
+    height: 100%;
+  }
+}
+
+.cl-stats {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 12px;
+}
+
+.cl-stat-card {
+  padding: 16px 20px;
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 10px;
+  box-shadow: 0 2px 8px rgb(15 23 42 / 6%);
+  transition: all 0.2s ease;
+
+  &:hover {
+    box-shadow: 0 6px 14px rgb(15 23 42 / 10%);
+    transform: translateY(-1px);
+  }
+
+  .cl-stat-label {
+    margin-bottom: 6px;
+    font-size: 13px;
+    color: rgb(0 0 0 / 45%);
+  }
+
+  .cl-stat-value {
+    font-size: 24px;
+    font-weight: 700;
+    line-height: 1.2;
+    color: rgb(0 0 0 / 88%);
+
+    &.blue {
+      color: #1677ff;
+    }
+
+    &.green {
+      color: #52c41a;
+    }
+
+    &.orange {
+      color: #fa8c16;
+    }
+  }
+
+  .cl-stat-sub {
+    margin-top: 4px;
+    font-size: 12px;
+    color: rgb(0 0 0 / 45%);
+  }
+}

apps/web-antd/src/views/customer/list/styles/responsive.less

@@ -0,0 +1,78 @@
+@media (max-width: 1600px) {
+  .cl-stats {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .cl-profile-kpis {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+  }
+}
+
+@media (max-width: 1024px) {
+  .cl-profile-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .cl-profile-card.full {
+    grid-column: auto;
+  }
+}
+
+@media (max-width: 768px) {
+  .cl-toolbar {
+    padding: 14px 12px;
+
+    .cl-store-select,
+    .cl-tag-select,
+    .cl-order-count-select,
+    .cl-register-period-select,
+    .cl-search-input {
+      width: 100%;
+    }
+
+    .cl-query-btn,
+    .cl-reset-btn {
+      flex: 1;
+    }
+
+    .cl-toolbar-right {
+      width: 100%;
+      margin-left: 0;
+    }
+
+    .cl-export-btn {
+      justify-content: center;
+      width: 100%;
+    }
+  }
+
+  .cl-stats {
+    grid-template-columns: 1fr;
+  }
+
+  .cl-overview-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .cl-detail-head {
+    flex-wrap: wrap;
+  }
+
+  .cl-detail-tags {
+    width: 100%;
+    margin-left: 0;
+  }
+
+  .cl-profile-head {
+    flex-wrap: wrap;
+  }
+
+  .cl-profile-tags {
+    width: 100%;
+    margin-left: 0;
+  }
+
+  .cl-profile-kpis {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}

apps/web-antd/src/views/customer/list/styles/table.less

@@ -0,0 +1,107 @@
+.cl-table-card {
+  overflow: hidden;
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 10px;
+  box-shadow: 0 2px 8px rgb(15 23 42 / 6%);
+
+  .ant-table-wrapper {
+    .ant-table-thead > tr > th {
+      font-size: 13px;
+      white-space: nowrap;
+      background: #f8f9fb;
+    }
+
+    .ant-table-tbody > tr > td {
+      vertical-align: middle;
+    }
+  }
+
+  .ant-pagination {
+    margin: 14px 16px;
+  }
+}
+
+.cl-customer-cell {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+}
+
+.cl-avatar {
+  display: inline-flex;
+  flex-shrink: 0;
+  gap: 0;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  font-size: 14px;
+  font-weight: 600;
+  color: #fff;
+  border-radius: 50%;
+}
+
+.cl-customer-main {
+  min-width: 0;
+}
+
+.cl-customer-name {
+  font-weight: 500;
+  color: rgb(0 0 0 / 88%);
+}
+
+.cl-customer-phone {
+  margin-top: 2px;
+  font-size: 12px;
+  color: rgb(0 0 0 / 45%);
+}
+
+.cl-order-count-cell {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.cl-order-count-value {
+  min-width: 20px;
+  font-weight: 600;
+}
+
+.cl-order-count-bar {
+  display: inline-flex;
+  flex: 1;
+  max-width: 90px;
+  height: 6px;
+  background: #1677ff;
+  border-radius: 3px;
+  opacity: 0.72;
+}
+
+.cl-amount,
+.cl-average-amount {
+  font-weight: 600;
+  white-space: nowrap;
+}
+
+.cl-tag-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+
+  .ant-tag {
+    margin-inline-end: 0;
+  }
+}
+
+.cl-detail-action {
+  padding-inline: 0;
+}
+
+.cl-row-dimmed td {
+  opacity: 0.55;
+}
+
+.cl-row-dimmed:hover td {
+  opacity: 0.78;
+}

apps/web-antd/src/views/customer/list/types.ts

@@ -0,0 +1,61 @@
+import type {
+  CustomerDetailDto,
+  CustomerListItemDto,
+  CustomerListStatsDto,
+  CustomerOrderCountRangeFilter,
+  CustomerProfileDto,
+  CustomerRegisterPeriodFilter,
+  CustomerTagFilter,
+} from '#/api/customer';
+
+export interface CustomerFilterState {
+  keyword: string;
+  orderCountRange: CustomerOrderCountRangeFilter;
+  registerPeriod: CustomerRegisterPeriodFilter;
+  tag: CustomerTagFilter;
+}
+
+export interface CustomerPaginationState {
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+export interface CustomerListPageState {
+  detail: CustomerDetailDto | null;
+  filters: CustomerFilterState;
+  isDetailDrawerOpen: boolean;
+  isDetailLoading: boolean;
+  isExporting: boolean;
+  isListLoading: boolean;
+  isProfileDrawerOpen: boolean;
+  isProfileLoading: boolean;
+  isStatsLoading: boolean;
+  pagination: CustomerPaginationState;
+  profile: CustomerProfileDto | null;
+  rows: CustomerListItemDto[];
+  stats: CustomerListStatsDto;
+}
+
+export interface OptionItem {
+  label: string;
+  value: string;
+}
+
+export interface CustomerListQueryPayload {
+  keyword?: string;
+  orderCountRange?: CustomerOrderCountRangeFilter;
+  page: number;
+  pageSize: number;
+  registerPeriod?: CustomerRegisterPeriodFilter;
+  storeId: string;
+  tag?: CustomerTagFilter;
+}
+
+export interface CustomerFilterQueryPayload {
+  keyword?: string;
+  orderCountRange?: CustomerOrderCountRangeFilter;
+  registerPeriod?: CustomerRegisterPeriodFilter;
+  storeId: string;
+  tag?: CustomerTagFilter;
+}

apps/web-antd/src/views/customer/profile/components/CustomerProfileHeader.vue

@@ -0,0 +1,52 @@
+<script setup lang="ts">
+import type { CustomerProfileDto } from '#/api/customer';
+
+import { Tag } from 'ant-design-vue';
+
+import {
+  formatInteger,
+  resolveAvatarText,
+  resolveTagColor,
+} from '../composables/customer-profile-page/helpers';
+
+interface Props {
+  profile: CustomerProfileDto;
+}
+
+const props = defineProps<Props>();
+</script>
+
+<template>
+  <div class="cp-header">
+    <div class="cp-avatar">{{ resolveAvatarText(props.profile.name) }}</div>
+
+    <div class="cp-header-main">
+      <div class="cp-name">{{ props.profile.name }}</div>
+      <div class="cp-meta">
+        {{ props.profile.phoneMasked }} · 首次下单
+        {{ props.profile.firstOrderAt }} · 来源：{{
+          props.profile.source || '--'
+        }}
+      </div>
+      <div class="cp-member-meta">
+        <template v-if="props.profile.member.isMember">
+          {{ props.profile.member.tierName || '会员' }} · 积分
+          {{ formatInteger(props.profile.member.pointsBalance) }} · 成长值
+          {{ formatInteger(props.profile.member.growthValue) }} · 入会
+          {{ props.profile.member.joinedAt || '--' }}
+        </template>
+        <template v-else>未入会</template>
+      </div>
+    </div>
+
+    <div class="cp-tags">
+      <Tag
+        v-for="tag in props.profile.tags"
+        :key="`${tag.code}-${tag.label}`"
+        :color="resolveTagColor(tag.tone)"
+      >
+        {{ tag.label }}
+      </Tag>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/customer/profile/components/CustomerProfileKpiGrid.vue

@@ -0,0 +1,41 @@
+<script setup lang="ts">
+import type { CustomerProfileDto } from '#/api/customer';
+
+import {
+  formatCurrency,
+  formatPercent,
+} from '../composables/customer-profile-page/helpers';
+
+interface Props {
+  profile: CustomerProfileDto;
+}
+
+const props = defineProps<Props>();
+</script>
+
+<template>
+  <div class="cp-kpis">
+    <div class="cp-kpi">
+      <div class="num blue">{{ props.profile.totalOrders }}</div>
+      <div class="lbl">下单次数</div>
+    </div>
+    <div class="cp-kpi">
+      <div class="num">{{ formatCurrency(props.profile.totalAmount) }}</div>
+      <div class="lbl">累计消费</div>
+    </div>
+    <div class="cp-kpi">
+      <div class="num">{{ formatCurrency(props.profile.averageAmount) }}</div>
+      <div class="lbl">客单价</div>
+    </div>
+    <div class="cp-kpi">
+      <div class="num success">
+        {{ formatPercent(props.profile.repurchaseRatePercent) }}
+      </div>
+      <div class="lbl">复购率</div>
+    </div>
+    <div class="cp-kpi">
+      <div class="num">{{ props.profile.averageOrderIntervalDays }}天</div>
+      <div class="lbl">平均下单间隔</div>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/customer/profile/components/CustomerProfilePanel.vue

@@ -0,0 +1,135 @@
+<script setup lang="ts">
+import type { CustomerProfileDto } from '#/api/customer';
+
+import { computed } from 'vue';
+
+import { Empty } from 'ant-design-vue';
+
+import { formatCurrency } from '../composables/customer-profile-page/helpers';
+import CustomerProfileHeader from './CustomerProfileHeader.vue';
+import CustomerProfileKpiGrid from './CustomerProfileKpiGrid.vue';
+import CustomerProfileRecentOrdersTable from './CustomerProfileRecentOrdersTable.vue';
+
+interface Props {
+  profile: CustomerProfileDto;
+}
+
+const props = defineProps<Props>();
+
+const trendMaxAmount = computed(() =>
+  Math.max(0, ...(props.profile.trend.map((item) => item.amount) ?? [])),
+);
+
+function resolveTrendHeight(amount: number) {
+  if (trendMaxAmount.value <= 0) {
+    return '0px';
+  }
+
+  const ratio = amount / trendMaxAmount.value;
+  return `${Math.max(12, Math.round(ratio * 90))}px`;
+}
+</script>
+
+<template>
+  <div class="cp-panel">
+    <CustomerProfileHeader :profile="props.profile" />
+    <CustomerProfileKpiGrid :profile="props.profile" />
+
+    <div class="cp-grid">
+      <div class="cp-card">
+        <div class="cp-card-title">消费偏好</div>
+        <div class="cp-pref-row">
+          <span class="label">偏好品类</span>
+          <span class="value">
+            {{
+              props.profile.preference.preferredCategories.length > 0
+                ? props.profile.preference.preferredCategories.join('、')
+                : '--'
+            }}
+          </span>
+        </div>
+        <div class="cp-pref-row">
+          <span class="label">常用口味</span>
+          <span class="value">--</span>
+        </div>
+        <div class="cp-pref-row">
+          <span class="label">下单高峰</span>
+          <span class="value">
+            {{ props.profile.preference.preferredOrderPeaks || '--' }}
+          </span>
+        </div>
+        <div class="cp-pref-row">
+          <span class="label">配送方式</span>
+          <span class="value">
+            {{ props.profile.preference.preferredDelivery || '--' }}
+          </span>
+        </div>
+        <div class="cp-pref-row">
+          <span class="label">支付方式</span>
+          <span class="value">
+            {{ props.profile.preference.preferredPaymentMethod || '--' }}
+          </span>
+        </div>
+        <div class="cp-pref-row">
+          <span class="label">平均配送距离</span>
+          <span class="value">
+            {{ props.profile.preference.averageDeliveryDistance || '--' }}
+          </span>
+        </div>
+      </div>
+
+      <div class="cp-card">
+        <div class="cp-card-title">常购商品 TOP 5</div>
+        <div v-if="props.profile.topProducts.length > 0" class="cp-top-list">
+          <div
+            v-for="product in props.profile.topProducts"
+            :key="`${product.rank}-${product.productName}`"
+            class="cp-top-item"
+          >
+            <span
+              class="cp-top-rank"
+              :class="[product.rank <= 3 ? 'gold' : 'silver']"
+            >
+              {{ product.rank }}
+            </span>
+            <span class="name">{{ product.productName }}</span>
+            <span class="bar">
+              <span
+                class="bar-inner"
+                :style="{
+                  width: `${Math.max(8, Math.min(100, product.proportionPercent))}%`,
+                }"
+              ></span>
+            </span>
+            <span class="count">{{ product.count }}次</span>
+          </div>
+        </div>
+        <Empty v-else description="暂无商品偏好" />
+      </div>
+
+      <div class="cp-card full">
+        <div class="cp-card-title">月度消费趋势</div>
+        <div v-if="props.profile.trend.length > 0" class="cp-trend-bars">
+          <div
+            v-for="point in props.profile.trend"
+            :key="point.label"
+            class="cp-trend-bar-col"
+          >
+            <div class="bar-val">{{ formatCurrency(point.amount) }}</div>
+            <div
+              class="bar"
+              :style="{ height: resolveTrendHeight(point.amount) }"
+            ></div>
+            <span class="bar-lbl">{{ point.label }}</span>
+          </div>
+        </div>
+        <Empty v-else description="暂无趋势数据" />
+      </div>
+
+      <div class="cp-card full">
+        <div class="cp-card-title">最近订单</div>
+        <CustomerProfileRecentOrdersTable :rows="props.profile.recentOrders" />
+      </div>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/customer/profile/components/CustomerProfileRecentOrdersTable.vue

@@ -0,0 +1,81 @@
+<script setup lang="ts">
+import type { TableProps } from 'ant-design-vue';
+
+import type { CustomerRecentOrderDto } from '#/api/customer';
+
+import { h } from 'vue';
+
+import { Table, Tag } from 'ant-design-vue';
+
+import {
+  formatCurrency,
+  resolveDeliveryTagColor,
+  resolveOrderStatusClass,
+} from '../composables/customer-profile-page/helpers';
+
+interface Props {
+  rows: CustomerRecentOrderDto[];
+}
+
+defineProps<Props>();
+
+const columns: TableProps['columns'] = [
+  {
+    title: '订单号',
+    dataIndex: 'orderNo',
+    width: 150,
+  },
+  {
+    title: '金额',
+    dataIndex: 'amount',
+    width: 110,
+    customRender: ({ text }) => formatCurrency(Number(text || 0)),
+  },
+  {
+    title: '商品',
+    dataIndex: 'itemsSummary',
+    ellipsis: true,
+  },
+  {
+    title: '方式',
+    dataIndex: 'deliveryType',
+    width: 100,
+    customRender: ({ text }) =>
+      h(Tag, { color: resolveDeliveryTagColor(String(text ?? '')) }, () =>
+        String(text ?? '--'),
+      ),
+  },
+  {
+    title: '状态',
+    dataIndex: 'status',
+    width: 90,
+    customRender: ({ text }) =>
+      h(
+        'span',
+        {
+          class: [
+            'cp-order-status',
+            resolveOrderStatusClass(String(text ?? '')),
+          ],
+        },
+        String(text ?? '--'),
+      ),
+  },
+  {
+    title: '时间',
+    dataIndex: 'orderedAt',
+    width: 170,
+  },
+];
+</script>
+
+<template>
+  <Table
+    class="cp-order-table"
+    row-key="orderNo"
+    :columns="columns"
+    :data-source="rows"
+    :pagination="false"
+    size="small"
+  />
+</template>

apps/web-antd/src/views/customer/profile/composables/customer-profile-page/constants.ts

@@ -0,0 +1,23 @@
+import type { CustomerProfileListFilters } from '../../types';
+
+/** 默认客户查询页码。 */
+export const PROFILE_DEFAULT_LIST_PAGE = 1;
+
+/** 默认客户查询条数。 */
+export const PROFILE_DEFAULT_LIST_PAGE_SIZE = 1;
+
+/** 门店下拉加载条数。 */
+export const PROFILE_STORE_QUERY_PAGE_SIZE = 200;
+
+/** 客户画像查看权限码。 */
+export const CUSTOMER_PROFILE_VIEW_PERMISSION = 'tenant:customer:profile:view';
+
+/** 默认客户筛选值。 */
+export function createDefaultListFilters(): CustomerProfileListFilters {
+  return {
+    keyword: '',
+    orderCountRange: 'all',
+    registerPeriod: 'all',
+    tag: 'all',
+  };
+}