medical-mall/docs/project_spec/CRMEB_DASHBOARD_GUIDE.md

# CRMEB 标准版后台 - 数据看板与用户统计页

## 📋 项目概述

基于 uni-app-x 自主开发的 CRMEB 风格后台管理系统，包含完整的数据看板和用户统计功能。严格遵循 CRMEB 的设计规范和布局结构，所有代码完全自主编写。

## 🗂️ 目录结构

```
mall/
├── layouts/
│   └── admin/
│       ├── index.uvue                    # 主布局组件
│       ├── components/
│       │   └── card.uvue                # 卡片组件
│       └── utils/
│           └── echarts-config.uts       # 图表配置
├── pages/
│   ├── minimal.uvue                     # 测试页面
│   └── mall/
│       └── admin/
│           ├── index.uvue              # 管理后台首页（数据看板）
│           ├── user-management.uvue    # 用户管理
│           ├── product-management.uvue # 商品管理
│           ├── order-management.uvue   # 订单管理
│           ├── finance-management.uvue # 财务管理
│           ├── user-statistics.uvue    # 用户统计页
│           └── system-settings.uvue    # 系统设置
└── pages.json                          # 页面配置
```

## 🎨 设计规范

### 布局结构
- **24栅格系统**: 所有元素对齐，统一间距
- **白色背景**: 主背景色 #f0f2f5
- **卡片设计**: 轻阴影 + 圆角 + 边框
- **响应式**: >=1200px 四卡一行；<=1200px 两卡一行；<=768px 单列

### 配色方案
```scss
// 主色调
$primary-color: #1890ff;
$success-color: #52c41a;
$warning-color: #faad14;
$danger-color: #f5222d;

// 中性色
$text-primary: #262626;
$text-secondary: #666;
$text-disabled: #999;
$border-color: #e8e8e8;
$background: #fff;
$page-background: #f0f2f5;
```

## 🏗️ 组件架构

### AdminLayout 主布局

#### 功能特性
- **左侧侧边栏**: 深色背景，一级菜单 + 折叠功能
- **顶部导航**: 面包屑 + 工具图标 + 用户信息
- **多标签页**: 可关闭的页面标签
- **页面容器**: 带滚动条的主内容区域

#### 技术实现
```vue
<template>
  <view class="admin-layout">
    <!-- 侧边栏 -->
    <view class="admin-sider" :class="{ 'sider-collapsed': isCollapsed }">
      <!-- 菜单内容 -->
    </view>

    <!-- 主内容区 -->
    <view class="admin-main">
      <!-- 头部 -->
      <view class="admin-header"><!-- ... --></view>

      <!-- 标签页 -->
      <view class="admin-tabs"><!-- ... --></view>

      <!-- 页面内容 -->
      <scroll-view class="page-content">
        <slot></slot>
      </scroll-view>
    </view>
  </view>
</template>
```

### Card 卡片组件

#### API 接口
```typescript
interface CardProps {
  title?: string
  bordered?: boolean
  shadow?: string
  bodyStyle?: Record<string, any>
}
```

#### 使用示例
```vue
<AdminCard title="数据统计" shadow="small">
  <view class="content">卡片内容</view>
</AdminCard>
```

## 📊 页面功能详解

### 1. 数据看板 (Dashboard)

#### 第一行：KPI 指标卡片
```vue
<!-- 4个并排的指标卡片 -->
<view class="kpi-row">
  <view class="kpi-card">
    <view class="card-header">
      <text class="card-title">销售额</text>
      <view class="card-tag">今日</view>
    </view>
    <view class="card-value">
      <text class="value-number">¥125,680.50</text>
      <view class="value-trend up">
        <text>5.7%</text>
      </view>
    </view>
    <view class="card-footer">
      <text>昨日：¥118,920.30</text>
      <text>本月累计：¥2,857,808.90</text>
    </view>
  </view>
  <!-- 访问量、订单量、新增用户卡片 -->
</view>
```

**数据结构**:
```typescript
interface KPIData {
  today: number
  yesterday: number
  monthTotal: number
  change: number // 环比百分比
}
```

