Files

danaisuiyuan a89825e23c docs(dashboard): 从 shjjy153 合并 dashboard 相关文档

补充 docs/dashboard/ 目录，包含：
- dashboard-frontend-dev-spec.md
- dashboard-frontend-technical-architecture.md
- boss-dashboard-development-guide.md
- crmeb-front-mysql-remote-connections.md

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-16 19:30:13 +08:00

15 KiB

Raw Blame History

老板驾驶舱 BI 开发说明

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

目标

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

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

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

开发原则

不先陷入复杂 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：

首页
日报
快报
风险
我的

首页内保留快捷入口：

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

建议路由：

/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

页面结构

页面自上而下：

顶部吸顶标题和日期口径
昨日经营 KPI 卡片
今日节点快报卡片
近 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

昨日经营口径

昨日范围：

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 快报范围：

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

14:55 快报范围：

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

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

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

快照表建议

后续阶段新增：

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：联调

联调顺序：

昨日经营复盘。
今日 10:15 快报。
今日 14:55 快报。
趋势图。
排行榜。
风险预警。

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 价值后再做。

15 KiB Raw Blame History Unescape Escape

老板驾驶舱 BI 开发说明

目标

开发原则

阶段划分

阶段一：前端 Mock 驾驶舱

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

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

前端开发说明

文件规划

菜单与路由

页面结构

顶部筛选区

KPI 卡片

今日快报模块

趋势图

排行榜

风险预警

下钻设计

Mock 数据要求

后端开发说明

接口规划

后端文件规划

数据来源

昨日经营口径

今日节点快报口径

快照表建议

风险预警规则

定时任务

前后端协作顺序

Step 1：前端出静态页面

Step 2：老板确认

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

Step 4：联调

Step 5：快照化与定时任务

测试说明

前端测试

后端测试

联调验收

里程碑

不在第一版范围

15 KiB

Raw Blame History