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
parent ccb70ca10e
commit a89825e23c
4 changed files with 2563 additions and 0 deletions
--- a/docs/dashboard/boss-dashboard-development-guide.md
+++ b/docs/dashboard/boss-dashboard-development-guide.md
@@ -0,0 +1,553 @@
 # 老板驾驶舱 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 价值后再做。
--- a/docs/dashboard/crmeb-front-mysql-remote-connections.md
+++ b/docs/dashboard/crmeb-front-mysql-remote-connections.md
@@ -0,0 +1,47 @@
 # 积分商城front MySQL 远程连接汇总
 整理范围：`backend/crmeb-front/src/main/resources/application*.yml`
 整理时间：2026-05-11
 ## 口径说明
 - 仅汇总 MySQL URL 中 host 为远程地址的配置。
 - 所属公司优先按 `docs/company-info-*.md`、`docs/*data-imgration*.md` 中的公司名称和 host ip 匹配；没有明确公司名时，按部署文档、域名、profile 或数据库名推断并注明。
 - 密码按当前配置文件完整记录。
 ## 按 MySQL 主机聚合
 | MySQL host:port | 关联 profile | 说明 |
 | --- | --- | --- |
 | `8.140.218.149:3306` | `byjyw149` | 宝应金雅文商贸 |
 | `8.136.120.231:3306` | `czc231` | 宝应晨召春商贸 |
 | `121.43.134.82:3306` | `czcf82` | 池州春芳商贸 |
 | `101.37.101.6:3306` | `czrt6` | 池州瑞棠商贸 |
 | `114.55.232.191:3306` | `hapr191` | 淮安鹏然商贸 |
 | `106.14.132.80:3306` | `sxsy80` | 太原树英商贸 |
 | `39.106.63.33:3306` | `miao33` | 夏盛军商贸 |
 | `123.56.214.80:3306` | `miao80` | 宝应博森元 |
 | `101.37.253.50:3306` | `miao50` | 上海文锦惠商贸 |
 | `101.132.245.153:3306` | `shjjy153` | 上海聚伽源商贸 |
 | `182.92.78.159:3306` | `shccd159` | 上海慈初德商贸 |
 ## 远程 MySQL 配置清单
 | Profile | 配置文件 | 所属公司 / 项目 | MySQL host:port | 数据库名 | 用户名 | 密码 | 依据 / 备注 |
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | `byjyw149` | `backend/crmeb-front/src/main/resources/application-byjyw149.yml` | 宝应金雅文商贸 | `8.140.218.149:3306` | `yangtangyoupin` | `yangtangyoupin` | `5Fn8eWrbYFtAhCZw` | `docs/company-info-byjyw149.md`、`docs/byjyw149-data-imgration.md` |
 | `czc231` | `backend/crmeb-front/src/main/resources/application-czc231.yml` | 宝应晨召春商贸 | `8.136.120.231:3306` | `yangtangyoupin` | `yangtangyoupin` | `5Fn8eWrbYFtAhCZw` | `docs/company-czc231-data-imgration.md`、`docs/company-czc231-integral-imgration.md` |
 | `czcf82` | `backend/crmeb-front/src/main/resources/application-czcf82.yml` | 池州春芳商贸 | `121.43.134.82:3306` | `yangtangyoupin` | `yangtangyoupin` | `5Fn8eWrbYFtAhCZw` | `docs/company-info-czcf82.md`、`docs/company-czcf82-data-imgration.md` |
 | `czrt6` | `backend/crmeb-front/src/main/resources/application-czrt6.yml` | 池州瑞棠商贸 | `101.37.101.6:3306` | `yangtangyoupin` | `yangtangyoupin` | `5Fn8eWrbYFtAhCZw` | `docs/company-info-czrt6.md`、`docs/company-czrt6-data-imgration.md` |
 | `hapr191` | `backend/crmeb-front/src/main/resources/application-hapr191.yml` | 淮安鹏然商贸 | `114.55.232.191:3306` | `yangtangyoupin` | `yangtangyoupin` | `5Fn8eWrbYFtAhCZw` | `docs/company-info.md`、`docs/company-data-imgration.md` |
 | `sxsy80` | `backend/crmeb-front/src/main/resources/application-sxsy80.yml` | 太原树英商贸 | `106.14.132.80:3306` | `yangtangyoupin` | `yangtangyoupin` | `5Fn8eWrbYFtAhCZw` | `docs/com-sxsy80.md`、`docs/com-sxsy80-data-imgration.md` |
 | `miao33` | `backend/crmeb-front/src/main/resources/application-miao33.yml` | 夏盛军商贸 | `39.106.63.33:3306` | `yangtangyoupin` | `yangtangyoupin` | `5Fn8eWrbYFtAhCZw` | `docs/com-xsj33-data-imgration.md`；部署文档中也标注 `jfadmin.xiashengjun.com` |
 | `miao80` | `backend/crmeb-front/src/main/resources/application-miao80.yml` | 宝应博森元 | `123.56.214.80:3306` | `yangtangyoupin` | `yangtangyoupin` | `5Fn8eWrbYFtAhCZw` | `backend-adminend/DEPLOY.md` 中 by80 示例域名为 `jfadmin.bosenyuan.com`；`.cursor/plans/bybsy80范围数据删除_1cf340f6.plan.md` 也指向该 host |
 | `miao50` | `backend/crmeb-front/src/main/resources/application-miao50.yml` | 上海文锦惠商贸 | `101.37.253.50:3306` | `yangtangyoupin` | `yangtangyoupin` | `5Fn8eWrbYFtAhCZw` | `backend/DEPLOY.md`、OpenClaw 配置文档中标注为生产环境 |
 | `shjjy153` | `backend/crmeb-front/src/main/resources/application-shjjy153.yml` | 上海聚伽源商贸 | `101.132.245.153:3306` | `yangtangyoupin` | `yangtangyoupin` | `5Fn8eWrbYFtAhCZw` | `docs/compare-shjjy153-shccd159.md` 标注域名 `jjy-jf.fwxgpt.com`、`jjy-jfadmin.fwxgpt.com` |
 | `shccd159` | `backend/crmeb-front/src/main/resources/application-shccd159.yml` | 上海慈初德商贸 | `182.92.78.159:3306` | `yangtangyoupin` | `yangtangyoupin` | `5Fn8eWrbYFtAhCZw` | `docs/compare-shjjy153-shccd159.md` 标注域名 `ccd-jf.fwxgpt.com`、`ccd-jfadmin.fwxgpt.com` |
