integral-shop/docs/dashboard/boss-dashboard-development-guide.md

# 老板驾驶舱 BI 开发说明

基于 `.cursor/plans/老板驾驶舱bi_1ae0092c.plan.md` 编写。

## 目标

建设一个面向公司老板的 H5 移动端商城运营驾驶舱，默认展示**昨日完整经营复盘**，并在每日 **10:15**、**14:55** 两个抢购/寄卖节点后展示**今日节点快报**。

本项目应按“先前端展示确认，再后端数据实现”的顺序推进：

1. 前端先做可点击、可切换、带 Mock 数据的 H5 高保真页面。
2. 给老板用手机确认信息层级、指标命名、视觉重点和下钻路径。
3. 确认后再做后端接口、数据聚合、快照任务和真实联调。

## 开发原则

- 不先陷入复杂 BI 汇总表设计，第一阶段以前端展示和老板确认口径为核心。
- 默认大盘展示“昨日”，避免当天数据未结束导致经营判断失真。
- 今日数据只作为 10:15、14:55 两个节点快报，不作为完整日报。
- 所有核心指标都要能追溯到现有明细页面或数据库表。
- 前后端接口契约先稳定，后端可分阶段从 Mock、实时 SQL、快照表演进。
- 前端第一版按 H5 移动端优先设计，不按 PC 后台页面铺开。

## 阶段划分

### 阶段一：前端 Mock 驾驶舱

目标：先把老板能看的页面做出来，用假数据确认展示结构。

交付内容：

- 新增“经营驾驶舱”菜单。
- 新增老板驾驶舱页面。
- 页面使用本地 Mock 数据，不依赖后端接口。
- 支持切换：昨日经营复盘、今日 10:15 快报、今日 14:55 快报、今日实时临时查看。
- KPI 卡、趋势图、排行、风险预警列表、下钻按钮均先展示出来。
- 使用手机端单列信息流、底部 Tab、顶部吸顶筛选和弹层选择器。

验收方式：

- 让老板用手机看实际 H5 页面或手机尺寸截图。
- 确认是否一眼能看懂经营情况。
- 确认哪些指标要放大、哪些指标可以下移或删除。
- 确认“昨日复盘 + 今日两次快报”的业务口径是否符合管理习惯。
- 确认手机首屏能否快速判断昨日经营是否正常。

### 阶段二：后端实时聚合接口

目标：在老板确认前端结构后，用真实数据替换 Mock。

交付内容：

- 新增老板驾驶舱接口。
- 先用实时 SQL 聚合昨日数据。
- 今日 10:15、14:55 快报先可按接口实时查询生成，不急于落快照表。
- 返回数据结构与前端 Mock 保持一致，减少前端返工。

验收方式：

- 昨日订单、用户、奖金、寄售数据与现有页面/数据库明细核对一致。
- 今日节点快报能在 10:15、14:55 后反映节点后的数据。
- 接口响应在常规数据量下控制在 3 秒内。

### 阶段三：快照表与定时任务

目标：让日报和今日快报可追溯、可复盘、可审计。

交付内容：

- 新增日报汇总表。
- 新增今日快报快照表。
- 新增定时任务：凌晨生成昨日完整日报，10:15 生成今日第一版快报，14:55 生成今日第二版快报。
- 快报生成失败时保留失败状态和错误信息。

验收方式：

- 可查看历史任意日期日报。
- 可查看某天 10:15 / 14:55 两个快报版本。
- 快报不会被手动刷新覆盖。

## 前端开发说明

### 文件规划

如果采用独立 Dashboard 前端项目，建议新增：

- `src/app/router/routes.tsx`
- `src/app/layouts/MobileLayout.tsx`
- `src/features/boss-dashboard/pages/BossDashboardPage.tsx`
- `src/features/boss-dashboard/components/KpiOverview.tsx`
- `src/features/boss-dashboard/components/TodaySnapshotSection.tsx`
- `src/features/boss-dashboard/components/TrendSection.tsx`
- `src/features/boss-dashboard/components/RankSection.tsx`
- `src/features/boss-dashboard/components/RiskAlertSection.tsx`
- `src/features/boss-dashboard/mock.ts`

可复用：

- `src/components/kpi/KpiCard.tsx`
- `src/components/charts/BaseChart.tsx`
- `src/components/feedback/RiskLevelTag.tsx`
- `src/services/api/dashboard.ts`
- `src/services/mock/handlers.ts`