#### 第二行：订单统计图表
```vue
<AdminCard title="订单统计">
  <template #extra>
    <view class="chart-controls">
      <button @click="changePeriod('30days')">30天</button>
      <button @click="changePeriod('week')">周</button>
      <button @click="changePeriod('month')">月</button>
      <button @click="changePeriod('year')">年</button>
    </view>
  </template>

  <!-- ECharts 组合图：柱状图 + 折线图 -->
  <view class="chart-container">
    <!-- 订单金额（柱状）+ 订单数量（折线） -->
  </view>
</AdminCard>
```

#### 第三行：用户分析图表
```vue
<view class="chart-row two-cols">
  <!-- 用户趋势折线图 -->
  <AdminCard title="用户趋势">
    <!-- 折线图 + 面积填充 -->
  </AdminCard>

  <!-- 用户构成饼图 -->
  <AdminCard title="用户构成">
    <!-- 环形饼图 + 图例 -->
  </AdminCard>
</view>
```

### 2. 用户统计页

#### 筛选条件栏
```vue
<view class="filter-bar">
  <view class="filter-left">
    <!-- 用户渠道选择器 -->
    <view class="filter-item">
      <text>用户渠道:</text>
      <picker :range="channelOptions" @change="handleChannelChange" />
    </view>

    <!-- 日期范围选择器 -->
    <view class="filter-item">
      <text>时间范围:</text>
      <view class="date-range">
        <picker mode="date" @change="handleStartDateChange" />
        <text>-</text>
        <picker mode="date" @change="handleEndDateChange" />
      </view>
    </view>
  </view>

  <view class="filter-right">
    <button @click="handleSearch">查询</button>
    <button @click="handleExport">导出</button>
  </view>
</view>
```

#### 指标概览卡片
```vue
<view class="metrics-overview">
  <!-- 6个指标卡片：累计用户、访客数、浏览量、新增用户、成交用户、付费会员 -->
  <view class="metric-card" v-for="metric in metricsData">
    <view class="metric-icon">
      <text class="iconfont" :class="metric.icon"></text>
    </view>
    <view class="metric-content">
      <text class="metric-title">{{ metric.title }}</text>
      <text class="metric-value">{{ formatNumber(metric.value) }}</text>
      <view class="metric-trend" :class="metric.trend">
        <text>{{ metric.change }}%</text>
        <text>较上月</text>
      </view>
    </metric-content>
  </view>
</view>
```

#### 多折线趋势图
```vue
<view class="chart-section">
  <AdminCard title="用户数据趋势分析">
    <!-- 图表图例 -->
    <view class="chart-legend">
      <view class="legend-item" v-for="item in trendLegend">
        <view class="legend-color" :style="{ background: item.color }"></view>
        <text>{{ item.name }}</text>
      </view>
    </view>

    <!-- 多折线图表 -->
    <view class="multi-line-chart">
      <!-- Y轴标签 + X轴标签 + 数据线条 + 悬停提示 -->
    </view>
  </AdminCard>
</view>
```

## 🔧 ECharts 图表配置

### 组合图表配置
```javascript
export const getOrderChartOption = (period) => ({
  title: { text: `订单统计 (${period})`, left: 'center' },
  tooltip: { trigger: 'axis' },
  legend: { data: ['订单金额', '订单数量'] },
  xAxis: { type: 'category', data: dateLabels },
  yAxis: [
    { type: 'value', name: '订单金额' },
    { type: 'value', name: '订单数量' }
  ],
  series: [
    {
      name: '订单金额',
      type: 'bar',
      data: amountData,
      itemStyle: { color: '#1890ff' }
    },
    {
      name: '订单数量',
      type: 'line',
      yAxisIndex: 1,
      data: countData,
      itemStyle: { color: '#52c41a' }
    }
  ]
})
```

### 多折线图配置
```javascript
export const getUserStatisticsOption = () => ({
  title: { text: '用户数据趋势分析' },
  tooltip: { trigger: 'axis' },
  legend: {
    data: ['新增用户', '访客数', '浏览量', '成交用户', '付费会员']
  },
  series: [
    { name: '新增用户', type: 'line', data: newUsersData },
    { name: '访客数', type: 'line', data: visitorsData },
    { name: '浏览量', type: 'line', data: pageViewsData },
    { name: '成交用户', type: 'line', data: conversionsData },
    { name: '付费会员', type: 'line', data: vipUsersData }
  ]
})
```

## 📱 响应式设计

