主题
数据分析系统
涉及子系统：云端 API（数据聚合）、管理后台（图表展示）
目标用户：老板、财务、门店管理员
核心业务：经营数据的统计、可视化展示，以及与飞书多维表格的集成
系统概述
数据分析系统基于业务数据库中已有的订单、进出记录、用户等数据进行聚合计算，在管理后台以图表形式呈现，同时支持推送至飞书多维表格供老板/财务灵活查阅。
财务分析
财务分析是数据分析系统的核心模块，面向老板和财务人员，提供多维度的财务数据统计。
收入统计
按渠道（微信支付 / 美团 / 抖音 / 其他）× 门店 × 时间周期（日/周/月/季/年）汇总实际支付金额。
GET /api/v1/admin/analytics/finance/revenue
?storeId=all|<storeId>
&channel=all|wechat|meituan|douyin
&period=day|week|month|quarter|year
&startDate=2026-01-01
&endDate=2026-03-31
&groupBy=day|week|month| 维度 | 说明 |
|---|---|
| 各渠道收入 | 微信自购 / 美团核销 / 抖音核销 分渠道汇总 |
| 各门店收入 | 按门店汇总，支持横向对比 |
| 按时间周期 | 日/周/月/季/年粒度灵活切换 |
| 产品类型拆分 | 体验卡 / 单店卡 / 跨店卡 / 洗浴卡 各自占比 |
结算金额统计
结算金额 = 收入 - 平台手续费 - 优惠券补贴（如有）。
| 渠道 | 结算逻辑 |
|---|---|
| 微信支付 | 收入直接到账，微信支付手续费按比例扣除 |
| 美团 | 美团按核销金额结算，扣除佣金后到账 |
| 抖音 | 抖音按核销金额结算，扣除佣金后到账 |
GET /api/v1/admin/analytics/finance/settlement
?storeId=all|<storeId>
&channel=all|wechat|meituan|douyin
&period=day|week|month|quarter|year退款统计
按渠道 × 门店 × 时间周期统计退款金额与笔数。
GET /api/v1/admin/analytics/finance/refunds
?storeId=all|<storeId>
&channel=all|wechat|meituan|douyin
&period=day|week|month|quarter|year核心分析维度
经营概览（Dashboard）
| 指标 | 说明 | 统计周期 |
|---|---|---|
| 今日营收 | 今日已支付订单总金额 | 日/周/月 |
| 今日进店人次 | 当日刷脸进入总次数 | 日/周/月 |
| 新增用户数 | 新注册用户数量 | 日/周/月 |
| 在场人数 | 当前在健身房内的用户数 | 实时 |
| 有效会员数 | 当前有 ACTIVE 订单的用户数 | 实时 |
营收分析
| 报表 | 说明 |
|---|---|
| 营收趋势图 | 按天/周/月展示营收曲线 |
| 产品销售占比 | 各套餐产品销售额/数量占比饼图 |
| 门店营收对比 | 多门店营收横向对比（老板视角） |
| 优惠券抵扣分析 | 优惠券使用金额及核销率统计 |
用户分析
| 报表 | 说明 |
|---|---|
| 用户增长趋势 | 新注册用户、人脸录入用户趋势 |
| 会员转化率 | 注册用户 → 首次购买的转化比例 |
| 会员续费率 | 到期用户中续费的比例 |
| 用户活跃度 | 月均进店次数分布 |
运营分析
| 报表 | 说明 |
|---|---|
| 进店热力图 | 按小时/星期几展示进店高峰 |
| 淋浴使用统计 | 淋浴使用频率与时长分布 |
| 设备告警统计 | 各类告警发生频次 |
数据粒度与权限
| 角色 | 数据范围 | 可查报表 |
|---|---|---|
| 老板 | 所有门店汇总 + 单店下钻 | 全部 |
| 财务 | 所有门店财务数据 | 营收分析、订单数据 |
| 门店管理员 | 仅本店数据 | 经营概览、进店分析 |
飞书多维表格集成
集成目标
允许老板/财务在飞书中灵活创建自定义视图、筛选、排序，无需依赖管理后台界面。
同步内容
| 飞书表格 | 同步内容 | 同步频率 |
|---|---|---|
| 每日经营汇总 | 各门店当日营收、进店人次、新增用户 | 每天凌晨自动同步 |
| 订单明细 | 近 N 天订单记录 | 每小时增量同步 |
| 用户列表 | 用户基本信息与会员状态 | 每天凌晨同步 |
| 告警记录 | 近 N 天设备告警 | 每小时增量同步 |
同步方式
使用飞书开放平台的「多维表格」API，通过 App Token 鉴权写入数据。
API 接口规划
GET /api/v1/admin/analytics/overview
?storeId=all&period=today/week/month
GET /api/v1/admin/analytics/revenue
?storeId=xxx&startDate=2026-01-01&endDate=2026-03-11&groupBy=day
GET /api/v1/admin/analytics/checkins
?storeId=xxx&startDate=...&endDate=...
GET /api/v1/admin/analytics/users
?storeId=xxx&period=month
GET /api/v1/admin/analytics/heatmap
?storeId=xxx&period=last30days数据导出
- 所有报表支持导出为 Excel / CSV
- 导出格式：表头中文，日期格式
YYYY-MM-DD - 大数据量导出采用异步任务（生成后通知下载链接）
待确认事项
- [ ] 飞书多维表格的具体表结构设计（与财务确认需要哪些字段）
- [ ] 数据同步的失败重试策略与告警机制
- [ ] 是否需要对接飞书机器人发送每日营业报告
- [ ] 在场人数实时统计的准确性容忍度（目前基于进出事件推算）
- [ ] 历史数据的保留时长（建议至少 2 年）