### 菜单与路由

H5 第一版不使用 PC 侧边栏菜单，采用底部 TabBar。

底部 Tab：

- 首页
- 日报
- 快报
- 风险
- 我的

首页内保留快捷入口：

- 用户排行
- 团队排行
- 商品排行
- 资金池
- 下钻明细

建议路由：

```text
/h5/dashboard/boss
/h5/dashboard/daily-report
/h5/dashboard/today-snapshot
/h5/dashboard/risk-center
/h5/dashboard/drill/user
/h5/dashboard/drill/order
/h5/dashboard/drill/product
/h5/dashboard/drill/team
```

### 页面结构

页面自上而下：

1. 顶部吸顶标题和日期口径
2. 昨日经营 KPI 卡片
3. 今日节点快报卡片
4. 近 7 天趋势图
5. 用户 / 团队 / 商品排行
6. 风险预警列表
7. 底部 TabBar 和下钻入口

H5 布局要求：

- 页面单列展示，不做 PC 两列大盘。
- 首屏显示核心 4 个 KPI 和今日快报状态。
- 其他 KPI、资金池、排行和风险通过继续下滑查看。
- KPI 使用双列小卡，重点金额卡可跨两列。
- 图表单列展示，高度控制在 220px 到 280px。
- 排行榜首页只展示 Top 5，点击查看全部。

### 顶部筛选区

字段：

- 经营日期：默认昨日。
- 时间范围：昨日、近 7 天、近 30 天、自定义。
- 今日快报：10:15 快报、14:55 快报、实时临时查看。
- 公司/环境：第一版可固定当前公司，后续支持多公司。

展示规则：

- 页面默认打开时展示昨日经营复盘。
- 如果选择今日 10:15 快报，但当前时间未到 10:15，显示“待生成”。
- 如果选择今日 14:55 快报，但当前时间未到 14:55，显示“待生成”。
- 实时临时查看必须有明显标识：`临时数据，不作为日报结论`。
- 日期、范围和快报版本筛选使用弹层或分段控件，不使用 PC 横向表单。

### KPI 卡片

第一行建议 8 张卡：

- 昨日成交金额
- 昨日订单数
- 昨日采购用户数
- 昨日新增注册用户
- 昨日新增寄售商品
- 昨日个人奖金发放
- 昨日推广奖金发放
- 昨日待支付 / 待结算金额

第二行资金池卡片：

- 余额总额
- 优惠券总额
- 个人奖金总额
- 推广奖金总额
- 积分总额
- 待审核提现金额

卡片要求：

- 显示主数值、同比/环比变化、状态颜色。
- 支持点击下钻。
- 对金额使用千分位与两/三位小数，和业务页面保持一致。
- 手机端点击热区不小于 44px。
- 长金额不得溢出卡片，可缩小字号或换行。

### 今日快报模块

今日快报单独放在 KPI 下方，避免和昨日完整日报混淆。

内容：

- 当前快报版本：10:15 / 14:55 / 实时临时。
- 生成时间。
- 累计采购用户数。
- 累计订单数。
- 累计成交金额。
- 累计支付金额。
- 新增寄售商品数。
- 个人奖金变化。
- 推广奖金变化。
- 团队 Top 10。

状态：

- `待生成`
- `已生成`
- `生成失败`
- `临时数据`

### 趋势图

至少 4 张：

- 近 7 天成交金额走势
- 近 7 天订单数走势
- 近 7 天新增用户走势
- 近 7 天奖金发放走势

第一版可以合并成两个图：

- 交易趋势：成交金额 + 订单数。
- 用户与奖金趋势：新增用户 + 奖金发放。

### 排行榜

建议三个排行：

- 高价值用户 Top 20：按个人奖金 + 推广奖金 + 积分折算排序。
- 团队贡献 Top 10：按成交金额、成员数、奖金贡献排序。
- 高货值未成交商品 Top 20：按寄售价格排序。

### 风险预警

风险列表字段：

- 等级：红 / 黄 / 灰。
- 类型：资金、订单、商品、用户、数据质量。
- 标题。
- 描述。
- 关联对象：用户、订单、商品。
- 操作：查看明细。

第一版预警规则：

- 积分与个人奖金比例异常。
- 单用户奖金余额过高。
- 大额待审核提现。
- 大额未支付订单。
- 高价商品长时间未成交。
- `wa_users` 与 `eb_user` 用户缺失或手机号不一致。

