integral-shop/docs/dashboard/dashboard-frontend-dev-spec.md

# 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、排行和风险项都具备下钻能力。