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

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

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

@@ -168,6 +168,154 @@ export interface CustomerExportDto {
   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', {
@@ -208,3 +356,69 @@ export async function exportCustomerCsvApi(params: CustomerListFilterQuery) {
     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/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/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/store-fees/index.ts

@@ -46,6 +46,8 @@ export interface StoreOtherFeesDto {
 export interface StoreFeesSettingsDto {
   /** 基础配送费 */
   baseDeliveryFee: number;
+  /** 平台服务费率（%） */
+  platformServiceRate: number;
   /** 固定包装费 */
   fixedPackagingFee: number;
   /** 免配送费门槛，空值表示关闭 */
@@ -70,6 +72,8 @@ export interface StoreFeesSettingsDto {
 export interface SaveStoreFeesSettingsParams {
   /** 基础配送费 */
   baseDeliveryFee: number;
+  /** 平台服务费率（%） */
+  platformServiceRate: number;
   /** 固定包装费 */
   fixedPackagingFee: number;
   /** 免配送费门槛，空值表示关闭 */

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

@@ -15,12 +15,16 @@ interface Props {
   detail: CustomerDetailDto | null;
   loading: boolean;
   open: boolean;
+  showMemberAction?: boolean;
 }
 
-const props = defineProps<Props>();
+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;
 }>();
@@ -60,6 +64,15 @@ function handleOpenProfilePage() {
 
   emit('profilePage', customerKey);
 }
+
+function handleOpenMember() {
+  const customerKey = props.detail?.customerKey || '';
+  if (!customerKey) {
+    return;
+  }
+
+  emit('member', customerKey);
+}
 </script>
 
 <template>
@@ -225,6 +238,12 @@ function handleOpenProfilePage() {
       <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>

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

@@ -14,6 +14,7 @@ import {
 export function useCustomerProfilePage() {
   const route = useRoute();
   const router = useRouter();
+  const PROFILE_ROUTE_PATH = '/customer/profile';
 
   const stores = ref<StoreListItemDto[]>([]);
   const selectedStoreId = ref('');
@@ -49,6 +50,10 @@ export function useCustomerProfilePage() {
   });
 
   async function syncRouteQuery(storeId: string, customerKey: string) {
+    if (route.path !== PROFILE_ROUTE_PATH) {
+      return;
+    }
+
     const currentStoreId = parseRouteQueryValue(route.query.storeId);
     const currentCustomerKey = parseRouteQueryValue(route.query.customerKey);
     if (currentStoreId === storeId && currentCustomerKey === customerKey) {
@@ -56,7 +61,7 @@ export function useCustomerProfilePage() {
     }
 
     await router.replace({
-      path: '/customer/profile',
+      path: PROFILE_ROUTE_PATH,
       query: buildRouteQuery(
         route.query as Record<string, unknown>,
         storeId,
@@ -75,6 +80,10 @@ export function useCustomerProfilePage() {
   }
 
   async function loadProfileByRoute() {
+    if (route.path !== PROFILE_ROUTE_PATH) {
+      return;
+    }
+
     if (stores.value.length === 0) {
       await loadStores();
     }
@@ -110,15 +119,24 @@ export function useCustomerProfilePage() {
   watch(
     () => route.fullPath,
     () => {
+      if (route.path !== PROFILE_ROUTE_PATH) {
+        return;
+      }
       void loadProfileByRoute();
     },
   );
 
   onMounted(() => {
+    if (route.path === PROFILE_ROUTE_PATH) {
       void loadProfileByRoute();
+    }
   });
 
   onActivated(() => {
+    if (route.path !== PROFILE_ROUTE_PATH) {
+      return;
+    }
+
     if (stores.value.length === 0) {
       void loadProfileByRoute();
     }

apps/web-antd/src/views/finance/cost/components/CostAnalysisComposition.vue

@@ -0,0 +1,119 @@
+<script setup lang="ts">
+import type { EchartsUIType } from '@vben/plugins/echarts';
+
+/**
+ * 文件职责：成本分析构成环图与图例。
+ */
+import type { FinanceCostCompositionDto } from '#/api/finance/cost';
+
+import { computed, nextTick, onMounted, ref, watch } from 'vue';
+
+import { EchartsUI, useEcharts } from '@vben/plugins/echarts';
+
+import { COST_CATEGORY_COLOR_MAP } from '../composables/cost-page/constants';
+import {
+  formatCurrency,
+  formatPercent,
+} from '../composables/cost-page/helpers';
+
+interface Props {
+  composition: FinanceCostCompositionDto[];
+}
+
+const props = defineProps<Props>();
+
+const chartRef = ref<EchartsUIType>();
+const { renderEcharts } = useEcharts(chartRef);
+
+const totalCost = computed(() =>
+  (props.composition ?? []).reduce(
+    (sum, item) => sum + Number(item.amount || 0),
+    0,
+  ),
+);
+
+function renderChart() {
+  const source = props.composition ?? [];
+  renderEcharts({
+    tooltip: {
+      trigger: 'item',
+      formatter(params: unknown) {
+        const data = params as {
+          name?: string;
+          percent?: number;
+          value?: number;
+        };
+        return `${data.name ?? ''}<br/>${formatCurrency(data.value ?? 0)} (${formatPercent(data.percent ?? 0)})`;
+      },
+    },
+    series: [
+      {
+        type: 'pie',
+        radius: ['52%', '76%'],
+        center: ['50%', '50%'],
+        data: source.map((item) => ({
+          name: item.categoryText,
+          value: item.amount,
+          itemStyle: {
+            color: COST_CATEGORY_COLOR_MAP[item.category] ?? '#2563eb',
+          },
+        })),
+        label: {
+          show: false,
+        },
+      },
+    ],
+  });
+}
+
+watch(
+  () => props.composition,
+  async () => {
+    await nextTick();
+    renderChart();
+  },
+  { deep: true },
+);
+
+onMounted(() => {
+  renderChart();
+});
+</script>
+
+<template>
+  <div class="fc-composition-card">
+    <div class="fc-section-title">成本构成</div>
+
+    <div class="fc-composition-body">
+      <div class="fc-composition-chart-wrap">
+        <EchartsUI ref="chartRef" class="fc-composition-chart" />
+        <div class="fc-composition-center">
+          <div class="fc-composition-center-value">
+            {{ formatCurrency(totalCost) }}
+          </div>
+          <div class="fc-composition-center-label">总成本</div>
+        </div>
+      </div>
+
+      <div class="fc-composition-legend">
+        <div
+          v-for="item in props.composition"
+          :key="item.category"
+          class="fc-composition-legend-item"
+        >
+          <span
+            class="fc-composition-dot"
+            :style="{ backgroundColor: COST_CATEGORY_COLOR_MAP[item.category] }"
+          ></span>
+          <span class="fc-composition-name">{{ item.categoryText }}</span>
+          <span class="fc-composition-amount">{{
+            formatCurrency(item.amount)
+          }}</span>
+          <span class="fc-composition-percent">{{
+            formatPercent(item.percentage)
+          }}</span>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/finance/cost/components/CostAnalysisDetailTable.vue

@@ -0,0 +1,87 @@
+<script setup lang="ts">
+/**
+ * 文件职责：成本分析明细表。
+ */
+import type { TableProps } from 'ant-design-vue';
+
+import type { FinanceCostMonthlyDetailRowDto } from '#/api/finance/cost';
+
+import { h } from 'vue';
+
+import { Table } from 'ant-design-vue';
+
+import {
+  formatCurrency,
+  formatPercent,
+} from '../composables/cost-page/helpers';
+
+interface Props {
+  loading: boolean;
+  rows: FinanceCostMonthlyDetailRowDto[];
+}
+
+const props = defineProps<Props>();
+
+const columns: TableProps['columns'] = [
+  {
+    title: '月份',
+    dataIndex: 'month',
+    width: 110,
+  },
+  {
+    title: '食材',
+    dataIndex: 'foodAmount',
+    align: 'right',
+    customRender: ({ text }) => formatCurrency(Number(text ?? 0)),
+  },
+  {
+    title: '人工',
+    dataIndex: 'laborAmount',
+    align: 'right',
+    customRender: ({ text }) => formatCurrency(Number(text ?? 0)),
+  },
+  {
+    title: '固定',
+    dataIndex: 'fixedAmount',
+    align: 'right',
+    customRender: ({ text }) => formatCurrency(Number(text ?? 0)),
+  },
+  {
+    title: '包装',
+    dataIndex: 'packagingAmount',
+    align: 'right',
+    customRender: ({ text }) => formatCurrency(Number(text ?? 0)),
+  },
+  {
+    title: '总计',
+    dataIndex: 'totalCost',
+    align: 'right',
+    customRender: ({ text }) =>
+      h(
+        'span',
+        { class: 'fc-total-amount' },
+        formatCurrency(Number(text ?? 0)),
+      ),
+  },
+  {
+    title: '成本率',
+    dataIndex: 'costRate',
+    align: 'right',
+    customRender: ({ text }) => formatPercent(Number(text ?? 0)),
+  },
+];
+</script>
+
+<template>
+  <div class="fc-table-card">
+    <div class="fc-section-title">成本明细</div>
+    <Table
+      row-key="month"
+      size="middle"
+      :columns="columns"
+      :data-source="props.rows"
+      :loading="props.loading"
+      :pagination="false"
+    />
+  </div>
+</template>

apps/web-antd/src/views/finance/cost/components/CostAnalysisStatsBar.vue

@@ -0,0 +1,57 @@
+<script setup lang="ts">
+/**
+ * 文件职责：成本分析统计卡。
+ */
+import type { FinanceCostAnalysisStatsDto } from '#/api/finance/cost';
+
+import { computed } from 'vue';
+
+import {
+  formatCurrency,
+  formatPercent,
+} from '../composables/cost-page/helpers';
+
+interface Props {
+  stats: FinanceCostAnalysisStatsDto;
+}
+
+const props = defineProps<Props>();
+
+const monthOnMonthClass = computed(() => {
+  if ((props.stats?.monthOnMonthChangeRate ?? 0) > 0) return 'is-up';
+  if ((props.stats?.monthOnMonthChangeRate ?? 0) < 0) return 'is-down';
+  return 'is-flat';
+});
+</script>
+
+<template>
+  <div class="fc-stats">
+    <div class="fc-stat-card">
+      <div class="fc-stat-label">本月总成本</div>
+      <div class="fc-stat-value">
+        {{ formatCurrency(props.stats.totalCost) }}
+      </div>
+    </div>
+
+    <div class="fc-stat-card">
+      <div class="fc-stat-label">食材成本率</div>
+      <div class="fc-stat-value">
+        {{ formatPercent(props.stats.foodCostRate) }}
+      </div>
+    </div>
+
+    <div class="fc-stat-card">
+      <div class="fc-stat-label">单均成本</div>
+      <div class="fc-stat-value">
+        {{ formatCurrency(props.stats.averageCostPerPaidOrder) }}
+      </div>
+    </div>
+
+    <div class="fc-stat-card">
+      <div class="fc-stat-label">环比变化</div>
+      <div class="fc-stat-value" :class="monthOnMonthClass">
+        {{ formatPercent(props.stats.monthOnMonthChangeRate) }}
+      </div>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/finance/cost/components/CostAnalysisTrendChart.vue

@@ -0,0 +1,114 @@
+<script setup lang="ts">
+import type { EchartsUIType } from '@vben/plugins/echarts';
+
+/**
+ * 文件职责：成本分析近 6 月趋势图。
+ */
+import type { FinanceCostTrendPointDto } from '#/api/finance/cost';
+
+import { nextTick, onMounted, ref, watch } from 'vue';
+
+import { EchartsUI, useEcharts } from '@vben/plugins/echarts';
+
+import { formatCurrency } from '../composables/cost-page/helpers';
+
+interface Props {
+  trend: FinanceCostTrendPointDto[];
+}
+
+const props = defineProps<Props>();
+
+const chartRef = ref<EchartsUIType>();
+const { renderEcharts } = useEcharts(chartRef);
+
+function renderChart() {
+  const source = props.trend ?? [];
+  renderEcharts({
+    color: ['#2563eb', '#16a34a'],
+    tooltip: {
+      trigger: 'axis',
+      formatter(params: unknown) {
+        if (!Array.isArray(params)) return '';
+        const records = params as Array<{
+          axisValue?: string;
+          seriesName?: string;
+          value?: number;
+        }>;
+        const month = String(records[0]?.axisValue ?? '');
+        const cost = Number(
+          records.find((item) => item.seriesName === '总成本')?.value ?? 0,
+        );
+        const revenue = Number(
+          records.find((item) => item.seriesName === '营业额')?.value ?? 0,
+        );
+        return `${month}<br/>总成本：${formatCurrency(cost)}<br/>营业额：${formatCurrency(revenue)}`;
+      },
+    },
+    grid: {
+      left: '3%',
+      right: '3%',
+      bottom: '1%',
+      containLabel: true,
+    },
+    legend: {
+      data: ['总成本', '营业额'],
+      top: 0,
+    },
+    xAxis: {
+      type: 'category',
+      boundaryGap: true,
+      axisTick: { show: false },
+      data: source.map((item) => item.month.slice(5)),
+    },
+    yAxis: {
+      type: 'value',
+      splitLine: {
+        lineStyle: {
+          color: '#f1f5f9',
+          type: 'dashed',
+        },
+      },
+      axisLabel: {
+        formatter: (value: number) => `${Math.round(value / 1000)}k`,
+      },
+    },
+    series: [
+      {
+        name: '总成本',
+        type: 'bar',
+        barWidth: 22,
+        data: source.map((item) => item.totalCost),
+        itemStyle: {
+          borderRadius: [6, 6, 0, 0],
+        },
+      },
+      {
+        name: '营业额',
+        type: 'line',
+        smooth: true,
+        data: source.map((item) => item.revenue),
+      },
+    ],
+  });
+}
+
+watch(
+  () => props.trend,
+  async () => {
+    await nextTick();
+    renderChart();
+  },
+  { deep: true },
+);
+
+onMounted(() => {
+  renderChart();
+});
+</script>
+
+<template>
+  <div class="fc-chart-card">
+    <div class="fc-section-title">近6个月成本趋势</div>
+    <EchartsUI ref="chartRef" class="fc-trend-chart" />
+  </div>
+</template>

apps/web-antd/src/views/finance/cost/components/CostDetailDeleteModal.vue

@@ -0,0 +1,36 @@
+<script setup lang="ts">
+/**
+ * 文件职责：成本明细删除确认弹窗。
+ */
+import { Modal } from 'ant-design-vue';
+
+interface Props {
+  itemName?: string;
+  open: boolean;
+}
+
+defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'cancel'): void;
+  (event: 'confirm'): void;
+}>();
+</script>
+
+<template>
+  <Modal
+    :open="open"
+    title="删除明细"
+    ok-text="确认删除"
+    ok-type="danger"
+    cancel-text="取消"
+    @cancel="emit('cancel')"
+    @ok="emit('confirm')"
+  >
+    <p class="fc-delete-tip">
+      确认删除明细项
+      <strong>{{ itemName || '未命名项' }}</strong>
+      吗？删除后需重新保存才会生效。
+    </p>
+  </Modal>
+</template>

apps/web-antd/src/views/finance/cost/components/CostEntryCategoryCard.vue

@@ -0,0 +1,157 @@
+<script setup lang="ts">
+import type { FinanceCostCategoryViewModel } from '../types';
+
+/**
+ * 文件职责：成本录入分类卡片（总额 + 明细列表）。
+ */
+import type { FinanceCostCategoryCode } from '#/api/finance/cost';
+
+import { IconifyIcon } from '@vben/icons';
+
+import { Button, Card, Empty, InputNumber, Tag } from 'ant-design-vue';
+
+import {
+  formatCurrency,
+  formatPercent,
+} from '../composables/cost-page/helpers';
+
+interface Props {
+  canManage: boolean;
+  category: FinanceCostCategoryViewModel;
+  color?: string;
+  icon?: string;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'addItem', category: FinanceCostCategoryCode): void;
+  (
+    event: 'deleteItem',
+    category: FinanceCostCategoryCode,
+    itemId: string,
+  ): void;
+  (event: 'editItem', category: FinanceCostCategoryCode, itemId: string): void;
+  (event: 'toggle', category: FinanceCostCategoryCode): void;
+  (
+    event: 'updateTotal',
+    category: FinanceCostCategoryCode,
+    value: number,
+  ): void;
+}>();
+
+function handleTotalChange(value: unknown) {
+  emit('updateTotal', props.category.category, Number(value ?? 0));
+}
+
+function handleEdit(itemId: string | undefined) {
+  if (!itemId) return;
+  emit('editItem', props.category.category, itemId);
+}
+
+function handleDelete(itemId: string | undefined) {
+  if (!itemId) return;
+  emit('deleteItem', props.category.category, itemId);
+}
+</script>
+
+<template>
+  <Card class="fc-entry-card" :bordered="false">
+    <div class="fc-entry-head">
+      <div class="fc-entry-icon" :style="{ color: props.color || '#1677ff' }">
+        <IconifyIcon :icon="props.icon || 'lucide:circle-dollar-sign'" />
+      </div>
+
+      <div class="fc-entry-meta">
+        <div class="fc-entry-name">
+          {{ props.category.categoryText }}
+          <span class="fc-entry-ratio">{{
+            formatPercent(props.category.percentage)
+          }}</span>
+        </div>
+      </div>
+
+      <div class="fc-entry-amount">
+        <span class="fc-entry-currency">¥</span>
+        <InputNumber
+          class="fc-entry-input"
+          :min="0"
+          :step="100"
+          :precision="2"
+          :value="props.category.totalAmount"
+          :controls="false"
+          :disabled="!props.canManage"
+          @update:value="(value) => handleTotalChange(value)"
+        />
+      </div>
+
+      <Button
+        type="link"
+        class="fc-entry-toggle"
+        @click="emit('toggle', props.category.category)"
+      >
+        {{ props.category.expanded ? '收起明细' : '展开明细' }}
+      </Button>
+    </div>
+
+    <div v-if="props.category.expanded" class="fc-entry-detail">
+      <template v-if="props.category.items.length > 0">
+        <div
+          v-for="item in props.category.items"
+          :key="item.itemId"
+          class="fc-entry-detail-row"
+        >
+          <div class="fc-entry-item-name">{{ item.itemName }}</div>
+
+          <div class="fc-entry-item-value">
+            <template v-if="props.category.category === 'labor'">
+              <Tag color="blue">{{ item.quantity ?? 0 }} 人</Tag>
+              <span class="fc-entry-mul">x</span>
+              <Tag color="cyan">{{ formatCurrency(item.unitPrice ?? 0) }}</Tag>
+              <span class="fc-entry-equal">=</span>
+            </template>
+            <span class="fc-entry-item-amount">{{
+              formatCurrency(item.amount)
+            }}</span>
+          </div>
+
+          <div class="fc-entry-item-actions">
+            <Button
+              type="link"
+              size="small"
+              :disabled="!props.canManage"
+              @click="handleEdit(item.itemId)"
+            >
+              编辑
+            </Button>
+            <Button
+              type="link"
+              size="small"
+              danger
+              :disabled="!props.canManage"
+              @click="handleDelete(item.itemId)"
+            >
+              删除
+            </Button>
+          </div>
+        </div>
+      </template>
+
+      <div v-else class="fc-entry-empty">
+        <Empty description="暂无明细" :image-style="{ height: '48px' }" />
+      </div>
+
+      <Button
+        type="link"
+        class="fc-entry-add"
+        :disabled="!props.canManage"
+        @click="emit('addItem', props.category.category)"
+      >
+        <template #icon>
+          <IconifyIcon icon="lucide:plus" />
+        </template>
+        添加明细
+      </Button>
+    </div>
+  </Card>
+</template>

apps/web-antd/src/views/finance/cost/components/CostEntrySummaryBar.vue

@@ -0,0 +1,37 @@
+<script setup lang="ts">
+/**
+ * 文件职责：成本录入底部汇总栏。
+ */
+import { Button } from 'ant-design-vue';
+
+import { formatCurrency } from '../composables/cost-page/helpers';
+
+interface Props {
+  canManage: boolean;
+  loading: boolean;
+  totalCost: number;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'save'): void;
+}>();
+</script>
+
+<template>
+  <div class="fc-summary">
+    <div class="fc-summary-label">本月总成本</div>
+    <div class="fc-summary-right">
+      <div class="fc-summary-value">{{ formatCurrency(props.totalCost) }}</div>
+      <Button
+        type="primary"
+        :loading="props.loading"
+        :disabled="!props.canManage"
+        @click="emit('save')"
+      >
+        保存
+      </Button>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/finance/cost/components/CostItemEditorDrawer.vue

@@ -0,0 +1,191 @@
+<script setup lang="ts">
+/**
+ * 文件职责：成本明细编辑抽屉（新增/编辑）。
+ */
+import type {
+  FinanceCostCategoryCode,
+  FinanceCostEntryDetailDto,
+} from '#/api/finance/cost';
+
+import { computed, reactive, watch } from 'vue';
+
+import { Button, Drawer, Form, Input, InputNumber } from 'ant-design-vue';
+
+import { roundAmount } from '../composables/cost-page/helpers';
+
+interface Props {
+  category: FinanceCostCategoryCode;
+  categoryText: string;
+  mode: 'create' | 'edit';
+  open: boolean;
+  sourceItem?: FinanceCostEntryDetailDto;
+  submitting: boolean;
+}
+
+interface EditorFormState {
+  amount: number;
+  itemId?: string;
+  itemName: string;
+  quantity?: number;
+  sortOrder: number;
+  unitPrice?: number;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'close'): void;
+  (event: 'submit', payload: FinanceCostEntryDetailDto): void;
+}>();
+
+const formState = reactive<EditorFormState>({
+  itemId: undefined,
+  itemName: '',
+  amount: 0,
+  quantity: 0,
+  unitPrice: 0,
+  sortOrder: 1,
+});
+
+const isLaborCategory = computed(() => props.category === 'labor');
+const drawerTitle = computed(() =>
+  props.mode === 'create'
+    ? `新增${props.categoryText}明细`
+    : `编辑${props.categoryText}明细`,
+);
+
+const laborComputedAmount = computed(() => {
+  if (!isLaborCategory.value) return formState.amount;
+  return roundAmount((formState.quantity ?? 0) * (formState.unitPrice ?? 0));
+});
+
+watch(
+  () => [props.open, props.sourceItem, props.mode] as const,
+  () => {
+    if (!props.open) return;
+
+    formState.itemId = props.sourceItem?.itemId;
+    formState.itemName = props.sourceItem?.itemName ?? '';
+    formState.amount = props.sourceItem?.amount ?? 0;
+    formState.quantity = props.sourceItem?.quantity ?? 0;
+    formState.unitPrice = props.sourceItem?.unitPrice ?? 0;
+    formState.sortOrder = props.sourceItem?.sortOrder ?? 1;
+  },
+  { immediate: true },
+);
+
+function handleSubmit() {
+  if (!formState.itemName.trim()) {
+    return;
+  }
+
+  formState.amount = isLaborCategory.value
+    ? laborComputedAmount.value
+    : roundAmount(formState.amount);
+
+  emit('submit', {
+    itemId: formState.itemId,
+    itemName: formState.itemName.trim(),
+    amount: Math.max(0, formState.amount),
+    quantity: isLaborCategory.value
+      ? roundAmount(formState.quantity ?? 0)
+      : undefined,
+    unitPrice: isLaborCategory.value
+      ? roundAmount(formState.unitPrice ?? 0)
+      : undefined,
+    sortOrder: Math.max(1, Number(formState.sortOrder || 1)),
+  });
+}
+</script>
+
+<template>
+  <Drawer
+    :open="props.open"
+    :title="drawerTitle"
+    width="460"
+    @close="emit('close')"
+  >
+    <Form layout="vertical">
+      <Form.Item label="明细名称" required>
+        <Input
+          :value="formState.itemName"
+          :maxlength="64"
+          placeholder="请输入明细名称"
+          @update:value="(value) => (formState.itemName = String(value ?? ''))"
+        />
+      </Form.Item>
+
+      <template v-if="isLaborCategory">
+        <Form.Item label="人数" required>
+          <InputNumber
+            class="fc-full-input"
+            :min="0"
+            :precision="2"
+            :controls="false"
+            :value="formState.quantity"
+            @update:value="(value) => (formState.quantity = Number(value ?? 0))"
+          />
+        </Form.Item>
+
+        <Form.Item label="月薪" required>
+          <InputNumber
+            class="fc-full-input"
+            :min="0"
+            :precision="2"
+            :controls="false"
+            :value="formState.unitPrice"
+            @update:value="
+              (value) => (formState.unitPrice = Number(value ?? 0))
+            "
+          />
+        </Form.Item>
+
+        <Form.Item label="小计">
+          <InputNumber
+            class="fc-full-input"
+            :value="laborComputedAmount"
+            :precision="2"
+            :controls="false"
+            disabled
+          />
+        </Form.Item>
+      </template>
+
+      <Form.Item v-else label="金额" required>
+        <InputNumber
+          class="fc-full-input"
+          :min="0"
+          :precision="2"
+          :controls="false"
+          :value="formState.amount"
+          @update:value="(value) => (formState.amount = Number(value ?? 0))"
+        />
+      </Form.Item>
+
+      <Form.Item label="排序">
+        <InputNumber
+          class="fc-full-input"
+          :min="1"
+          :precision="0"
+          :controls="false"
+          :value="formState.sortOrder"
+          @update:value="(value) => (formState.sortOrder = Number(value ?? 1))"
+        />
+      </Form.Item>
+    </Form>
+
+    <template #footer>
+      <div class="fc-drawer-footer">
+        <Button @click="emit('close')">取消</Button>
+        <Button
+          type="primary"
+          :loading="props.submitting"
+          :disabled="!formState.itemName.trim()"
+          @click="handleSubmit"
+        >
+          确认
+        </Button>
+      </div>
+    </template>
+  </Drawer>
+</template>

apps/web-antd/src/views/finance/cost/components/CostPageToolbar.vue

@@ -0,0 +1,107 @@
+<script setup lang="ts">
+import type { FinanceCostTabKey, OptionItem } from '../types';
+
+/**
+ * 文件职责：成本管理顶部工具条（Tab、维度、门店、月份）。
+ */
+import type { FinanceCostDimension } from '#/api/finance/cost';
+
+import { IconifyIcon } from '@vben/icons';
+
+import { Button, Input, Segmented, Select } from 'ant-design-vue';
+
+interface Props {
+  activeTab: FinanceCostTabKey;
+  dimension: FinanceCostDimension;
+  dimensionOptions: Array<{ label: string; value: FinanceCostDimension }>;
+  isStoreLoading: boolean;
+  month: string;
+  monthTitle: string;
+  showStoreSelect: boolean;
+  storeId: string;
+  storeOptions: OptionItem[];
+  tabOptions: Array<{ label: string; value: FinanceCostTabKey }>;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'nextMonth'): void;
+  (event: 'prevMonth'): void;
+  (event: 'update:activeTab', value: FinanceCostTabKey): void;
+  (event: 'update:dimension', value: FinanceCostDimension): void;
+  (event: 'update:month', value: string): void;
+  (event: 'update:storeId', value: string): void;
+}>();
+
+function handleStoreChange(value: unknown) {
+  if (typeof value === 'number' || typeof value === 'string') {
+    emit('update:storeId', String(value));
+    return;
+  }
+  emit('update:storeId', '');
+}
+</script>
+
+<template>
+  <div class="fc-toolbar">
+    <Segmented
+      class="fc-tab-segmented"
+      :value="props.activeTab"
+      :options="props.tabOptions"
+      @update:value="
+        (value) =>
+          emit('update:activeTab', (value as FinanceCostTabKey) || 'entry')
+      "
+    />
+
+    <div class="fc-toolbar-right">
+      <Segmented
+        class="fc-dimension-segmented"
+        :value="props.dimension"
+        :options="props.dimensionOptions"
+        @update:value="
+          (value) =>
+            emit(
+              'update:dimension',
+              (value as FinanceCostDimension) || 'tenant',
+            )
+        "
+      />
+
+      <Select
+        v-if="props.showStoreSelect"
+        class="fc-store-select"
+        :value="props.storeId"
+        :options="props.storeOptions"
+        :loading="props.isStoreLoading"
+        :disabled="props.storeOptions.length === 0"
+        placeholder="请选择门店"
+        @update:value="(value) => handleStoreChange(value)"
+      />
+
+      <div class="fc-month-picker">
+        <Button class="fc-month-arrow" @click="emit('prevMonth')">
+          <template #icon>
+            <IconifyIcon icon="lucide:chevron-left" />
+          </template>
+        </Button>
+
+        <div class="fc-month-title">{{ props.monthTitle }}</div>
+
+        <Button class="fc-month-arrow" @click="emit('nextMonth')">
+          <template #icon>
+            <IconifyIcon icon="lucide:chevron-right" />
+          </template>
+        </Button>
+
+        <Input
+          class="fc-month-input"
+          type="month"
+          :value="props.month"
+          @update:value="(value) => emit('update:month', String(value ?? ''))"
+        />
+      </div>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/finance/cost/composables/cost-page/constants.ts

@@ -0,0 +1,96 @@
+import type {
+  FinanceCostAnalysisState,
+  FinanceCostCategoryViewModel,
+  FinanceCostEntryState,
+  FinanceCostFilterState,
+  FinanceCostTabKey,
+} from '../../types';
+
+/**
+ * 文件职责：成本管理页面常量与默认状态定义。
+ */
+import type { FinanceCostDimension } from '#/api/finance/cost';
+
+/** 成本管理查看权限。 */
+export const FINANCE_COST_VIEW_PERMISSION = 'tenant:finance:cost:view';
+
+/** 成本管理维护权限。 */
+export const FINANCE_COST_MANAGE_PERMISSION = 'tenant:finance:cost:manage';
+
+/** 页面 Tab 选项。 */
+export const COST_TAB_OPTIONS: Array<{
+  label: string;
+  value: FinanceCostTabKey;
+}> = [
+  { label: '成本录入', value: 'entry' },
+  { label: '成本分析', value: 'analysis' },
+];
+
+/** 维度切换选项。 */
+export const COST_DIMENSION_OPTIONS: Array<{
+  label: string;
+  value: FinanceCostDimension;
+}> = [
+  { label: '租户汇总', value: 'tenant' },
+  { label: '门店视角', value: 'store' },
+];
+
+/** 分类颜色映射。 */
+export const COST_CATEGORY_COLOR_MAP: Record<string, string> = {
+  food: '#2563eb',
+  labor: '#16a34a',
+  fixed: '#ca8a04',
+  packaging: '#db2777',
+};
+
+/** 分类图标映射。 */
+export const COST_CATEGORY_ICON_MAP: Record<string, string> = {
+  food: 'lucide:utensils-crossed',
+  labor: 'lucide:users',
+  fixed: 'lucide:building-2',
+  packaging: 'lucide:package',
+};
+
+/** 默认录入状态。 */
+export const DEFAULT_ENTRY_STATE: FinanceCostEntryState = {
+  monthRevenue: 0,
+  totalCost: 0,
+  costRate: 0,
+  categories: [],
+};
+
+/** 默认分析状态。 */
+export const DEFAULT_ANALYSIS_STATE: FinanceCostAnalysisState = {
+  stats: {
+    totalCost: 0,
+    foodCostRate: 0,
+    averageCostPerPaidOrder: 0,
+    monthOnMonthChangeRate: 0,
+    revenue: 0,
+    paidOrderCount: 0,
+  },
+  trend: [],
+  composition: [],
+  detailRows: [],
+};
+
+/** 默认筛选状态。 */
+export const DEFAULT_FILTER_STATE: FinanceCostFilterState = {
+  dimension: 'tenant',
+  month: '',
+  storeId: '',
+};
+
+/** 趋势月数。 */
+export const TREND_MONTH_COUNT = 6;
+
+/** 复制分类列表并重置展开状态。 */
+export function cloneCategoriesWithExpandState(
+  categories: FinanceCostCategoryViewModel[],
+) {
+  return categories.map((item) => ({
+    ...item,
+    items: [...item.items],
+    expanded: Boolean(item.expanded),
+  }));
+}

apps/web-antd/src/views/finance/cost/composables/cost-page/data-actions.ts

@@ -0,0 +1,169 @@
+/**
+ * 文件职责：成本管理页面数据加载与保存动作。
+ */
+import type {
+  FinanceCostAnalysisState,
+  FinanceCostCategoryViewModel,
+  FinanceCostEntryState,
+  FinanceCostFilterState,
+} from '../../types';
+
+import type { StoreListItemDto } from '#/api/store';
+
+import { message } from 'ant-design-vue';
+
+import {
+  getFinanceCostAnalysisApi,
+  getFinanceCostEntryApi,
+  saveFinanceCostEntryApi,
+} from '#/api/finance/cost';
+import { getStoreListApi } from '#/api/store';
+
+import { DEFAULT_ANALYSIS_STATE, DEFAULT_ENTRY_STATE } from './constants';
+import {
+  buildSaveCategoryPayload,
+  buildScopeQueryPayload,
+  mapCategoriesToViewModel,
+} from './helpers';
+
+interface DataActionOptions {
+  analysis: FinanceCostAnalysisState;
+  entry: FinanceCostEntryState;
+  filters: FinanceCostFilterState;
+  isAnalysisLoading: { value: boolean };
+  isEntryLoading: { value: boolean };
+  isSaving: { value: boolean };
+  isStoreLoading: { value: boolean };
+  stores: { value: StoreListItemDto[] };
+}
+
+/** 创建数据动作集合。 */
+export function createDataActions(options: DataActionOptions) {
+  async function loadStores() {
+    options.isStoreLoading.value = true;
+    try {
+      const result = await getStoreListApi({ page: 1, pageSize: 200 });
+      options.stores.value = result.items ?? [];
+    } finally {
+      options.isStoreLoading.value = false;
+    }
+  }
+
+  function clearEntry() {
+    options.entry.monthRevenue = DEFAULT_ENTRY_STATE.monthRevenue;
+    options.entry.totalCost = DEFAULT_ENTRY_STATE.totalCost;
+    options.entry.costRate = DEFAULT_ENTRY_STATE.costRate;
+    options.entry.categories = [];
+  }
+
+  function clearAnalysis() {
+    options.analysis.stats = { ...DEFAULT_ANALYSIS_STATE.stats };
+    options.analysis.trend = [];
+    options.analysis.composition = [];
+    options.analysis.detailRows = [];
+  }
+
+  function clearAllData() {
+    clearEntry();
+    clearAnalysis();
+  }
+
+  async function loadEntryData() {
+    if (options.filters.dimension === 'store' && !options.filters.storeId) {
+      clearEntry();
+      return;
+    }
+
+    options.isEntryLoading.value = true;
+    try {
+      const expandedMap = new Map(
+        (options.entry.categories ?? []).map((item) => [
+          item.category,
+          Boolean(item.expanded),
+        ]),
+      );
+
+      const result = await getFinanceCostEntryApi(
+        buildScopeQueryPayload(options.filters),
+      );
+
+      options.entry.monthRevenue = result.monthRevenue;
+      options.entry.totalCost = result.totalCost;
+      options.entry.costRate = result.costRate;
+      options.entry.categories = mapCategoriesToViewModel(
+        result.categories ?? [],
+        expandedMap,
+      );
+    } finally {
+      options.isEntryLoading.value = false;
+    }
+  }
+
+  async function loadAnalysisData() {
+    if (options.filters.dimension === 'store' && !options.filters.storeId) {
+      clearAnalysis();
+      return;
+    }
+
+    options.isAnalysisLoading.value = true;
+    try {
+      const result = await getFinanceCostAnalysisApi({
+        ...buildScopeQueryPayload(options.filters),
+        trendMonthCount: 6,
+      });
+
+      options.analysis.stats = { ...result.stats };
+      options.analysis.trend = [...(result.trend ?? [])];
+      options.analysis.composition = [...(result.composition ?? [])];
+      options.analysis.detailRows = [...(result.detailRows ?? [])];
+    } finally {
+      options.isAnalysisLoading.value = false;
+    }
+  }
+
+  async function saveEntryData() {
+    if (options.filters.dimension === 'store' && !options.filters.storeId) {
+      message.warning('请先选择门店');
+      return;
+    }
+
+    options.isSaving.value = true;
+    try {
+      const result = await saveFinanceCostEntryApi({
+        ...buildScopeQueryPayload(options.filters),
+        categories: buildSaveCategoryPayload(
+          options.entry.categories as FinanceCostCategoryViewModel[],
+        ),
+      });
+
+      const expandedMap = new Map(
+        (options.entry.categories ?? []).map((item) => [
+          item.category,
+          Boolean(item.expanded),
+        ]),
+      );
+
+      options.entry.monthRevenue = result.monthRevenue;
+      options.entry.totalCost = result.totalCost;
+      options.entry.costRate = result.costRate;
+      options.entry.categories = mapCategoriesToViewModel(
+        result.categories ?? [],
+        expandedMap,
+      );
+
+      message.success('成本数据保存成功');
+    } finally {
+      options.isSaving.value = false;
+    }
+  }
+
+  return {
+    clearAllData,
+    clearAnalysis,
+    clearEntry,
+    loadAnalysisData,
+    loadEntryData,
+    loadStores,
+    saveEntryData,
+  };
+}

apps/web-antd/src/views/finance/cost/composables/cost-page/drawer-actions.ts

@@ -0,0 +1,89 @@
+import type { CostDeleteModalState, CostDetailDrawerState } from '../../types';
+
+/**
+ * 文件职责：成本明细抽屉与删除弹窗动作。
+ */
+import type {
+  FinanceCostCategoryCode,
+  FinanceCostEntryDetailDto,
+} from '#/api/finance/cost';
+
+interface DrawerActionOptions {
+  deleteModalState: CostDeleteModalState;
+  drawerState: CostDetailDrawerState;
+  removeDetailItem: (
+    category: FinanceCostCategoryCode,
+    itemId: string | undefined,
+  ) => void;
+  upsertDetailItem: (
+    category: FinanceCostCategoryCode,
+    detail: FinanceCostEntryDetailDto,
+    mode: 'create' | 'edit',
+  ) => void;
+}
+
+/** 创建抽屉与弹窗动作。 */
+export function createDrawerActions(options: DrawerActionOptions) {
+  function openCreateDrawer(category: FinanceCostCategoryCode) {
+    options.drawerState.open = true;
+    options.drawerState.mode = 'create';
+    options.drawerState.category = category;
+    options.drawerState.sourceItem = undefined;
+  }
+
+  function openEditDrawer(
+    category: FinanceCostCategoryCode,
+    item: FinanceCostEntryDetailDto,
+  ) {
+    options.drawerState.open = true;
+    options.drawerState.mode = 'edit';
+    options.drawerState.category = category;
+    options.drawerState.sourceItem = { ...item };
+  }
+
+  function closeDrawer() {
+    options.drawerState.open = false;
+    options.drawerState.sourceItem = undefined;
+  }
+
+  function submitDrawer(detail: FinanceCostEntryDetailDto) {
+    options.upsertDetailItem(
+      options.drawerState.category,
+      detail,
+      options.drawerState.mode,
+    );
+    closeDrawer();
+  }
+
+  function openDeleteModal(
+    category: FinanceCostCategoryCode,
+    item: FinanceCostEntryDetailDto,
+  ) {
+    options.deleteModalState.open = true;
+    options.deleteModalState.category = category;
+    options.deleteModalState.item = item;
+  }
+
+  function closeDeleteModal() {
+    options.deleteModalState.open = false;
+    options.deleteModalState.item = undefined;
+  }
+
+  function confirmDelete() {
+    options.removeDetailItem(
+      options.deleteModalState.category,
+      options.deleteModalState.item?.itemId,
+    );
+    closeDeleteModal();
+  }
+
+  return {
+    closeDeleteModal,
+    closeDrawer,
+    confirmDelete,
+    openCreateDrawer,
+    openDeleteModal,
+    openEditDrawer,
+    submitDrawer,
+  };
+}

apps/web-antd/src/views/finance/cost/composables/cost-page/entry-actions.ts

@@ -0,0 +1,122 @@
+import type { FinanceCostEntryState } from '../../types';
+
+/**
+ * 文件职责：成本录入分类与明细本地编辑动作。
+ */
+import type {
+  FinanceCostCategoryCode,
+  FinanceCostEntryDetailDto,
+} from '#/api/finance/cost';
+
+import { roundAmount, sumAllCategoryTotal, sumCategoryItems } from './helpers';
+
+interface EntryActionOptions {
+  entry: FinanceCostEntryState;
+}
+
+/** 创建录入区编辑动作。 */
+export function createEntryActions(options: EntryActionOptions) {
+  function toggleCategoryExpanded(category: FinanceCostCategoryCode) {
+    const target = options.entry.categories.find(
+      (item) => item.category === category,
+    );
+    if (!target) return;
+    target.expanded = !target.expanded;
+  }
+
+  function setCategoryTotal(category: FinanceCostCategoryCode, value: number) {
+    const target = options.entry.categories.find(
+      (item) => item.category === category,
+    );
+    if (!target) return;
+    target.totalAmount = Math.max(0, roundAmount(value));
+    syncEntrySummary();
+  }
+
+  function upsertDetailItem(
+    category: FinanceCostCategoryCode,
+    detail: FinanceCostEntryDetailDto,
+    mode: 'create' | 'edit',
+  ) {
+    const target = options.entry.categories.find(
+      (item) => item.category === category,
+    );
+    if (!target) return;
+
+    const nextItem: FinanceCostEntryDetailDto = {
+      ...detail,
+      itemId: detail.itemId || createTempItemId(),
+      amount: resolveDetailAmount(category, detail),
+      quantity:
+        detail.quantity === undefined
+          ? undefined
+          : roundAmount(detail.quantity),
+      unitPrice:
+        detail.unitPrice === undefined
+          ? undefined
+          : roundAmount(detail.unitPrice),
+      sortOrder: detail.sortOrder > 0 ? detail.sortOrder : 1,
+    };
+
+    const index = target.items.findIndex(
+      (item) => item.itemId === detail.itemId,
+    );
+    if (mode === 'edit' && index !== -1) {
+      target.items.splice(index, 1, nextItem);
+    } else {
+      target.items.push(nextItem);
+    }
+
+    target.items.sort((left, right) => left.sortOrder - right.sortOrder);
+    target.totalAmount = sumCategoryItems(target);
+    syncEntrySummary();
+  }
+
+  function removeDetailItem(
+    category: FinanceCostCategoryCode,
+    itemId: string | undefined,
+  ) {
+    const target = options.entry.categories.find(
+      (item) => item.category === category,
+    );
+    if (!target || !itemId) return;
+
+    target.items = target.items.filter((item) => item.itemId !== itemId);
+    target.totalAmount = sumCategoryItems(target);
+    syncEntrySummary();
+  }
+
+  function syncEntrySummary() {
+    const totalCost = sumAllCategoryTotal(options.entry.categories);
+    options.entry.totalCost = totalCost;
+    options.entry.costRate =
+      options.entry.monthRevenue > 0
+        ? roundAmount((totalCost / options.entry.monthRevenue) * 100)
+        : 0;
+  }
+
+  return {
+    removeDetailItem,
+    setCategoryTotal,
+    syncEntrySummary,
+    toggleCategoryExpanded,
+    upsertDetailItem,
+  };
+}
+
+function resolveDetailAmount(
+  category: FinanceCostCategoryCode,
+  detail: FinanceCostEntryDetailDto,
+) {
+  if (category !== 'labor') {
+    return Math.max(0, roundAmount(detail.amount));
+  }
+
+  const quantity = roundAmount(detail.quantity ?? 0);
+  const unitPrice = roundAmount(detail.unitPrice ?? 0);
+  return Math.max(0, roundAmount(quantity * unitPrice));
+}
+
+function createTempItemId() {
+  return `tmp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}

apps/web-antd/src/views/finance/cost/composables/cost-page/filter-actions.ts

@@ -0,0 +1,53 @@
+import type { FinanceCostFilterState, FinanceCostTabKey } from '../../types';
+
+/**
+ * 文件职责：成本管理页面筛选项与月份切换动作。
+ */
+import type { FinanceCostDimension } from '#/api/finance/cost';
+
+import { getCurrentMonthString, shiftMonth } from './helpers';
+
+interface FilterActionOptions {
+  activeTab: { value: FinanceCostTabKey };
+  filters: FinanceCostFilterState;
+}
+
+/** 创建筛选动作。 */
+export function createFilterActions(options: FilterActionOptions) {
+  function setActiveTab(value: FinanceCostTabKey) {
+    options.activeTab.value = value;
+  }
+
+  function setDimension(value: FinanceCostDimension) {
+    options.filters.dimension = value;
+  }
+
+  function setStoreId(value: string) {
+    options.filters.storeId = value;
+  }
+
+  function setMonth(value: string) {
+    options.filters.month = value || getCurrentMonthString();
+  }
+
+  function shiftCurrentMonth(offset: number) {
+    options.filters.month = shiftMonth(options.filters.month, offset);
+  }
+
+  function setPreviousMonth() {
+    shiftCurrentMonth(-1);
+  }
+
+  function setNextMonth() {
+    shiftCurrentMonth(1);
+  }
+
+  return {
+    setActiveTab,
+    setDimension,
+    setMonth,
+    setNextMonth,
+    setPreviousMonth,
+    setStoreId,
+  };
+}

apps/web-antd/src/views/finance/cost/composables/cost-page/helpers.ts

@@ -0,0 +1,154 @@
+import type { FinanceCostFilterState } from '../../types';
+
+/**
+ * 文件职责：成本管理页面纯函数与格式化工具。
+ */
+import type {
+  FinanceCostCategoryCode,
+  FinanceCostEntryCategoryDto,
+  SaveFinanceCostCategoryPayload,
+} from '#/api/finance/cost';
+
+/** 解析为有限数字。 */
+export function toFiniteNumber(value: unknown, fallback = 0) {
+  const normalized = Number(value);
+  return Number.isFinite(normalized) ? normalized : fallback;
+}
+
+/** 金额保留两位小数。 */
+export function roundAmount(value: unknown) {
+  const normalized = toFiniteNumber(value, 0);
+  return Math.round(normalized * 100) / 100;
+}
+
+/** 货币格式化。 */
+export function formatCurrency(value: unknown) {
+  return new Intl.NumberFormat('zh-CN', {
+    style: 'currency',
+    currency: 'CNY',
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  }).format(roundAmount(value));
+}
+
+/** 百分比格式化。 */
+export function formatPercent(value: unknown) {
+  return `${roundAmount(value).toFixed(2)}%`;
+}
+
+/** 获取当前月份（yyyy-MM）。 */
+export function getCurrentMonthString() {
+  const now = new Date();
+  const month = `${now.getMonth() + 1}`.padStart(2, '0');
+  return `${now.getFullYear()}-${month}`;
+}
+
+/** 月份字符串转标题文本。 */
+export function formatMonthTitle(month: string) {
+  const normalized = month.trim();
+  const [year, monthValue] = normalized.split('-');
+  if (!year || !monthValue) {
+    return normalized || '--';
+  }
+  return `${year}年${Number(monthValue)}月`;
+}
+
+/** 月份位移。 */
+export function shiftMonth(month: string, offset: number) {
+  const parsed = parseMonth(month);
+  if (!parsed) {
+    return getCurrentMonthString();
+  }
+  parsed.setMonth(parsed.getMonth() + offset);
+  return formatMonth(parsed);
+}
+
+/** 构建查询作用域参数。 */
+export function buildScopeQueryPayload(filters: FinanceCostFilterState) {
+  return {
+    dimension: filters.dimension,
+    month: filters.month || undefined,
+    storeId:
+      filters.dimension === 'store' ? filters.storeId || undefined : undefined,
+  };
+}
+
+/** 将 API 分类数据映射为页面视图模型。 */
+export function mapCategoriesToViewModel(
+  categories: FinanceCostEntryCategoryDto[],
+  expandedMap: Map<FinanceCostCategoryCode, boolean>,
+) {
+  return (categories ?? []).map((item) => ({
+    ...item,
+    items: [...(item.items ?? [])],
+    expanded: expandedMap.get(item.category) ?? false,
+  }));
+}
+
+/** 计算分类总金额。 */
+export function sumCategoryItems(
+  category: Pick<FinanceCostEntryCategoryDto, 'category' | 'items'>,
+) {
+  let total = 0;
+  for (const item of category.items ?? []) {
+    if (category.category === 'labor') {
+      const quantity = toFiniteNumber(item.quantity, 0);
+      const unitPrice = toFiniteNumber(item.unitPrice, 0);
+      total += roundAmount(quantity * unitPrice);
+      continue;
+    }
+    total += roundAmount(item.amount);
+  }
+  return roundAmount(total);
+}
+
+/** 计算全部分类总成本。 */
+export function sumAllCategoryTotal(categories: FinanceCostEntryCategoryDto[]) {
+  let total = 0;
+  for (const category of categories ?? []) {
+    total += roundAmount(category.totalAmount);
+  }
+  return roundAmount(total);
+}
+
+/** 构建保存请求分类数组。 */
+export function buildSaveCategoryPayload(
+  categories: FinanceCostEntryCategoryDto[],
+): SaveFinanceCostCategoryPayload[] {
+  return (categories ?? []).map((category) => ({
+    category: category.category,
+    totalAmount: roundAmount(category.totalAmount),
+    items: (category.items ?? []).map((item, index) => ({
+      itemId: item.itemId,
+      itemName: item.itemName.trim(),
+      amount: roundAmount(item.amount),
+      quantity:
+        item.quantity === undefined ? undefined : roundAmount(item.quantity),
+      unitPrice:
+        item.unitPrice === undefined ? undefined : roundAmount(item.unitPrice),
+      sortOrder: item.sortOrder > 0 ? item.sortOrder : index + 1,
+    })),
+  }));
+}
+
+function parseMonth(value: string) {
+  const normalized = value.trim();
+  const [year, month] = normalized.split('-');
+  const yearValue = Number(year);
+  const monthValue = Number(month);
+  if (
+    !Number.isInteger(yearValue) ||
+    !Number.isInteger(monthValue) ||
+    monthValue < 1 ||
+    monthValue > 12
+  ) {
+    return null;
+  }
+  return new Date(yearValue, monthValue - 1, 1);
+}
+
+function formatMonth(date: Date) {
+  const year = date.getFullYear();
+  const month = `${date.getMonth() + 1}`.padStart(2, '0');
+  return `${year}-${month}`;
+}

apps/web-antd/src/views/finance/cost/composables/useFinanceCostPage.ts

@@ -0,0 +1,313 @@
+import type {
+  CostDeleteModalState,
+  CostDetailDrawerState,
+  FinanceCostAnalysisState,
+  FinanceCostEntryState,
+  FinanceCostFilterState,
+  FinanceCostTabKey,
+  OptionItem,
+} from '../types';
+
+/**
+ * 文件职责：成本管理页面状态与动作编排。
+ */
+import type { FinanceCostCategoryCode } from '#/api/finance/cost';
+import type { StoreListItemDto } from '#/api/store';
+
+import { computed, onActivated, onMounted, reactive, ref, watch } from 'vue';
+
+import { useAccessStore } from '@vben/stores';
+
+import { message } from 'ant-design-vue';
+
+import {
+  COST_DIMENSION_OPTIONS,
+  COST_TAB_OPTIONS,
+  DEFAULT_ANALYSIS_STATE,
+  DEFAULT_ENTRY_STATE,
+  DEFAULT_FILTER_STATE,
+  FINANCE_COST_MANAGE_PERMISSION,
+  FINANCE_COST_VIEW_PERMISSION,
+} from './cost-page/constants';
+import { createDataActions } from './cost-page/data-actions';
+import { createDrawerActions } from './cost-page/drawer-actions';
+import { createEntryActions } from './cost-page/entry-actions';
+import { createFilterActions } from './cost-page/filter-actions';
+import { formatMonthTitle, getCurrentMonthString } from './cost-page/helpers';
+
+/** 创建成本管理页面组合状态。 */
+export function useFinanceCostPage() {
+  const accessStore = useAccessStore();
+
+  const stores = ref<StoreListItemDto[]>([]);
+  const activeTab = ref<FinanceCostTabKey>('entry');
+  const filters = reactive<FinanceCostFilterState>({
+    ...DEFAULT_FILTER_STATE,
+    month: getCurrentMonthString(),
+  });
+
+  const entry = reactive<FinanceCostEntryState>({
+    ...DEFAULT_ENTRY_STATE,
+  });
+  const analysis = reactive<FinanceCostAnalysisState>({
+    ...DEFAULT_ANALYSIS_STATE,
+  });
+
+  const isStoreLoading = ref(false);
+  const isEntryLoading = ref(false);
+  const isAnalysisLoading = ref(false);
+  const isSaving = ref(false);
+
+  const drawerState = reactive<CostDetailDrawerState>({
+    open: false,
+    mode: 'create',
+    category: 'food',
+  });
+  const deleteModalState = reactive<CostDeleteModalState>({
+    open: false,
+    category: 'food',
+  });
+
+  const accessCodeSet = computed(
+    () => new Set((accessStore.accessCodes ?? []).map(String)),
+  );
+  const canManage = computed(() =>
+    accessCodeSet.value.has(FINANCE_COST_MANAGE_PERMISSION),
+  );
+  const canView = computed(
+    () =>
+      accessCodeSet.value.has(FINANCE_COST_VIEW_PERMISSION) ||
+      accessCodeSet.value.has(FINANCE_COST_MANAGE_PERMISSION),
+  );
+
+  const storeOptions = computed<OptionItem[]>(() =>
+    stores.value.map((item) => ({
+      label: item.name,
+      value: item.id,
+    })),
+  );
+
+  const selectedStoreName = computed(
+    () =>
+      storeOptions.value.find((item) => item.value === filters.storeId)
+        ?.label ?? '--',
+  );
+
+  const monthTitle = computed(() => formatMonthTitle(filters.month));
+  const showStoreSelect = computed(() => filters.dimension === 'store');
+  const hasStore = computed(() => stores.value.length > 0);
+  const canQueryCurrentScope = computed(
+    () => filters.dimension === 'tenant' || Boolean(filters.storeId),
+  );
+  const drawerCategoryText = computed(() => {
+    const matched = entry.categories.find(
+      (item) => item.category === drawerState.category,
+    );
+    return matched?.categoryText || '明细';
+  });
+  const tabOptions = computed(() => COST_TAB_OPTIONS);
+  const dimensionOptions = computed(() => COST_DIMENSION_OPTIONS);
+
+  const dataActions = createDataActions({
+    stores,
+    filters,
+    entry,
+    analysis,
+    isStoreLoading,
+    isEntryLoading,
+    isAnalysisLoading,
+    isSaving,
+  });
+  const entryActions = createEntryActions({ entry });
+  const filterActions = createFilterActions({ activeTab, filters });
+  const drawerActions = createDrawerActions({
+    drawerState,
+    deleteModalState,
+    upsertDetailItem: entryActions.upsertDetailItem,
+    removeDetailItem: entryActions.removeDetailItem,
+  });
+
+  async function loadByCurrentTab() {
+    if (!canView.value) return;
+    if (!canQueryCurrentScope.value) {
+      if (activeTab.value === 'entry') {
+        dataActions.clearEntry();
+      } else {
+        dataActions.clearAnalysis();
+      }
+      return;
+    }
+
+    if (activeTab.value === 'entry') {
+      await dataActions.loadEntryData();
+      return;
+    }
+
+    await dataActions.loadAnalysisData();
+  }
+
+  async function loadAllPanels() {
+    if (!canView.value || !canQueryCurrentScope.value) return;
+    await Promise.all([
+      dataActions.loadEntryData(),
+      dataActions.loadAnalysisData(),
+    ]);
+  }
+
+  function ensureStoreSelection() {
+    if (filters.dimension !== 'store') return;
+    if (filters.storeId) return;
+    if (stores.value.length === 0) return;
+    filters.storeId = stores.value[0]?.id ?? '';
+  }
+
+  function clearByPermission() {
+    stores.value = [];
+    filters.storeId = '';
+    dataActions.clearAllData();
+    drawerActions.closeDrawer();
+    drawerActions.closeDeleteModal();
+  }
+
+  async function initPageData() {
+    if (!canView.value) {
+      clearByPermission();
+      return;
+    }
+
+    await dataActions.loadStores();
+    ensureStoreSelection();
+    await loadByCurrentTab();
+  }
+
+  async function saveEntry() {
+    if (!canManage.value) {
+      message.warning('当前账号没有维护权限');
+      return;
+    }
+
+    await dataActions.saveEntryData();
+    await dataActions.loadAnalysisData();
+  }
+
+  function openAddDetail(category: FinanceCostCategoryCode) {
+    if (!canManage.value) {
+      message.warning('当前账号没有维护权限');
+      return;
+    }
+    drawerActions.openCreateDrawer(category);
+  }
+
+  function openEditDetail(category: FinanceCostCategoryCode, itemId: string) {
+    if (!canManage.value) {
+      message.warning('当前账号没有维护权限');
+      return;
+    }
+
+    const targetCategory = entry.categories.find(
+      (current) => current.category === category,
+    );
+    const targetItem = targetCategory?.items.find(
+      (current) => current.itemId === itemId,
+    );
+    if (!targetItem) return;
+    drawerActions.openEditDrawer(category, targetItem);
+  }
+
+  function openDeleteDetail(category: FinanceCostCategoryCode, itemId: string) {
+    if (!canManage.value) {
+      message.warning('当前账号没有维护权限');
+      return;
+    }
+
+    const targetCategory = entry.categories.find(
+      (current) => current.category === category,
+    );
+    const targetItem = targetCategory?.items.find(
+      (current) => current.itemId === itemId,
+    );
+    if (!targetItem) return;
+    drawerActions.openDeleteModal(category, targetItem);
+  }
+
+  watch(
+    () => activeTab.value,
+    async () => {
+      await loadByCurrentTab();
+    },
+  );
+
+  watch(
+    () => [filters.dimension, filters.storeId, filters.month],
+    async () => {
+      if (filters.dimension === 'store') {
+        ensureStoreSelection();
+      }
+      await loadByCurrentTab();
+    },
+  );
+
+  watch(
+    () => canView.value,
+    async (value, oldValue) => {
+      if (value === oldValue) return;
+      if (!value) {
+        clearByPermission();
+        return;
+      }
+      await initPageData();
+    },
+  );
+
+  onMounted(async () => {
+    await initPageData();
+  });
+
+  onActivated(() => {
+    if (!canView.value) return;
+    if (stores.value.length === 0) {
+      void initPageData();
+    }
+  });
+
+  return {
+    activeTab,
+    analysis,
+    canManage,
+    canQueryCurrentScope,
+    canView,
+    deleteModalState,
+    dimensionOptions,
+    drawerCategoryText,
+    drawerState,
+    entry,
+    filters,
+    hasStore,
+    isAnalysisLoading,
+    isEntryLoading,
+    isSaving,
+    isStoreLoading,
+    loadAllPanels,
+    monthTitle,
+    openAddDetail,
+    openDeleteDetail,
+    openEditDetail,
+    saveEntry,
+    selectedStoreName,
+    setActiveTab: filterActions.setActiveTab,
+    setCategoryTotal: entryActions.setCategoryTotal,
+    setDimension: filterActions.setDimension,
+    setMonth: filterActions.setMonth,
+    setNextMonth: filterActions.setNextMonth,
+    setPreviousMonth: filterActions.setPreviousMonth,
+    setStoreId: filterActions.setStoreId,
+    showStoreSelect,
+    storeOptions,
+    submitDetailFromDrawer: drawerActions.submitDrawer,
+    tabOptions,
+    toggleCategoryExpanded: entryActions.toggleCategoryExpanded,
+    closeDetailDrawer: drawerActions.closeDrawer,
+    closeDeleteModal: drawerActions.closeDeleteModal,
+    confirmDeleteDetail: drawerActions.confirmDelete,
+  };
+}

apps/web-antd/src/views/finance/cost/index.vue

@@ -0,0 +1,184 @@
+<script setup lang="ts">
+/**
+ * 文件职责：财务中心成本管理页面入口编排。
+ */
+import type {
+  FinanceCostCategoryCode,
+  FinanceCostEntryDetailDto,
+} from '#/api/finance/cost';
+
+import { Page } from '@vben/common-ui';
+
+import { Empty } from 'ant-design-vue';
+
+import CostAnalysisComposition from './components/CostAnalysisComposition.vue';
+import CostAnalysisDetailTable from './components/CostAnalysisDetailTable.vue';
+import CostAnalysisStatsBar from './components/CostAnalysisStatsBar.vue';
+import CostAnalysisTrendChart from './components/CostAnalysisTrendChart.vue';
+import CostDetailDeleteModal from './components/CostDetailDeleteModal.vue';
+import CostEntryCategoryCard from './components/CostEntryCategoryCard.vue';
+import CostEntrySummaryBar from './components/CostEntrySummaryBar.vue';
+import CostItemEditorDrawer from './components/CostItemEditorDrawer.vue';
+import CostPageToolbar from './components/CostPageToolbar.vue';
+import {
+  COST_CATEGORY_COLOR_MAP,
+  COST_CATEGORY_ICON_MAP,
+} from './composables/cost-page/constants';
+import { formatCurrency } from './composables/cost-page/helpers';
+import { useFinanceCostPage } from './composables/useFinanceCostPage';
+
+const {
+  activeTab,
+  analysis,
+  canManage,
+  canQueryCurrentScope,
+  canView,
+  closeDeleteModal,
+  closeDetailDrawer,
+  confirmDeleteDetail,
+  deleteModalState,
+  dimensionOptions,
+  drawerCategoryText,
+  drawerState,
+  entry,
+  filters,
+  hasStore,
+  isAnalysisLoading,
+  isEntryLoading,
+  isSaving,
+  isStoreLoading,
+  monthTitle,
+  openAddDetail,
+  openDeleteDetail,
+  openEditDetail,
+  saveEntry,
+  setActiveTab,
+  setCategoryTotal,
+  setDimension,
+  setMonth,
+  setNextMonth,
+  setPreviousMonth,
+  setStoreId,
+  showStoreSelect,
+  storeOptions,
+  submitDetailFromDrawer,
+  tabOptions,
+  toggleCategoryExpanded,
+} = useFinanceCostPage();
+
+function handleAddDetail(category: FinanceCostCategoryCode) {
+  openAddDetail(category);
+}
+
+function handleEditDetail(category: FinanceCostCategoryCode, itemId: string) {
+  openEditDetail(category, itemId);
+}
+
+function handleDeleteDetail(category: FinanceCostCategoryCode, itemId: string) {
+  openDeleteDetail(category, itemId);
+}
+
+function handleSubmitDrawer(detail: FinanceCostEntryDetailDto) {
+  submitDetailFromDrawer(detail);
+}
+</script>
+
+<template>
+  <Page title="成本管理" content-class="page-finance-cost">
+    <div class="fc-page">
+      <CostPageToolbar
+        :active-tab="activeTab"
+        :tab-options="tabOptions"
+        :dimension="filters.dimension"
+        :dimension-options="dimensionOptions"
+        :show-store-select="showStoreSelect"
+        :store-id="filters.storeId"
+        :store-options="storeOptions"
+        :is-store-loading="isStoreLoading"
+        :month="filters.month"
+        :month-title="monthTitle"
+        @update:active-tab="setActiveTab"
+        @update:dimension="setDimension"
+        @update:store-id="setStoreId"
+        @update:month="setMonth"
+        @prev-month="setPreviousMonth"
+        @next-month="setNextMonth"
+      />
+
+      <Empty v-if="!canView" description="暂无成本管理页面访问权限" />
+
+      <div v-else-if="showStoreSelect && !hasStore" class="fc-empty">
+        <Empty description="暂无门店，请先创建门店" />
+      </div>
+
+      <div v-else-if="!canQueryCurrentScope" class="fc-empty">
+        <Empty description="请选择门店后查看数据" />
+      </div>
+
+      <template v-else>
+        <section v-show="activeTab === 'entry'" class="fc-entry-panel">
+          <div class="fc-entry-revenue">
+            本月营业额：<strong>{{
+              formatCurrency(entry.monthRevenue)
+            }}</strong>
+          </div>
+
+          <div class="fc-entry-list" :class="{ 'is-loading': isEntryLoading }">
+            <CostEntryCategoryCard
+              v-for="category in entry.categories"
+              :key="category.category"
+              :category="category"
+              :can-manage="canManage"
+              :icon="COST_CATEGORY_ICON_MAP[category.category]"
+              :color="COST_CATEGORY_COLOR_MAP[category.category]"
+              @toggle="toggleCategoryExpanded"
+              @update-total="setCategoryTotal"
+              @add-item="handleAddDetail"
+              @edit-item="handleEditDetail"
+              @delete-item="handleDeleteDetail"
+            />
+          </div>
+
+          <CostEntrySummaryBar
+            :can-manage="canManage"
+            :loading="isSaving"
+            :total-cost="entry.totalCost"
+            @save="saveEntry"
+          />
+        </section>
+
+        <section v-show="activeTab === 'analysis'" class="fc-analysis-panel">
+          <CostAnalysisStatsBar :stats="analysis.stats" />
+          <CostAnalysisTrendChart :trend="analysis.trend" />
+          <CostAnalysisComposition :composition="analysis.composition" />
+          <CostAnalysisDetailTable
+            :rows="analysis.detailRows"
+            :loading="isAnalysisLoading"
+          />
+        </section>
+      </template>
+    </div>
+
+    <CostItemEditorDrawer
+      :open="drawerState.open"
+      :mode="drawerState.mode"
+      :category="drawerState.category"
+      :category-text="drawerCategoryText"
+      :source-item="drawerState.sourceItem"
+      :submitting="false"
+      @close="closeDetailDrawer"
+      @submit="handleSubmitDrawer"
+    />
+
+    <CostDetailDeleteModal
+      :open="deleteModalState.open"
+      :item-name="deleteModalState.item?.itemName"
+      @cancel="closeDeleteModal"
+      @confirm="confirmDeleteDetail"
+    />
+  </Page>
+</template>
+
+<style lang="less">
+@import './styles/index.less';
+</style>

apps/web-antd/src/views/finance/cost/styles/analysis.less

@@ -0,0 +1,146 @@
+/**
+ * 文件职责：成本分析区域样式。
+ */
+.fc-stats {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 12px;
+}
+
+.fc-stat-card {
+  padding: 16px;
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 10px;
+  box-shadow: 0 2px 8px rgb(15 23 42 / 5%);
+}
+
+.fc-stat-label {
+  margin-bottom: 8px;
+  font-size: 12px;
+  color: rgb(0 0 0 / 45%);
+}
+
+.fc-stat-value {
+  font-size: 22px;
+  font-weight: 800;
+  color: rgb(0 0 0 / 88%);
+
+  &.is-up {
+    color: #ef4444;
+  }
+
+  &.is-down {
+    color: #16a34a;
+  }
+
+  &.is-flat {
+    color: rgb(0 0 0 / 65%);
+  }
+}
+
+.fc-section-title {
+  padding-left: 10px;
+  margin-bottom: 14px;
+  font-size: 15px;
+  font-weight: 600;
+  color: rgb(0 0 0 / 88%);
+  border-left: 3px solid #1677ff;
+}
+
+.fc-chart-card,
+.fc-composition-card,
+.fc-table-card {
+  padding: 18px;
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 10px;
+  box-shadow: 0 2px 8px rgb(15 23 42 / 5%);
+}
+
+.fc-trend-chart {
+  height: 260px;
+}
+
+.fc-composition-body {
+  display: flex;
+  gap: 20px;
+  align-items: center;
+}
+
+.fc-composition-chart-wrap {
+  position: relative;
+  flex-shrink: 0;
+  width: 220px;
+  height: 220px;
+}
+
+.fc-composition-chart {
+  width: 100%;
+  height: 100%;
+}
+
+.fc-composition-center {
+  position: absolute;
+  inset: 71px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  pointer-events: none;
+}
+
+.fc-composition-center-value {
+  font-size: 14px;
+  font-weight: 700;
+  color: rgb(0 0 0 / 88%);
+}
+
+.fc-composition-center-label {
+  font-size: 11px;
+  color: rgb(0 0 0 / 45%);
+}
+
+.fc-composition-legend {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.fc-composition-legend-item {
+  display: grid;
+  grid-template-columns: 10px 1fr auto auto;
+  gap: 8px;
+  align-items: center;
+  font-size: 13px;
+}
+
+.fc-composition-dot {
+  width: 10px;
+  height: 10px;
+  border-radius: 2px;
+}
+
+.fc-composition-name {
+  color: rgb(0 0 0 / 88%);
+}
+
+.fc-composition-amount {
+  min-width: 88px;
+  color: rgb(0 0 0 / 65%);
+  text-align: right;
+}
+
+.fc-composition-percent {
+  min-width: 54px;
+  font-weight: 600;
+  color: rgb(0 0 0 / 88%);
+  text-align: right;
+}
+
+.fc-total-amount {
+  font-weight: 700;
+  color: #1677ff;
+}

apps/web-antd/src/views/finance/cost/styles/base.less

@@ -0,0 +1,22 @@
+/**
+ * 文件职责：成本管理页面基础容器样式。
+ */
+.page-finance-cost {
+  .ant-card {
+    border: 1px solid #f0f0f0;
+    border-radius: 10px;
+  }
+}
+
+.fc-page {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.fc-empty {
+  padding: 36px 0;
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 10px;
+}

apps/web-antd/src/views/finance/cost/styles/drawer.less

@@ -0,0 +1,24 @@
+/**
+ * 文件职责：成本明细抽屉与删除弹窗样式。
+ */
+.fc-full-input {
+  width: 100%;
+}
+
+.fc-drawer-footer {
+  display: flex;
+  gap: 8px;
+  justify-content: flex-end;
+}
+
+.fc-delete-tip {
+  margin: 4px 0 0;
+  font-size: 13px;
+  line-height: 1.8;
+  color: rgb(0 0 0 / 65%);
+
+  strong {
+    margin: 0 4px;
+    color: rgb(0 0 0 / 88%);
+  }
+}

apps/web-antd/src/views/finance/cost/styles/entry.less

@@ -0,0 +1,153 @@
+/**
+ * 文件职责：成本录入区域样式。
+ */
+.fc-entry-list {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.fc-entry-card {
+  .ant-card-body {
+    padding: 0;
+  }
+}
+
+.fc-entry-head {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  padding: 16px 18px;
+}
+
+.fc-entry-icon {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+  width: 40px;
+  height: 40px;
+  font-size: 20px;
+  background: rgb(22 119 255 / 8%);
+  border-radius: 10px;
+}
+
+.fc-entry-meta {
+  min-width: 160px;
+}
+
+.fc-entry-name {
+  font-size: 14px;
+  font-weight: 600;
+  color: rgb(0 0 0 / 88%);
+}
+
+.fc-entry-ratio {
+  margin-left: 8px;
+  font-size: 12px;
+  font-weight: 400;
+  color: rgb(0 0 0 / 45%);
+}
+
+.fc-entry-amount {
+  display: flex;
+  gap: 6px;
+  align-items: center;
+  margin-left: auto;
+}
+
+.fc-entry-currency {
+  font-size: 13px;
+  color: rgb(0 0 0 / 45%);
+}
+
+.fc-entry-input {
+  width: 130px;
+}
+
+.fc-entry-toggle {
+  padding: 0;
+}
+
+.fc-entry-detail {
+  padding: 0 18px 16px;
+  border-top: 1px solid #f3f4f6;
+}
+
+.fc-entry-detail-row {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+  padding: 10px 0;
+  border-bottom: 1px solid #f6f7f9;
+}
+
+.fc-entry-item-name {
+  flex: 1;
+  min-width: 120px;
+  font-size: 13px;
+  color: rgb(0 0 0 / 88%);
+}
+
+.fc-entry-item-value {
+  display: inline-flex;
+  gap: 6px;
+  align-items: center;
+  justify-content: flex-end;
+  min-width: 240px;
+}
+
+.fc-entry-item-amount {
+  font-size: 13px;
+  font-weight: 600;
+  color: rgb(0 0 0 / 88%);
+}
+
+.fc-entry-mul,
+.fc-entry-equal {
+  font-size: 12px;
+  color: rgb(0 0 0 / 45%);
+}
+
+.fc-entry-item-actions {
+  display: inline-flex;
+  justify-content: flex-end;
+  min-width: 104px;
+}
+
+.fc-entry-add {
+  padding: 0;
+  margin-top: 6px;
+}
+
+.fc-entry-empty {
+  padding: 10px 0 2px;
+}
+
+.fc-summary {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 16px 20px;
+  background: #f8f9fb;
+  border: 1px solid #eef0f4;
+  border-radius: 10px;
+}
+
+.fc-summary-label {
+  font-size: 16px;
+  font-weight: 700;
+  color: rgb(0 0 0 / 88%);
+}
+
+.fc-summary-right {
+  display: inline-flex;
+  gap: 14px;
+  align-items: center;
+}
+
+.fc-summary-value {
+  font-size: 24px;
+  font-weight: 800;
+  color: #1677ff;
+}

apps/web-antd/src/views/finance/cost/styles/index.less

@@ -0,0 +1,9 @@
+/**
+ * 文件职责：成本管理页面样式聚合入口。
+ */
+@import './base.less';
+@import './layout.less';
+@import './entry.less';
+@import './analysis.less';
+@import './drawer.less';
+@import './responsive.less';

apps/web-antd/src/views/finance/cost/styles/layout.less

@@ -0,0 +1,86 @@
+/**
+ * 文件职责：成本管理页面布局与顶部工具条样式。
+ */
+.fc-toolbar {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  justify-content: space-between;
+  padding: 14px 16px;
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 10px;
+}
+
+.fc-toolbar-right {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  align-items: center;
+  justify-content: flex-end;
+}
+
+.fc-tab-segmented {
+  .ant-segmented-item {
+    min-width: 108px;
+    text-align: center;
+  }
+}
+
+.fc-dimension-segmented {
+  .ant-segmented-item {
+    min-width: 92px;
+    text-align: center;
+  }
+}
+
+.fc-store-select {
+  width: 230px;
+}
+
+.fc-month-picker {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.fc-month-arrow {
+  width: 32px;
+  min-width: 32px;
+  height: 32px;
+  color: rgb(0 0 0 / 65%);
+}
+
+.fc-month-title {
+  min-width: 100px;
+  font-size: 15px;
+  font-weight: 700;
+  color: rgb(0 0 0 / 88%);
+  text-align: center;
+}
+
+.fc-month-input {
+  width: 128px;
+}
+
+.fc-entry-revenue {
+  padding: 10px 12px;
+  font-size: 13px;
+  color: rgb(0 0 0 / 65%);
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 10px;
+
+  strong {
+    margin-left: 6px;
+    font-size: 15px;
+    color: #1677ff;
+  }
+}
+
+.fc-entry-panel,
+.fc-analysis-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}

apps/web-antd/src/views/finance/cost/styles/responsive.less

@@ -0,0 +1,84 @@
+/**
+ * 文件职责：成本管理页面响应式适配样式。
+ */
+@media (max-width: 1280px) {
+  .fc-stats {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .fc-composition-body {
+    align-items: flex-start;
+  }
+}
+
+@media (max-width: 992px) {
+  .fc-toolbar {
+    flex-direction: column;
+    align-items: stretch;
+  }
+
+  .fc-toolbar-right {
+    justify-content: flex-start;
+  }
+
+  .fc-store-select {
+    width: 100%;
+  }
+
+  .fc-stats {
+    grid-template-columns: 1fr;
+  }
+
+  .fc-composition-body {
+    flex-direction: column;
+  }
+
+  .fc-composition-chart-wrap {
+    margin: 0 auto;
+  }
+}
+
+@media (max-width: 768px) {
+  .fc-entry-head {
+    flex-wrap: wrap;
+  }
+
+  .fc-entry-meta {
+    width: calc(100% - 56px);
+    min-width: unset;
+  }
+
+  .fc-entry-amount {
+    width: 100%;
+    margin-left: 0;
+  }
+
+  .fc-entry-input {
+    flex: 1;
+  }
+
+  .fc-entry-toggle {
+    margin-left: auto;
+  }
+
+  .fc-entry-detail-row {
+    flex-wrap: wrap;
+  }
+
+  .fc-entry-item-value {
+    justify-content: flex-start;
+    width: 100%;
+    min-width: unset;
+  }
+
+  .fc-entry-item-actions {
+    justify-content: flex-start;
+    width: 100%;
+  }
+
+  .fc-summary {
+    flex-direction: column;
+    gap: 10px;
+    align-items: flex-start;
+  }
+}

apps/web-antd/src/views/finance/cost/types.ts

@@ -0,0 +1,67 @@
+/**
+ * 文件职责：成本管理页面本地类型定义。
+ */
+import type {
+  FinanceCostAnalysisDto,
+  FinanceCostCategoryCode,
+  FinanceCostCompositionDto,
+  FinanceCostDimension,
+  FinanceCostEntryCategoryDto,
+  FinanceCostEntryDetailDto,
+  FinanceCostTrendPointDto,
+} from '#/api/finance/cost';
+
+/** 页面 Tab 键。 */
+export type FinanceCostTabKey = 'analysis' | 'entry';
+
+/** 选项项。 */
+export interface OptionItem {
+  label: string;
+  value: string;
+}
+
+/** 成本分类视图模型。 */
+export interface FinanceCostCategoryViewModel extends FinanceCostEntryCategoryDto {
+  expanded: boolean;
+}
+
+/** 录入区域状态。 */
+export interface FinanceCostEntryState {
+  categories: FinanceCostCategoryViewModel[];
+  costRate: number;
+  monthRevenue: number;
+  totalCost: number;
+}
+
+/** 分析区域状态。 */
+export interface FinanceCostAnalysisState {
+  composition: FinanceCostCompositionDto[];
+  detailRows: FinanceCostAnalysisDto['detailRows'];
+  stats: FinanceCostAnalysisDto['stats'];
+  trend: FinanceCostTrendPointDto[];
+}
+
+/** 明细抽屉模式。 */
+export type CostDetailDrawerMode = 'create' | 'edit';
+
+/** 明细抽屉状态。 */
+export interface CostDetailDrawerState {
+  category: FinanceCostCategoryCode;
+  mode: CostDetailDrawerMode;
+  open: boolean;
+  sourceItem?: FinanceCostEntryDetailDto;
+}
+
+/** 删除弹窗状态。 */
+export interface CostDeleteModalState {
+  category: FinanceCostCategoryCode;
+  item?: FinanceCostEntryDetailDto;
+  open: boolean;
+}
+
+/** 页面筛选状态。 */
+export interface FinanceCostFilterState {
+  dimension: FinanceCostDimension;
+  month: string;
+  storeId: string;
+}

apps/web-antd/src/views/finance/invoice/components/InvoiceDetailDrawer.vue

@@ -0,0 +1,136 @@
+<script setup lang="ts">
+/**
+ * 文件职责：发票记录详情抽屉。
+ */
+import type { FinanceInvoiceRecordDetailDto } from '#/api/finance';
+
+import { Button, Drawer, Empty, Spin, Tag } from 'ant-design-vue';
+
+import {
+  formatCurrency,
+  resolveInvoiceStatusTagColor,
+  resolveInvoiceTypeTagColor,
+} from '../composables/invoice-page/helpers';
+
+interface Props {
+  detail: FinanceInvoiceRecordDetailDto | null;
+  loading: boolean;
+  open: boolean;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'close'): void;
+}>();
+</script>
+
+<template>
+  <Drawer
+    :open="props.open"
+    width="620"
+    :title="`发票详情 ${props.detail?.invoiceNo ?? ''}`"
+    @close="emit('close')"
+  >
+    <Spin :spinning="props.loading">
+      <template v-if="props.detail">
+        <div class="fi-section">
+          <div class="fi-section-title">基本信息</div>
+          <div class="fi-info-grid">
+            <div>
+              <span class="label">发票号码：</span>
+              <span class="fi-mono">{{ props.detail.invoiceNo }}</span>
+            </div>
+            <div>
+              <span class="label">状态：</span>
+              <Tag :color="resolveInvoiceStatusTagColor(props.detail.status)">
+                {{ props.detail.statusText }}
+              </Tag>
+            </div>
+            <div>
+              <span class="label">申请人：</span>
+              <span>{{ props.detail.applicantName || '--' }}</span>
+            </div>
+            <div>
+              <span class="label">发票类型：</span>
+              <Tag :color="resolveInvoiceTypeTagColor(props.detail.invoiceType)">
+                {{ props.detail.invoiceTypeText || '--' }}
+              </Tag>
+            </div>
+            <div class="full">
+              <span class="label">公司抬头：</span>
+              <span>{{ props.detail.companyName || '--' }}</span>
+            </div>
+            <div>
+              <span class="label">纳税人识别号：</span>
+              <span class="fi-mono">{{ props.detail.taxpayerNumber || '--' }}</span>
+            </div>
+            <div>
+              <span class="label">开票金额：</span>
+              <span class="fi-amount-strong">{{ formatCurrency(props.detail.amount) }}</span>
+            </div>
+            <div class="full">
+              <span class="label">关联订单：</span>
+              <span class="fi-mono">{{ props.detail.orderNo || '--' }}</span>
+            </div>
+          </div>
+        </div>
+
+        <div class="fi-section">
+          <div class="fi-section-title">联系信息</div>
+          <div class="fi-info-grid">
+            <div>
+              <span class="label">接收邮箱：</span>
+              <span>{{ props.detail.contactEmail || '--' }}</span>
+            </div>
+            <div>
+              <span class="label">联系电话：</span>
+              <span>{{ props.detail.contactPhone || '--' }}</span>
+            </div>
+          </div>
+        </div>
+
+        <div class="fi-section">
+          <div class="fi-section-title">状态记录</div>
+          <div class="fi-timeline">
+            <div class="fi-timeline-item">
+              <span class="text">提交申请</span>
+              <span class="time">{{ props.detail.appliedAt }}</span>
+            </div>
+            <div v-if="props.detail.issuedAt" class="fi-timeline-item">
+              <span class="text">开票完成</span>
+              <span class="time">{{ props.detail.issuedAt }}</span>
+            </div>
+            <div v-if="props.detail.voidedAt" class="fi-timeline-item">
+              <span class="text">发票作废</span>
+              <span class="time">{{ props.detail.voidedAt }}</span>
+            </div>
+          </div>
+        </div>
+
+        <div class="fi-section">
+          <div class="fi-section-title">备注信息</div>
+          <div class="fi-remark-box">
+            <div class="fi-remark-line">
+              <span class="label">申请备注：</span>
+              <span>{{ props.detail.applyRemark || '无' }}</span>
+            </div>
+            <div class="fi-remark-line">
+              <span class="label">开票备注：</span>
+              <span>{{ props.detail.issueRemark || '无' }}</span>
+            </div>
+            <div class="fi-remark-line">
+              <span class="label">作废原因：</span>
+              <span>{{ props.detail.voidReason || '无' }}</span>
+            </div>
+          </div>
+        </div>
+      </template>
+      <Empty v-else description="暂无发票详情" />
+    </Spin>
+
+    <template #footer>
+      <Button @click="emit('close')">关闭</Button>
+    </template>
+  </Drawer>
+</template>

apps/web-antd/src/views/finance/invoice/components/InvoiceFilterBar.vue

@@ -0,0 +1,101 @@
+<script setup lang="ts">
+/**
+ * 文件职责：发票记录筛选工具栏。
+ */
+import type { FinanceInvoiceFilterState } from '../types';
+
+import { IconifyIcon } from '@vben/icons';
+
+import { Input, Select } from 'ant-design-vue';
+
+import {
+  INVOICE_STATUS_OPTIONS,
+  INVOICE_TYPE_OPTIONS,
+} from '../composables/invoice-page/constants';
+
+interface Props {
+  filters: FinanceInvoiceFilterState;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'search'): void;
+  (event: 'update:endDate', value: string): void;
+  (event: 'update:invoiceType', value: string): void;
+  (event: 'update:keyword', value: string): void;
+  (event: 'update:startDate', value: string): void;
+  (event: 'update:status', value: string): void;
+}>();
+
+function handleStartDateChange(value: string | undefined) {
+  emit('update:startDate', String(value ?? ''));
+  emit('search');
+}
+
+function handleEndDateChange(value: string | undefined) {
+  emit('update:endDate', String(value ?? ''));
+  emit('search');
+}
+
+function handleStatusChange(value: unknown) {
+  emit('update:status', String(value ?? 'all'));
+  emit('search');
+}
+
+function handleInvoiceTypeChange(value: unknown) {
+  emit('update:invoiceType', String(value ?? 'all'));
+  emit('search');
+}
+
+function handleKeywordChange(value: string | undefined) {
+  emit('update:keyword', String(value ?? ''));
+}
+</script>
+
+<template>
+  <div class="fi-toolbar">
+    <Input
+      class="fi-date-input"
+      type="date"
+      :value="props.filters.startDate"
+      @update:value="(value) => handleStartDateChange(value)"
+    />
+    <span class="fi-date-sep">至</span>
+    <Input
+      class="fi-date-input"
+      type="date"
+      :value="props.filters.endDate"
+      @update:value="(value) => handleEndDateChange(value)"
+    />
+
+    <Select
+      class="fi-status-select"
+      :value="props.filters.status"
+      :options="INVOICE_STATUS_OPTIONS"
+      @update:value="(value) => handleStatusChange(value)"
+    />
+
+    <Select
+      class="fi-type-select"
+      :value="props.filters.invoiceType"
+      :options="INVOICE_TYPE_OPTIONS"
+      @update:value="(value) => handleInvoiceTypeChange(value)"
+    />
+
+    <div class="fi-toolbar-spacer" />
+
+    <Input
+      class="fi-search"
+      :value="props.filters.keyword"
+      placeholder="搜索发票号码/公司名"
+      allow-clear
+      @update:value="(value) => handleKeywordChange(value)"
+      @press-enter="emit('search')"
+    >
+      <template #prefix>
+        <IconifyIcon icon="lucide:search" class="fi-search-icon" />
+      </template>
+    </Input>
+  </div>
+</template>

apps/web-antd/src/views/finance/invoice/components/InvoiceIssueDrawer.vue

@@ -0,0 +1,121 @@
+<script setup lang="ts">
+/**
+ * 文件职责：发票开票抽屉。
+ */
+import type {
+  FinanceInvoiceRecordDetailDto,
+  FinanceInvoiceRecordListItemDto,
+} from '#/api/finance';
+import type { FinanceInvoiceIssueFormState } from '../types';
+
+import { Button, Drawer, Form, Input, Spin, Tag } from 'ant-design-vue';
+
+import {
+  formatCurrency,
+  resolveInvoiceTypeTagColor,
+} from '../composables/invoice-page/helpers';
+
+interface Props {
+  detail: FinanceInvoiceRecordDetailDto | null;
+  form: FinanceInvoiceIssueFormState;
+  loadingDetail: boolean;
+  open: boolean;
+  submitting: boolean;
+  targetRecord: FinanceInvoiceRecordListItemDto | null;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'close'): void;
+  (event: 'submit'): void;
+  (event: 'update:contactEmail', value: string): void;
+  (event: 'update:issueRemark', value: string): void;
+}>();
+
+function toStringValue(value: string | undefined) {
+  return String(value ?? '');
+}
+</script>
+
+<template>
+  <Drawer
+    :open="props.open"
+    width="560"
+    title="发票开票"
+    @close="emit('close')"
+  >
+    <Spin :spinning="props.loadingDetail">
+      <div class="fi-section">
+        <div class="fi-section-title">开票信息</div>
+        <div class="fi-info-grid">
+          <div>
+            <span class="label">发票号码：</span>
+            <span class="fi-mono">{{ props.targetRecord?.invoiceNo || '--' }}</span>
+          </div>
+          <div>
+            <span class="label">发票类型：</span>
+            <Tag
+              :color="resolveInvoiceTypeTagColor(props.targetRecord?.invoiceType || '')"
+            >
+              {{ props.targetRecord?.invoiceTypeText || '--' }}
+            </Tag>
+          </div>
+          <div>
+            <span class="label">申请人：</span>
+            <span>{{ props.targetRecord?.applicantName || '--' }}</span>
+          </div>
+          <div>
+            <span class="label">开票金额：</span>
+            <span class="fi-amount-strong">{{ formatCurrency(Number(props.targetRecord?.amount || 0)) }}</span>
+          </div>
+          <div class="full">
+            <span class="label">公司抬头：</span>
+            <span>{{ props.targetRecord?.companyName || '--' }}</span>
+          </div>
+          <div class="full">
+            <span class="label">关联订单：</span>
+            <span class="fi-mono">{{ props.targetRecord?.orderNo || '--' }}</span>
+          </div>
+          <div class="full">
+            <span class="label">纳税人识别号：</span>
+            <span class="fi-mono">{{ props.detail?.taxpayerNumber || '--' }}</span>
+          </div>
+        </div>
+      </div>
+
+      <div class="fi-section">
+        <div class="fi-section-title">开票补充信息</div>
+        <Form layout="vertical">
+          <Form.Item label="接收邮箱">
+            <Input
+              :value="props.form.contactEmail"
+              placeholder="请输入开票接收邮箱"
+              @update:value="(value) => emit('update:contactEmail', toStringValue(value))"
+            />
+          </Form.Item>
+
+          <Form.Item label="开票备注">
+            <Input.TextArea
+              :value="props.form.issueRemark"
+              placeholder="请输入开票备注（选填）"
+              :maxlength="200"
+              :rows="4"
+              show-count
+              @update:value="(value) => emit('update:issueRemark', toStringValue(value))"
+            />
+          </Form.Item>
+        </Form>
+      </div>
+    </Spin>
+
+    <template #footer>
+      <div class="fi-drawer-footer">
+        <Button @click="emit('close')">取消</Button>
+        <Button type="primary" :loading="props.submitting" @click="emit('submit')">
+          确认开票
+        </Button>
+      </div>
+    </template>
+  </Drawer>
+</template>

apps/web-antd/src/views/finance/invoice/components/InvoiceIssueResultModal.vue

@@ -0,0 +1,62 @@
+<script setup lang="ts">
+/**
+ * 文件职责：发票开票成功结果弹窗。
+ */
+import type { FinanceInvoiceIssueResultDto } from '#/api/finance';
+
+import { Button } from 'ant-design-vue';
+import { Modal } from 'ant-design-vue';
+
+import { formatCurrency } from '../composables/invoice-page/helpers';
+
+interface Props {
+  open: boolean;
+  result: FinanceInvoiceIssueResultDto | null;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'close'): void;
+}>();
+</script>
+
+<template>
+  <Modal
+    :open="props.open"
+    title="开票完成"
+    :footer="null"
+    @cancel="emit('close')"
+  >
+    <div class="fi-issue-result">
+      <div class="fi-result-title">发票已成功开具</div>
+
+      <div class="fi-result-list">
+        <div class="fi-result-line">
+          <span class="label">发票号码</span>
+          <span class="value fi-mono">{{ props.result?.invoiceNo || '--' }}</span>
+        </div>
+        <div class="fi-result-line">
+          <span class="label">公司抬头</span>
+          <span class="value">{{ props.result?.companyName || '--' }}</span>
+        </div>
+        <div class="fi-result-line">
+          <span class="label">开票金额</span>
+          <span class="value">{{ formatCurrency(Number(props.result?.amount || 0)) }}</span>
+        </div>
+        <div class="fi-result-line">
+          <span class="label">接收邮箱</span>
+          <span class="value">{{ props.result?.contactEmail || '--' }}</span>
+        </div>
+        <div class="fi-result-line">
+          <span class="label">开票时间</span>
+          <span class="value">{{ props.result?.issuedAt || '--' }}</span>
+        </div>
+      </div>
+
+      <div class="fi-result-footer">
+        <Button type="primary" @click="emit('close')">我知道了</Button>
+      </div>
+    </div>
+  </Modal>
+</template>

apps/web-antd/src/views/finance/invoice/components/InvoiceSegmentTabs.vue

@@ -0,0 +1,29 @@
+<script setup lang="ts">
+/**
+ * 文件职责：发票管理分段切换栏。
+ */
+import type { FinanceInvoiceTabKey } from '../types';
+
+import { Segmented } from 'ant-design-vue';
+
+interface Props {
+  activeTab: FinanceInvoiceTabKey;
+  options: Array<{ label: string; value: FinanceInvoiceTabKey }>;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'update:activeTab', value: FinanceInvoiceTabKey): void;
+}>();
+</script>
+
+<template>
+  <div v-if="props.options.length > 0" class="fi-seg-wrap">
+    <Segmented
+      :value="props.activeTab"
+      :options="props.options"
+      @update:value="(value) => emit('update:activeTab', value as FinanceInvoiceTabKey)"
+    />
+  </div>
+</template>

apps/web-antd/src/views/finance/invoice/components/InvoiceSettingsConfirmModal.vue

@@ -0,0 +1,72 @@
+<script setup lang="ts">
+/**
+ * 文件职责：保存发票设置确认弹窗。
+ */
+import type { FinanceInvoiceSettingFormState } from '../types';
+
+import { Modal } from 'ant-design-vue';
+
+import { formatCurrency } from '../composables/invoice-page/helpers';
+
+interface Props {
+  form: FinanceInvoiceSettingFormState;
+  open: boolean;
+  submitting: boolean;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'close'): void;
+  (event: 'confirm'): void;
+}>();
+
+function resolveEnabledText(value: boolean) {
+  return value ? '已开启' : '已关闭';
+}
+</script>
+
+<template>
+  <Modal
+    :open="props.open"
+    title="确认保存发票设置"
+    ok-text="确认保存"
+    cancel-text="取消"
+    :confirm-loading="props.submitting"
+    @ok="emit('confirm')"
+    @cancel="emit('close')"
+  >
+    <div class="fi-settings-confirm">
+      <p class="fi-settings-desc">
+        即将更新企业开票信息与开票规则，请确认以下关键配置：
+      </p>
+
+      <div class="fi-settings-list">
+        <div class="fi-settings-line">
+          <span class="label">企业名称</span>
+          <span class="value">{{ props.form.companyName || '--' }}</span>
+        </div>
+        <div class="fi-settings-line">
+          <span class="label">纳税人识别号</span>
+          <span class="value fi-mono">{{ props.form.taxpayerNumber || '--' }}</span>
+        </div>
+        <div class="fi-settings-line">
+          <span class="label">电子普通发票</span>
+          <span class="value">{{ resolveEnabledText(props.form.enableElectronicNormalInvoice) }}</span>
+        </div>
+        <div class="fi-settings-line">
+          <span class="label">电子专用发票</span>
+          <span class="value">{{ resolveEnabledText(props.form.enableElectronicSpecialInvoice) }}</span>
+        </div>
+        <div class="fi-settings-line">
+          <span class="label">自动开票</span>
+          <span class="value">{{ resolveEnabledText(props.form.enableAutoIssue) }}</span>
+        </div>
+        <div class="fi-settings-line">
+          <span class="label">自动开票上限</span>
+          <span class="value">{{ formatCurrency(Number(props.form.autoIssueMaxAmount || 0)) }}</span>
+        </div>
+      </div>
+    </div>
+  </Modal>
+</template>

apps/web-antd/src/views/finance/invoice/components/InvoiceSettingsPanel.vue

@@ -0,0 +1,171 @@
+<script setup lang="ts">
+/**
+ * 文件职责：发票设置表单区域。
+ */
+import type { FinanceInvoiceSettingFormState } from '../types';
+
+import { Button, Card, Divider, Form, Input, InputNumber, Switch } from 'ant-design-vue';
+
+interface Props {
+  canManageSettings: boolean;
+  form: FinanceInvoiceSettingFormState;
+  saving: boolean;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'reset'): void;
+  (event: 'save'): void;
+  (event: 'update:autoIssueMaxAmount', value: number): void;
+  (event: 'update:bankAccount', value: string): void;
+  (event: 'update:bankName', value: string): void;
+  (event: 'update:companyName', value: string): void;
+  (event: 'update:enableAutoIssue', value: boolean): void;
+  (event: 'update:enableElectronicNormalInvoice', value: boolean): void;
+  (event: 'update:enableElectronicSpecialInvoice', value: boolean): void;
+  (event: 'update:registeredAddress', value: string): void;
+  (event: 'update:registeredPhone', value: string): void;
+  (event: 'update:taxpayerNumber', value: string): void;
+}>();
+
+function toStringValue(value: string | undefined) {
+  return String(value ?? '');
+}
+
+function toNumberValue(value: null | number | string) {
+  const numeric = Number(value ?? 0);
+  return Number.isFinite(numeric) ? numeric : 0;
+}
+</script>
+
+<template>
+  <div class="fi-settings">
+    <Card>
+      <div class="fi-section-hd">企业开票信息</div>
+      <Form layout="vertical">
+        <div class="fi-form-grid">
+          <Form.Item label="企业名称" required>
+            <Input
+              :value="props.form.companyName"
+              placeholder="请输入企业全称"
+              :disabled="!props.canManageSettings"
+              @update:value="(value) => emit('update:companyName', toStringValue(value))"
+            />
+          </Form.Item>
+
+          <Form.Item label="纳税人识别号" required>
+            <Input
+              :value="props.form.taxpayerNumber"
+              placeholder="请输入统一社会信用代码"
+              :disabled="!props.canManageSettings"
+              @update:value="(value) => emit('update:taxpayerNumber', toStringValue(value))"
+            />
+          </Form.Item>
+
+          <Form.Item label="注册地址">
+            <Input
+              :value="props.form.registeredAddress"
+              placeholder="请输入注册地址"
+              :disabled="!props.canManageSettings"
+              @update:value="(value) => emit('update:registeredAddress', toStringValue(value))"
+            />
+          </Form.Item>
+
+          <Form.Item label="注册电话">
+            <Input
+              :value="props.form.registeredPhone"
+              placeholder="请输入注册电话"
+              :disabled="!props.canManageSettings"
+              @update:value="(value) => emit('update:registeredPhone', toStringValue(value))"
+            />
+          </Form.Item>
+
+          <Form.Item label="开户银行">
+            <Input
+              :value="props.form.bankName"
+              placeholder="请输入开户银行名称"
+              :disabled="!props.canManageSettings"
+              @update:value="(value) => emit('update:bankName', toStringValue(value))"
+            />
+          </Form.Item>
+
+          <Form.Item label="银行账号">
+            <Input
+              :value="props.form.bankAccount"
+              placeholder="请输入银行账号"
+              :disabled="!props.canManageSettings"
+              @update:value="(value) => emit('update:bankAccount', toStringValue(value))"
+            />
+          </Form.Item>
+        </div>
+      </Form>
+    </Card>
+
+    <Card>
+      <div class="fi-section-hd">发票类型设置</div>
+      <div class="fi-toggle-row">
+        <Switch
+          :checked="props.form.enableElectronicNormalInvoice"
+          :disabled="!props.canManageSettings"
+          @update:checked="(value) => emit('update:enableElectronicNormalInvoice', Boolean(value))"
+        />
+        <span class="fi-toggle-label">电子普通发票</span>
+      </div>
+
+      <div class="fi-toggle-row">
+        <Switch
+          :checked="props.form.enableElectronicSpecialInvoice"
+          :disabled="!props.canManageSettings"
+          @update:checked="(value) => emit('update:enableElectronicSpecialInvoice', Boolean(value))"
+        />
+        <span class="fi-toggle-label">电子专用发票</span>
+        <span class="fi-toggle-hint">（需先完成税务资质认证）</span>
+      </div>
+    </Card>
+
+    <Card>
+      <div class="fi-section-hd">自动开票设置</div>
+      <div class="fi-toggle-row">
+        <Switch
+          :checked="props.form.enableAutoIssue"
+          :disabled="!props.canManageSettings"
+          @update:checked="(value) => emit('update:enableAutoIssue', Boolean(value))"
+        />
+        <span class="fi-toggle-label">自动开票</span>
+        <span class="fi-toggle-hint">开启后，顾客申请发票将自动开具</span>
+      </div>
+
+      <Divider />
+
+      <Form layout="vertical" class="fi-auto-form">
+        <Form.Item label="单张发票最大金额">
+          <InputNumber
+            class="fi-max-amount-input"
+            :value="props.form.autoIssueMaxAmount"
+            :min="0"
+            :precision="2"
+            :step="100"
+            :disabled="!props.canManageSettings"
+            :formatter="(value) => `￥ ${value}`"
+            :parser="(value) => String(value || '').replace(/￥\s?/g, '')"
+            @update:value="(value) => emit('update:autoIssueMaxAmount', toNumberValue(value))"
+          />
+          <div class="fi-toggle-hint">超过此金额的发票需人工审核后开具</div>
+        </Form.Item>
+      </Form>
+    </Card>
+
+    <div class="fi-save-bar">
+      <Button :disabled="!props.canManageSettings" @click="emit('reset')">重置</Button>
+      <Button
+        type="primary"
+        :disabled="!props.canManageSettings"
+        :loading="props.saving"
+        @click="emit('save')"
+      >
+        保存设置
+      </Button>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/finance/invoice/components/InvoiceStatsBar.vue

@@ -0,0 +1,47 @@
+<script setup lang="ts">
+/**
+ * 文件职责：发票记录统计卡片栏。
+ */
+import type { FinanceInvoiceStatsDto } from '#/api/finance';
+
+import { IconifyIcon } from '@vben/icons';
+
+import { formatCurrency } from '../composables/invoice-page/helpers';
+
+interface Props {
+  stats: FinanceInvoiceStatsDto;
+}
+
+const props = defineProps<Props>();
+</script>
+
+<template>
+  <div class="fi-stats">
+    <div class="fi-stat-card">
+      <div class="fi-stat-label">
+        <IconifyIcon icon="lucide:receipt-text" class="fi-stat-icon" />
+        <span>本月开票</span>
+      </div>
+      <div class="fi-stat-val">{{ formatCurrency(props.stats.currentMonthIssuedAmount) }}</div>
+      <div class="fi-stat-sub">共 {{ props.stats.currentMonthIssuedCount }} 张</div>
+    </div>
+
+    <div class="fi-stat-card warn">
+      <div class="fi-stat-label">
+        <IconifyIcon icon="lucide:clock" class="fi-stat-icon" />
+        <span>待开票</span>
+      </div>
+      <div class="fi-stat-val">{{ props.stats.pendingCount }}</div>
+      <div class="fi-stat-sub">张待处理</div>
+    </div>
+
+    <div class="fi-stat-card danger">
+      <div class="fi-stat-label">
+        <IconifyIcon icon="lucide:ban" class="fi-stat-icon" />
+        <span>已作废</span>
+      </div>
+      <div class="fi-stat-val">{{ props.stats.voidedCount }}</div>
+      <div class="fi-stat-sub">张已作废</div>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/finance/invoice/components/InvoiceTableCard.vue

@@ -0,0 +1,206 @@
+<script setup lang="ts">
+/**
+ * 文件职责：发票记录表格与分页。
+ */
+import type { TablePaginationConfig, TableProps } from 'ant-design-vue';
+
+import type { FinanceInvoiceRecordListItemDto } from '#/api/finance';
+import type { VNode } from 'vue';
+
+import { h } from 'vue';
+
+import { Button, Table, Tag } from 'ant-design-vue';
+
+import {
+  formatCurrency,
+  isIssuedInvoice,
+  isPendingInvoice,
+  resolveInvoiceStatusTagColor,
+  resolveInvoiceTypeTagColor,
+} from '../composables/invoice-page/helpers';
+
+interface PaginationState {
+  page: number;
+  pageSize: number;
+  totalCount: number;
+}
+
+interface Props {
+  canIssue: boolean;
+  canVoid: boolean;
+  loading: boolean;
+  pagination: PaginationState;
+  rows: FinanceInvoiceRecordListItemDto[];
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'detail', recordId: string): void;
+  (event: 'issue', row: FinanceInvoiceRecordListItemDto): void;
+  (event: 'pageChange', page: number, pageSize: number): void;
+  (event: 'void', row: FinanceInvoiceRecordListItemDto): void;
+}>();
+
+function renderActionButtons(row: FinanceInvoiceRecordListItemDto) {
+  const buttons: VNode[] = [];
+
+  if (isPendingInvoice(row.status)) {
+    if (props.canIssue) {
+      buttons.push(
+        h(
+          Button,
+          {
+            type: 'link',
+            class: 'fi-link-action',
+            onClick: () => emit('issue', row),
+          },
+          () => '开票',
+        ),
+      );
+    } else {
+      buttons.push(
+        h(
+          Button,
+          {
+            type: 'link',
+            class: 'fi-link-action',
+            onClick: () => emit('detail', row.recordId),
+          },
+          () => '查看',
+        ),
+      );
+    }
+
+    return h('div', { class: 'fi-action-wrap' }, buttons);
+  }
+
+  buttons.push(
+    h(
+      Button,
+      {
+        type: 'link',
+        class: 'fi-link-action',
+        onClick: () => emit('detail', row.recordId),
+      },
+      () => '查看',
+    ),
+  );
+
+  if (isIssuedInvoice(row.status) && props.canVoid) {
+    buttons.push(
+      h(
+        Button,
+        {
+          type: 'link',
+          danger: true,
+          class: 'fi-link-action',
+          onClick: () => emit('void', row),
+        },
+        () => '作废',
+      ),
+    );
+  }
+
+  return h('div', { class: 'fi-action-wrap' }, buttons);
+}
+
+const columns: TableProps['columns'] = [
+  {
+    title: '发票号码',
+    dataIndex: 'invoiceNo',
+    width: 190,
+    customRender: ({ record }) =>
+      h(
+        'span',
+        {
+          class: 'fi-mono',
+        },
+        String(record.invoiceNo || '--'),
+      ),
+  },
+  {
+    title: '申请人 / 公司名',
+    dataIndex: 'companyName',
+    width: 220,
+    customRender: ({ record }) =>
+      h('div', { class: 'fi-company-cell' }, [
+        h('div', { class: 'fi-applicant' }, String(record.applicantName || '--')),
+        h('div', { class: 'fi-company' }, String(record.companyName || '--')),
+      ]),
+  },
+  {
+    title: '发票类型',
+    dataIndex: 'invoiceTypeText',
+    width: 110,
+    customRender: ({ record }) =>
+      h(
+        Tag,
+        { color: resolveInvoiceTypeTagColor(String(record.invoiceType || '')) },
+        () => String(record.invoiceTypeText || '--'),
+      ),
+  },
+  {
+    title: '金额',
+    dataIndex: 'amount',
+    width: 130,
+    align: 'right',
+    customRender: ({ record }) =>
+      h('span', { class: 'fi-amount' }, formatCurrency(Number(record.amount || 0))),
+  },
+  {
+    title: '关联订单',
+    dataIndex: 'orderNo',
+    width: 170,
+    customRender: ({ text }) =>
+      h('span', { class: 'fi-mono' }, String(text || '--')),
+  },
+  {
+    title: '状态',
+    dataIndex: 'statusText',
+    width: 100,
+    customRender: ({ record }) =>
+      h(
+        Tag,
+        { color: resolveInvoiceStatusTagColor(String(record.status || '')) },
+        () => String(record.statusText || '--'),
+      ),
+  },
+  {
+    title: '申请时间',
+    dataIndex: 'appliedAt',
+    width: 180,
+    customRender: ({ text }) => h('span', { class: 'fi-time' }, String(text || '--')),
+  },
+  {
+    title: '操作',
+    key: 'actions',
+    width: 150,
+    customRender: ({ record }) => renderActionButtons(record),
+  },
+];
+
+function handleTableChange(next: TablePaginationConfig) {
+  emit('pageChange', Number(next.current || 1), Number(next.pageSize || 10));
+}
+</script>
+
+<template>
+  <div class="fi-table-card">
+    <Table
+      row-key="recordId"
+      :columns="columns"
+      :data-source="props.rows"
+      :loading="props.loading"
+      :pagination="{
+        current: props.pagination.page,
+        pageSize: props.pagination.pageSize,
+        total: props.pagination.totalCount,
+        showSizeChanger: true,
+        pageSizeOptions: ['10', '20', '50'],
+        showTotal: (total: number) => `共 ${total} 条`,
+      }"
+      @change="handleTableChange"
+    />
+  </div>
+</template>

apps/web-antd/src/views/finance/invoice/components/InvoiceVoidConfirmModal.vue

@@ -0,0 +1,71 @@
+<script setup lang="ts">
+/**
+ * 文件职责：发票作废确认弹窗。
+ */
+import type { FinanceInvoiceRecordListItemDto } from '#/api/finance';
+import type { FinanceInvoiceVoidFormState } from '../types';
+
+import { Modal, Input } from 'ant-design-vue';
+
+import { formatCurrency } from '../composables/invoice-page/helpers';
+
+interface Props {
+  form: FinanceInvoiceVoidFormState;
+  open: boolean;
+  submitting: boolean;
+  targetRecord: FinanceInvoiceRecordListItemDto | null;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'close'): void;
+  (event: 'submit'): void;
+  (event: 'update:voidReason', value: string): void;
+}>();
+
+function toStringValue(value: string | undefined) {
+  return String(value ?? '');
+}
+</script>
+
+<template>
+  <Modal
+    :open="props.open"
+    title="确认作废发票"
+    ok-text="确认作废"
+    cancel-text="取消"
+    ok-type="danger"
+    :confirm-loading="props.submitting"
+    @ok="emit('submit')"
+    @cancel="emit('close')"
+  >
+    <div class="fi-void-modal">
+      <p class="fi-void-warning">发票作废后不可恢复，请确认本次操作。</p>
+
+      <div class="fi-void-summary">
+        <div class="fi-void-line">
+          <span class="label">发票号码</span>
+          <span class="value fi-mono">{{ props.targetRecord?.invoiceNo || '--' }}</span>
+        </div>
+        <div class="fi-void-line">
+          <span class="label">公司抬头</span>
+          <span class="value">{{ props.targetRecord?.companyName || '--' }}</span>
+        </div>
+        <div class="fi-void-line">
+          <span class="label">开票金额</span>
+          <span class="value">{{ formatCurrency(Number(props.targetRecord?.amount || 0)) }}</span>
+        </div>
+      </div>
+
+      <Input.TextArea
+        :value="props.form.voidReason"
+        :rows="4"
+        :maxlength="200"
+        show-count
+        placeholder="请输入作废原因"
+        @update:value="(value) => emit('update:voidReason', toStringValue(value))"
+      />
+    </div>
+  </Modal>
+</template>

apps/web-antd/src/views/finance/invoice/composables/invoice-page/constants.ts

@@ -0,0 +1,108 @@
+import type {
+  FinanceInvoiceSettingFormState,
+  FinanceInvoiceTabKey,
+  OptionItem,
+} from '../../types';
+
+/**
+ * 文件职责：发票管理页面常量定义。
+ */
+import type { FinanceInvoiceStatsDto } from '#/api/finance';
+
+import { getMonthFirstDateString, getTodayDateString } from './helpers';
+
+/** 发票管理页面查看权限。 */
+export const FINANCE_INVOICE_VIEW_PERMISSION = 'tenant:finance:invoice:view';
+
+/** 发票开票权限。 */
+export const FINANCE_INVOICE_ISSUE_PERMISSION = 'tenant:finance:invoice:issue';
+
+/** 发票作废权限。 */
+export const FINANCE_INVOICE_VOID_PERMISSION = 'tenant:finance:invoice:void';
+
+/** 发票设置权限。 */
+export const FINANCE_INVOICE_SETTINGS_PERMISSION =
+  'tenant:finance:invoice:settings';
+
+/** 分段选项。 */
+export const INVOICE_TAB_OPTIONS: Array<{
+  label: string;
+  value: FinanceInvoiceTabKey;
+}> = [
+  { label: '开票记录', value: 'records' },
+  { label: '发票设置', value: 'settings' },
+];
+
+/** 发票状态筛选项。 */
+export const INVOICE_STATUS_OPTIONS: OptionItem[] = [
+  { label: '全部状态', value: 'all' },
+  { label: '待开票', value: 'pending' },
+  { label: '已开票', value: 'issued' },
+  { label: '已作废', value: 'voided' },
+];
+
+/** 发票类型筛选项。 */
+export const INVOICE_TYPE_OPTIONS: OptionItem[] = [
+  { label: '全部类型', value: 'all' },
+  { label: '普通发票', value: 'normal' },
+  { label: '专用发票', value: 'special' },
+];
+
+/** 默认统计数据。 */
+export const DEFAULT_INVOICE_STATS: FinanceInvoiceStatsDto = {
+  currentMonthIssuedAmount: 0,
+  currentMonthIssuedCount: 0,
+  pendingCount: 0,
+  voidedCount: 0,
+};
+
+/** 创建默认筛选条件。 */
+export function createDefaultFilters() {
+  return {
+    startDate: getMonthFirstDateString(),
+    endDate: getTodayDateString(),
+    status: 'all',
+    invoiceType: 'all',
+    keyword: '',
+  };
+}
+
+/** 创建默认分页。 */
+export function createDefaultPagination() {
+  return {
+    page: 1,
+    pageSize: 10,
+    totalCount: 0,
+  };
+}
+
+/** 创建默认设置表单。 */
+export function createDefaultSettingsForm(): FinanceInvoiceSettingFormState {
+  return {
+    companyName: '',
+    taxpayerNumber: '',
+    registeredAddress: '',
+    registeredPhone: '',
+    bankName: '',
+    bankAccount: '',
+    enableElectronicNormalInvoice: true,
+    enableElectronicSpecialInvoice: false,
+    enableAutoIssue: false,
+    autoIssueMaxAmount: 10_000,
+  };
+}
+
+/** 创建默认开票表单。 */
+export function createDefaultIssueForm() {
+  return {
+    contactEmail: '',
+    issueRemark: '',
+  };
+}
+
+/** 创建默认作废表单。 */
+export function createDefaultVoidForm() {
+  return {
+    voidReason: '',
+  };
+}

apps/web-antd/src/views/finance/invoice/composables/invoice-page/data-actions.ts

@@ -0,0 +1,126 @@
+import type {
+  FinanceInvoiceRecordListItemDto,
+  FinanceInvoiceSettingDto,
+  FinanceInvoiceStatsDto,
+} from '#/api/finance';
+import type {
+  FinanceInvoiceFilterState,
+  FinanceInvoicePaginationState,
+  FinanceInvoiceSettingFormState,
+} from '../../types';
+
+/**
+ * 文件职责：发票管理页面数据加载动作。
+ */
+import {
+  getFinanceInvoiceRecordListApi,
+  getFinanceInvoiceSettingDetailApi,
+} from '#/api/finance';
+
+import {
+  applySettingDtoToForm,
+  buildInvoiceListQuery,
+  cloneSettingsForm,
+} from './helpers';
+
+interface DataActionOptions {
+  canViewRecords: { value: boolean };
+  canViewSettings: { value: boolean };
+  createDefaultSettingsForm: () => FinanceInvoiceSettingFormState;
+  filters: FinanceInvoiceFilterState;
+  isListLoading: { value: boolean };
+  isSettingsLoading: { value: boolean };
+  pagination: FinanceInvoicePaginationState;
+  rows: { value: FinanceInvoiceRecordListItemDto[] };
+  settingForm: FinanceInvoiceSettingFormState;
+  settingSnapshot: { value: FinanceInvoiceSettingFormState };
+  stats: FinanceInvoiceStatsDto;
+}
+
+/** 创建页面数据动作。 */
+export function createDataActions(options: DataActionOptions) {
+  function resetStats() {
+    options.stats.currentMonthIssuedAmount = 0;
+    options.stats.currentMonthIssuedCount = 0;
+    options.stats.pendingCount = 0;
+    options.stats.voidedCount = 0;
+  }
+
+  function clearRecordData() {
+    options.rows.value = [];
+    options.pagination.totalCount = 0;
+    resetStats();
+  }
+
+  function resetSettings() {
+    const defaults = options.createDefaultSettingsForm();
+    Object.assign(options.settingForm, defaults);
+    options.settingSnapshot.value = cloneSettingsForm(defaults);
+  }
+
+  function applySettingsResult(result: FinanceInvoiceSettingDto) {
+    applySettingDtoToForm(options.settingForm, result);
+    options.settingSnapshot.value = cloneSettingsForm(options.settingForm);
+  }
+
+  async function loadRecordList() {
+    if (!options.canViewRecords.value) {
+      clearRecordData();
+      return;
+    }
+
+    options.isListLoading.value = true;
+    try {
+      const result = await getFinanceInvoiceRecordListApi(
+        buildInvoiceListQuery(options.filters, options.pagination),
+      );
+
+      options.rows.value = result.items;
+      options.pagination.page = result.page;
+      options.pagination.pageSize = result.pageSize;
+      options.pagination.totalCount = result.totalCount;
+
+      options.stats.currentMonthIssuedAmount =
+        result.stats.currentMonthIssuedAmount;
+      options.stats.currentMonthIssuedCount = result.stats.currentMonthIssuedCount;
+      options.stats.pendingCount = result.stats.pendingCount;
+      options.stats.voidedCount = result.stats.voidedCount;
+    } finally {
+      options.isListLoading.value = false;
+    }
+  }
+
+  async function loadSettings() {
+    if (!options.canViewSettings.value) {
+      resetSettings();
+      return;
+    }
+
+    options.isSettingsLoading.value = true;
+    try {
+      const result = await getFinanceInvoiceSettingDetailApi();
+      applySettingsResult(result);
+    } finally {
+      options.isSettingsLoading.value = false;
+    }
+  }
+
+  function clearByPermission() {
+    if (!options.canViewRecords.value) {
+      clearRecordData();
+    }
+
+    if (!options.canViewSettings.value) {
+      resetSettings();
+    }
+  }
+
+  return {
+    applySettingsResult,
+    clearByPermission,
+    clearRecordData,
+    loadRecordList,
+    loadSettings,
+    resetSettings,
+  };
+}

apps/web-antd/src/views/finance/invoice/composables/invoice-page/drawer-actions.ts

@@ -0,0 +1,253 @@
+import type {
+  FinanceInvoiceIssueResultDto,
+  FinanceInvoiceRecordDetailDto,
+  FinanceInvoiceRecordListItemDto,
+} from '#/api/finance';
+import type {
+  FinanceInvoiceIssueFormState,
+  FinanceInvoiceVoidFormState,
+} from '../../types';
+
+/**
+ * 文件职责：发票管理页面抽屉与弹窗动作。
+ */
+import {
+  getFinanceInvoiceRecordDetailApi,
+  issueFinanceInvoiceRecordApi,
+  voidFinanceInvoiceRecordApi,
+} from '#/api/finance';
+
+import { message } from 'ant-design-vue';
+
+import { isPendingInvoice, toOptionalTrimmed } from './helpers';
+
+interface DrawerActionOptions {
+  canIssue: { value: boolean };
+  canVoid: { value: boolean };
+  detail: { value: FinanceInvoiceRecordDetailDto | null };
+  isDetailDrawerOpen: { value: boolean };
+  isDetailLoading: { value: boolean };
+  isIssueDetailLoading: { value: boolean };
+  isIssueDrawerOpen: { value: boolean };
+  isIssueResultModalOpen: { value: boolean };
+  isIssueSubmitting: { value: boolean };
+  isVoidModalOpen: { value: boolean };
+  isVoidSubmitting: { value: boolean };
+  issueDetail: { value: FinanceInvoiceRecordDetailDto | null };
+  issueForm: FinanceInvoiceIssueFormState;
+  issueResult: { value: FinanceInvoiceIssueResultDto | null };
+  issueTargetRecord: { value: FinanceInvoiceRecordListItemDto | null };
+  reloadRecordList: () => Promise<void>;
+  voidForm: FinanceInvoiceVoidFormState;
+  voidTargetRecord: { value: FinanceInvoiceRecordListItemDto | null };
+}
+
+/** 创建抽屉与弹窗动作。 */
+export function createDrawerActions(options: DrawerActionOptions) {
+  async function loadDetail(recordId: string) {
+    const result = await getFinanceInvoiceRecordDetailApi({ recordId });
+    options.detail.value = result;
+    return result;
+  }
+
+  function setDetailDrawerOpen(value: boolean) {
+    options.isDetailDrawerOpen.value = value;
+    if (!value) {
+      options.detail.value = null;
+    }
+  }
+
+  function setIssueDrawerOpen(value: boolean) {
+    options.isIssueDrawerOpen.value = value;
+    if (!value) {
+      options.issueTargetRecord.value = null;
+      options.issueDetail.value = null;
+      options.issueForm.contactEmail = '';
+      options.issueForm.issueRemark = '';
+    }
+  }
+
+  function setVoidModalOpen(value: boolean) {
+    options.isVoidModalOpen.value = value;
+    if (!value) {
+      options.voidTargetRecord.value = null;
+      options.voidForm.voidReason = '';
+    }
+  }
+
+  function setIssueResultModalOpen(value: boolean) {
+    options.isIssueResultModalOpen.value = value;
+    if (!value) {
+      options.issueResult.value = null;
+    }
+  }
+
+  async function openDetail(recordId: string) {
+    if (!recordId) {
+      return;
+    }
+
+    options.isDetailDrawerOpen.value = true;
+    options.isDetailLoading.value = true;
+    try {
+      await loadDetail(recordId);
+    } finally {
+      options.isDetailLoading.value = false;
+    }
+  }
+
+  async function openIssue(record: FinanceInvoiceRecordListItemDto) {
+    if (!options.canIssue.value) {
+      message.warning('当前账号暂无开票权限');
+      return;
+    }
+
+    if (!isPendingInvoice(record.status)) {
+      message.warning('仅待开票记录可执行开票');
+      return;
+    }
+
+    options.issueTargetRecord.value = record;
+    options.issueForm.contactEmail = '';
+    options.issueForm.issueRemark = '';
+    options.issueDetail.value = null;
+    options.isIssueDrawerOpen.value = true;
+
+    options.isIssueDetailLoading.value = true;
+    try {
+      const detail = await getFinanceInvoiceRecordDetailApi({
+        recordId: record.recordId,
+      });
+      options.issueDetail.value = detail;
+      options.issueForm.contactEmail = detail.contactEmail ?? '';
+    } finally {
+      options.isIssueDetailLoading.value = false;
+    }
+  }
+
+  async function refreshOpenDetailAfterMutation(recordId: string) {
+    if (!options.isDetailDrawerOpen.value) {
+      return;
+    }
+
+    if (options.detail.value?.recordId !== recordId) {
+      return;
+    }
+
+    options.isDetailLoading.value = true;
+    try {
+      await loadDetail(recordId);
+    } finally {
+      options.isDetailLoading.value = false;
+    }
+  }
+
+  async function submitIssue() {
+    if (!options.canIssue.value) {
+      message.warning('当前账号暂无开票权限');
+      return;
+    }
+
+    const target = options.issueTargetRecord.value;
+    if (!target?.recordId) {
+      message.warning('请选择待开票记录');
+      return;
+    }
+
+    if (!isPendingInvoice(target.status)) {
+      message.warning('当前记录状态不可开票');
+      return;
+    }
+
+    const email = options.issueForm.contactEmail.trim();
+    if (email && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+      message.warning('请填写正确的邮箱地址');
+      return;
+    }
+
+    options.isIssueSubmitting.value = true;
+    try {
+      const result = await issueFinanceInvoiceRecordApi({
+        recordId: target.recordId,
+        contactEmail: toOptionalTrimmed(options.issueForm.contactEmail),
+        issueRemark: toOptionalTrimmed(options.issueForm.issueRemark),
+      });
+
+      options.issueResult.value = result;
+      options.isIssueDrawerOpen.value = false;
+      options.isIssueResultModalOpen.value = true;
+      message.success('发票开具成功');
+
+      await options.reloadRecordList();
+      await refreshOpenDetailAfterMutation(target.recordId);
+    } finally {
+      options.isIssueSubmitting.value = false;
+    }
+  }
+
+  function openVoid(record: FinanceInvoiceRecordListItemDto) {
+    if (!options.canVoid.value) {
+      message.warning('当前账号暂无作废权限');
+      return;
+    }
+
+    options.voidTargetRecord.value = record;
+    options.voidForm.voidReason = '';
+    options.isVoidModalOpen.value = true;
+  }
+
+  async function submitVoid() {
+    if (!options.canVoid.value) {
+      message.warning('当前账号暂无作废权限');
+      return;
+    }
+
+    const target = options.voidTargetRecord.value;
+    if (!target?.recordId) {
+      message.warning('请选择需要作废的发票');
+      return;
+    }
+
+    const reason = options.voidForm.voidReason.trim();
+    if (!reason) {
+      message.warning('请填写作废原因');
+      return;
+    }
+
+    options.isVoidSubmitting.value = true;
+    try {
+      const detail = await voidFinanceInvoiceRecordApi({
+        recordId: target.recordId,
+        voidReason: reason,
+      });
+
+      message.success('发票已作废');
+      options.isVoidModalOpen.value = false;
+      options.voidTargetRecord.value = null;
+      options.voidForm.voidReason = '';
+
+      if (
+        options.isDetailDrawerOpen.value &&
+        options.detail.value?.recordId === detail.recordId
+      ) {
+        options.detail.value = detail;
+      }
+
+      await options.reloadRecordList();
+    } finally {
+      options.isVoidSubmitting.value = false;
+    }
+  }
+
+  return {
+    openDetail,
+    openIssue,
+    openVoid,
+    setDetailDrawerOpen,
+    setIssueDrawerOpen,
+    setIssueResultModalOpen,
+    setVoidModalOpen,
+    submitIssue,
+    submitVoid,
+  };
+}

apps/web-antd/src/views/finance/invoice/composables/invoice-page/helpers.ts

@@ -0,0 +1,173 @@
+import type {
+  FinanceInvoiceRecordListQuery,
+  FinanceInvoiceSettingDto,
+  FinanceInvoiceStatusFilter,
+  FinanceInvoiceTypeFilter,
+} from '#/api/finance';
+import type {
+  FinanceInvoiceFilterState,
+  FinanceInvoicePaginationState,
+  FinanceInvoiceSettingFormState,
+} from '../../types';
+
+/**
+ * 文件职责：发票管理页面纯函数工具。
+ */
+
+function formatDate(date: Date) {
+  const year = date.getFullYear();
+  const month = `${date.getMonth() + 1}`.padStart(2, '0');
+  const day = `${date.getDate()}`.padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+function normalizeStatus(
+  status: FinanceInvoiceStatusFilter,
+): Exclude<FinanceInvoiceStatusFilter, 'all'> | undefined {
+  return status === 'all' ? undefined : status;
+}
+
+function normalizeInvoiceType(
+  invoiceType: FinanceInvoiceTypeFilter,
+): Exclude<FinanceInvoiceTypeFilter, 'all'> | undefined {
+  return invoiceType === 'all' ? undefined : invoiceType;
+}
+
+/** 获取今天日期字符串（yyyy-MM-dd）。 */
+export function getTodayDateString() {
+  return formatDate(new Date());
+}
+
+/** 获取当月第一天日期字符串（yyyy-MM-dd）。 */
+export function getMonthFirstDateString() {
+  const now = new Date();
+  return formatDate(new Date(now.getFullYear(), now.getMonth(), 1));
+}
+
+/** 构建发票记录列表查询参数。 */
+export function buildInvoiceListQuery(
+  filters: FinanceInvoiceFilterState,
+  pagination: FinanceInvoicePaginationState,
+): FinanceInvoiceRecordListQuery {
+  return {
+    page: pagination.page,
+    pageSize: pagination.pageSize,
+    startDate: filters.startDate || undefined,
+    endDate: filters.endDate || undefined,
+    status: normalizeStatus(filters.status),
+    invoiceType: normalizeInvoiceType(filters.invoiceType),
+    keyword: filters.keyword.trim() || undefined,
+  };
+}
+
+/** 判断日期范围是否合法。 */
+export function isDateRangeInvalid(filters: FinanceInvoiceFilterState) {
+  if (!filters.startDate || !filters.endDate) {
+    return false;
+  }
+  return filters.startDate > filters.endDate;
+}
+
+/** 货币格式化（人民币）。 */
+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 resolveInvoiceTypeTagColor(type: string) {
+  if (type === 'normal') return 'blue';
+  if (type === 'special') return 'purple';
+  return 'default';
+}
+
+/** 发票状态标签颜色。 */
+export function resolveInvoiceStatusTagColor(status: string) {
+  if (status === 'pending') return 'orange';
+  if (status === 'issued') return 'green';
+  if (status === 'voided') return 'default';
+  return 'default';
+}
+
+/** 是否为待开票状态。 */
+export function isPendingInvoice(status: string) {
+  return status === 'pending';
+}
+
+/** 是否为已开票状态。 */
+export function isIssuedInvoice(status: string) {
+  return status === 'issued';
+}
+
+/** 应用设置 DTO 到表单。 */
+export function applySettingDtoToForm(
+  target: FinanceInvoiceSettingFormState,
+  source: FinanceInvoiceSettingDto,
+) {
+  target.companyName = source.companyName || '';
+  target.taxpayerNumber = source.taxpayerNumber || '';
+  target.registeredAddress = source.registeredAddress || '';
+  target.registeredPhone = source.registeredPhone || '';
+  target.bankName = source.bankName || '';
+  target.bankAccount = source.bankAccount || '';
+  target.enableElectronicNormalInvoice = Boolean(
+    source.enableElectronicNormalInvoice,
+  );
+  target.enableElectronicSpecialInvoice = Boolean(
+    source.enableElectronicSpecialInvoice,
+  );
+  target.enableAutoIssue = Boolean(source.enableAutoIssue);
+  target.autoIssueMaxAmount = Number(source.autoIssueMaxAmount || 0);
+}
+
+/** 深拷贝设置表单快照。 */
+export function cloneSettingsForm(
+  source: FinanceInvoiceSettingFormState,
+): FinanceInvoiceSettingFormState {
+  return {
+    companyName: source.companyName,
+    taxpayerNumber: source.taxpayerNumber,
+    registeredAddress: source.registeredAddress,
+    registeredPhone: source.registeredPhone,
+    bankName: source.bankName,
+    bankAccount: source.bankAccount,
+    enableElectronicNormalInvoice: source.enableElectronicNormalInvoice,
+    enableElectronicSpecialInvoice: source.enableElectronicSpecialInvoice,
+    enableAutoIssue: source.enableAutoIssue,
+    autoIssueMaxAmount: source.autoIssueMaxAmount,
+  };
+}
+
+/** 比较设置表单是否发生变化。 */
+export function isSettingsChanged(
+  current: FinanceInvoiceSettingFormState,
+  snapshot: FinanceInvoiceSettingFormState,
+) {
+  return JSON.stringify(current) !== JSON.stringify(snapshot);
+}
+
+/** 生成保存设置请求体。 */
+export function buildSettingSavePayload(form: FinanceInvoiceSettingFormState) {
+  return {
+    companyName: form.companyName.trim(),
+    taxpayerNumber: form.taxpayerNumber.trim(),
+    registeredAddress: form.registeredAddress.trim() || undefined,
+    registeredPhone: form.registeredPhone.trim() || undefined,
+    bankName: form.bankName.trim() || undefined,
+    bankAccount: form.bankAccount.trim() || undefined,
+    enableElectronicNormalInvoice: form.enableElectronicNormalInvoice,
+    enableElectronicSpecialInvoice: form.enableElectronicSpecialInvoice,
+    enableAutoIssue: form.enableAutoIssue,
+    autoIssueMaxAmount: Number(form.autoIssueMaxAmount || 0),
+  };
+}
+
+/** 文本转空值。 */
+export function toOptionalTrimmed(value: string) {
+  const normalized = value.trim();
+  return normalized ? normalized : undefined;
+}

apps/web-antd/src/views/finance/invoice/composables/invoice-page/settings-actions.ts

@@ -0,0 +1,120 @@
+import type { FinanceInvoiceSettingFormState } from '../../types';
+
+/**
+ * 文件职责：发票设置保存与确认动作。
+ */
+import type { FinanceInvoiceSettingDto } from '#/api/finance';
+
+import { saveFinanceInvoiceSettingApi } from '#/api/finance';
+
+import { message } from 'ant-design-vue';
+
+import {
+  buildSettingSavePayload,
+  cloneSettingsForm,
+  isSettingsChanged,
+} from './helpers';
+
+interface SettingsActionOptions {
+  applySettingsResult: (result: FinanceInvoiceSettingDto) => void;
+  canManageSettings: { value: boolean };
+  isSettingsConfirmModalOpen: { value: boolean };
+  isSettingsSaving: { value: boolean };
+  settingForm: FinanceInvoiceSettingFormState;
+  settingSnapshot: { value: FinanceInvoiceSettingFormState };
+}
+
+/** 创建发票设置动作。 */
+export function createSettingsActions(options: SettingsActionOptions) {
+  function setSettingsConfirmModalOpen(value: boolean) {
+    options.isSettingsConfirmModalOpen.value = value;
+  }
+
+  function resetSettings() {
+    Object.assign(options.settingForm, cloneSettingsForm(options.settingSnapshot.value));
+  }
+
+  function hasSettingsChanged() {
+    return isSettingsChanged(options.settingForm, options.settingSnapshot.value);
+  }
+
+  function validateSettings() {
+    if (!options.settingForm.companyName.trim()) {
+      message.warning('请输入企业名称');
+      return false;
+    }
+
+    if (!options.settingForm.taxpayerNumber.trim()) {
+      message.warning('请输入纳税人识别号');
+      return false;
+    }
+
+    if (
+      !options.settingForm.enableElectronicNormalInvoice &&
+      !options.settingForm.enableElectronicSpecialInvoice
+    ) {
+      message.warning('请至少启用一种发票类型');
+      return false;
+    }
+
+    if (options.settingForm.enableAutoIssue) {
+      const maxAmount = Number(options.settingForm.autoIssueMaxAmount || 0);
+      if (!Number.isFinite(maxAmount) || maxAmount <= 0) {
+        message.warning('自动开票最大金额必须大于 0');
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  function openSettingsConfirmModal() {
+    if (!options.canManageSettings.value) {
+      message.warning('当前账号暂无发票设置权限');
+      return;
+    }
+
+    if (!validateSettings()) {
+      return;
+    }
+
+    if (!hasSettingsChanged()) {
+      message.info('未检测到设置变更');
+      return;
+    }
+
+    options.isSettingsConfirmModalOpen.value = true;
+  }
+
+  async function submitSettings() {
+    if (!options.canManageSettings.value) {
+      message.warning('当前账号暂无发票设置权限');
+      return;
+    }
+
+    if (!validateSettings()) {
+      return;
+    }
+
+    options.isSettingsSaving.value = true;
+    try {
+      const result = await saveFinanceInvoiceSettingApi(
+        buildSettingSavePayload(options.settingForm),
+      );
+      options.applySettingsResult(result);
+      options.isSettingsConfirmModalOpen.value = false;
+      message.success('发票设置已保存');
+    } finally {
+      options.isSettingsSaving.value = false;
+    }
+  }
+
+  return {
+    hasSettingsChanged,
+    openSettingsConfirmModal,
+    resetSettings,
+    setSettingsConfirmModalOpen,
+    submitSettings,
+    validateSettings,
+  };
+}

apps/web-antd/src/views/finance/invoice/composables/useFinanceInvoicePage.ts

@@ -0,0 +1,397 @@
+/**
+ * 文件职责：发票管理页面状态与动作编排。
+ */
+import type {
+  FinanceInvoiceIssueResultDto,
+  FinanceInvoiceRecordDetailDto,
+  FinanceInvoiceRecordListItemDto,
+  FinanceInvoiceStatsDto,
+} from '#/api/finance';
+import type {
+  FinanceInvoiceFilterState,
+  FinanceInvoiceIssueFormState,
+  FinanceInvoicePaginationState,
+  FinanceInvoiceSettingFormState,
+  FinanceInvoiceTabKey,
+  FinanceInvoiceVoidFormState,
+} from '../types';
+
+import { computed, onActivated, onMounted, reactive, ref, watch } from 'vue';
+
+import { useAccessStore } from '@vben/stores';
+
+import { message } from 'ant-design-vue';
+
+import {
+  createDefaultFilters,
+  createDefaultIssueForm,
+  createDefaultPagination,
+  createDefaultSettingsForm,
+  createDefaultVoidForm,
+  DEFAULT_INVOICE_STATS,
+  FINANCE_INVOICE_ISSUE_PERMISSION,
+  FINANCE_INVOICE_SETTINGS_PERMISSION,
+  FINANCE_INVOICE_VIEW_PERMISSION,
+  FINANCE_INVOICE_VOID_PERMISSION,
+  INVOICE_TAB_OPTIONS,
+} from './invoice-page/constants';
+import { createDataActions } from './invoice-page/data-actions';
+import { createDrawerActions } from './invoice-page/drawer-actions';
+import { isDateRangeInvalid } from './invoice-page/helpers';
+import { createSettingsActions } from './invoice-page/settings-actions';
+
+/** 创建发票管理页面组合状态。 */
+export function useFinanceInvoicePage() {
+  const accessStore = useAccessStore();
+
+  const activeTab = ref<FinanceInvoiceTabKey>('records');
+
+  const filters = reactive<FinanceInvoiceFilterState>(
+    createDefaultFilters() as FinanceInvoiceFilterState,
+  );
+  const pagination = reactive<FinanceInvoicePaginationState>(
+    createDefaultPagination(),
+  );
+  const rows = ref<FinanceInvoiceRecordListItemDto[]>([]);
+
+  const stats = reactive<FinanceInvoiceStatsDto>({ ...DEFAULT_INVOICE_STATS });
+
+  const settingForm = reactive<FinanceInvoiceSettingFormState>(
+    createDefaultSettingsForm(),
+  );
+  const settingSnapshot = ref<FinanceInvoiceSettingFormState>(
+    createDefaultSettingsForm(),
+  );
+
+  const issueForm = reactive<FinanceInvoiceIssueFormState>(
+    createDefaultIssueForm(),
+  );
+  const voidForm = reactive<FinanceInvoiceVoidFormState>(createDefaultVoidForm());
+
+  const detail = ref<FinanceInvoiceRecordDetailDto | null>(null);
+  const issueDetail = ref<FinanceInvoiceRecordDetailDto | null>(null);
+  const issueResult = ref<FinanceInvoiceIssueResultDto | null>(null);
+
+  const issueTargetRecord = ref<FinanceInvoiceRecordListItemDto | null>(null);
+  const voidTargetRecord = ref<FinanceInvoiceRecordListItemDto | null>(null);
+
+  const isListLoading = ref(false);
+  const isSettingsLoading = ref(false);
+  const isDetailLoading = ref(false);
+  const isIssueDetailLoading = ref(false);
+  const isIssueSubmitting = ref(false);
+  const isVoidSubmitting = ref(false);
+  const isSettingsSaving = ref(false);
+
+  const isDetailDrawerOpen = ref(false);
+  const isIssueDrawerOpen = ref(false);
+  const isVoidModalOpen = ref(false);
+  const isIssueResultModalOpen = ref(false);
+  const isSettingsConfirmModalOpen = ref(false);
+
+  const accessCodeSet = computed(
+    () => new Set((accessStore.accessCodes ?? []).map(String)),
+  );
+
+  const canViewRecords = computed(() => {
+    const accessCodes = accessCodeSet.value;
+    return (
+      accessCodes.has(FINANCE_INVOICE_VIEW_PERMISSION) ||
+      accessCodes.has(FINANCE_INVOICE_ISSUE_PERMISSION) ||
+      accessCodes.has(FINANCE_INVOICE_VOID_PERMISSION)
+    );
+  });
+
+  const canIssue = computed(() =>
+    accessCodeSet.value.has(FINANCE_INVOICE_ISSUE_PERMISSION),
+  );
+
+  const canVoid = computed(() =>
+    accessCodeSet.value.has(FINANCE_INVOICE_VOID_PERMISSION),
+  );
+
+  const canViewSettings = computed(() => {
+    const accessCodes = accessCodeSet.value;
+    return (
+      accessCodes.has(FINANCE_INVOICE_VIEW_PERMISSION) ||
+      accessCodes.has(FINANCE_INVOICE_SETTINGS_PERMISSION)
+    );
+  });
+
+  const canManageSettings = computed(() =>
+    accessCodeSet.value.has(FINANCE_INVOICE_SETTINGS_PERMISSION),
+  );
+
+  const canViewPage = computed(
+    () => canViewRecords.value || canViewSettings.value,
+  );
+
+  const tabOptions = computed(() =>
+    INVOICE_TAB_OPTIONS.filter((item) => {
+      if (item.value === 'records') {
+        return canViewRecords.value;
+      }
+      if (item.value === 'settings') {
+        return canViewSettings.value;
+      }
+      return false;
+    }),
+  );
+
+  const {
+    applySettingsResult,
+    clearByPermission,
+    clearRecordData,
+    loadRecordList,
+    loadSettings,
+  } = createDataActions({
+    canViewRecords,
+    canViewSettings,
+    createDefaultSettingsForm,
+    filters,
+    isListLoading,
+    isSettingsLoading,
+    pagination,
+    rows,
+    settingForm,
+    settingSnapshot,
+    stats,
+  });
+
+  const {
+    openDetail,
+    openIssue,
+    openVoid,
+    setDetailDrawerOpen,
+    setIssueDrawerOpen,
+    setIssueResultModalOpen,
+    setVoidModalOpen,
+    submitIssue,
+    submitVoid,
+  } = createDrawerActions({
+    canIssue,
+    canVoid,
+    detail,
+    isDetailDrawerOpen,
+    isDetailLoading,
+    isIssueDetailLoading,
+    isIssueDrawerOpen,
+    isIssueResultModalOpen,
+    isIssueSubmitting,
+    isVoidModalOpen,
+    isVoidSubmitting,
+    issueDetail,
+    issueForm,
+    issueResult,
+    issueTargetRecord,
+    reloadRecordList: loadRecordList,
+    voidForm,
+    voidTargetRecord,
+  });
+
+  const {
+    hasSettingsChanged,
+    openSettingsConfirmModal,
+    resetSettings,
+    setSettingsConfirmModalOpen,
+    submitSettings,
+  } = createSettingsActions({
+    applySettingsResult,
+    canManageSettings,
+    isSettingsConfirmModalOpen,
+    isSettingsSaving,
+    settingForm,
+    settingSnapshot,
+  });
+
+  function setActiveTab(value: FinanceInvoiceTabKey) {
+    activeTab.value = value;
+  }
+
+  function setStartDate(value: string) {
+    filters.startDate = value;
+  }
+
+  function setEndDate(value: string) {
+    filters.endDate = value;
+  }
+
+  function setStatus(value: string) {
+    filters.status = (value || 'all') as FinanceInvoiceFilterState['status'];
+  }
+
+  function setInvoiceType(value: string) {
+    filters.invoiceType = (value || 'all') as FinanceInvoiceFilterState['invoiceType'];
+  }
+
+  function setKeyword(value: string) {
+    filters.keyword = value;
+  }
+
+  function setIssueFormContactEmail(value: string) {
+    issueForm.contactEmail = value;
+  }
+
+  function setIssueFormRemark(value: string) {
+    issueForm.issueRemark = value;
+  }
+
+  function setVoidReason(value: string) {
+    voidForm.voidReason = value;
+  }
+
+  function setSettingsField<K extends keyof FinanceInvoiceSettingFormState>(
+    field: K,
+    value: FinanceInvoiceSettingFormState[K],
+  ) {
+    settingForm[field] = value;
+  }
+
+  async function handleSearch() {
+    if (isDateRangeInvalid(filters)) {
+      message.warning('开始日期不能晚于结束日期');
+      return;
+    }
+
+    pagination.page = 1;
+    await loadRecordList();
+  }
+
+  async function handlePageChange(page: number, pageSize: number) {
+    pagination.page = page;
+    pagination.pageSize = pageSize;
+    await loadRecordList();
+  }
+
+  function closeTransientPanels() {
+    setDetailDrawerOpen(false);
+    setIssueDrawerOpen(false);
+    setVoidModalOpen(false);
+    setIssueResultModalOpen(false);
+    setSettingsConfirmModalOpen(false);
+  }
+
+  async function loadByPermission() {
+    const tasks: Array<Promise<void>> = [];
+
+    if (canViewRecords.value) {
+      tasks.push(loadRecordList());
+    } else {
+      clearRecordData();
+    }
+
+    if (canViewSettings.value) {
+      tasks.push(loadSettings());
+    }
+
+    await Promise.all(tasks);
+  }
+
+  watch(tabOptions, (next) => {
+    const values = next.map((item) => item.value);
+    if (values.length === 0) {
+      return;
+    }
+
+    if (!values.includes(activeTab.value)) {
+      activeTab.value = values[0] as FinanceInvoiceTabKey;
+    }
+  });
+
+  watch(
+    canViewPage,
+    async (value, oldValue) => {
+      if (value === oldValue) {
+        return;
+      }
+
+      if (!value) {
+        clearByPermission();
+        closeTransientPanels();
+        return;
+      }
+
+      await loadByPermission();
+    },
+    { immediate: false },
+  );
+
+  onMounted(async () => {
+    if (!canViewPage.value) {
+      clearByPermission();
+      closeTransientPanels();
+      return;
+    }
+
+    await loadByPermission();
+  });
+
+  onActivated(() => {
+    if (!canViewPage.value) {
+      return;
+    }
+
+    void loadByPermission();
+  });
+
+  return {
+    activeTab,
+    canIssue,
+    canManageSettings,
+    canViewPage,
+    canViewRecords,
+    canViewSettings,
+    canVoid,
+    detail,
+    filters,
+    handlePageChange,
+    handleSearch,
+    hasSettingsChanged,
+    isDetailDrawerOpen,
+    isDetailLoading,
+    isIssueDetailLoading,
+    isIssueDrawerOpen,
+    isIssueResultModalOpen,
+    isIssueSubmitting,
+    isListLoading,
+    isSettingsConfirmModalOpen,
+    isSettingsLoading,
+    isSettingsSaving,
+    isVoidModalOpen,
+    isVoidSubmitting,
+    issueDetail,
+    issueForm,
+    issueResult,
+    issueTargetRecord,
+    openDetail,
+    openIssue,
+    openSettingsConfirmModal,
+    openVoid,
+    pagination,
+    resetSettings,
+    rows,
+    setActiveTab,
+    setDetailDrawerOpen,
+    setEndDate,
+    setInvoiceType,
+    setIssueDrawerOpen,
+    setIssueFormContactEmail,
+    setIssueFormRemark,
+    setIssueResultModalOpen,
+    setKeyword,
+    setSettingsConfirmModalOpen,
+    setSettingsField,
+    setStartDate,
+    setStatus,
+    setVoidModalOpen,
+    setVoidReason,
+    settingForm,
+    stats,
+    submitIssue,
+    submitSettings,
+    submitVoid,
+    tabOptions,
+    voidForm,
+    voidTargetRecord,
+  };
+}

apps/web-antd/src/views/finance/invoice/index.vue

@@ -0,0 +1,198 @@
+<script setup lang="ts">
+/**
+ * 文件职责：财务中心发票管理页面入口编排。
+ */
+import { Page } from '@vben/common-ui';
+
+import { Empty, Spin } from 'ant-design-vue';
+
+import InvoiceDetailDrawer from './components/InvoiceDetailDrawer.vue';
+import InvoiceFilterBar from './components/InvoiceFilterBar.vue';
+import InvoiceIssueDrawer from './components/InvoiceIssueDrawer.vue';
+import InvoiceIssueResultModal from './components/InvoiceIssueResultModal.vue';
+import InvoiceSegmentTabs from './components/InvoiceSegmentTabs.vue';
+import InvoiceSettingsConfirmModal from './components/InvoiceSettingsConfirmModal.vue';
+import InvoiceSettingsPanel from './components/InvoiceSettingsPanel.vue';
+import InvoiceStatsBar from './components/InvoiceStatsBar.vue';
+import InvoiceTableCard from './components/InvoiceTableCard.vue';
+import InvoiceVoidConfirmModal from './components/InvoiceVoidConfirmModal.vue';
+import { useFinanceInvoicePage } from './composables/useFinanceInvoicePage';
+
+const {
+  activeTab,
+  canIssue,
+  canManageSettings,
+  canViewPage,
+  canViewRecords,
+  canViewSettings,
+  canVoid,
+  detail,
+  filters,
+  handlePageChange,
+  handleSearch,
+  isDetailDrawerOpen,
+  isDetailLoading,
+  isIssueDetailLoading,
+  isIssueDrawerOpen,
+  isIssueResultModalOpen,
+  isIssueSubmitting,
+  isListLoading,
+  isSettingsConfirmModalOpen,
+  isSettingsLoading,
+  isSettingsSaving,
+  isVoidModalOpen,
+  isVoidSubmitting,
+  issueDetail,
+  issueForm,
+  issueResult,
+  issueTargetRecord,
+  openDetail,
+  openIssue,
+  openSettingsConfirmModal,
+  openVoid,
+  pagination,
+  resetSettings,
+  rows,
+  setActiveTab,
+  setDetailDrawerOpen,
+  setEndDate,
+  setInvoiceType,
+  setIssueDrawerOpen,
+  setIssueFormContactEmail,
+  setIssueFormRemark,
+  setIssueResultModalOpen,
+  setKeyword,
+  setSettingsConfirmModalOpen,
+  setSettingsField,
+  setStartDate,
+  setStatus,
+  setVoidModalOpen,
+  setVoidReason,
+  settingForm,
+  stats,
+  submitIssue,
+  submitSettings,
+  submitVoid,
+  tabOptions,
+  voidForm,
+  voidTargetRecord,
+} = useFinanceInvoicePage();
+</script>
+
+<template>
+  <Page title="发票管理" content-class="page-finance-invoice">
+    <div class="fi-page">
+      <Empty v-if="!canViewPage" description="暂无发票管理页面访问权限" />
+
+      <template v-else>
+        <InvoiceSegmentTabs
+          :active-tab="activeTab"
+          :options="tabOptions"
+          @update:active-tab="setActiveTab"
+        />
+
+        <section v-show="activeTab === 'records'" class="fi-tab-panel">
+          <template v-if="canViewRecords">
+            <InvoiceStatsBar :stats="stats" />
+
+            <InvoiceFilterBar
+              :filters="filters"
+              @update:start-date="setStartDate"
+              @update:end-date="setEndDate"
+              @update:status="setStatus"
+              @update:invoice-type="setInvoiceType"
+              @update:keyword="setKeyword"
+              @search="handleSearch"
+            />
+
+            <InvoiceTableCard
+              :rows="rows"
+              :loading="isListLoading"
+              :pagination="pagination"
+              :can-issue="canIssue"
+              :can-void="canVoid"
+              @page-change="handlePageChange"
+              @detail="openDetail"
+              @issue="openIssue"
+              @void="openVoid"
+            />
+          </template>
+          <Empty v-else description="暂无开票记录访问权限" />
+        </section>
+
+        <section v-show="activeTab === 'settings'" class="fi-tab-panel">
+          <template v-if="canViewSettings">
+            <Spin :spinning="isSettingsLoading">
+              <InvoiceSettingsPanel
+                :form="settingForm"
+                :can-manage-settings="canManageSettings"
+                :saving="isSettingsSaving"
+                @update:company-name="(value) => setSettingsField('companyName', value)"
+                @update:taxpayer-number="(value) => setSettingsField('taxpayerNumber', value)"
+                @update:registered-address="(value) => setSettingsField('registeredAddress', value)"
+                @update:registered-phone="(value) => setSettingsField('registeredPhone', value)"
+                @update:bank-name="(value) => setSettingsField('bankName', value)"
+                @update:bank-account="(value) => setSettingsField('bankAccount', value)"
+                @update:enable-electronic-normal-invoice="(value) => setSettingsField('enableElectronicNormalInvoice', value)"
+                @update:enable-electronic-special-invoice="(value) => setSettingsField('enableElectronicSpecialInvoice', value)"
+                @update:enable-auto-issue="(value) => setSettingsField('enableAutoIssue', value)"
+                @update:auto-issue-max-amount="(value) => setSettingsField('autoIssueMaxAmount', value)"
+                @reset="resetSettings"
+                @save="openSettingsConfirmModal"
+              />
+            </Spin>
+          </template>
+          <Empty v-else description="暂无发票设置访问权限" />
+        </section>
+      </template>
+    </div>
+
+    <InvoiceIssueDrawer
+      :open="isIssueDrawerOpen"
+      :submitting="isIssueSubmitting"
+      :loading-detail="isIssueDetailLoading"
+      :target-record="issueTargetRecord"
+      :detail="issueDetail"
+      :form="issueForm"
+      @close="setIssueDrawerOpen(false)"
+      @update:contact-email="setIssueFormContactEmail"
+      @update:issue-remark="setIssueFormRemark"
+      @submit="submitIssue"
+    />
+
+    <InvoiceDetailDrawer
+      :open="isDetailDrawerOpen"
+      :loading="isDetailLoading"
+      :detail="detail"
+      @close="setDetailDrawerOpen(false)"
+    />
+
+    <InvoiceVoidConfirmModal
+      :open="isVoidModalOpen"
+      :submitting="isVoidSubmitting"
+      :target-record="voidTargetRecord"
+      :form="voidForm"
+      @close="setVoidModalOpen(false)"
+      @update:void-reason="setVoidReason"
+      @submit="submitVoid"
+    />
+
+    <InvoiceIssueResultModal
+      :open="isIssueResultModalOpen"
+      :result="issueResult"
+      @close="setIssueResultModalOpen(false)"
+    />
+
+    <InvoiceSettingsConfirmModal
+      :open="isSettingsConfirmModalOpen"
+      :submitting="isSettingsSaving"
+      :form="settingForm"
+      @close="setSettingsConfirmModalOpen(false)"
+      @confirm="submitSettings"
+    />
+  </Page>
+</template>
+
+<style lang="less">
+@import './styles/index.less';
+</style>

apps/web-antd/src/views/finance/invoice/styles/base.less

@@ -0,0 +1,24 @@
+/**
+ * 文件职责：发票管理页面基础样式。
+ */
+.page-finance-invoice {
+  .ant-card {
+    border-radius: 10px;
+  }
+}
+
+.fi-page {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.fi-tab-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.fi-mono {
+  font-family: ui-monospace, sfmono-regular, menlo, consolas, monospace;
+}

apps/web-antd/src/views/finance/invoice/styles/drawer.less

@@ -0,0 +1,135 @@
+/**
+ * 文件职责：发票抽屉样式。
+ */
+.page-finance-invoice {
+  .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;
+    }
+  }
+}
+
+.fi-section {
+  margin-bottom: 20px;
+}
+
+.fi-section-title {
+  padding-left: 10px;
+  margin-bottom: 14px;
+  font-size: 14px;
+  font-weight: 600;
+  color: rgb(0 0 0 / 88%);
+  border-left: 3px solid #1677ff;
+}
+
+.fi-info-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 10px 20px;
+  font-size: 13px;
+
+  .label {
+    color: rgb(0 0 0 / 45%);
+  }
+
+  .full {
+    grid-column: 1 / -1;
+  }
+}
+
+.fi-amount-strong {
+  font-weight: 600;
+  color: rgb(0 0 0 / 88%);
+}
+
+.fi-drawer-footer {
+  display: flex;
+  gap: 8px;
+  justify-content: flex-end;
+}
+
+.fi-timeline {
+  position: relative;
+  padding-left: 22px;
+}
+
+.fi-timeline-item {
+  position: relative;
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  padding-bottom: 18px;
+  font-size: 13px;
+
+  &::before {
+    position: absolute;
+    top: 5px;
+    left: -22px;
+    width: 10px;
+    height: 10px;
+    content: '';
+    background: #1677ff;
+    border: 2px solid #d6e4ff;
+    border-radius: 50%;
+  }
+
+  &::after {
+    position: absolute;
+    top: 17px;
+    left: -18px;
+    width: 2px;
+    height: calc(100% - 12px);
+    content: '';
+    background: #e8e8e8;
+  }
+
+  &:last-child {
+    padding-bottom: 0;
+
+    &::after {
+      display: none;
+    }
+  }
+
+  .text {
+    font-weight: 500;
+    color: rgb(0 0 0 / 88%);
+  }
+
+  .time {
+    color: rgb(0 0 0 / 45%);
+  }
+}
+
+.fi-remark-box {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 10px 14px;
+  font-size: 13px;
+  color: rgb(0 0 0 / 65%);
+  background: #fafafa;
+  border: 1px solid #f0f0f0;
+  border-radius: 8px;
+}
+
+.fi-remark-line {
+  display: flex;
+  gap: 8px;
+
+  .label {
+    width: 70px;
+    flex-shrink: 0;
+    color: rgb(0 0 0 / 45%);
+  }
+}

apps/web-antd/src/views/finance/invoice/styles/index.less

@@ -0,0 +1,9 @@
+/**
+ * 文件职责：发票管理页面样式聚合入口。
+ */
+@import './base.less';
+@import './layout.less';
+@import './table.less';
+@import './drawer.less';
+@import './modal.less';
+@import './responsive.less';

apps/web-antd/src/views/finance/invoice/styles/layout.less

@@ -0,0 +1,166 @@
+/**
+ * 文件职责：发票管理页面布局样式。
+ */
+.fi-seg-wrap {
+  margin-bottom: 2px;
+}
+
+.fi-stats {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 12px;
+}
+
+.fi-stat-card {
+  padding: 18px 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);
+  }
+
+  &.warn .fi-stat-val {
+    color: #fa8c16;
+  }
+
+  &.danger .fi-stat-val {
+    color: #ff4d4f;
+  }
+}
+
+.fi-stat-label {
+  display: flex;
+  gap: 6px;
+  align-items: center;
+  margin-bottom: 8px;
+  font-size: 13px;
+  color: rgb(0 0 0 / 45%);
+}
+
+.fi-stat-icon {
+  width: 16px;
+  height: 16px;
+}
+
+.fi-stat-val {
+  font-size: 24px;
+  font-weight: 700;
+  line-height: 1.2;
+  color: rgb(0 0 0 / 88%);
+}
+
+.fi-stat-sub {
+  margin-top: 4px;
+  font-size: 12px;
+  color: rgb(0 0 0 / 45%);
+}
+
+.fi-toolbar {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  align-items: center;
+  padding: 14px 16px;
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 10px;
+  box-shadow: 0 2px 8px rgb(15 23 42 / 6%);
+
+  .fi-date-input {
+    width: 146px;
+  }
+
+  .fi-status-select,
+  .fi-type-select {
+    width: 124px;
+  }
+
+  .fi-date-sep {
+    font-size: 13px;
+    line-height: 32px;
+    color: rgb(0 0 0 / 45%);
+  }
+
+  .fi-toolbar-spacer {
+    flex: 1;
+  }
+
+  .fi-search {
+    width: 220px;
+  }
+
+  .fi-search-icon {
+    width: 14px;
+    height: 14px;
+    color: rgb(0 0 0 / 45%);
+  }
+
+  .ant-select-selector,
+  .ant-input,
+  .ant-input-affix-wrapper {
+    height: 32px;
+    font-size: 13px;
+  }
+
+  .ant-input-affix-wrapper .ant-input {
+    height: 100%;
+  }
+}
+
+.fi-settings {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.fi-section-hd {
+  padding-left: 10px;
+  margin-bottom: 16px;
+  font-size: 15px;
+  font-weight: 600;
+  color: rgb(0 0 0 / 88%);
+  border-left: 3px solid #1677ff;
+}
+
+.fi-form-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 8px 24px;
+}
+
+.fi-toggle-row {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+  margin-bottom: 14px;
+}
+
+.fi-toggle-label {
+  font-size: 13px;
+  font-weight: 500;
+  color: rgb(0 0 0 / 88%);
+}
+
+.fi-toggle-hint {
+  font-size: 12px;
+  color: rgb(0 0 0 / 45%);
+}
+
+.fi-auto-form {
+  max-width: 340px;
+}
+
+.fi-max-amount-input {
+  width: 100%;
+}
+
+.fi-save-bar {
+  display: flex;
+  gap: 8px;
+  justify-content: flex-end;
+}

apps/web-antd/src/views/finance/invoice/styles/modal.less

@@ -0,0 +1,63 @@
+/**
+ * 文件职责：发票弹窗样式。
+ */
+.fi-void-modal,
+.fi-issue-result,
+.fi-settings-confirm {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.fi-void-warning {
+  margin: 0;
+  font-size: 13px;
+  color: #cf1322;
+}
+
+.fi-void-summary,
+.fi-result-list,
+.fi-settings-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 12px 14px;
+  background: #fafafa;
+  border: 1px solid #f0f0f0;
+  border-radius: 8px;
+}
+
+.fi-void-line,
+.fi-result-line,
+.fi-settings-line {
+  display: flex;
+  gap: 16px;
+  justify-content: space-between;
+  font-size: 13px;
+
+  .label {
+    color: rgb(0 0 0 / 45%);
+  }
+
+  .value {
+    color: rgb(0 0 0 / 88%);
+    text-align: right;
+  }
+}
+
+.fi-result-title {
+  font-size: 15px;
+  font-weight: 600;
+  color: #1677ff;
+}
+
+.fi-result-footer {
+  display: flex;
+  justify-content: flex-end;
+}
+
+.fi-settings-desc {
+  margin: 0;
+  font-size: 13px;
+  color: rgb(0 0 0 / 65%);
+}

apps/web-antd/src/views/finance/invoice/styles/responsive.less

@@ -0,0 +1,47 @@
+/**
+ * 文件职责：发票管理页面响应式样式。
+ */
+@media (max-width: 1600px) {
+  .fi-stats {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (max-width: 768px) {
+  .fi-stats {
+    grid-template-columns: 1fr;
+  }
+
+  .fi-toolbar {
+    padding: 14px 12px;
+
+    .fi-date-input,
+    .fi-status-select,
+    .fi-type-select,
+    .fi-search {
+      width: 100%;
+    }
+
+    .fi-date-sep,
+    .fi-toolbar-spacer {
+      display: none;
+    }
+  }
+
+  .fi-form-grid,
+  .fi-info-grid {
+    grid-template-columns: 1fr;
+
+    .full {
+      grid-column: auto;
+    }
+  }
+
+  .fi-save-bar {
+    justify-content: stretch;
+
+    .ant-btn {
+      flex: 1;
+    }
+  }
+}

apps/web-antd/src/views/finance/invoice/styles/table.less

@@ -0,0 +1,62 @@
+/**
+ * 文件职责：发票记录表格样式。
+ */
+.fi-table-card {
+  overflow: hidden;
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 10px;
+
+  .ant-table-wrapper {
+    .ant-table-thead > tr > th {
+      font-size: 13px;
+      white-space: nowrap;
+    }
+
+    .ant-table-tbody > tr > td {
+      font-size: 13px;
+      vertical-align: middle;
+    }
+  }
+
+  .ant-pagination {
+    margin: 14px 16px;
+  }
+}
+
+.fi-company-cell {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+
+  .fi-applicant {
+    font-weight: 500;
+    color: rgb(0 0 0 / 88%);
+  }
+
+  .fi-company {
+    font-size: 12px;
+    color: rgb(0 0 0 / 45%);
+  }
+}
+
+.fi-amount {
+  font-weight: 600;
+  color: rgb(0 0 0 / 88%);
+}
+
+.fi-time {
+  font-size: 12px;
+  color: rgb(0 0 0 / 45%);
+  white-space: nowrap;
+}
+
+.fi-link-action {
+  padding-inline: 0;
+}
+
+.fi-action-wrap {
+  display: inline-flex;
+  gap: 8px;
+  align-items: center;
+}

apps/web-antd/src/views/finance/invoice/types.ts

@@ -0,0 +1,57 @@
+/**
+ * 文件职责：发票管理页面本地状态类型定义。
+ */
+import type {
+  FinanceInvoiceStatusFilter,
+  FinanceInvoiceTypeFilter,
+} from '#/api/finance';
+
+/** 页面分段键。 */
+export type FinanceInvoiceTabKey = 'records' | 'settings';
+
+/** 发票记录筛选状态。 */
+export interface FinanceInvoiceFilterState {
+  endDate: string;
+  invoiceType: FinanceInvoiceTypeFilter;
+  keyword: string;
+  startDate: string;
+  status: FinanceInvoiceStatusFilter;
+}
+
+/** 发票记录分页状态。 */
+export interface FinanceInvoicePaginationState {
+  page: number;
+  pageSize: number;
+  totalCount: number;
+}
+
+/** 发票设置表单状态。 */
+export interface FinanceInvoiceSettingFormState {
+  autoIssueMaxAmount: number;
+  bankAccount: string;
+  bankName: string;
+  companyName: string;
+  enableAutoIssue: boolean;
+  enableElectronicNormalInvoice: boolean;
+  enableElectronicSpecialInvoice: boolean;
+  registeredAddress: string;
+  registeredPhone: string;
+  taxpayerNumber: string;
+}
+
+/** 发票开票抽屉表单状态。 */
+export interface FinanceInvoiceIssueFormState {
+  contactEmail: string;
+  issueRemark: string;
+}
+
+/** 发票作废弹窗表单状态。 */
+export interface FinanceInvoiceVoidFormState {
+  voidReason: string;
+}
+
+/** 通用选项项。 */
+export interface OptionItem {
+  label: string;
+  value: string;
+}

apps/web-antd/src/views/finance/overview/components/OverviewCompositionCard.vue

@@ -0,0 +1,115 @@
+<script setup lang="ts">
+import type { EchartsUIType } from '@vben/plugins/echarts';
+
+/**
+ * 文件职责：财务概览构成环图卡片。
+ */
+import type { FinanceOverviewCompositionViewItem } from '../types';
+
+import { nextTick, onMounted, ref, watch } from 'vue';
+
+import { EchartsUI, useEcharts } from '@vben/plugins/echarts';
+
+import {
+  formatCurrency,
+  formatPercent,
+} from '../composables/overview-page/helpers';
+
+interface Props {
+  items: FinanceOverviewCompositionViewItem[];
+  title: string;
+  totalAmount: number;
+  totalLabel: string;
+}
+
+const props = defineProps<Props>();
+
+const chartRef = ref<EchartsUIType>();
+const { renderEcharts } = useEcharts(chartRef);
+
+function renderChart() {
+  renderEcharts({
+    tooltip: {
+      trigger: 'item',
+      formatter(params: unknown) {
+        const record = params as {
+          name?: string;
+          percent?: number;
+          value?: number;
+        };
+        return `${record.name ?? ''}<br/>${formatCurrency(Number(record.value ?? 0))} (${formatPercent(Number(record.percent ?? 0))})`;
+      },
+    },
+    series: [
+      {
+        type: 'pie',
+        radius: ['55%', '76%'],
+        center: ['50%', '50%'],
+        avoidLabelOverlap: true,
+        label: {
+          show: false,
+        },
+        data: props.items.map((item) => ({
+          name: item.name,
+          value: item.amount,
+          itemStyle: {
+            color: item.color,
+          },
+        })),
+      },
+    ],
+  });
+}
+
+watch(
+  () => props.items,
+  async () => {
+    await nextTick();
+    renderChart();
+  },
+  { deep: true },
+);
+
+onMounted(() => {
+  renderChart();
+});
+</script>
+
+<template>
+  <div class="fo-section-card">
+    <div class="fo-section-title">{{ props.title }}</div>
+
+    <div class="fo-composition-wrap">
+      <div class="fo-composition-chart-wrap">
+        <EchartsUI ref="chartRef" class="fo-composition-chart" />
+
+        <div class="fo-composition-center">
+          <div class="fo-composition-center-value">
+            {{ formatCurrency(props.totalAmount) }}
+          </div>
+          <div class="fo-composition-center-label">{{ props.totalLabel }}</div>
+        </div>
+      </div>
+
+      <div class="fo-composition-legend">
+        <div
+          v-for="item in props.items"
+          :key="item.key"
+          class="fo-composition-legend-item"
+        >
+          <span
+            class="fo-composition-dot"
+            :style="{ backgroundColor: item.color }"
+          ></span>
+          <span class="fo-composition-name">{{ item.name }}</span>
+          <span class="fo-composition-percent">{{
+            formatPercent(item.percentage)
+          }}</span>
+          <span class="fo-composition-amount">{{
+            formatCurrency(item.amount)
+          }}</span>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/finance/overview/components/OverviewIncomeTrendCard.vue

@@ -0,0 +1,143 @@
+<script setup lang="ts">
+import type { EchartsUIType } from '@vben/plugins/echarts';
+
+/**
+ * 文件职责：财务概览收入趋势图卡片。
+ */
+import type {
+  FinanceOverviewIncomeTrendPointDto,
+  FinanceOverviewTrendRange,
+} from '#/api/finance/overview';
+
+import { nextTick, onMounted, ref, watch } from 'vue';
+
+import { EchartsUI, useEcharts } from '@vben/plugins/echarts';
+
+import {
+  formatAxisAmount,
+  formatCurrency,
+} from '../composables/overview-page/helpers';
+
+interface Props {
+  points: FinanceOverviewIncomeTrendPointDto[];
+  range: FinanceOverviewTrendRange;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'update:range', value: FinanceOverviewTrendRange): void;
+}>();
+
+const chartRef = ref<EchartsUIType>();
+const { renderEcharts } = useEcharts(chartRef);
+
+function renderChart() {
+  renderEcharts({
+    tooltip: {
+      trigger: 'axis',
+      formatter(params: unknown) {
+        if (!Array.isArray(params) || params.length === 0) return '';
+        const records = params as Array<{
+          axisValue?: string;
+          value?: number;
+        }>;
+        const record = records[0] ?? {};
+        return `${record.axisValue ?? ''}<br/>实收：${formatCurrency(Number(record.value ?? 0))}`;
+      },
+    },
+    grid: {
+      left: '1%',
+      right: '2%',
+      bottom: '2%',
+      top: '8%',
+      containLabel: true,
+    },
+    xAxis: {
+      type: 'category',
+      boundaryGap: false,
+      axisTick: { show: false },
+      axisLine: {
+        lineStyle: {
+          color: '#e5e7eb',
+        },
+      },
+      data: props.points.map((item) => item.dateLabel),
+    },
+    yAxis: {
+      type: 'value',
+      axisLabel: {
+        formatter: (value: number) => formatAxisAmount(value),
+      },
+      splitLine: {
+        lineStyle: {
+          color: '#f1f5f9',
+          type: 'dashed',
+        },
+      },
+    },
+    series: [
+      {
+        name: '实收',
+        type: 'line',
+        smooth: true,
+        symbol: 'circle',
+        symbolSize: 6,
+        itemStyle: {
+          color: '#1677ff',
+        },
+        areaStyle: {
+          color: 'rgba(22,119,255,0.15)',
+        },
+        lineStyle: {
+          color: '#1677ff',
+          width: 2.5,
+        },
+        data: props.points.map((item) => item.amount),
+      },
+    ],
+  });
+}
+
+watch(
+  () => props.points,
+  async () => {
+    await nextTick();
+    renderChart();
+  },
+  { deep: true },
+);
+
+onMounted(() => {
+  renderChart();
+});
+</script>
+
+<template>
+  <div class="fo-section-card">
+    <div class="fo-section-head">
+      <div class="fo-section-title">收入趋势</div>
+
+      <div class="fo-pills">
+        <button
+          class="fo-pill"
+          :class="{ 'is-active': props.range === '7' }"
+          type="button"
+          @click="emit('update:range', '7')"
+        >
+          近7天
+        </button>
+        <button
+          class="fo-pill"
+          :class="{ 'is-active': props.range === '30' }"
+          type="button"
+          @click="emit('update:range', '30')"
+        >
+          近30天
+        </button>
+      </div>
+    </div>
+
+    <EchartsUI ref="chartRef" class="fo-trend-chart" />
+  </div>
+</template>

apps/web-antd/src/views/finance/overview/components/OverviewKpiRow.vue

@@ -0,0 +1,59 @@
+<script setup lang="ts">
+/**
+ * 文件职责：财务概览 KPI 指标卡。
+ */
+import type { FinanceOverviewKpiKey } from '../composables/overview-page/constants';
+
+import type { FinanceOverviewDashboardDto } from '#/api/finance/overview';
+
+import { computed } from 'vue';
+
+import { IconifyIcon } from '@vben/icons';
+
+import { OVERVIEW_KPI_CONFIG } from '../composables/overview-page/constants';
+import {
+  formatChangeRate,
+  formatCurrency,
+  resolveKpiTrendClass,
+  resolveKpiTrendIcon,
+} from '../composables/overview-page/helpers';
+
+interface Props {
+  dashboard: FinanceOverviewDashboardDto;
+}
+
+const props = defineProps<Props>();
+
+const kpiCards = computed(() =>
+  OVERVIEW_KPI_CONFIG.map((item) => ({
+    ...item,
+    value: props.dashboard[item.key as FinanceOverviewKpiKey],
+  })),
+);
+</script>
+
+<template>
+  <div class="fo-kpi-row">
+    <div
+      v-for="card in kpiCards"
+      :key="card.key"
+      class="fo-kpi-card"
+      :class="`is-${card.tone}`"
+    >
+      <div class="fo-kpi-top">
+        <span class="fo-kpi-label">{{ card.label }}</span>
+        <span class="fo-kpi-icon">
+          <IconifyIcon :icon="card.icon" />
+        </span>
+      </div>
+
+      <div class="fo-kpi-value">{{ formatCurrency(card.value.amount) }}</div>
+
+      <div class="fo-kpi-change" :class="resolveKpiTrendClass(card.value)">
+        <IconifyIcon :icon="resolveKpiTrendIcon(card.value)" />
+        <span>{{ formatChangeRate(card.value.changeRate) }}</span>
+        <span>{{ card.value.compareLabel }}</span>
+      </div>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/finance/overview/components/OverviewProfitTrendCard.vue

@@ -0,0 +1,186 @@
+<script setup lang="ts">
+import type { EchartsUIType } from '@vben/plugins/echarts';
+
+/**
+ * 文件职责：财务概览利润走势图卡片。
+ */
+import type {
+  FinanceOverviewProfitTrendPointDto,
+  FinanceOverviewTrendRange,
+} from '#/api/finance/overview';
+
+import { nextTick, onMounted, ref, watch } from 'vue';
+
+import { EchartsUI, useEcharts } from '@vben/plugins/echarts';
+
+import {
+  formatAxisAmount,
+  formatCurrency,
+} from '../composables/overview-page/helpers';
+
+interface Props {
+  points: FinanceOverviewProfitTrendPointDto[];
+  range: FinanceOverviewTrendRange;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'update:range', value: FinanceOverviewTrendRange): void;
+}>();
+
+const chartRef = ref<EchartsUIType>();
+const { renderEcharts } = useEcharts(chartRef);
+
+function renderChart() {
+  renderEcharts({
+    tooltip: {
+      trigger: 'axis',
+      formatter(params: unknown) {
+        if (!Array.isArray(params) || params.length === 0) return '';
+        const records = params as Array<{
+          axisValue?: string;
+          seriesName?: string;
+          value?: number;
+        }>;
+
+        const date = records[0]?.axisValue ?? '';
+        const revenue = Number(
+          records.find((item) => item.seriesName === '营收')?.value ?? 0,
+        );
+        const cost = Number(
+          records.find((item) => item.seriesName === '成本')?.value ?? 0,
+        );
+        const netProfit = Number(
+          records.find((item) => item.seriesName === '净利润')?.value ?? 0,
+        );
+
+        return `${date}<br/>营收：${formatCurrency(revenue)}<br/>成本：${formatCurrency(cost)}<br/>净利润：${formatCurrency(netProfit)}`;
+      },
+    },
+    grid: {
+      left: '1%',
+      right: '2%',
+      bottom: '2%',
+      top: '8%',
+      containLabel: true,
+    },
+    xAxis: {
+      type: 'category',
+      boundaryGap: false,
+      axisTick: { show: false },
+      axisLine: {
+        lineStyle: {
+          color: '#e5e7eb',
+        },
+      },
+      data: props.points.map((item) => item.dateLabel),
+    },
+    yAxis: {
+      type: 'value',
+      axisLabel: {
+        formatter: (value: number) => formatAxisAmount(value),
+      },
+      splitLine: {
+        lineStyle: {
+          color: '#f1f5f9',
+          type: 'dashed',
+        },
+      },
+    },
+    series: [
+      {
+        name: '营收',
+        type: 'line',
+        smooth: true,
+        symbol: 'none',
+        lineStyle: {
+          color: '#1677ff',
+          width: 2.5,
+        },
+        data: props.points.map((item) => item.revenueAmount),
+      },
+      {
+        name: '成本',
+        type: 'line',
+        smooth: true,
+        symbol: 'none',
+        lineStyle: {
+          color: '#ef4444',
+          width: 2,
+          type: 'dashed',
+        },
+        data: props.points.map((item) => item.costAmount),
+      },
+      {
+        name: '净利润',
+        type: 'line',
+        smooth: true,
+        symbol: 'none',
+        lineStyle: {
+          color: '#22c55e',
+          width: 2.5,
+        },
+        data: props.points.map((item) => item.netProfitAmount),
+      },
+    ],
+  });
+}
+
+watch(
+  () => props.points,
+  async () => {
+    await nextTick();
+    renderChart();
+  },
+  { deep: true },
+);
+
+onMounted(() => {
+  renderChart();
+});
+</script>
+
+<template>
+  <div class="fo-section-card">
+    <div class="fo-section-head">
+      <div class="fo-section-title">利润走势</div>
+
+      <div class="fo-pills">
+        <button
+          class="fo-pill"
+          :class="{ 'is-active': props.range === '7' }"
+          type="button"
+          @click="emit('update:range', '7')"
+        >
+          近7天
+        </button>
+        <button
+          class="fo-pill"
+          :class="{ 'is-active': props.range === '30' }"
+          type="button"
+          @click="emit('update:range', '30')"
+        >
+          近30天
+        </button>
+      </div>
+    </div>
+
+    <EchartsUI ref="chartRef" class="fo-profit-chart" />
+
+    <div class="fo-profit-legend">
+      <div class="fo-profit-legend-item">
+        <span class="fo-profit-legend-line is-revenue"></span>
+        营收
+      </div>
+      <div class="fo-profit-legend-item">
+        <span class="fo-profit-legend-line is-cost"></span>
+        成本
+      </div>
+      <div class="fo-profit-legend-item">
+        <span class="fo-profit-legend-line is-net"></span>
+        净利润
+      </div>
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/finance/overview/components/OverviewToolbar.vue

@@ -0,0 +1,66 @@
+<script setup lang="ts">
+/**
+ * 文件职责：财务概览顶部维度工具条。
+ */
+import type { OptionItem } from '../types';
+
+import type { FinanceOverviewDimension } from '#/api/finance/overview';
+
+import { Segmented, Select } from 'ant-design-vue';
+
+interface Props {
+  dimension: FinanceOverviewDimension;
+  dimensionOptions: Array<{ label: string; value: FinanceOverviewDimension }>;
+  isStoreLoading: boolean;
+  showStoreSelect: boolean;
+  storeId: string;
+  storeOptions: OptionItem[];
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+  (event: 'update:dimension', value: FinanceOverviewDimension): void;
+  (event: 'update:storeId', value: string): void;
+}>();
+
+function handleStoreChange(value: unknown) {
+  if (typeof value === 'number' || typeof value === 'string') {
+    emit('update:storeId', String(value));
+    return;
+  }
+  emit('update:storeId', '');
+}
+</script>
+
+<template>
+  <div class="fo-toolbar">
+    <div class="fo-toolbar-title">财务概览驾驶舱</div>
+
+    <div class="fo-toolbar-right">
+      <Segmented
+        class="fo-dimension-segmented"
+        :value="props.dimension"
+        :options="props.dimensionOptions"
+        @update:value="
+          (value) =>
+            emit(
+              'update:dimension',
+              (value as FinanceOverviewDimension) || 'tenant',
+            )
+        "
+      />
+
+      <Select
+        v-if="props.showStoreSelect"
+        class="fo-store-select"
+        :value="props.storeId"
+        :options="props.storeOptions"
+        :loading="props.isStoreLoading"
+        :disabled="props.storeOptions.length === 0"
+        placeholder="请选择门店"
+        @update:value="(value) => handleStoreChange(value)"
+      />
+    </div>
+  </div>
+</template>

apps/web-antd/src/views/finance/overview/components/OverviewTopProductsCard.vue

@@ -0,0 +1,109 @@
+<script setup lang="ts">
+/**
+ * 文件职责：财务概览 TOP10 商品排行表。
+ */
+import type { FinanceOverviewTopProductItemDto } from '#/api/finance/overview';
+
+import { computed } from 'vue';
+
+import { Table } from 'ant-design-vue';
+
+import {
+  calcTopProductBarWidth,
+  formatCurrency,
+  formatPercent,
+} from '../composables/overview-page/helpers';
+
+interface Props {
+  items: FinanceOverviewTopProductItemDto[];
+  maxPercentage: number;
+  periodDays: number;
+}
+
+const props = defineProps<Props>();
+
+const columns = [
+  {
+    title: '排名',
+    key: 'rank',
+    width: 86,
+  },
+  {
+    title: '商品名称',
+    dataIndex: 'productName',
+    key: 'productName',
+  },
+  {
+    title: '销量',
+    dataIndex: 'salesQuantity',
+    key: 'salesQuantity',
+    width: 100,
+  },
+  {
+    title: '营收',
+    key: 'revenueAmount',
+    width: 120,
+  },
+  {
+    title: '占比',
+    key: 'percentage',
+    width: 190,
+  },
+];
+
+const dataSource = computed(() => props.items);
+
+function resolveRankClass(rank: number) {
+  if (rank === 1) return 'is-top1';
+  if (rank === 2) return 'is-top2';
+  if (rank === 3) return 'is-top3';
+  return 'is-normal';
+}
+</script>
+
+<template>
+  <div class="fo-section-card fo-top-card">
+    <div class="fo-section-title">
+      TOP10 商品营收排行（近{{ props.periodDays }}天）
+    </div>
+
+    <Table
+      class="fo-top-table"
+      :columns="columns"
+      :data-source="dataSource"
+      :pagination="false"
+      :row-key="(record) => `${record.rank}-${record.productName}`"
+      size="middle"
+    >
+      <template #bodyCell="{ column, record }">
+        <template v-if="column.key === 'rank'">
+          <span class="fo-rank-num" :class="resolveRankClass(record.rank)">
+            {{ record.rank }}
+          </span>
+        </template>
+
+        <template v-else-if="column.key === 'revenueAmount'">
+          <span class="fo-revenue-text">{{
+            formatCurrency(record.revenueAmount)
+          }}</span>
+        </template>
+
+        <template v-else-if="column.key === 'percentage'">
+          <div class="fo-percent-wrap">
+            <div class="fo-percent-track">
+              <div
+                class="fo-percent-fill"
+                :style="{
+                  width: `${calcTopProductBarWidth(record.percentage, props.maxPercentage)}%`,
+                }"
+              ></div>
+            </div>
+            <span class="fo-percent-text">{{
+              formatPercent(record.percentage)
+            }}</span>
+          </div>
+        </template>
+      </template>
+    </Table>
+  </div>
+</template>

apps/web-antd/src/views/finance/overview/composables/overview-page/constants.ts

@@ -0,0 +1,153 @@
+import type { FinanceOverviewTrendState } from '../../types';
+
+import type {
+  FinanceOverviewDashboardDto,
+  FinanceOverviewDimension,
+  FinanceOverviewKpiCardDto,
+  FinanceOverviewTrendRange,
+} from '#/api/finance/overview';
+
+/**
+ * 文件职责：财务概览页面常量定义。
+ */
+
+/** 财务概览查看权限。 */
+export const FINANCE_OVERVIEW_VIEW_PERMISSION = 'tenant:finance:overview:view';
+
+/** 维度切换选项。 */
+export const OVERVIEW_DIMENSION_OPTIONS: Array<{
+  label: string;
+  value: FinanceOverviewDimension;
+}> = [
+  { label: '租户汇总', value: 'tenant' },
+  { label: '门店视角', value: 'store' },
+];
+
+/** KPI 键。 */
+export type FinanceOverviewKpiKey =
+  | 'actualReceived'
+  | 'netIncome'
+  | 'refundAmount'
+  | 'todayRevenue'
+  | 'withdrawableBalance';
+
+/** KPI 卡片配置信息。 */
+export const OVERVIEW_KPI_CONFIG: Array<{
+  icon: string;
+  key: FinanceOverviewKpiKey;
+  label: string;
+  tone: 'blue' | 'green' | 'orange' | 'purple' | 'red';
+}> = [
+  {
+    key: 'todayRevenue',
+    label: '今日营业额',
+    icon: 'lucide:coins',
+    tone: 'blue',
+  },
+  {
+    key: 'actualReceived',
+    label: '实收',
+    icon: 'lucide:badge-check',
+    tone: 'green',
+  },
+  {
+    key: 'refundAmount',
+    label: '退款',
+    icon: 'lucide:undo-2',
+    tone: 'red',
+  },
+  {
+    key: 'netIncome',
+    label: '净收入',
+    icon: 'lucide:wallet',
+    tone: 'purple',
+  },
+  {
+    key: 'withdrawableBalance',
+    label: '可提现余额',
+    icon: 'lucide:landmark',
+    tone: 'orange',
+  },
+];
+
+/** 收入构成颜色映射。 */
+export const INCOME_COMPOSITION_COLOR_MAP: Record<string, string> = {
+  delivery: '#1677ff',
+  pickup: '#22c55e',
+  dine_in: '#f59e0b',
+};
+
+/** 成本构成颜色映射。 */
+export const COST_COMPOSITION_COLOR_MAP: Record<string, string> = {
+  food: '#ef4444',
+  labor: '#f59e0b',
+  fixed: '#8b5cf6',
+  packaging: '#06b6d4',
+  platform: '#94a3b8',
+};
+
+/** 默认筛选状态。 */
+export const DEFAULT_OVERVIEW_FILTER = {
+  dimension: 'tenant',
+  storeId: '',
+} as const;
+
+/** 默认趋势状态。 */
+export const DEFAULT_OVERVIEW_TREND_STATE: FinanceOverviewTrendState = {
+  incomeRange: '7',
+  profitRange: '7',
+};
+
+/** 默认 KPI 卡片。 */
+export const EMPTY_KPI_CARD: FinanceOverviewKpiCardDto = {
+  amount: 0,
+  compareAmount: 0,
+  changeRate: 0,
+  compareLabel: '较昨日',
+  trend: 'flat',
+};
+
+/** 默认财务概览数据。 */
+export function createDefaultFinanceOverviewDashboard(): FinanceOverviewDashboardDto {
+  return {
+    dimension: 'tenant',
+    storeId: undefined,
+    todayRevenue: { ...EMPTY_KPI_CARD },
+    actualReceived: { ...EMPTY_KPI_CARD },
+    refundAmount: { ...EMPTY_KPI_CARD },
+    netIncome: { ...EMPTY_KPI_CARD },
+    withdrawableBalance: {
+      ...EMPTY_KPI_CARD,
+      compareLabel: '较上周',
+    },
+    incomeTrend: {
+      last7Days: [],
+      last30Days: [],
+    },
+    profitTrend: {
+      last7Days: [],
+      last30Days: [],
+    },
+    incomeComposition: {
+      totalAmount: 0,
+      items: [],
+    },
+    costComposition: {
+      totalAmount: 0,
+      items: [],
+    },
+    topProducts: {
+      periodDays: 30,
+      items: [],
+    },
+  };
+}
+
+/** 趋势范围枚举。 */
+export const TREND_RANGE_OPTIONS: Array<{
+  label: string;
+  value: FinanceOverviewTrendRange;
+}> = [
+  { label: '近7天', value: '7' },
+  { label: '近30天', value: '30' },
+];

apps/web-antd/src/views/finance/overview/composables/overview-page/data-actions.ts

@@ -0,0 +1,109 @@
+/**
+ * 文件职责：财务概览页面数据动作。
+ */
+import type { Ref } from 'vue';
+
+import type {
+  FinanceOverviewDashboardState,
+  FinanceOverviewFilterState,
+} from '../../types';
+
+import type { StoreListItemDto } from '#/api/store';
+
+import { message } from 'ant-design-vue';
+
+import { getFinanceOverviewDashboardApi } from '#/api/finance/overview';
+import { getStoreListApi } from '#/api/store';
+
+import { createDefaultFinanceOverviewDashboard } from './constants';
+import { buildDashboardQuery } from './helpers';
+
+interface CreateDataActionsOptions {
+  dashboard: FinanceOverviewDashboardState;
+  filters: FinanceOverviewFilterState;
+  isDashboardLoading: Ref<boolean>;
+  isStoreLoading: Ref<boolean>;
+  stores: Ref<StoreListItemDto[]>;
+}
+
+/** 创建页面数据动作。 */
+export function createDataActions(options: CreateDataActionsOptions) {
+  function syncDashboard(source: FinanceOverviewDashboardState) {
+    options.dashboard.dimension = source.dimension;
+    options.dashboard.storeId = source.storeId;
+    options.dashboard.todayRevenue = { ...source.todayRevenue };
+    options.dashboard.actualReceived = { ...source.actualReceived };
+    options.dashboard.refundAmount = { ...source.refundAmount };
+    options.dashboard.netIncome = { ...source.netIncome };
+    options.dashboard.withdrawableBalance = { ...source.withdrawableBalance };
+    options.dashboard.incomeTrend = {
+      last7Days: [...source.incomeTrend.last7Days],
+      last30Days: [...source.incomeTrend.last30Days],
+    };
+    options.dashboard.profitTrend = {
+      last7Days: [...source.profitTrend.last7Days],
+      last30Days: [...source.profitTrend.last30Days],
+    };
+    options.dashboard.incomeComposition = {
+      totalAmount: source.incomeComposition.totalAmount,
+      items: [...source.incomeComposition.items],
+    };
+    options.dashboard.costComposition = {
+      totalAmount: source.costComposition.totalAmount,
+      items: [...source.costComposition.items],
+    };
+    options.dashboard.topProducts = {
+      periodDays: source.topProducts.periodDays,
+      items: [...source.topProducts.items],
+    };
+  }
+
+  function clearDashboard() {
+    syncDashboard(createDefaultFinanceOverviewDashboard());
+  }
+
+  async function loadStores() {
+    options.isStoreLoading.value = true;
+    try {
+      const result = await getStoreListApi({
+        page: 1,
+        pageSize: 200,
+      });
+      options.stores.value = result.items ?? [];
+    } catch (error) {
+      console.error(error);
+      options.stores.value = [];
+      message.error('加载门店列表失败，请稍后重试');
+    } finally {
+      options.isStoreLoading.value = false;
+    }
+  }
+
+  async function loadDashboard() {
+    if (options.filters.dimension === 'store' && !options.filters.storeId) {
+      clearDashboard();
+      return;
+    }
+
+    options.isDashboardLoading.value = true;
+    try {
+      const result = await getFinanceOverviewDashboardApi(
+        buildDashboardQuery(options.filters),
+      );
+      syncDashboard(result);
+    } catch (error) {
+      console.error(error);
+      clearDashboard();
+      message.error('加载财务概览失败，请稍后重试');
+    } finally {
+      options.isDashboardLoading.value = false;
+    }
+  }
+
+  return {
+    clearDashboard,
+    loadDashboard,
+    loadStores,
+    syncDashboard,
+  };
+}

apps/web-antd/src/views/finance/overview/composables/overview-page/helpers.ts

@@ -0,0 +1,138 @@
+/**
+ * 文件职责：财务概览页面工具方法。
+ */
+import type {
+  FinanceOverviewCompositionViewItem,
+  FinanceOverviewFilterState,
+} from '../../types';
+
+import type {
+  FinanceOverviewDashboardQuery,
+  FinanceOverviewKpiCardDto,
+} from '#/api/finance/overview';
+
+import {
+  COST_COMPOSITION_COLOR_MAP,
+  INCOME_COMPOSITION_COLOR_MAP,
+} from './constants';
+
+const currencyFormatter = new Intl.NumberFormat('zh-CN', {
+  minimumFractionDigits: 0,
+  maximumFractionDigits: 2,
+});
+
+const percentFormatter = new Intl.NumberFormat('zh-CN', {
+  minimumFractionDigits: 0,
+  maximumFractionDigits: 2,
+});
+
+/** 货币格式化。 */
+export function formatCurrency(value: number) {
+  return `¥${currencyFormatter.format(value)}`;
+}
+
+/** 百分比格式化。 */
+export function formatPercent(value: number) {
+  return `${percentFormatter.format(value)}%`;
+}
+
+/** 变化率格式化（带正负号）。 */
+export function formatChangeRate(value: number) {
+  const sign = value > 0 ? '+' : '';
+  return `${sign}${percentFormatter.format(value)}%`;
+}
+
+/** 图表纵轴金额格式化。 */
+export function formatAxisAmount(value: number) {
+  if (Math.abs(value) >= 10_000) {
+    return `${percentFormatter.format(value / 10_000)}万`;
+  }
+  return currencyFormatter.format(value);
+}
+
+/** 生成查询参数。 */
+export function buildDashboardQuery(
+  filters: FinanceOverviewFilterState,
+): FinanceOverviewDashboardQuery {
+  if (filters.dimension === 'store') {
+    return {
+      dimension: filters.dimension,
+      storeId: filters.storeId,
+    };
+  }
+
+  return {
+    dimension: filters.dimension,
+  };
+}
+
+/** 计算 TOP 占比条宽度。 */
+export function calcTopProductBarWidth(
+  percentage: number,
+  maxPercentage: number,
+) {
+  if (maxPercentage <= 0) return 0;
+  return Math.round((percentage / maxPercentage) * 100);
+}
+
+/** 收入构成转换为视图结构。 */
+export function toIncomeCompositionViewItems(
+  items: Array<{
+    amount: number;
+    channel: string;
+    channelText: string;
+    percentage: number;
+  }>,
+): FinanceOverviewCompositionViewItem[] {
+  return items.map((item) => ({
+    key: item.channel,
+    name: item.channelText,
+    amount: item.amount,
+    percentage: item.percentage,
+    color: INCOME_COMPOSITION_COLOR_MAP[item.channel] ?? '#1677ff',
+  }));
+}
+
+/** 成本构成转换为视图结构。 */
+export function toCostCompositionViewItems(
+  items: Array<{
+    amount: number;
+    category: string;
+    categoryText: string;
+    percentage: number;
+  }>,
+): FinanceOverviewCompositionViewItem[] {
+  return items.map((item) => ({
+    key: item.category,
+    name: item.categoryText,
+    amount: item.amount,
+    percentage: item.percentage,
+    color: COST_COMPOSITION_COLOR_MAP[item.category] ?? '#94a3b8',
+  }));
+}
+
+/** 获取 KPI 趋势样式标识。 */
+export function resolveKpiTrendClass(card: FinanceOverviewKpiCardDto) {
+  if (card.trend === 'up') {
+    return 'is-up';
+  }
+
+  if (card.trend === 'down') {
+    return 'is-down';
+  }
+
+  return 'is-flat';
+}
+
+/** 获取 KPI 趋势图标。 */
+export function resolveKpiTrendIcon(card: FinanceOverviewKpiCardDto) {
+  if (card.trend === 'up') {
+    return 'lucide:trending-up';
+  }
+
+  if (card.trend === 'down') {
+    return 'lucide:trending-down';
+  }
+
+  return 'lucide:minus';
+}

apps/web-antd/src/views/finance/overview/composables/useFinanceOverviewPage.ts

@@ -0,0 +1,249 @@
+/**
+ * 文件职责：财务概览页面状态编排。
+ */
+import type {
+  FinanceOverviewCompositionViewItem,
+  FinanceOverviewDashboardState,
+  FinanceOverviewFilterState,
+  FinanceOverviewTrendState,
+  OptionItem,
+} from '../types';
+
+import type {
+  FinanceOverviewDimension,
+  FinanceOverviewTrendRange,
+} from '#/api/finance/overview';
+import type { StoreListItemDto } from '#/api/store';
+
+import { computed, onActivated, onMounted, reactive, ref, watch } from 'vue';
+
+import { useAccessStore } from '@vben/stores';
+
+import {
+  createDefaultFinanceOverviewDashboard,
+  DEFAULT_OVERVIEW_FILTER,
+  DEFAULT_OVERVIEW_TREND_STATE,
+  FINANCE_OVERVIEW_VIEW_PERMISSION,
+  OVERVIEW_DIMENSION_OPTIONS,
+} from './overview-page/constants';
+import { createDataActions } from './overview-page/data-actions';
+import {
+  toCostCompositionViewItems,
+  toIncomeCompositionViewItems,
+} from './overview-page/helpers';
+
+/** 创建财务概览页面组合状态。 */
+export function useFinanceOverviewPage() {
+  const accessStore = useAccessStore();
+
+  const stores = ref<StoreListItemDto[]>([]);
+  const filters = reactive<FinanceOverviewFilterState>({
+    ...DEFAULT_OVERVIEW_FILTER,
+  });
+  const trendState = reactive<FinanceOverviewTrendState>({
+    ...DEFAULT_OVERVIEW_TREND_STATE,
+  });
+  const dashboard = reactive<FinanceOverviewDashboardState>(
+    createDefaultFinanceOverviewDashboard(),
+  );
+
+  const isStoreLoading = ref(false);
+  const isDashboardLoading = ref(false);
+
+  const accessCodeSet = computed(
+    () => new Set((accessStore.accessCodes ?? []).map(String)),
+  );
+
+  const canView = computed(() =>
+    accessCodeSet.value.has(FINANCE_OVERVIEW_VIEW_PERMISSION),
+  );
+
+  const storeOptions = computed<OptionItem[]>(() =>
+    stores.value.map((item) => ({
+      label: item.name,
+      value: item.id,
+    })),
+  );
+
+  const showStoreSelect = computed(() => filters.dimension === 'store');
+  const hasStore = computed(() => stores.value.length > 0);
+  const canQueryCurrentScope = computed(
+    () => filters.dimension === 'tenant' || Boolean(filters.storeId),
+  );
+
+  const incomeTrendPoints = computed(() =>
+    trendState.incomeRange === '7'
+      ? dashboard.incomeTrend.last7Days
+      : dashboard.incomeTrend.last30Days,
+  );
+
+  const profitTrendPoints = computed(() =>
+    trendState.profitRange === '7'
+      ? dashboard.profitTrend.last7Days
+      : dashboard.profitTrend.last30Days,
+  );
+
+  const incomeCompositionItems = computed<FinanceOverviewCompositionViewItem[]>(
+    () => toIncomeCompositionViewItems(dashboard.incomeComposition.items),
+  );
+
+  const costCompositionItems = computed<FinanceOverviewCompositionViewItem[]>(
+    () => toCostCompositionViewItems(dashboard.costComposition.items),
+  );
+
+  const topProductMaxPercentage = computed(() => {
+    if (dashboard.topProducts.items.length === 0) {
+      return 0;
+    }
+    return Math.max(
+      ...dashboard.topProducts.items.map((item) => item.percentage),
+    );
+  });
+
+  const dataActions = createDataActions({
+    stores,
+    filters,
+    dashboard,
+    isStoreLoading,
+    isDashboardLoading,
+  });
+
+  function ensureStoreSelection() {
+    if (filters.dimension !== 'store') {
+      return false;
+    }
+
+    if (filters.storeId) {
+      return false;
+    }
+
+    const firstStore = stores.value[0];
+    if (!firstStore) {
+      return false;
+    }
+
+    filters.storeId = firstStore.id;
+    return true;
+  }
+
+  async function loadByCurrentScope() {
+    if (!canView.value) {
+      return;
+    }
+
+    if (filters.dimension === 'store' && !filters.storeId) {
+      dataActions.clearDashboard();
+      return;
+    }
+
+    await dataActions.loadDashboard();
+  }
+
+  async function initPageData() {
+    if (!canView.value) {
+      stores.value = [];
+      filters.storeId = '';
+      dataActions.clearDashboard();
+      return;
+    }
+
+    await dataActions.loadStores();
+
+    if (ensureStoreSelection()) {
+      return;
+    }
+
+    await loadByCurrentScope();
+  }
+
+  function setDimension(value: FinanceOverviewDimension) {
+    filters.dimension = value;
+  }
+
+  function setStoreId(value: string) {
+    filters.storeId = value;
+  }
+
+  function setIncomeRange(value: FinanceOverviewTrendRange) {
+    trendState.incomeRange = value;
+  }
+
+  function setProfitRange(value: FinanceOverviewTrendRange) {
+    trendState.profitRange = value;
+  }
+
+  watch(
+    () => [filters.dimension, filters.storeId],
+    async () => {
+      if (!canView.value) {
+        return;
+      }
+
+      if (filters.dimension === 'store' && ensureStoreSelection()) {
+        return;
+      }
+
+      await loadByCurrentScope();
+    },
+  );
+
+  watch(
+    () => canView.value,
+    async (value, oldValue) => {
+      if (value === oldValue) {
+        return;
+      }
+
+      if (!value) {
+        stores.value = [];
+        filters.storeId = '';
+        dataActions.clearDashboard();
+        return;
+      }
+
+      await initPageData();
+    },
+  );
+
+  onMounted(async () => {
+    await initPageData();
+  });
+
+  onActivated(() => {
+    if (!canView.value) {
+      return;
+    }
+
+    if (stores.value.length === 0) {
+      void initPageData();
+      return;
+    }
+
+    if (!showStoreSelect.value || filters.storeId) {
+      void loadByCurrentScope();
+    }
+  });
+
+  return {
+    canQueryCurrentScope,
+    canView,
+    costCompositionItems,
+    dashboard,
+    hasStore,
+    incomeCompositionItems,
+    incomeTrendPoints,
+    isDashboardLoading,
+    isStoreLoading,
+    OVERVIEW_DIMENSION_OPTIONS,
+    profitTrendPoints,
+    showStoreSelect,
+    storeOptions,
+    topProductMaxPercentage,
+    trendState,
+    filters,
+    setDimension,
+    setStoreId,
+    setIncomeRange,
+    setProfitRange,
+  };
+}