integral-shop/docs/dashboard/dashboard-frontend-technical-architecture.md

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. 总体架构

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. 项目目录设计

建议目录：

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：用户、订单、商品、团队等下钻页

每个模块内部建议结构：

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 节点快报。
• 展示趋势图、排行榜、风险预警。
• 提供下钻入口。

页面结构：

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 数据流示意

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

业务页面只传入标准数据：

{
  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。确认后再接真实接口和快照数据，避免后端先做大量数据聚合后发现展示口径需要重改。