Web 报表模块 — CUJ 关键用户旅程

Reports & Analytics | 更新时间: 2026-02-08

TOUCHES (Pages 14): reports/page.tsx, reports/layout.tsx, reports/ReportsLayoutClient.tsx, reports/business/page.tsx, reports/finance/page.tsx, reports/employee/page.tsx, reports/operational/page.tsx, reports/loyalty/page.tsx, reports/sales/page.tsx, reports/profit/page.tsx, reports/entitlements/page.tsx, reports/working-hours/page.tsx, reports/platform/page.tsx, reports/schedules/page.tsx

TOUCHES (Components 23): Reports/KPICard.tsx, Reports/KPICardGrid, Reports/ExportMenu.tsx, Reports/ExportButton, Reports/ExportProgress, Reports/ReportChart.tsx, Reports/ReportTable.tsx, Reports/DateRangePicker.tsx, Reports/ComparisonBadge.tsx, Reports/StoreSelector.tsx, Reports/TenantSelector.tsx, Reports/ScheduleForm.tsx, Reports/RetentionChart.tsx, Reports/ChurnWarningTable.tsx, Reports/MembershipTierChart.tsx, Reports/PointsStatsCard.tsx, Reports/GiftCardStatsCard.tsx, Reports/EmployeeRankingChart.tsx, Reports/UtilizationChart.tsx, Reports/AppointmentSourceChart.tsx, Reports/TimeSlotHeatmap.tsx, Reports/PaymentMethodChart.tsx, Reports/PlatformOverview.tsx

TOUCHES (Hooks 3): hooks/useReportData.ts, hooks/useReportExport.ts, hooks/useReportSchedule.ts

TOUCHES (Backend API 13): api/reports/index.js, api/reports/business.js, api/reports/finance.js, api/reports/employee.js, api/reports/operational.js, api/reports/loyalty.js, api/reports/sales.js, api/reports/profit.js, api/reports/entitlements.js, api/reports/working-hours.js, api/reports/platform.js, api/reports/schedules.js, api/reports/export.js

