From a89825e23c9850e6d41c979f0a252076c8b6d4c7 Mon Sep 17 00:00:00 2001
From: danaisuiyuan <mac@danaisuiyuandeMacBook-Pro.local>
Date: Sat, 16 May 2026 19:30:13 +0800
Subject: [PATCH] =?UTF-8?q?docs(dashboard):=20=E4=BB=8E=20shjjy153=20?=
 =?UTF-8?q?=E5=90=88=E5=B9=B6=20dashboard=20=E7=9B=B8=E5=85=B3=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

补充 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>
---
 .../boss-dashboard-development-guide.md       |  553 ++++++++
 .../crmeb-front-mysql-remote-connections.md   |   47 +
 docs/dashboard/dashboard-frontend-dev-spec.md | 1212 +++++++++++++++++
 ...shboard-frontend-technical-architecture.md |  751 ++++++++++
 4 files changed, 2563 insertions(+)
 create mode 100644 docs/dashboard/boss-dashboard-development-guide.md
 create mode 100644 docs/dashboard/crmeb-front-mysql-remote-connections.md
 create mode 100644 docs/dashboard/dashboard-frontend-dev-spec.md
 create mode 100644 docs/dashboard/dashboard-frontend-technical-architecture.md

diff --git a/docs/dashboard/boss-dashboard-development-guide.md b/docs/dashboard/boss-dashboard-development-guide.md
new file mode 100644
index 0000000..bf3198e
--- /dev/null
+++ 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 价值后再做。
diff --git a/docs/dashboard/crmeb-front-mysql-remote-connections.md b/docs/dashboard/crmeb-front-mysql-remote-connections.md
new file mode 100644
index 0000000..f7d67cc
--- /dev/null
+++ 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` |
+
+
+
+
diff --git a/docs/dashboard/dashboard-frontend-dev-spec.md b/docs/dashboard/dashboard-frontend-dev-spec.md
new file mode 100644
index 0000000..19eee42
--- /dev/null
+++ b/docs/dashboard/dashboard-frontend-dev-spec.md
@@ -0,0 +1,1212 @@
+# Dashboard 前端项目 Dev Spec
+
+基于以下文档整理：
+
+- `docs/dashboard/dashboard-frontend-technical-architecture.md`
+- `docs/dashboard/boss-dashboard-development-guide.md`
+
+本文档是独立 Dashboard 前端项目的详细开发说明，不依赖当前商城后台前端技术架构。开发团队应按本文档从 0 初始化一个新的前端项目，先完成可演示、可确认的 Mock 版老板驾驶舱，再接入后端真实接口。
+
+## 1. 项目目标
+
+建设一个独立的经营分析 Dashboard 前端项目，用于承载：
+
+- 老板驾驶舱首页
+- 昨日经营复盘
+- 今日 10:15 / 14:55 节点快报
+- 经营趋势分析
+- 用户、团队、商品排行
+- 风险预警中心
+- KPI 下钻与明细查看
+
+第一阶段目标不是做完整 BI 平台，而是快速交付一套老板能看、能确认、能下钻的经营驾驶舱前端。
+
+## 2. 技术栈定稿
+
+本项目采用以下技术栈：
+
+- 框架：`React 19`
+- 语言：`TypeScript`
+- 构建：`Vite`
+- 包管理：`pnpm`
+- 路由：`React Router`
+- UI：`Vant React` 或等价移动端组件库
+- 服务端状态：`TanStack Query`
+- 客户端状态：`Zustand`
+- 请求库：`Axios`
+- 图表：`Apache ECharts`
+- Mock：`MSW`
+- 单元测试：`Vitest`
+- 组件测试：`React Testing Library`
+- E2E：`Playwright`
+- 样式：`CSS Modules` + `CSS Variables`
+- 代码规范：`ESLint` + `Prettier`
+
+说明：
+
+- 第一版按 H5 移动端优先开发，默认目标设备是老板手机浏览器、企业微信内置浏览器和移动端 WebView。
+- 第一版不使用微前端。
+- 第一版不做低代码 BI 编辑器。
+- 第一版不做多租户 SaaS 架构。
+- 第一版不直接复用当前商城后台前端工程。
+- 第一版不采用 PC 后台表格密集型布局。
+
+## 3. 项目初始化规范
+
+### 3.1 项目名称
+
+建议项目目录：
+
+```text
+dashboard-frontend/
+```
+
+建议应用名：
+
+```text
+mall-ops-dashboard
+```
+
+### 3.2 Node 版本
+
+建议：
+
+```text
+Node.js >= 20
+pnpm >= 9
+```
+
+### 3.3 环境变量
+
+必须提供：
+
+```text
+VITE_APP_ENV=development
+VITE_API_BASE_URL=http://localhost:30032/api/admin
+VITE_MOCK_ENABLED=true
+VITE_APP_TITLE=经营驾驶舱
+VITE_BUILD_VERSION=local
+```
+
+环境文件：
+
+```text
+.env.local
+.env.development
+.env.staging
+.env.production
+```
+
+### 3.4 必备脚本
+
+`package.json` 至少提供：
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc -b --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:e2e": "playwright test"
+  }
+}
+```
+
+## 4. 目录结构规范
+
+最终目录建议：
+
+```text
+dashboard-frontend/
+  public/
+  src/
+    app/
+      App.tsx
+      main.tsx
+      providers/
+        AppProviders.tsx
+        QueryProvider.tsx
+        ThemeProvider.tsx
+      router/
+        routes.tsx
+        routeGuards.tsx
+      layouts/
+        BasicLayout.tsx
+        MobileLayout.tsx
+    assets/
+      images/
+      icons/
+    components/
+      common/
+      charts/
+      kpi/
+      table/
+      feedback/
+      layout/
+    features/
+      boss-dashboard/
+      daily-report/
+      today-snapshot/
+      risk-center/
+      data-drill/
+    services/
+      api/
+      http/
+      mock/
+      adapters/
+    stores/
+      appStore.ts
+      dashboardStore.ts
+      permissionStore.ts
+    hooks/
+    utils/
+    types/
+    styles/
+    tests/
+  .env.development
+  .env.production
+  package.json
+  vite.config.ts
+  tsconfig.json
+```
+
+## 5. 分层职责
+
+### 5.1 `app`
+
+负责应用级能力：
+
+- 应用入口
+- 全局 Provider
+- 路由注册
+- 布局
+- 权限守卫
+- 主题注入
+- 全局错误边界
+
+不得放具体业务逻辑。
+
+### 5.2 `features`
+
+负责业务模块。
+
+每个模块内部必须自包含：
+
+```text
+features/<feature-name>/
+  pages/
+  components/
+  hooks/
+  api.ts
+  types.ts
+  constants.ts
+  mock.ts
+```
+
+模块之间不能互相直接引用内部组件。如确有复用，应提升到 `components` 或 `services`。
+
+### 5.3 `components`
+
+负责跨业务模块复用组件。
+
+建议分类：
+
+- `common`：空态、加载态、错误态、页面标题
+- `charts`：通用图表封装
+- `kpi`：指标卡、指标组、环比同比
+- `table`：统一表格封装
+- `feedback`：风险标签、状态标签、异常提示
+- `layout`：页面区域、卡片网格、筛选栏
+
+### 5.4 `services`
+
+负责外部数据访问和数据适配。
+
+必须包含：
+
+- HTTP 客户端
+- API 方法
+- 请求拦截器
+- 响应解包
+- 错误处理
+- Mock handlers
+- DTO 到 ViewModel 的 adapter
+
+### 5.5 `stores`
+
+只存客户端状态，不存接口返回的大业务数据。
+
+可以存：
+
+- 当前主题
+- 菜单折叠状态
+- 当前公司
+- 当前 Dashboard 筛选条件
+- 当前今日快报版本
+- 用户偏好
+
+不应该存：
+
+- KPI 接口结果
+- 趋势图接口结果
+- 风险列表接口结果
+- 排行榜接口结果
+
+这些应由 `TanStack Query` 管理。
+
+## 6. 路由设计
+
+### 6.1 一级路由
+
+建议路由：
+
+```text
+/h5/dashboard
+/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
+/login
+/403
+/404
+```
+
+### 6.2 H5 导航结构
+
+第一版不使用 PC 侧边菜单，使用移动端底部 Tab + 页面内快捷入口。
+
+底部 Tab：
+
+```text
+首页
+日报
+快报
+风险
+我的
+```
+
+首页内快捷入口：
+
+```text
+用户排行
+团队排行
+商品排行
+资金池
+下钻明细
+导出/分享
+```
+
+### 6.3 路由参数规范
+
+Dashboard 页面筛选条件尽量进入 URL。
+
+示例：
+
+```text
+/h5/dashboard/boss?date=2026-05-10&range=yesterday&slot=1015
+/h5/dashboard/risk-center?level=red&type=fund
+/h5/dashboard/drill/user?uid=93231&from=risk-center
+```
+
+## 7. 页面开发规范
+
+### 7.1 老板驾驶舱页面
+
+路径：
+
+```text
+features/boss-dashboard/pages/BossDashboardPage.tsx
+```
+
+页面结构：
+
+```text
+BossDashboardPage
+  MobileStickyHeader
+  MobileDateFilterSheet
+  YesterdayOverviewSection
+  TodaySnapshotSection
+  TrendSection
+  RankSection
+  RiskAlertSection
+  BottomTabBar
+```
+
+### 7.2 首屏内容
+
+首屏必须优先展示：
+
+- 页面标题：经营驾驶舱
+- 当前数据口径：默认昨日
+- 今日快报入口：10:15 / 14:55
+- 昨日核心 KPI
+- 今日快报状态
+
+老板打开手机页面后，首屏不滚动也应看到昨日经营是否正常，以及今日 10:15 / 14:55 快报当前状态。
+
+### 7.3 KPI 区域
+
+第一版必须包含：
+
+- 昨日成交金额
+- 昨日订单数
+- 昨日采购用户数
+- 昨日新增用户数
+- 昨日新增寄售商品数
+- 昨日个人奖金发放
+- 昨日推广奖金发放
+- 昨日待支付 / 待结算金额
+
+资金池 KPI：
+
+- 余额总额
+- 优惠券总额
+- 个人奖金总额
+- 推广奖金总额
+- 积分总额
+- 待审核提现金额
+
+H5 展示规则：
+
+- 首屏只展示最核心 4 个 KPI：成交金额、订单数、采购用户数、新增用户。
+- 其余 KPI 收在“查看更多经营指标”折叠区。
+- 资金池 KPI 单独成组，默认折叠，避免手机首屏过长。
+- KPI 卡片采用双列小卡；金额类重点指标可跨两列展示。
+
+### 7.4 今日快报区域
+
+今日快报必须和昨日复盘视觉上区分。
+
+必须展示：
+
+- 快报版本：10:15 / 14:55
+- 快报状态：待生成 / 已生成 / 生成失败 / 临时数据
+- 生成时间
+- 累计采购用户数
+- 累计订单数
+- 累计成交金额
+- 累计支付金额
+- 新增寄售商品数
+- 个人奖金变化
+- 推广奖金变化
+- 团队 Top 10 简表
+
+未到生成时间时：
+
+```text
+10:15 快报待生成，预计 10:15 后可查看。
+```
+
+生成失败时：
+
+```text
+今日 10:15 快报生成失败，请查看最近一次成功快照或联系技术处理。
+```
+
+### 7.5 趋势区域
+
+第一版至少两个图：
+
+- 交易趋势：成交金额 + 订单数
+- 用户与奖金趋势：新增用户 + 奖金发放
+
+第二版扩展：
+
+- 采购用户趋势
+- 寄售商品趋势
+- 提现趋势
+- 风险数量趋势
+
+### 7.6 排行区域
+
+第一版三个榜单：
+
+- 高价值用户 Top 20
+- 团队贡献 Top 10
+- 高货值未成交商品 Top 20
+
+榜单必须支持点击下钻。
+
+H5 展示规则：
+
+- 排行榜默认每个榜单展示前 5 条。
+- 点击“查看全部”进入独立列表页。
+- 列表行高度不低于 48px，保证触控区域足够。
+
+### 7.7 风险预警区域
+
+第一版风险类型：
+
+- 资金异常
+- 订单异常
+- 商品异常
+- 用户异常
+- 数据质量异常
+
+风险等级：
+
+- 红色：当天必须处理
+- 黄色：需要关注
+- 灰色：数据质量或低优先级问题
+
+风险列表字段：
+
+- 风险等级
+- 风险类型
+- 风险标题
+- 风险描述
+- 关联对象
+- 发现时间
+- 操作按钮
+
+## 8. 组件开发规范
+
+### 8.1 KPI 组件
+
+组件路径：
+
+```text
+components/kpi/KpiCard.tsx
+components/kpi/KpiGrid.tsx
+```
+
+`KpiCard` 入参：
+
+```ts
+type KpiCardProps = {
+  title: string;
+  value: string | number;
+  unit?: string;
+  trendValue?: number;
+  trendLabel?: string;
+  status?: 'normal' | 'success' | 'warning' | 'danger';
+  loading?: boolean;
+  onClick?: () => void;
+};
+```
+
+显示规则：
+
+- `loading=true` 显示骨架屏。
+- `value=null` 或 `undefined` 显示 `--`。
+- `status=danger` 使用风险色。
+- 有 `onClick` 时鼠标悬浮显示可点击状态。
+
+### 8.2 今日快报组件
+
+组件路径：
+
+```text
+features/boss-dashboard/components/TodaySnapshotSection.tsx
+features/today-snapshot/components/SnapshotStatusTag.tsx
+```
+
+状态枚举：
+
+```ts
+type SnapshotStatus = 'pending' | 'success' | 'failed' | 'temporary';
+type SnapshotSlot = '1015' | '1455';
+```
+
+展示要求：
+
+- `pending`：显示预计生成时间。
+- `success`：显示生成时间和指标。
+- `failed`：显示错误摘要和最近一次成功快照入口。
+- `temporary`：显示“临时数据，不作为日报结论”。
+
+### 8.3 图表组件
+
+组件路径：
+
+```text
+components/charts/BaseChart.tsx
+components/charts/LineTrendChart.tsx
+components/charts/DualAxisChart.tsx
+components/charts/RankBarChart.tsx
+```
+
+所有图表必须支持：
+
+- loading
+- empty
+- error
+- resize
+- theme
+- fullscreen
+
+业务页面不得直接写复杂 ECharts option，应通过图表组件和 adapter 生成。
+
+### 8.4 风险标签组件
+
+组件路径：
+
+```text
+components/feedback/RiskLevelTag.tsx
+components/feedback/RiskTypeTag.tsx
+```
+
+颜色规范：
+
+- red：资金高危、当天必须处理
+- orange：业务波动，需要关注
+- gray：数据质量问题
+
+## 9. 类型定义规范
+
+### 9.1 全局基础类型
+
+路径：
+
+```text
+types/common.ts
+```
+
+建议定义：
+
+```ts
+type DateString = string;
+type DateTimeString = string;
+type MoneyString = string;
+type PercentString = string;
+
+type ApiResponse<T> = {
+  code: number;
+  message: string;
+  data: T;
+};
+```
+
+### 9.2 Dashboard 类型
+
+路径：
+
+```text
+features/boss-dashboard/types.ts
+```
+
+核心类型：
+
+```ts
+type DashboardOverview = {
+  date: DateString;
+  generatedAt: DateTimeString;
+  kpis: KpiMetric[];
+  fundPool: KpiMetric[];
+  todaySnapshots: TodaySnapshotSummary[];
+  trends: TrendPanelData[];
+  ranks: RankPanelData[];
+  risks: RiskAlert[];
+};
+
+type KpiMetric = {
+  key: string;
+  title: string;
+  value: number | string | null;
+  unit?: string;
+  trendValue?: number;
+  trendLabel?: string;
+  status: 'normal' | 'success' | 'warning' | 'danger';
+  drill?: DrillLink;
+};
+
+type DrillLink = {
+  path: string;
+  query?: Record<string, string | number>;
+};
+```
+
+## 10. API 开发规范
+
+### 10.1 API 文件
+
+建议：
+
+```text
+services/http/client.ts
+services/http/error.ts
+services/api/dashboard.ts
+features/boss-dashboard/api.ts
+features/risk-center/api.ts
+```
+
+### 10.2 接口列表
+
+第一版前端按以下接口契约开发：
+
+```text
+GET /dashboard/overview?date=YYYY-MM-DD
+GET /dashboard/today-snapshot?date=YYYY-MM-DD&slot=1015|1455
+GET /dashboard/trends?range=7|30
+GET /dashboard/ranks?date=YYYY-MM-DD&type=user|team|product
+GET /dashboard/risks?date=YYYY-MM-DD&level=red|yellow|gray
+GET /dashboard/drill-options
+```
+
+### 10.3 请求封装要求
+
+HTTP Client 必须处理：
+
+- baseURL
+- token
+- timeout
+- requestId
+- 401 跳登录
+- 403 跳无权限页
+- 500 统一提示
+- 网络异常提示
+- 响应解包
+
+### 10.4 Adapter 要求
+
+后端 DTO 不直接进入组件。
+
+必须经过：
+
+```text
+API Response -> DTO -> Adapter -> ViewModel -> Component
+```
+
+Adapter 必须处理：
+
+- 空值兜底
+- 金额格式化前的数值规范化
+- 日期字符串规范化
+- 枚举转换
+- 风险等级映射
+- drill link 生成
+
+## 11. Mock 开发规范
+
+### 11.1 Mock 工具
+
+使用 `MSW`。
+
+目录：
+
+```text
+services/mock/
+  browser.ts
+  handlers.ts
+  data/
+    dashboard.ts
+    risks.ts
+    ranks.ts
+```
+
+### 11.2 Mock 启用规则
+
+环境变量：
+
+```text
+VITE_MOCK_ENABLED=true
+```
+
+当开启 Mock：
+
+- 浏览器请求由 MSW 拦截。
+- API 方法不需要改。
+- 页面表现应与真实 API 一致。
+
+### 11.3 必备 Mock 场景
+
+必须提供：
+
+- 昨日经营正常
+- 昨日经营明显下滑
+- 今日 10:15 已生成
+- 今日 14:55 待生成
+- 今日快报生成失败
+- 今日临时数据
+- 风险列表为空
+- 风险列表包含红黄灰
+- 趋势图空数据
+- 某个接口 500
+- 某个接口超时
+
+## 12. 状态管理规范
+
+### 12.1 Query Key
+
+统一管理 Query Key：
+
+```text
+services/api/queryKeys.ts
+```
+
+命名示例：
+
+```ts
+dashboardKeys.overview(date)
+dashboardKeys.todaySnapshot(date, slot)
+dashboardKeys.trends(range)
+dashboardKeys.ranks(date, type)
+dashboardKeys.risks(filters)
+```
+
+### 12.2 自动刷新
+
+刷新策略：
+
+- 昨日 overview：不自动刷新。
+- 今日 10:15 / 14:55 快报：到达节点后刷新一次。
+- 临时实时查看：可 60 秒刷新一次。
+- 风险预警：可 1 到 5 分钟刷新一次。
+- 页面不可见时暂停刷新。
+
+### 12.3 Zustand Store
+
+建议：
+
+```text
+stores/dashboardStore.ts
+```
+
+状态：
+
+- selectedDate
+- selectedRange
+- selectedSnapshotSlot
+- isFullscreen
+- riskFilterDraft
+
+注意：
+
+- Store 只放 UI 状态。
+- 接口数据不进 Store。
+
+## 13. 样式与视觉规范
+
+### 13.1 主题
+
+支持：
+
+- 默认浅色主题
+- 深色移动端主题
+
+第一版可先实现浅色主题，但 CSS Variables 需要预留深色主题变量。
+
+### 13.2 布局
+
+建议：
+
+- 页面按移动端 H5 优先设计，核心适配宽度为 360px、375px、390px、414px。
+- 在 PC 浏览器打开时，内容区最大宽度建议限制为 430px 并居中，模拟手机页面。
+- 页面采用单列信息流布局。
+- KPI 使用 2 列卡片网格，重点金额卡片可跨 2 列。
+- 图表区域单列展示，每个图表高度建议 220px 到 280px。
+- 底部固定 TabBar，高度纳入安全区计算。
+- 顶部筛选可用吸顶 Header + 弹出式筛选面板，不使用 PC 横向筛选表单。
+
+### 13.2.1 H5 适配要求
+
+- 使用 `viewport-fit=cover`，适配 iPhone 安全区。
+- 底部操作区必须增加 `safe-area-inset-bottom`。
+- 点击热区不小于 44px。
+- 页面横向不得出现滚动条。
+- 长数字允许缩小字号或换行，但不得溢出卡片。
+- 图表 tooltip 必须适合触摸，不依赖鼠标 hover。
+- 重要筛选项使用弹层、分段控件或底部 ActionSheet。
+
+### 13.3 数字格式
+
+金额：
+
+```text
+¥1,234,567.89
+```
+
+积分：
+
+```text
+1,234,567.000
+```
+
+比例：
+
+```text
+12.34%
+```
+
+缺失值：
+
+```text
+--
+```
+
+### 13.4 状态颜色
+
+建议：
+
+- 正常：参考图中的活力橙/珊瑚橙主色或默认色
+- 增长：绿色
+- 下降：活力橙或警示橙
+- 高危：红色
+- 待生成：灰色
+- 失败：红色
+
+## 14. 权限规范
+
+### 14.1 角色
+
+第一版建议角色：
+
+- `boss`：老板，查看全部经营数据。
+- `manager`：经营管理人员，可查看大部分数据。
+- `operator`：运营人员，可查看非敏感数据。
+- `readonly`：只读角色。
+
+### 14.2 权限点
+
+建议：
+
+```text
+dashboard:view
+dashboard:fund:view
+dashboard:risk:view
+dashboard:export
+dashboard:drill
+```
+
+### 14.3 前端权限处理
+
+- 无页面权限：跳转 403。
+- 无模块权限：模块显示无权限状态。
+- 无字段权限：金额或手机号脱敏。
+- 无导出权限：隐藏导出按钮。
+
+## 15. 下钻规范
+
+### 15.1 下钻入口
+
+必须支持：
+
+- KPI 卡片点击下钻
+- 图表点位点击下钻
+- 排行榜行点击下钻
+- 风险项点击下钻
+
+### 15.2 下钻上下文
+
+跳转时携带：
+
+- 来源页面
+- 日期范围
+- 指标 key
+- 关联对象 ID
+- 风险 ID
+
+示例：
+
+```text
+/dashboard/drill/user?uid=93231&from=boss-dashboard&metric=highValueUser
+```
+
+### 15.3 返回逻辑
+
+从下钻页返回驾驶舱时：
+
+- 保留日期范围
+- 保留快报版本
+- 保留滚动位置可选
+
+## 16. 错误与空态规范
+
+### 16.1 页面级错误
+
+整个页面关键接口失败时显示页面级错误。
+
+需要包含：
+
+- 错误标题
+- 错误描述
+- 重试按钮
+- 返回首页按钮
+
+### 16.2 区块级错误
+
+某个模块失败时，只影响该模块。
+
+例如：
+
+- 趋势图失败，不影响 KPI。
+- 风险列表失败，不影响今日快报。
+
+### 16.3 空态
+
+空态文案示例：
+
+```text
+暂无风险预警
+暂无今日快报数据
+暂无符合条件的排行数据
+```
+
+## 17. 性能规范
+
+### 17.1 首屏
+
+要求：
+
+- 首屏优先加载 KPI 和今日快报。
+- 排行榜和风险列表可延迟加载。
+- 图表组件懒加载。
+
+### 17.2 数据请求
+
+要求：
+
+- 并行请求互不依赖模块。
+- 同一 Query Key 请求去重。
+- 重试次数不超过 2 次。
+- 今日实时临时查看才允许定时刷新。
+
+### 17.3 图表性能
+
+要求：
+
+- 图表组件卸载时销毁实例。
+- 窗口变化时节流 resize。
+- 大数据量趋势图做采样或限制时间范围。
+
+## 18. 测试规范
+
+### 18.1 单元测试
+
+必须覆盖：
+
+- 金额格式化
+- 日期范围计算
+- 风险等级映射
+- DTO 到 ViewModel adapter
+- Query Key 生成
+
+### 18.2 组件测试
+
+必须覆盖：
+
+- KPI 卡 loading、empty、normal、danger 状态。
+- 今日快报 pending、success、failed、temporary 状态。
+- 风险列表空态和多级风险展示。
+- 图表 empty 和 error 状态。
+
+### 18.3 E2E 测试
+
+必须覆盖：
+
+- 使用移动端 viewport 打开老板驾驶舱，默认展示昨日。
+- 切换 10:15 快报。
+- 切换 14:55 快报。
+- 点击 KPI 下钻。
+- 点击风险项进入下钻页。
+- 接口失败时页面不白屏。
+- 底部 Tab 能正常切换。
+- 筛选弹层能正常打开、选择和关闭。
+
+## 19. 开发阶段拆分
+
+### Phase 1：项目脚手架
+
+交付：
+
+- Vite + React + TypeScript 项目
+- 路由
+- H5 Layout
+- 移动端 UI 组件库
+- Query Provider
+- Zustand Store
+- MSW Mock
+- ESLint / Prettier / Vitest
+
+验收：
+
+- 本地可启动。
+- 页面可访问。
+- Mock 请求可返回数据。
+
+### Phase 2：老板驾驶舱 Mock 页面
+
+交付：
+
+- 老板驾驶舱页面
+- KPI 卡片
+- 今日快报
+- 趋势图
+- 排行榜
+- 风险预警
+- 下钻按钮
+- 底部 TabBar
+- 移动端筛选弹层
+
+验收：
+
+- 不依赖后端即可完整展示页面。
+- 四种快报状态可切换验证。
+- 风险红黄灰状态可展示。
+- 375px 手机宽度下无横向滚动。
+
+### Phase 3：接口契约与 API 层
+
+交付：
+
+- API 方法
+- Query Hooks
+- Adapter
+- TypeScript 类型
+- Mock 与真实 API 可切换
+
+验收：
+
+- 页面组件不直接依赖后端 DTO。
+- 替换真实 API 时页面改动最小。
+
+### Phase 4：真实联调
+
+交付：
+
+- 接入真实后端接口。
+- 对账关键指标。
+- 完成下钻链路。
+- 完成权限控制。
+
+验收：
+
+- 昨日经营数据与后端口径一致。
+- 今日快报数据与节点口径一致。
+- 核心 KPI 可下钻。
+
+### Phase 5：上线增强
+
+交付：
+
+- 错误监控
+- 性能优化
+- 导出能力
+- 深色主题
+- E2E 测试
+
+验收：
+
+- 生产可部署。
+- 关键路径测试通过。
+- 异常场景不白屏。
+
+## 20. 前端验收清单
+
+### 页面验收
+
+- 老板驾驶舱默认展示昨日经营复盘。
+- 今日 10:15 / 14:55 快报入口清晰。
+- 未到时间显示待生成。
+- 生成失败显示失败状态。
+- 临时数据有明确提示。
+- KPI、趋势、排行、风险布局清晰。
+- 手机首屏能看见核心经营结果。
+- 底部 TabBar 和筛选弹层交互顺畅。
+
+### 数据验收
+
+- Mock 数据覆盖全部状态。
+- 金额格式统一。
+- 日期格式统一。
+- 空值显示 `--`。
+- 接口失败有降级展示。
+
+### 交互验收
+
+- 日期范围可切换。
+- 快报版本可切换。
+- KPI 可点击。
+- 风险项可点击。
+- 下钻后可返回。
+
+### 工程验收
+
+- TypeScript 无类型错误。
+- Lint 通过。
+- 单元测试通过。
+- 组件测试覆盖关键状态。
+- 生产构建成功。
+
+## 21. 与后端协作边界
+
+前端负责：
+
+- 页面展示
+- 交互状态
+- Mock 数据
+- 接口调用
+- 数据适配
+- 图表渲染
+- 下钻跳转
+
+后端负责：
+
+- 指标口径
+- SQL 聚合
+- 快照生成
+- 风险规则
+- 权限数据
+- 导出数据
+
+前端不得在页面中自行计算复杂资金口径，例如个人奖金、推广奖金、积分健康检查等核心经营指标。前端只做展示和简单格式化。
+
+## 22. 第一版不做
+
+- 不做拖拽搭建大屏。
+- 不做用户自定义图表。
+- 不做复杂多租户。
+- 不做 PC 版完整后台。
+- 不做所有历史明细管理功能。
+- 不在前端硬编码真实敏感数据。
+- 不把后端财务口径搬到前端计算。
+
+## 23. 交付物
+
+第一版前端应交付：
+
+- 独立 Dashboard 前端项目
+- 老板驾驶舱 Mock 页面
+- Mock 数据集
+- API 契约类型
+- 通用 KPI 组件
+- 通用图表组件
+- 今日快报组件
+- 风险预警组件
+- 下钻页面基础框架
+- 基础测试
+- 构建部署说明
+
+## 24. 推荐开发顺序
+
+1. 初始化项目和工程规范。
+2. 搭建 Layout、路由、主题和 Provider。
+3. 接入 MSW，准备 Dashboard Mock 数据。
+4. 开发移动端底部 Tab、吸顶 Header、筛选弹层。
+5. 开发 KPI、快报、图表、排行、风险基础组件。
+6. 组装老板驾驶舱 H5 页面。
+7. 做空态、错误态、loading 态。
+8. 做下钻路由和跳转参数。
+9. 给老板用手机确认页面展示。
+10. 冻结接口字段。
+11. 接真实 API 并联调。
+
+## 25. 最终要求
+
+第一版成功标准：
+
+- 老板能在一个页面看懂昨日经营是否正常。
+- 老板能在 10:15 和 14:55 后看到今日节点快报。
+- 老板能在手机 H5 页面顺畅查看核心指标、排行和风险。
+- 页面在无后端情况下也能通过 Mock 完整演示。
+- 后端接口上线后，前端只替换数据源，不大改页面。
+- 核心 KPI、排行和风险项都具备下钻能力。
diff --git a/docs/dashboard/dashboard-frontend-technical-architecture.md b/docs/dashboard/dashboard-frontend-technical-architecture.md
new file mode 100644
index 0000000..2ce5910
--- /dev/null
+++ 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。确认后再接真实接口和快照数据，避免后端先做大量数据聚合后发现展示口径需要重改。