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