--- a/docs/dashboard/dashboard-frontend-dev-spec.md
+++ b/docs/dashboard/dashboard-frontend-dev-spec.md
--- a/docs/dashboard/dashboard-frontend-technical-architecture.md
+++ b/docs/dashboard/dashboard-frontend-technical-architecture.md
@@ -0,0 +1,751 @@
 # Dashboard 前端项目技术架构方案
 ## 1. 方案定位
 本文档面向一个全新的 Dashboard 前端项目，不考虑当前商城后台已有技术架构、目录结构和历史包袱。
 目标是建设一个适合老板手机查看的 H5 经营驾驶舱，覆盖经营分析、BI 报表、风险预警和数据下钻。项目应具备快速交付、长期可维护、强类型、易扩展、易联调和可独立部署的能力。
 ## 2. 架构目标
 - 支持经营驾驶舱、日报、快报、趋势分析、排行榜、风险预警等 BI 场景。
 - 优先支持 H5 移动端展示，适配手机浏览器、企业微信内置浏览器和移动端 WebView。
 - 在 PC 浏览器访问时以手机宽度居中展示，不优先建设 PC 后台版。
 - 前端可先独立使用 Mock 数据完成页面确认，不依赖后端开发进度。
 - 接口契约稳定后，平滑从 Mock 切换到真实 API。
 - 支持权限、菜单、主题、国际化、错误边界、埋点和性能监控。
 - 支持独立构建、独立部署、独立版本发布。
 ## 3. 推荐技术栈
 ### 3.1 核心框架
 - 前端框架：`React 19`
 - 开发语言：`TypeScript`
 - 构建工具：`Vite`
 - 包管理器：`pnpm`
 - 路由：`React Router`
 - 服务端状态：`TanStack Query`
 - 客户端状态：`Zustand`
 - HTTP 请求：`Axios`
 - 图表：`Apache ECharts`
 - UI 组件库：`Vant React` 或等价移动端组件库
 - 样式方案：`CSS Modules` + `CSS Variables`
 - 代码规范：`ESLint` + `Prettier`，或统一采用 `Biome`
 - 单元测试：`Vitest`
 - 组件测试：`React Testing Library`
 - E2E 测试：`Playwright`
 - Mock：`MSW`
 ### 3.2 技术选型理由
 `React + TypeScript + Vite` 适合从 0 建设独立 BI Dashboard，生态成熟、类型安全、启动和构建速度快。
 `Vant React` 更适合 H5 移动端经营驾驶舱场景，提供移动端表单、弹层、Tab、日期选择、列表、Toast、Dialog 等基础能力，能降低手机端交互开发成本。如果团队最终选用其他 React 移动端组件库，也应满足同等移动端触控和适配能力。
 `ECharts` 适合经营分析中的复杂图表需求，包括折线图、柱状图、饼图、仪表盘、热力图和双轴图。移动端使用时需要封装触控友好的 tooltip、缩放和空态，不直接套用 PC 大图表配置。
 `TanStack Query` 负责接口数据、缓存、刷新、重试和加载状态，避免把接口数据塞进全局状态。
 `Zustand` 只管理前端本地状态，例如主题、底部 Tab、筛选条件、当前快报版本、用户偏好。
 ## 4. 总体架构
 ```mermaid
 flowchart TD
    Browser[浏览器] --> App[Dashboard App]
    App --> Router[路由层]
    App --> Layout[H5 布局层]
    App --> FeatureModules[业务模块]
    App --> Shared[共享能力]
    FeatureModules --> BossDashboard[老板驾驶舱]
    FeatureModules --> DailyReport[经营日报]
    FeatureModules --> TodaySnapshot[今日节点快报]
    FeatureModules --> RiskCenter[风险预警中心]
    FeatureModules --> DataDrill[数据下钻]
    Shared --> ApiClient[API Client]
    Shared --> QueryLayer[TanStack Query]
    Shared --> Store[Zustand Store]
    Shared --> ChartKit[Chart Kit]
    Shared --> Permission[权限与移动端导航]
    Shared --> Theme[主题系统]
    ApiClient --> Backend[BI API 服务]
    QueryLayer --> ApiClient
 ```
 ## 5. 项目目录设计
 建议目录：
 ```text
 dashboard-frontend/
  public/
  src/
    app/
      App.tsx
      providers/
      router/
      layouts/
    assets/
    components/
      common/
      charts/
      kpi/
      list/
      feedback/
    features/
      boss-dashboard/
      daily-report/
      today-snapshot/
      risk-center/
      data-drill/
    services/
      api/
      http/
      mock/
    stores/
    hooks/
    utils/
    types/
    styles/
    tests/
  .env.development
  .env.production
  package.json
  vite.config.ts
  tsconfig.json
 ```
 ### 5.1 `app`
 承载项目启动、全局 Provider、路由、布局和全局配置。
 包含：
 - 路由初始化
 - QueryClient 初始化
 - 移动端 UI ConfigProvider
 - 权限上下文
 - 主题上下文
 - 全局错误边界
 ### 5.2 `features`
 按业务功能拆分模块，避免所有页面堆在 `views` 下。
 建议模块：
 - `boss-dashboard`：老板驾驶舱首页
 - `daily-report`：昨日/历史经营日报
 - `today-snapshot`：今日 10:15、14:55 快报
 - `risk-center`：风险预警列表与处理
 - `data-drill`：用户、订单、商品、团队等下钻页
 每个模块内部建议结构：
 ```text
 features/boss-dashboard/
  pages/
  components/
  hooks/
  api.ts
  types.ts
  constants.ts
  mock.ts
 ```
 ### 5.3 `components`
 放跨模块复用组件。
 建议拆分：
 - `common`：页面标题、空状态、加载状态、错误状态
 - `charts`：折线图、柱状图、饼图、双轴图、仪表盘
 - `kpi`：指标卡、指标组、同比环比组件
 - `table`：统一表格封装
 - `feedback`：异常提示、状态标签、风险等级标签
 ### 5.4 `services`
 承载接口、HTTP 客户端、Mock 和数据适配。
 核心职责：
 - 统一请求拦截
 - 统一响应解包
 - 统一错误提示
 - 统一登录态处理
 - Mock 与真实 API 切换
 - 后端字段到前端视图模型的适配
 ### 5.5 `types`
 放全局类型和跨模块共享类型。
 原则：
 - 接口响应类型和页面视图类型分开。
 - 后端 DTO 不直接污染页面组件。
 - 金额、日期、枚举、状态统一定义。
 ## 6. 模块架构设计
 ### 6.1 老板驾驶舱
 职责：
 - 展示昨日经营总览。
 - 展示今日 10:15 / 14:55 节点快报。
 - 展示趋势图、排行榜、风险预警。
 - 提供下钻入口。
 页面结构：
 ```text
 BossDashboardPage
  MobileStickyHeader
  MobileDateFilterSheet
  KpiOverview
  TodaySnapshotPanel
  TrendSection
  RankSection
  RiskAlertSection
  BottomTabBar
 ```
 H5 展示要求：
 - 首屏优先展示 4 个核心 KPI 和今日快报状态。
 - 其他 KPI 使用折叠区或分组卡片承载。
 - 页面采用单列信息流，不使用 PC 两列 Dashboard。
 - 排行榜默认展示 Top 5，点击进入完整列表。
 - 筛选条件使用弹层、分段控件或底部 ActionSheet。
 ### 6.2 经营日报
 职责：
 - 查看昨日、近 7 天、近 30 天和自定义日期经营数据。
 - 支持日报导出。
 - 支持历史日期切换。
 ### 6.3 今日节点快报
 职责：
 - 展示 10:15 快报。
 - 展示 14:55 快报。
 - 标识快报状态：待生成、已生成、生成失败、临时数据。
 - 支持与昨日同节点或昨日全天对比。
 ### 6.4 风险预警中心
 职责：
 - 展示资金、订单、商品、用户、数据质量风险。
 - 支持风险等级筛选。
 - 支持跳转明细。
 - 支持风险状态流转：未处理、处理中、已处理、已忽略。
 ### 6.5 数据下钻
 职责：
 - 从 KPI、图表、排行和风险项跳转到明细视图。
 - 支持携带筛选条件。
 - 支持返回驾驶舱时保留上下文。
 ## 7. 数据流设计
 ### 7.1 数据流原则
 - 接口数据归 `TanStack Query` 管。
 - 页面交互状态归组件本地状态或 `Zustand` 管。
 - 复杂筛选条件可以进入 URL Query，方便分享和刷新恢复。
 - 图表组件只接收标准化后的数据，不直接请求接口。
 ### 7.2 数据流示意
 ```mermaid
 sequenceDiagram
    participant Page as 页面
    participant Hook as Query Hook
    participant API as API Service
    participant Adapter as Data Adapter
    participant Chart as Chart/KPI 组件
    participant Backend as BI API
    Page->>Hook: 传入日期、快报版本、筛选条件
    Hook->>API: 请求接口
    API->>Backend: HTTP Request
    Backend-->>API: DTO Response
    API->>Adapter: 字段转换与默认值处理
    Adapter-->>Hook: ViewModel
    Hook-->>Page: data/loading/error
    Page->>Chart: 传入标准图表数据
 ```
 ## 8. 接口契约设计
 ### 8.1 前端视图模型
 前端不直接依赖后端原始字段，统一转换为页面视图模型。
 核心模型：
 - `DashboardOverview`
 - `KpiMetric`
 - `TodaySnapshot`
 - `TrendSeries`
 - `RankItem`
 - `RiskAlert`
 - `DrillLink`
 ### 8.2 接口分层
 建议接口：
 - `GET /dashboard/overview`
 - `GET /dashboard/today-snapshot`
 - `GET /dashboard/trends`
 - `GET /dashboard/ranks`
 - `GET /dashboard/risks`
 - `GET /dashboard/drill-options`
 前端可以先使用相同结构的 Mock 数据，后端上线后只替换请求来源。
 ### 8.3 错误处理
 接口错误分三层：
 - 页面级错误：整个模块无法加载。
 - 区块级错误：某个图表或榜单失败。
 - 字段级兜底：单个指标缺失时显示 `--`。
 老板驾驶舱首页不应因为某一个模块失败而整页不可用。
 ## 9. 状态管理方案
 ### 9.1 Server State
 由 `TanStack Query` 管理：
 - 接口缓存
 - 自动刷新
 - 重试
 - loading / error 状态
 - 后台静默刷新
 - 请求去重
 适用数据：
 - KPI 数据
 - 趋势数据
 - 排行数据
 - 风险列表
 - 快报快照
 ### 9.2 Client State
 由 `Zustand` 管理：
 - 当前主题
 - 底部 Tab 当前选中状态
 - 筛选弹层打开状态
 - 当前公司
 - 当前快报版本
 - 用户偏好
 - 全局筛选草稿
 ### 9.3 URL State
 建议进入 URL 的状态：
 - 日期范围
 - 快报版本
 - 风险等级
 - 团队 ID
 - 下钻来源
 这样可以支持刷新恢复和链接分享。
 ## 10. 图表体系
 ### 10.1 图表库
 推荐使用 `Apache ECharts`。
 原因：
 - 适合 BI 场景。
 - 支持复杂组合图。
 - 支持大数据量渲染优化。
 - 国内开发者熟悉度高。
 - 主题定制能力强。
 ### 10.2 图表封装原则
 不要在业务页面直接写大量 ECharts option。
 建议封装：
 - `LineTrendChart`
 - `BarCompareChart`
 - `PieRatioChart`
 - `DualAxisChart`
 - `GaugeMetricChart`
 - `RankBarChart`
 业务页面只传入标准数据：
 ```text
 {
  title,
  xAxis,
  series,
  unit,
  loading,
  empty
 }
 ```
 ### 10.3 图表状态
 每个图表必须支持：
 - loading
 - empty
 - error
 - normal
 - fullscreen
 ## 11. 权限与安全
 ### 11.1 权限模型
 建议分三层：
 - 路由权限：是否能访问驾驶舱。
 - 模块权限：是否能看资金、奖金、团队等模块。
 - 字段权限：是否脱敏手机号、姓名、金额。
 ### 11.2 前端安全
 - Token 不写死。
 - 请求统一携带认证信息。
 - 敏感字段按权限展示。
 - 不在前端保存数据库连接信息。
 - 不在 Mock 数据中使用真实手机号、真实姓名、真实金额。
 ### 11.3 敏感信息展示
 老板角色可以看完整金额。
 普通管理角色建议：
 - 手机号脱敏。
 - 用户姓名部分脱敏。
 - 大额资金需要权限。
 - 导出需要二次确认。
 ## 12. Mock 与联调
 ### 12.1 Mock 优先
 第一阶段必须支持无后端运行。
 推荐使用 `MSW`：
 - 拦截浏览器请求。
 - Mock 真实接口。
 - 与后端接口格式保持一致。
 - 联调时可以逐个接口关闭 Mock。
 ### 12.2 Mock 数据场景
 至少覆盖：
 - 昨日经营正常。
 - 昨日经营下滑。
 - 今日 10:15 已生成。
 - 今日 14:55 待生成。
 - 今日快报生成失败。
 - 风险为空。
 - 风险包含红黄灰三级。
 - 某个图表接口失败。
 - 某个 KPI 缺失。
 ### 12.3 联调策略
 前端接口层设置数据源模式：
 - `mock`
 - `api`
 - `hybrid`
 `hybrid` 用于部分接口接真实 API，部分接口继续使用 Mock。
 ## 13. 样式与主题
 ### 13.1 设计方向
 老板驾驶舱应偏“手机经营简报”风格：信息聚焦、数字醒目、可快速滑动浏览，并兼顾老板在企业微信或手机浏览器内查看的可读性。
 建议：
 - 默认浅色主题。
 - 后续可支持深色移动端主题。
 - 金额、风险、增长下降用统一颜色。
 - 卡片信息密度高但不拥挤。
 - 关键数字明显大于说明文字。
 - 手机首屏必须能看见昨日经营核心结论。
 - 底部导航和顶部筛选不遮挡内容。
 ### 13.1.1 H5 布局要求
 - 核心适配宽度：360px、375px、390px、414px。
 - PC 浏览器访问时，内容区最大宽度建议 430px 并居中。
 - 使用单列信息流。
 - KPI 使用 2 列卡片，重点金额卡片可跨 2 列。
 - 图表单列展示，高度建议 220px 到 280px。
 - 底部 TabBar 需要适配 `safe-area-inset-bottom`。
 - 点击热区不小于 44px。
 - 不允许页面出现横向滚动条。
 ### 13.2 主题变量
 统一管理：
 - 主色
  - 第一版确定使用参考图中的活力橙/珊瑚橙作为主色调，主色建议接近 `#ff5b36`，辅色使用橙黄 `#ffb000`，用于核心按钮、选中态、关键图表主线和高亮数字。
 - 成功色
 - 警告色
 - 危险色
 - 背景色
 - 卡片背景
 - 字体颜色
 - 边框颜色
 - 图表色板
 ## 14. 性能方案
 ### 14.1 加载性能
 - 路由懒加载。
 - 图表组件懒加载。
 - 大模块按需加载。
 - 首屏接口并行请求。
 - 非核心模块延迟加载。
 - 移动端首屏优先加载 KPI 和快报，排行榜、风险列表可延迟加载。
 ### 14.2 渲染性能
 - 大表格虚拟滚动。
 - 图表数据降采样。
 - 趋势图默认展示合理时间窗口。
 - 避免父组件频繁重渲染图表。
 - ECharts 实例销毁和 resize 管理统一封装。
 ### 14.3 数据刷新
 - 昨日数据不频繁刷新。
 - 今日快报按节点刷新。
 - 风险预警可设置 1 到 5 分钟刷新。
 - 页面不可见时暂停自动刷新。
 ## 15. 测试策略
 ### 15.1 单元测试
 覆盖：
 - 数据适配器
 - 金额格式化
 - 日期范围计算
 - 风险等级映射
 - KPI 状态计算
 ### 15.2 组件测试
 覆盖：
 - KPI 卡片不同状态展示。
 - 今日快报待生成/已生成/失败状态。
 - 风险列表空态和多级风险。
 - 图表空数据和错误状态。
 ### 15.3 E2E 测试
 覆盖关键路径：
 - 打开老板驾驶舱。
 - 切换昨日、近 7 天、近 30 天。
 - 切换 10:15 / 14:55 快报。
 - 点击 KPI 下钻。
 - 点击风险项查看明细。
 - 导出日报。
 ## 16. 部署架构
 ### 16.1 独立部署
 推荐 Dashboard 前端独立部署为静态站点。
 部署目标：
 - Nginx
 - OSS/CDN
 - Docker + Nginx
 - 企业内网静态服务
 ### 16.2 环境划分
 建议环境：
 - `local`
 - `development`
 - `staging`
 - `production`
 环境变量：
 - `VITE_APP_ENV`
 - `VITE_API_BASE_URL`
 - `VITE_MOCK_ENABLED`
 - `VITE_SENTRY_DSN`
 - `VITE_BUILD_VERSION`
 ### 16.3 版本发布
 每次构建写入：
 - 构建版本
 - Git Commit
 - 构建时间
 - 环境名称
 页面底部或调试面板可查看当前版本，便于排查问题。
 ## 17. 监控与可观测性
 建议接入：
 - 前端错误监控
 - 页面性能监控
 - API 请求耗时统计
 - 白屏监控
 - 用户行为埋点
 关键埋点：
 - 老板驾驶舱访问次数
 - 日期范围切换
 - 今日快报查看
 - KPI 点击下钻
 - 风险项点击
 - 导出日报
 ## 18. CI/CD
 推荐流水线：
 1. 安装依赖
 2. 类型检查
 3. Lint
 4. 单元测试
 5. 构建
 6. 产物上传
 7. 部署到目标环境
 8. 冒烟测试
 质量门禁：
 - TypeScript 不允许类型错误。
 - Lint 不允许错误。
 - 核心测试必须通过。
 - 构建产物大小超限需要提醒。
 ## 19. 开发流程
 ### 19.1 第一阶段：前端原型
 目标：快速给老板确认。
 内容：
 - 初始化项目。
 - 接入 UI 组件库。
 - 完成路由和布局。
 - 完成老板驾驶舱 Mock 页面。
 - 完成 KPI、趋势图、快报、排行、风险预警。
 - 完成 H5 底部 Tab、吸顶 Header、筛选弹层和手机端适配。
 ### 19.2 第二阶段：接口契约
 目标：冻结前后端字段。
 内容：
 - 输出接口字段文档。
 - 前端 Mock 与接口文档保持一致。
 - 后端按契约实现。
 - 前端通过数据适配器兼容后端字段差异。
 ### 19.3 第三阶段：真实联调
 目标：替换 Mock。
 内容：
 - 接入真实 API。
 - 保留 Mock 作为开发和演示能力。
 - 校验金额、日期、趋势、风险口径。
 - 完成下钻联动。
 ### 19.4 第四阶段：上线增强
 目标：稳定可用。
 内容：
 - 权限控制。
 - 错误监控。
 - 性能优化。
 - 导出能力。
 - 深色移动端主题。
 ## 20. 推荐里程碑
 - 第 1 到 2 天：项目初始化、H5 路由、移动端布局、主题、Mock 框架。
 - 第 3 到 5 天：老板驾驶舱 H5 核心页面，包括 KPI、今日快报、趋势、排行、风险。
 - 第 6 到 7 天：老板确认与页面调整。
 - 第 8 到 10 天：接口契约冻结，接入第一批真实 API。
 - 第 11 到 14 天：完整联调、权限、错误处理、基础测试。
 - 第 15 天以后：快照、导出、监控、深色主题和必要的 PC 预览适配。
 ## 21. 不建议第一版做的事
 - 不做复杂自定义 BI 报表编辑器。
 - 不做多租户平台化架构。
 - 不做拖拽式大屏搭建。
 - 不做 PC 后台完整版本。
 - 不做全量数据仓库前端建模。
 - 不把所有历史后台功能重新做一遍。
 - 不在前端处理复杂财务计算，前端只展示后端已确认口径的数据。
 ## 22. 最终建议
 建议采用：
 - `React 19 + TypeScript + Vite`
 - `Vant React` 或等价移动端组件库
 - `TanStack Query + Zustand`
 - `ECharts`
 - `MSW`
 - `Vitest + Testing Library + Playwright`
 第一版以“老板在手机上能看懂、能确认、能下钻”为核心，先交付独立 H5 Mock Dashboard。确认后再接真实接口和快照数据，避免后端先做大量数据聚合后发现展示口径需要重改。