TOUCHES (Backend Services 6 + Queries 23): services/reports/report-engine.js, services/reports/export-service.js, services/reports/export-worker.js, services/reports/scheduler.js, services/reports/report-cache.js, services/reports/audit-logger.js, services/reports/queries/*.js (23 query modules)

报表系统架构

flowchart TB
    subgraph Frontend["前端 — React Query + Components"]
        RP["reports/page.tsx 首页"]
        PAGES["10 个报表页面"]
        HOOKS["useReportData / useReportExport / useReportSchedule"]
        COMP["23 个可复用组件 (KPICard, Chart, Table...)"]
    end

    subgraph Backend["后端 — Report Engine"]
        API["API Layer (13 route files)"]
        ENGINE["ReportEngine (report-engine.js)"]
        CACHE["ReportCache (Redis)"]
        QUERIES["Query Modules (23 modules, 90+ functions)"]
        EXPORT["ExportService + ExportWorker"]
        SCHED["Scheduler (cron-based)"]
        AUDIT["AuditLogger"]
    end

    subgraph Data["数据层"]
        DB["PostgreSQL (tenant schema)"]
        S3["S3 (export files)"]
    end

    RP --> PAGES
    PAGES --> HOOKS
    HOOKS --> API
    API --> ENGINE
    ENGINE --> CACHE
    ENGINE --> QUERIES
    QUERIES --> DB
    API --> EXPORT
    EXPORT --> S3
    API --> SCHED
    ENGINE --> AUDIT

报表类别总览

类别	API 前缀	权限	子报表数	说明
Business	`/reports/business`	`reports:view`	1 (KPI Dashboard)	营收、客流、客单价、同环比
Finance	`/reports/finance`	`reports:finance`	3 (Revenue/Tips/PaymentMethods)	收入分布、小费、支付方式
Employee	`/reports/employee`	`reports:view_employee`	4 (Performance/Utilization/Ranking/Detail)	绩效排名、利用率
Operational	`/reports/operational`	`reports:operational`	3 (Appointments/Cancellations/Heatmap)	预约来源、爽约、热力图
Loyalty	`/reports/loyalty`	`reports:view`	5 (Retention/Churn/Membership/Points/GiftCards)	留存队列、流失、会员、积分
Sales	`/reports/sales`	`reports:sales`	3 (Consumption/Detail/Summary)	消费明细、销售汇总 (US10)
Profit	`/reports/profit`	`reports:profit`	5 (SellCard/ConsumeCard/Comparison/Trend/IncomeExpense)	双算法利润、收支 (US11)
Entitlements	`/reports/entitlements`	`reports:view`	4 (Summary/Customers/ByTier/Expiring)	权益汇总、到期提醒 (US12)
Working Hours	`/reports/working-hours`	`reports:view`	4 (Summary/ByEmployee/Trend/ByDay)	工时统计 (US4-EXT)
Platform	`/reports/platform`	`reports:view_platform`	2 (Overview/Comparison)	跨租户平台级报表

ReportEngine 查询映射 (report-engine.js)

核心机制: REPORT_QUERY_MAP 将 30+ 种 reportType 映射到对应的 query function。 Engine 负责：(1) 执行查询 (2) Redis 缓存 (3) 计算同环比 comparison (YoY/MoM/WoW) (4) 返回 {data, meta: {fromCache}}。前端通过 useReportData<T>(reportType, params) 消费。

CUJ 总览与优先级矩阵
CUJ-H1: Business KPI Dashboard (P0)
CUJ-H2: Finance 财务报表 (P0)
CUJ-H3: Employee 员工绩效报表 (P1)
CUJ-H4: Operational 运营报表 (P1)
CUJ-H5: Loyalty 客户忠诚度报表 (P1)
CUJ-H6: Sales 销售报表 (P1)
CUJ-H7: Profit 利润报表 (P1)
CUJ-H8: Entitlements 客户权益报表 (P2)
CUJ-H9: Working Hours 工时报表 (P2)
CUJ-H10: Platform 平台级报表 (P2)
CUJ-H11: Report Export 报表导出 (P0)
CUJ-H12: Report Schedules 定时报表 (P2)
跨模块依赖
业务规则

CUJ 总览与优先级矩阵

CUJ	优先级	描述	触发点	业务价值	E2E 状态
H1	P0	Business KPI Dashboard	管理员查看 /reports/business	核心数据洞察 — 营收/客流/客单价	已覆盖
H2	P0	Finance 财务报表	查看 /reports/finance	财务分析 — 收入/小费/支付方式	已覆盖
H3	P1	Employee 员工绩效	查看 /reports/employee	绩效管理 — 排名/利用率/明细	已覆盖
H4	P1	Operational 运营报表	查看 /reports/operational	运营优化 — 预约来源/爽约/热力图	已覆盖
H5	P1	Loyalty 忠诚度报表	查看 /reports/loyalty	留存分析 — 留存队列/流失/会员	部分覆盖
H6	P1	Sales 销售报表	查看 /reports/sales	销售分析 — 消费明细/销售汇总 (US10)	部分覆盖
H7	P1	Profit 利润报表	查看 /reports/profit	利润洞察 — 双算法对比/收支 (US11)	部分覆盖
H8	P2	Entitlements 权益报表	查看 /reports/entitlements	权益管理 — 汇总/到期提醒 (US12)	未覆盖
H9	P2	Working Hours 工时报表	查看 /reports/working-hours	工时管理 — 出勤/趋势 (US4-EXT)	未覆盖
H10	P2	Platform 平台级报表	platform_superadmin 查看	平台运营 — 跨租户对比	未覆盖
H11	P0	Report Export 导出	任意报表页点击导出	数据可移植 — Excel/PDF	部分覆盖
H12	P2	Report Schedules 定时报表	管理员配置定时发送	自动化 — 定期邮件报表	未覆盖

CUJ-H1: Business KPI Dashboard

P0 核心洞察 — 管理员快速了解营收、客流、客单价等关键指标

TOUCHES: reports/business/page.tsx → Reports/KPICard.tsx, Reports/ReportChart.tsx, Reports/DateRangePicker.tsx, Reports/StoreSelector.tsx, Reports/ExportMenu.tsx, Reports/ComparisonBadge.tsx → hooks/useReportData.ts (useKPIData) → api/reports/business.js (GET /kpi) → queries/revenue.js, queries/traffic.js

用户流程

flowchart TD
    A["侧边栏 Reports"] --> B["报表首页 /reports"]
    B --> C["7 类报表卡片"]
    C -->|"Business"| D["/reports/business"]
    D --> E["KPI Cards Grid"]
    E --> F["Revenue / Traffic / Avg Ticket"]
    E --> G["Appointments / Walk-Ins / Tips"]
    E --> H["Return Rate / Cancel Rate"]
    D --> I["Hourly Traffic Chart"]
    D --> J["Customer Breakdown Pie"]
    D --> K["Store Selector (multi)"]
    D --> L["DateRangePicker"]
    D --> M{"导出?"}
    M -->|"Excel/PDF"| N["ExportMenu"]

    style D fill:#2196F3,stroke:#1565C0,color:#fff
    style E fill:#4CAF50,stroke:#2E7D32,color:#fff

KPI 指标卡片

指标	格式	颜色	说明
Total Revenue	currency	blue	总营收（含小费）
Total Traffic	number	green	客流量（预约+Walk-in）
Average Ticket	currency	purple	客单价 = 营收/客流
Appointments	number	indigo	预约数量
Walk-Ins	number	yellow	Walk-in 数量
Total Tips	currency	green	小费总额
Return Rate	percent	blue	回头客比例
Cancel Rate	percent	red	爽约率

BDD 场景

场景 H1.1: 查看 KPI Dashboard

Given 用户已登录并拥有 reports:view 权限，且具备对应范围(scope)
When 导航到 /reports/business
Then 显示 8 张 KPICard（Revenue / Traffic / AvgTicket / Appointments / Walk-Ins / Tips / ReturnRate / CancelRate）
  And 每张卡片包含 ComparisonBadge 显示同环比变化
  And 默认日期范围为"本周"
  And 下方显示 Hourly Traffic 柱状图 + Customer Breakdown 饼图

测试: reports/business-report.spec.ts

场景 H1.2: 多门店筛选

Given 用户已登录并拥有对应功能所需权限与范围(scope)，管理多家门店
When 在 StoreSelector 中选择门店 A 和门店 B
Then KPI 数据聚合为所选门店的合计
And 图表仅显示所选门店数据

场景 H1.3: 切换日期范围

Given 正在查看本周数据
When 通过 DateRangePicker 切换为"本月"
Then 所有 KPI 卡片和图表刷新为本月数据
And ComparisonBadge 更新为 MoM 对比

测试: reports/business-report.spec.ts

CUJ-H2: Finance 财务报表

P0 财务分析 — 收入分布、小费明细、支付方式占比

TOUCHES: reports/finance/page.tsx (3 tabs: Revenue / Tips / PaymentMethods) → Reports/PaymentMethodChart.tsx, Reports/KPICard.tsx → api/reports/finance.js (GET /revenue, GET /tips, GET /payment-methods) → queries/revenue.js, queries/tips.js, queries/payment-methods.js

Tab 结构

Tab	API	KPI 指标	图表
Revenue	`GET /finance/revenue`	总收入、按期间分布、按门店分布	Period 柱状图
Tips	`GET /finance/tips`	总小费、按员工、按天、百分比分布	Employee 排名图
Payment Methods	`GET /finance/payment-methods`	按支付方式分布	PaymentMethodChart 饼图

BDD 场景

场景 H2.1: 查看收入分布

Given 用户已登录并拥有 reports:finance 权限，且具备对应范围(scope)
When 导航到 /reports/finance，默认 Revenue tab
Then 显示总收入 KPI 卡片
And 按日期期间的收入柱状图
And 按门店的收入对比表

测试: reports/finance-report.spec.ts

场景 H2.2: 查看小费分布

Given 在 Finance 报表页面
When 切换到 Tips tab
Then 显示小费汇总（总额、平均、最高）
  And 按员工的小费排名
  And 按天的小费趋势
  And 小费百分比分布（10%/15%/20%/25%/Other）

场景 H2.3: 支付方式分析

Given 在 Finance 报表页面
When 切换到 Payment Methods tab
Then 显示 PaymentMethodChart 饼图（Cash / Credit Card / Gift Card / Points / Other）
And 显示各支付方式金额和占比表格

测试: reports/finance-report.spec.ts

CUJ-H3: Employee 员工绩效报表

P1 绩效管理 — 员工排名、利用率分析、个人明细

TOUCHES: reports/employee/page.tsx (3 tabs: Performance / Utilization / Detail) → Reports/EmployeeRankingChart.tsx, Reports/UtilizationChart.tsx → api/reports/employee.js (4 endpoints) → queries/employee.js, queries/utilization.js, queries/ranking.js

BDD 场景

场景 H3.1: 员工绩效排名

Given 用户已登录并拥有 reports:view_employee 权限，且具备对应范围(scope)
When 在 Performance tab 选择排名指标 "revenue"
Then EmployeeRankingChart 显示按营收排序的员工柱状图
And 每位员工显示: 营收、服务数量、小费、平均评分
And 支持切换排名维度（revenue / services / tips / average）

测试: reports/employee-report.spec.ts

场景 H3.2: 员工利用率分析

Given 在 Utilization tab
When 查看利用率数据
Then UtilizationChart 显示各员工利用率百分比
And 时段利用率热力图（哪些小时最忙）
And UtilizationSummaryCard 显示平均利用率

场景 H3.3: 个别员工详情

Given 在 Detail tab
When 从下拉菜单选择员工 Alice
Then 显示 Alice 的个人绩效报表（营收趋势、服务分类、客户满意度）
And 默认时间范围 7 天

CUJ-H4: Operational 运营报表

P1 运营优化 — 预约来源分析、爽约分析、时段热力图

TOUCHES: reports/operational/page.tsx (3 tabs: Appointments / Cancellations / Heatmap) → Reports/AppointmentSourceChart.tsx, Reports/TimeSlotHeatmap.tsx → api/reports/operational.js (3 endpoints) → queries/appointments.js, queries/cancellations.js

BDD 场景

场景 H4.1: 预约来源分布

Given 用户已登录并拥有对应功能所需权限与范围(scope)，在 /reports/operational
When 查看 Appointments tab
Then AppointmentSourceChart 饼图显示来源分布（Walk-in / Online / Phone / Kiosk）
And KPI 卡片: 总预约数、完成率、爽约率
And 预约趋势折线图

测试: reports/operational-report.spec.ts

场景 H4.2: 爽约分析

Given 在 Cancellations tab
When 查看爽约数据
Then 显示取消原因分布（客户取消/员工取消/爽约/其他）
And 重复爽约者名单（RepeatOffenders 表格）
And 取消趋势图

场景 H4.3: 时段热力图

Given 在 Heatmap tab
When 查看热力图
Then TimeSlotHeatmap 显示一周 7 天 × 营业时间的热力格
And BusiestTimesCard 列出最忙的前 5 个时段
And 颜色深浅表示预约密度

CUJ-H5: Loyalty 客户忠诚度报表

P1 留存分析 — 留存队列、流失预警、会员分布、积分/礼品卡负债

TOUCHES: reports/loyalty/page.tsx (5 tabs: Retention / Churn / Membership / Points / GiftCards) → Reports/RetentionChart.tsx, Reports/ChurnWarningTable.tsx, Reports/MembershipTierChart.tsx, Reports/PointsStatsCard.tsx, Reports/GiftCardStatsCard.tsx → api/reports/loyalty.js (5 endpoints) → queries/retention.js, queries/churn.js, queries/membership.js, queries/points.js, queries/giftcards.js

BDD 场景

场景 H5.1: 客户留存队列

Given 在 Retention tab，默认时间范围 3 个月
When 查看留存数据
Then RetentionChart 显示队列分析表（cohort matrix）
  And 留存曲线折线图
  And 访问频率分布（1次/2-3次/4+次）
  And 留存趋势

场景 H5.2: 流失预警

Given 在 Churn tab
When 查看流失风险
Then ChurnWarningTable 显示高风险客户列表（含风险评分、最后访问日、消费金额）
And 流失趋势图
And Win-back Opportunities 列表（可挽回客户）

场景 H5.3: 会员等级分布

Given 在 Membership tab
When 查看会员分布
Then MembershipTierChart 饼图显示各等级人数
  And MembershipSummaryCard 汇总统计
  And TopMembersTable 显示 Top 会员排行榜
  And MembershipTrendChart 趋势图

场景 H5.4: 积分负债与礼品卡分析

Given 在 Points 或 GiftCards tab
When 查看积分/礼品卡数据
Then 显示汇总卡片（总积分/总礼品卡金额）
  And 负债卡片（未消费的积分/礼品卡价值 = 潜在负债）
  And 趋势图 + 余额分布图
  And 即将过期列表（ExpiringCards / TopEarners Table）

CUJ-H6: Sales 销售报表

P1 销售分析 — 消费明细、销售详情、分类汇总 (Feature US10)

TOUCHES: reports/sales/page.tsx (3 tabs: Consumption / Detail / Summary) → api/reports/sales.js (3 endpoints) → queries/consumption.js, queries/sales-detail.js, queries/sales-summary.js

BDD 场景

场景 H6.1: 客户消费明细

Given 用户已登录并拥有 reports:sales 权限，且具备对应范围(scope)
When 在 Consumption tab 查看
Then 显示客户消费明细列表（客户名、消费金额、次数、最后消费日期）
And KPI 卡片: 总销售额、成交笔数、平均客单价

场景 H6.2: 销售汇总

Given 在 Summary tab
When 查看销售汇总
Then 按服务项目的销售排名（TopSellingServices）
And 按分类的销售占比
And 按员工的销售详情

CUJ-H7: Profit 利润报表

P1 利润洞察 — 双算法利润计算、收支分析 (Feature US11)

TOUCHES: reports/profit/page.tsx (2 sections: Profit / IncomeExpense) → api/reports/profit.js (5 endpoints) → queries/profit.js, queries/income-expense.js

双算法机制:

Sell Card Method (卖卡法): 营收在卖出卡的当期确认
Consume Card Method (消卡法): 营收在卡被消费时确认

两种算法产生不同的利润数字，/profit/comparison 端点并排对比。

BDD 场景

场景 H7.1: 双算法利润对比

Given 用户已登录并拥有 reports:profit 权限，且具备对应范围(scope)
When 导航到 /reports/profit
Then 显示两列对比: Sell Card Profit vs Consume Card Profit
And KPI 卡片: 总利润、总收入、总支出
And Profit Trend 折线图（两条线叠加）

场景 H7.2: 收支汇总

Given 在 Income/Expense section
When 查看收支数据
Then 按分类的收支列表（IncomeExpenseByCategory）
And 收支趋势图
And 收支汇总卡片（净利润 = 收入 - 支出）

CUJ-H8: Entitlements 客户权益报表

P2 权益管理 — 客户礼品卡/积分/会员权益汇总与到期提醒 (Feature US12)

TOUCHES: reports/entitlements/page.tsx → api/reports/entitlements.js (5 endpoints) → queries/entitlements.js

BDD 场景

场景 H8.1: 权益汇总

Given 用户已登录并拥有 reports:view 权限，且具备对应范围(scope)
When 导航到 /reports/entitlements
Then 汇总卡片: 礼品卡总额、积分总量、会员总数
And 客户权益列表（可搜索、可排序）
And 支持按权益类型筛选

场景 H8.2: 到期权益预警

Given 有客户权益即将到期
When 查看到期提醒区域
Then 列出即将 30 天内到期的礼品卡和积分
And 按等级分组的权益分布图

CUJ-H9: Working Hours 工时报表

P2 工时管理 — 员工出勤统计、趋势分析 (Feature US4-EXT)

TOUCHES: reports/working-hours/page.tsx → api/reports/working-hours.js (5 endpoints) → queries/working-hours.js

BDD 场景

场景 H9.1: 工时汇总

Given 用户已登录并拥有对应功能所需权限与范围(scope)，在 /reports/working-hours
When 查看工时数据
Then KPI: 总工时、平均每人工时、排班 vs 实际
And 按员工的工时明细表
And 工时趋势折线图

场景 H9.2: 按星期分布

Given 在工时报表页面
When 查看 By Day 数据
Then 按星期几的工时分布柱状图（周一至周日）
And 识别工时最多/最少的日子

CUJ-H10: Platform 平台级报表

P2 平台运营 — 跨租户对比与增长趋势（仅 platform_superadmin）

TOUCHES: reports/platform/page.tsx → Reports/PlatformOverview.tsx, Reports/TenantSelector.tsx, Reports/StoreRankingTable.tsx → api/reports/platform.js (4 endpoints) → queries/platform.js

BDD 场景

场景 H10.1: 平台概览

Given 用户已登录并拥有 reports:view_platform 权限，且具备平台范围(scope)
When 导航到 /reports/platform
Then PlatformOverview 显示: 租户总数、总营收、总门店数、总用户数
  And 租户对比表（按营收/客流排序）
  And 跨租户营收趋势图
  And 套餐分布图（Basic / Standard / Enterprise）

场景 H10.2: 租户增长趋势

Given 在平台报表页面
When 查看 Growth Trend
Then 显示租户增长趋势（新增/活跃/流失）
And StoreRankingTable 显示全平台 Top 门店

CUJ-H11: Report Export 报表导出

P0 数据可移植 — 导出 Excel/PDF 用于离线分析或分享

TOUCHES: Reports/ExportMenu.tsx, Reports/ExportButton.tsx, Reports/ExportProgress.tsx → hooks/useReportExport.ts → api/reports/export.js (POST /export, POST /export/async, GET /export/:taskId) → services/reports/export-service.js, services/reports/export-worker.js

导出流程

flowchart LR
    A["ExportMenu 选格式"] --> B{"文件大小?"}
    B -->|"小"| C["POST /export (同步)"]
    C --> D["直接下载文件"]
    B -->|"大"| E["POST /export/async"]
    E --> F["返回 taskId"]
    F --> G["ExportProgress 轮询"]
    G --> H["GET /export/:taskId"]
    H --> I{"status?"}
    I -->|"processing"| G
    I -->|"completed"| J["下载 fileUrl"]
    I -->|"failed"| K["显示错误"]

    style A fill:#2196F3,stroke:#1565C0,color:#fff
    style J fill:#4CAF50,stroke:#2E7D32,color:#fff

BDD 场景

场景 H11.1: 同步导出 Excel

Given 用户已登录并拥有对应功能所需权限与范围(scope)，正在查看任意报表
When 点击 ExportMenu → "Excel (.xlsx)"
Then 浏览器下载 .xlsx 文件
And 文件名格式: {reportType}_{startDate}_{endDate}.xlsx
And 文件包含当前筛选条件下的完整数据

场景 H11.2: 异步导出大报表

Given 报表数据量较大（如全年财务报表）
When 触发导出
Then ExportProgress 显示进度状态（pending → processing → completed）
And 轮询间隔 1 秒，最多 60 次
And 完成后自动下载（S3 URL）

场景 H11.3: 导出 PDF

Given 需要打印或分享报表
When 选择 "PDF (.pdf)" 导出
Then 生成包含图表和表格的 PDF 文档
And 布局适合 A4 打印

CUJ-H12: Report Schedules 定时报表

P2 自动化 — 配置定时发送报表到指定邮箱

TOUCHES: reports/schedules/page.tsx → Reports/ScheduleForm.tsx → hooks/useReportSchedule.ts → api/reports/schedules.js (7 endpoints: CRUD + run + stats + types) → services/reports/scheduler.js

定时类型

类型	cron 示例	说明
daily	`0 8 * * *`	每天早上 8 点
weekly	`0 8 * * 1`	每周一早上 8 点
monthly	`0 8 1 * *`	每月 1 号早上 8 点
custom	用户自定义 cron	自定义频率

BDD 场景

场景 H12.1: 创建定时报表

Given 用户已登录并拥有 reports:schedule 权限，且具备对应范围(scope)
When 在 /reports/schedules 点击"新建"
  And 选择报表类型 "Business KPI"
  And 选择频率 "weekly"
  And 添加收件人邮箱
  And 选择格式 "PDF"
Then 定时任务创建成功
  And 出现在定时列表中（状态: active）

场景 H12.2: 手动触发

Given 已有一个定时报表任务
When 点击"立即运行"
Then 报表立即生成并发送到收件人邮箱
And lastRunAt 更新为当前时间
And runCount +1

场景 H12.3: 暂停/恢复

Given 有一个 active 的定时任务
When 点击暂停
Then 状态变为 paused
And 不再按时执行
And 可以随时恢复为 active

跨模块依赖

依赖方向	说明
H → CUJ-B (Appointments)	Business/Operational 报表数据来源：预约表
H → CUJ-F (Payments)	Finance/Sales/Profit 报表数据来源：支付记录
H → CUJ-D (Employees)	Employee 报表数据来源：员工和排班表
H → CUJ-E (Guests)	Loyalty 报表数据来源：客户、会员、积分表
H → CUJ-M (Loyalty/GiftCards)	Entitlements/Loyalty 报表的礼品卡和积分数据
H → CUJ-L (Stores/Services)	StoreSelector 依赖门店列表；Sales 按服务分类
H → CUJ-N (Platform)	Platform 报表需要跨租户数据访问
H → CUJ-C (Day-End Closeout)	Finance 报表的现金差异数据来自日结
CUJ-J (Settings) → H	reports:* 权限配置影响报表访问

业务规则

#	规则	实现位置
1	权限分级: reports:view (基础) / reports:finance (财务) / reports:view_employee (员工) / reports:view_platform (平台) / reports:schedule (定时)	各 API 路由 requirePermission
2	数据租户隔离: 所有查询通过 tenantDb.query(req, ...) 确保只能看到自己租户的数据；platform 报表例外	queries/*.js + data-access layer
3	Redis 缓存: ReportEngine 按 reportType + params 生成缓存 key，TTL 按报表类型配置；meta.fromCache 标记是否命中缓存	report-cache.js + report-engine.js
4	同环比计算: comparison.js 自动计算 YoY/MoM/WoW 变化率，ComparisonBadge 前端展示	queries/comparison.js + ComparisonBadge.tsx
5	导出文件格式: Excel (.xlsx) 含多 sheet + 格式化；PDF 含图表渲染。异步导出上传 S3，60 秒轮询超时	export-service.js + export-worker.js
6	审计日志: 所有报表访问和导出操作记录到 audit-logger	audit-logger.js
7	Profit 双算法: Sell Card (卖卡时确认营收) vs Consume Card (消费时确认营收)，/comparison 端点并排对比	queries/profit.js + profit/page.tsx
8	Tab Prefetch: Loyalty 页面使用 usePrefetchReport 在切换 tab 前预取下一个 tab 的数据	loyalty/page.tsx + useReportData.ts
9	定时报表 cron: scheduler.js 根据 scheduleType 生成 cron 表达式；支持 daily/weekly/monthly/custom	scheduler.js + schedules.js
10	门店筛选: StoreSelector 支持 multi-select，报表数据自动聚合所选门店	StoreSelector.tsx + 各查询 storeId 参数

跨文档参考:

CUJ-M: 忠诚度与礼品卡 — Loyalty 报表数据源
CUJ-N: 平台管理 — Platform 报表 (H10) 的管理端
CUJ-J: 系统设置 — reports:* 权限配置

Web 报表模块 — CUJ 关键用户旅程

报表系统架构

报表类别总览

ReportEngine 查询映射 (report-engine.js)

目录

CUJ 总览与优先级矩阵

CUJ-H1: Business KPI Dashboard

用户流程

KPI 指标卡片

BDD 场景

场景 H1.1: 查看 KPI Dashboard

场景 H1.2: 多门店筛选

场景 H1.3: 切换日期范围

CUJ-H2: Finance 财务报表

Tab 结构

BDD 场景

场景 H2.1: 查看收入分布

场景 H2.2: 查看小费分布

场景 H2.3: 支付方式分析

CUJ-H3: Employee 员工绩效报表

BDD 场景

场景 H3.1: 员工绩效排名

场景 H3.2: 员工利用率分析

场景 H3.3: 个别员工详情

CUJ-H4: Operational 运营报表

BDD 场景

场景 H4.1: 预约来源分布

场景 H4.2: 爽约分析

场景 H4.3: 时段热力图

CUJ-H5: Loyalty 客户忠诚度报表

BDD 场景

场景 H5.1: 客户留存队列

场景 H5.2: 流失预警

场景 H5.3: 会员等级分布

场景 H5.4: 积分负债与礼品卡分析

CUJ-H6: Sales 销售报表

BDD 场景

场景 H6.1: 客户消费明细

场景 H6.2: 销售汇总

CUJ-H7: Profit 利润报表

BDD 场景

场景 H7.1: 双算法利润对比

场景 H7.2: 收支汇总

CUJ-H8: Entitlements 客户权益报表

BDD 场景

场景 H8.1: 权益汇总

场景 H8.2: 到期权益预警

CUJ-H9: Working Hours 工时报表

BDD 场景

场景 H9.1: 工时汇总

场景 H9.2: 按星期分布

CUJ-H10: Platform 平台级报表

BDD 场景

场景 H10.1: 平台概览

场景 H10.2: 租户增长趋势

CUJ-H11: Report Export 报表导出

导出流程

BDD 场景

场景 H11.1: 同步导出 Excel

场景 H11.2: 异步导出大报表

场景 H11.3: 导出 PDF

CUJ-H12: Report Schedules 定时报表

定时类型

BDD 场景

场景 H12.1: 创建定时报表

场景 H12.2: 手动触发

场景 H12.3: 暂停/恢复

跨模块依赖

业务规则