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

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