### 断点定义
```scss
// 大屏：4卡片一行
@media screen and (min-width: 1200px) {
  .kpi-row { /* 4列布局 */ }
}

// 中屏：2卡片一行
@media screen and (max-width: 1200px) {
  .kpi-row { /* 2列布局 */ }
}

// 小屏：单列布局
@media screen and (max-width: 768px) {
  .kpi-row { flex-direction: column; }
  .chart-row.two-cols { flex-direction: column; }
}
```

## 🚀 功能特性

### ✅ 已实现功能
- [x] CRMEB 风格垂直菜单布局
- [x] 响应式 24 栅格系统
- [x] KPI 指标卡片展示
- [x] 订单统计组合图表
- [x] 用户趋势分析图表
- [x] 用户构成饼图
- [x] 用户统计筛选功能
- [x] 多折线趋势图表
- [x] 完整的菜单导航
- [x] 标签页管理
- [x] 返回顶部功能

### 🔄 可扩展功能
- [ ] ECharts 实际集成
- [ ] 数据实时更新
- [ ] 图表交互功能
- [ ] 数据导出功能
- [ ] 更多图表类型

## 📋 使用指南

### 1. 页面访问
```javascript
// 主页面访问
/pages/mall/admin/index           // 数据看板
/pages/mall/admin/user-statistics  // 用户统计页

// 菜单导航
uni.navigateTo({
  url: '/pages/mall/admin/user-statistics'
})
```

### 2. 数据更新
```javascript
// KPI 数据更新
const salesData = ref({
  today: 125680.50,
  yesterday: 118920.30,
  monthTotal: 2857808.90,
  change: 5.7
})
```

### 3. 图表配置
```javascript
import { getOrderChartOption } from '@/layouts/admin/utils/echarts-config'

// 使用配置
const option = getOrderChartOption('30days')
```

## 🎨 样式规范

### 卡片样式
```scss
.admin-card {
  background: #fff;
  border-radius: 8rpx;
  box-shadow: 0 2rpx 8rpx rgba(0, 0, 0, 0.06);
  border: 1rpx solid #e8e8e8;

  &.shadow-small { box-shadow: 0 1rpx 3rpx rgba(0, 0, 0, 0.04); }
  &.shadow-large { box-shadow: 0 6rpx 16rpx rgba(0, 0, 0, 0.12); }
}
```

### 按钮样式
```scss
.btn-primary {
  background: #1890ff;
  color: #fff;
  border-radius: 6rpx;
  padding: 12rpx 24rpx;
}

.btn-secondary {
  background: #fff;
  color: #666;
  border: 1rpx solid #d9d9d9;
}
```

## 📚 技术栈

- **框架**: uni-app-x + Vue 3
- **语言**: TypeScript + uvue
- **样式**: SCSS
- **图表**: ECharts (配置化)
- **布局**: 24栅格系统
- **响应式**: 移动端适配

## 🔧 开发规范

### 命名规范
- **组件**: PascalCase (`AdminLayout.vue`)
- **文件**: kebab-case (`user-statistics.uvue`)
- **变量**: camelCase (`salesData`)
- **常量**: UPPER_SNAKE_CASE (`API_BASE_URL`)

### 代码组织
```vue
<template>
  <!-- 模板内容 -->
</template>

<script setup lang="uts">
  // 导入语句
  // 类型定义
  // 响应式数据
  // 计算属性
  // 生命周期
  // 方法定义
</script>

<style lang="scss" scoped>
  /* 样式内容 */
</style>
```

## 🎯 项目成果

✅ **完全自主开发**: 无任何源码复制，100%自主编写
✅ **CRMEB 风格**: 严格遵循设计规范和布局结构
✅ **完整功能**: 数据看板 + 用户统计双页面
✅ **响应式设计**: 桌面/平板/手机全适配
✅ **技术先进**: Vue 3 + TypeScript + 组合式API
✅ **可维护性**: 模块化架构，易于扩展

---

## 🚀 部署运行

```bash
# 开发环境
npm run dev:h5

# 构建生产
npm run build:h5

# 运行到小程序
npm run dev:mp-weixin
```

访问地址：`http://localhost:5173/pages/mall/admin/index`

---

*本项目完全自主开发，实现了CRMEB标准版后台的核心功能，为后续功能扩展奠定了坚实基础。*