### 下钻设计

点击 KPI 或风险项时跳转现有页面：

- 用户相关：`/user/list` 或 `/integral-external/user`
- 用户积分明细：`/integral-external/user/integral-detail?uid=xxx`
- 寄售商品：`/consignment/merchandise`
- 寄卖订单：`/consignment/order` 或现有订单管理页面
- 提现：`/consignment/withdraw`
- 财务日志：`/consignment/financial-log`

如现有路由不存在对应路径，第一版先保留按钮并提示“待接入明细页”。

### Mock 数据要求

前端第一阶段必须使用 Mock 数据覆盖所有展示状态：

- 昨日经营正常。
- 今日 10:15 已生成。
- 今日 14:55 待生成。
- 今日快报生成失败。
- 风险列表为空。
- 风险列表有红黄灰多级预警。

Mock 数据结构应和后端接口设计一致，后续只替换 API 数据源。

## 后端开发说明

### 接口规划

建议第一版接口：

- `GET /api/admin/dashboard/boss/yesterday`
- `GET /api/admin/dashboard/boss/today-report?slot=1015`
- `GET /api/admin/dashboard/boss/today-report?slot=1455`
- `GET /api/admin/dashboard/boss/trends?range=7`
- `GET /api/admin/dashboard/boss/alerts`

也可以合并成一个接口：

- `GET /api/admin/dashboard/boss/overview?mode=yesterday|today&slot=1015|1455`

建议先保持多个接口，便于前端按模块加载和失败降级。

### 后端文件规划

建议新增：

- `backend/crmeb-admin/src/main/java/com/zbkj/admin/controller/BossDashboardController.java`
- `backend/crmeb-service/src/main/java/com/zbkj/service/service/BossDashboardService.java`
- `backend/crmeb-service/src/main/java/com/zbkj/service/service/impl/BossDashboardServiceImpl.java`
- `backend/crmeb-common/src/main/java/com/zbkj/common/response/dashboard/BossDashboardResponse.java`
- `backend/crmeb-common/src/main/java/com/zbkj/common/response/dashboard/BossTodayReportResponse.java`
- `backend/crmeb-common/src/main/java/com/zbkj/common/response/dashboard/BossRiskAlertResponse.java`

### 数据来源

用户：

- `wa_users`
- `eb_user`

交易：

- `wa_order`

寄售商品：

- `wa_merchandise`

奖金：

- `wa_selfbonus_log`
- `wa_sharebonus_log`

提现：

- `wa_withdraw`

积分：

- `eb_user_integral_record`
- `eb_user.integral`

### 昨日经营口径

昨日范围：

```sql
created_at >= CURDATE() - INTERVAL 1 DAY
AND created_at < CURDATE()
```

如果表字段是 `join_time`、`create_time`、`pay_time`，按对应字段替换。

关键指标：

- 昨日新增用户：`wa_users.created_at` 或 `wa_users.join_time`
- 昨日采购用户：`wa_order.buyer_id` 去重
- 昨日订单数：`wa_order.created_at`
- 昨日成交金额：`wa_order.total_money`
- 昨日新增寄售商品：`wa_merchandise.created_at`
- 昨日个人奖金发放：`wa_selfbonus_log.type = 1`
- 昨日推广奖金发放：`wa_sharebonus_log.type = 1`
- 昨日待支付金额：`wa_order.status = 0`
- 昨日已支付未完成金额：`wa_order.status = 1`

### 今日节点快报口径

10:15 快报范围：

```sql
created_at >= CURDATE()
AND created_at <= CONCAT(CURDATE(), ' 10:15:00')
```

14:55 快报范围：

```sql
created_at >= CURDATE()
AND created_at <= CONCAT(CURDATE(), ' 14:55:00')
```

快报需要记录生成时刻，避免后续数据变化导致历史快报不可复现。

第一版如果不建表，可实时查询并明确标记为“临时快报”。正式版需要落表。

### 快照表建议

后续阶段新增：

```sql
CREATE TABLE bi_today_snapshot (
  id INT AUTO_INCREMENT PRIMARY KEY,
  report_date DATE NOT NULL,
  slot VARCHAR(16) NOT NULL COMMENT '1015/1455',
  status TINYINT NOT NULL DEFAULT 1 COMMENT '1=成功,2=失败',
  generated_at DATETIME NOT NULL,
  payload JSON,
  error_message VARCHAR(1000),
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  UNIQUE KEY uk_report_slot (report_date, slot)
);
```

如果当前 MySQL 版本或项目 JSON 字段支持不稳定，可把 `payload` 改为 `LONGTEXT` 存 JSON 字符串。

### 风险预警规则

第一版实时计算即可。

建议规则：

- 积分与个人奖金比例异常：`ABS(eb_user.integral - wa_users.self_bonus / 2) > 1`
- 单用户个人奖金过高：`wa_users.self_bonus >= 阈值`
- 单用户推广奖金过高：`wa_users.share_bonus >= 阈值`
- 大额待审核提现：`wa_withdraw.status = 0 AND money >= 阈值`
- 大额未支付订单：`wa_order.status = 0 AND total_money >= 阈值`
- 高价滞销商品：`wa_merchandise.status = 1 AND price >= 阈值 AND created_at <= NOW() - INTERVAL N DAY`
- 数据不一致：`wa_users.id` 在 `eb_user.uid` 中不存在，或 `wa_users.mobile != eb_user.phone`

阈值第一版可写死在服务层，后续再做配置化。

### 定时任务

建议任务：

- 每天 00:10：生成昨日经营日报。
- 每天 10:15：生成今日第一版快报。
- 每天 14:55：生成今日第二版快报。
- 每小时：刷新风险预警。

如果系统已有 Quartz/ScheduleJob，则接入现有任务体系。

## 前后端协作顺序

### Step 1：前端出静态页面

前端完成：

- H5 底部 TabBar
- 手机端页面布局
- 顶部吸顶 Header
- 筛选弹层
- Mock 数据
- 图表
- 风险列表
- 下钻按钮

不等待后端。

### Step 2：老板确认

确认内容：

- 是否默认看昨日。
- 今日快报是否放在合适位置。
- 10:15、14:55 两个节点名称是否符合业务习惯。
- KPI 是否足够。
- 哪些风险最重要。
- 哪些排行需要保留。
- 手机首屏是否足够清楚。
- 滑动查看排行榜、风险和下钻是否顺手。

确认后冻结第一版字段。

### Step 3：后端按字段实现接口

后端按前端 Mock 字段实现真实接口。

要求：

- 字段名不随意改。
- 缺数据返回 0 或空数组。
- 金额统一 BigDecimal。
- 日期统一 `yyyy-MM-dd HH:mm:ss`。

### Step 4：联调

联调顺序：

1. 昨日经营复盘。
2. 今日 10:15 快报。
3. 今日 14:55 快报。
4. 趋势图。
5. 排行榜。
6. 风险预警。

### Step 5：快照化与定时任务

如果老板确认使用，再做快照表和定时任务。

## 测试说明

### 前端测试

- 页面能独立打开。
- Mock 数据展示完整。
- 今日快报四种状态展示正常。
- 图表在空数据时不报错。
- 风险列表为空时显示空状态。
- 点击下钻按钮不报错。
- 375px 手机宽度下无横向滚动。
- 底部 TabBar、筛选弹层、返回逻辑正常。

### 后端测试

- 昨日时间范围正确。
- 10:15 快报范围正确。
- 14:55 快报范围正确。
- 金额汇总和数据库明细一致。
- 用户、订单、商品、奖金、提现为空时接口正常返回。
- 风险规则命中样例正确。

### 联调验收

- 老板能通过一个页面看懂昨日经营是否正常。
- 10:15 后能看到第一版今日快报。
- 14:55 后能看到第二版今日快报。
- 核心指标能下钻到现有业务页面。
- 与现有后台明细抽样核对一致。
- 老板能在手机 H5 页面顺畅查看核心指标、排行和风险。

## 里程碑

- 前端 Mock：1-2 天，交付可访问的 H5 经营驾驶舱页面，用于老板手机确认页面和指标。
- 后端实时接口：2-4 天，交付 BI 查询接口，用真实数据替换 Mock。
- 联调验收：1-2 天，完成指标和明细对账，形成可用 MVP。
- 快照任务：3-5 天，交付汇总表、快照表和定时任务。

## 不在第一版范围

- PC 后台完整看板。
- 多公司统一看板。
- 复杂权限隔离。
- 自定义指标配置。
- 老板微信/企微推送。
- 完整 BI 报表编辑器。
- 所有历史日报回填。

这些可在老板确认 MVP 价值后再做。