---
url: /blog/pfelrb1e/index.md
---
# Template2 数据看板开发规范

## 概述

本文档规定了 ShopXO 系统 databoard 插件中 Template2 数据看板的功能说明、技术架构、数据指标和开发规范，供开发人员参考。

## 功能说明

Template2 数据看板是一个全面展示电商核心运营数据的可视化大屏，支持实时数据刷新、自定义时间范围、多维度对比分析。

### 核心特性

* **17个KPI指标卡片** - 涵盖销售、订单、退款等核心数据
* **全链路转化漏斗** - 5阶段转化分析
* **7个侧栏指标** - AOV、复购率、连带率等关键指标
* **3个排行榜** - 热卖商品、加购排行、地区排行
* **多维度对比** - 支持日环比/月环比对比
* **时区支持** - 时区偏移，正确处理跨时区数据
* **自动刷新** - 可配置自动刷新间隔

## 技术架构

```
插件目录：app/plugins/databoard/
├── admin/
│   └── Template2.php           # 后台控制器
├── service/
│   └── StatsTemplate2Service.php # 统计服务层
└── view/
    └── admin/
        └── template2/
            └── index.html      # 看板视图

数据来源：
├── sxo_order              # 订单表
├── sxo_order_detail       # 订单详情表
├── sxo_order_address      # 订单地址表
├── sxo_order_aftersale    # 售后表
├── sxo_cart               # 购物车表
├── sxo_goods_browse       # 商品浏览表
└── sxo_payment            # 支付方式表
```

## 数据指标详解

### 1. KPI概览 (17张卡片)

| 指标 | 说明 | 数据来源 | 趋势样式 |
|------|------|---------|----------|
| `total_sales_with_cancel` | 下单总额（含取消、折扣前） | order.price | 正常 |
| `total_sales_before_discount` | 成交总额（折扣前） | order.price | 正常 |
| `total_sales_without_cancel` | 成交总额（折扣后） | order.total\_price | 正常 |
| `collect_order_count` | 揽收订单数 | -- | 待实现 |
| `collect_goods_total` | 揽收订单商品总额 | -- | 待实现 |
| `collect_shipping_fee` | 揽收的订单运费 | -- | 待实现 |
| `signed_order_count` | 签收订单数 | order.collect\_time | 正常 |
| `refuse_order_count` | 拒收订单数 | order.upd\_time | 警告 |
| `operation_cost` | 运费/加价总计 | order.increase\_price | 正常 |
| `valid_order_count` | 有效订单数 | order.status in \[2,3,4] | 正常 |
| `cancel_order_count` | 取消订单数 | order.cancel\_time | 警告 |
| `refund_total` | 退款总额 | aftersale.price | 警告 |
| `visit_uv` | 访问UV | 统计得出 | 高亮 |
| `warning_order_count` | 异常订单数 | 订单详情购买数>5 | 警告 |
| `presell_rate_count` | 预售占比 | goods.sales\_type=1 | 正常 |
| `spot_rate_count` | 现货占比 | goods.sales\_type=2 | 正常 |
| `clearance_rate_count` | 清仓占比 | goods.sales\_type=3 | 正常 |

**订单状态说明**:

* `status = 1`: 待付款
* `status = 2`: 待发货
* `status = 3`: 待收货
* `status = 4`: 已完成
* `status = 5`: 已取消
* `status = 7`: 退件中
* `status = 8`: 已退件

### 2. 转化漏斗 (5阶段)

| 阶段 | 说明 | 数据来源 |
|------|------|---------|
| 访问商店 | 浏览+加购+下单用户去重 | goods\_browse + cart + order |
| 加入购物车 | 加购用户数 | cart.user\_id 去重 |
| 发起结账 | 填写地址用户数 | order\_address.user\_id 去重 |
| 填写收货地址 | 有地址的用户数 | order\_address.user\_id 去重 |
| 下单用户数 | 有效订单用户数 | order.user\_id 去重 |

**转化率计算**:

* 占比: 当前阶段数 / 访问商店数
* 转化率: 当前阶段数 / 上一阶段数
* 全店转化率: 下单用户数 / 访问商店数

### 3. 侧栏指标 (7张卡片)

| 指标 | 说明 | 计算公式 | 警告 |
|------|------|---------|------|
| `aov` | 订单均价 | 总销售额 / 订单数 | 否 |
| `repurchase_rate` | COD复购率 | 复购用户数 / 购买用户数 | 否 |
| `discount_rate` | 平均补贴率 | 优惠金额 / 订单金额 | 否 |
| `commission_rate` | 平均佣金率 | -- (待实现) | 否 |
| `attach_rate` | 平均连带率 | 商品总数 / 订单数 | 否 |
| `cancel_rate` | 整体取消率 | 取消订单数 / 总订单数 | 是 |
| `core_refuse_rate` | 核心拒收率 | 拒收订单数 / 已发货订单数 | 是 |

### 4. 排行榜 (3个)

#### 热卖商品排行

**字段**: 商品名称、销量、销售额
**排序**: 按销量降序
**限制**: 前10名

#### 商品加购排行

**字段**: 商品名称、加购人数、加购率
**排序**: 按加购人数降序
**限制**: 前10名

#### 地区购买排行

**字段**: 地区名称、下单人数、客单价
**排序**: 按下单人数降序
**限制**: 前10名

## 时间处理逻辑

### 时区偏移 (tz\_offset)

```php
// 前端传递的时区偏移（分钟）
// 例如：UTC+8 = -480 分钟
$tz_offset = -480;

// 将本地日期转换为UTC时间戳
$utc_timestamp = self::DateToUtcTimestamp($date, $time, $tz_offset);
```

### 对比周期计算

#### 日环比 (period\_type = day)

```
当前范围: 2026-01-15 00:00:00 ~ 2026-01-15 23:59:59
上期范围: 2026-01-14 00:00:00 ~ 2026-01-14 23:59:59
```

#### 月环比 (period\_type = month)

**整月对比**:

```
当前范围: 2026-01-01 00:00:00 ~ 2026-01-31 23:59:59
上期范围: 2025-12-01 00:00:00 ~ 2025-12-31 23:59:59
```

**部分月份对比**:

```
当前范围: 2026-01-15 00:00:00 ~ 2026-01-20 23:59:59
上期范围: 2025-12-15 00:00:00 ~ 2025-12-20 23:59:59
```

**特殊处理**: 如果上月天数较少（如1月31日对比2月），自动调整为上月最后一天。

### 统计时间字段说明

| 指标 | 时间字段 | 说明 |
|------|---------|------|
| 下单总额 | add\_time | 按下单时间统计 |
| 签收订单数 | collect\_time | 按签收时间统计 |
| 拒收订单数 | upd\_time | 按更新时间（拒收时间）统计 |
| 取消订单数 | cancel\_time | 按取消时间统计 |
| 退款总额 | audit\_time | 按售后审核完成时间统计 |

## Service 层方法

### StatsTemplate2Service::KpiOverview()

获取KPI概览数据（17张卡片）。

**参数**: `$params` (包含时间范围、时区偏移、周期类型等)
**返回**: 关联数组，包含各指标值和趋势数据

### StatsTemplate2Service::ConversionFunnel()

获取转化漏斗数据（5阶段）。

**返回**:

```php
[
    'stages' => [
        ['stage' => '访问商店', 'count' => '1000', 'rate' => '100%', 'conversion' => '-'],
        ['stage' => '加入购物车', 'count' => '300', 'rate' => '30%', 'conversion' => '30%'],
        // ...
    ],
    'overall_conversion' => '5.5%', // 全店最终转化率
]
```

### StatsTemplate2Service::SideMetrics()

获取侧栏指标数据（7张卡片）。

**参数**: `$params`
**返回**: 关联数组，包含各指标值和趋势数据

### StatsTemplate2Service::HotGoodsRanking()

获取热卖商品排行。

**返回**:

```php
[
    'columns' => ['商品名称', '销量', '销售额'],
    'data' => [
        ['goods_id' => 1, 'goods_title' => '商品A', 'sales_count' => 100, 'sales_amount' => 1000],
        // ...
    ],
]
```

### StatsTemplate2Service::CartAddRanking()

获取商品加购排行。

**返回**:

```php
[
    'columns' => ['商品名称', '加购人数', '加购率'],
    'data' => [...],
    'metric_chip' => '按独立访客(UV)',
    'total_uv' => 1000,
]
```

### StatsTemplate2Service::RegionRanking()

获取地区购买排行。

**返回**:

```php
[
    'columns' => ['地区名称', '下单人数', '客单价'],
    'data' => [
        ['province_name' => '广东省', 'buyer_count' => 100, 'avg_order_formatted' => '¥100'],
        // ...
    ],
    'metric_chip' => '按下单人数(UV)',
]
```

### StatsTemplate2Service::PeriodRangeInfo()

获取周期范围信息，用于调试和展示。

**返回**:

```php
[
    'period_type' => 'month',
    'current' => [
        'start' => 时间戳,
        'end' => 时间戳,
        'start_text' => '2026-01-01 00:00:00',
        'end_text' => '2026-01-31 23:59:59',
    ],
    'last' => [
        'start' => 时间戳,
        'end' => 时间戳,
        'start_text' => '2025-12-01 00:00:00',
        'end_text' => '2025-12-31 23:59:59',
    ],
]
```

## 趋势计算

### CalculateTrend()

计算当前值与上期值的趋势。

**参数**:

* `$current`: 当前值
* `$previous`: 上期值
* `$type`: 类型 (currency/number/percent/count/rate)

**返回**:

```php
[
    'value' => '+1,234',        // 差异值（格式化）
    'rate' => '+12.5%',         // 百分比变化
    'is_up' => true,            // 是否上升
    'is_warning' => false,      // 是否警告（调用方设置）
]
```

**特殊处理**:

* 上期值为0且当前值>0: 显示为 `+N`，百分比为 `-`
* 两者都为0: 显示为 `-`

## 商品类型说明

### sales\_type (销售类型)

| 值 | 说明 |
|----|------|
| 1 | 预售商品 |
| 2 | 现货商品 |
| 3 | 清仓商品 |

**占比计算**:

```
预售占比 = 预售商品数量 / (预售+现货+清仓总数量) * 100%
现货占比 = 现货商品数量 / (预售+现货+清仓总数量) * 100%
清仓占比 = 清仓商品数量 / (预售+现货+清仓总数量) * 100%
```

## COD复购率计算

**定义**: 仅统计货到付款(COD)订单，且考虑24小时取消时效。

**逻辑**:

1. 获取货到付款支付方式ID (`payment = 'DeliveryPayment'`)
2. 筛选指定时间范围内的COD订单
3. 计算24小时截止时间 (`当前时间 - 24小时`)
4. 有效订单条件：
   * 未取消订单 (status != 5)
   * 或取消时间早于截止时间的订单 (upd\_time < cutoff\_time)
5. 统计每个用户的订单数量
6. 复购用户 = 订单数 >= 2 的用户
7. 复购率 = 复购用户数 / 总用户数 \* 100%

## 前端集成

### 日期选择器

```javascript
// 快捷选择
data-preset="today"        // 今天
data-preset="yesterday"    // 昨天
data-preset="last7days"    // 7天
data-preset="last30days"   // 30天
data-preset="thismonth"    // 本月
data-preset="lastmonth"    // 上月
```

### 自动刷新

```javascript
// 刷新间隔（秒）
var intervalTime = 30; // 默认30秒

setInterval(function() {
    window.DataboardTemplate2.refresh();
}, intervalTime * 1000);
```

### 数据卡片类型映射

```javascript
// KPI卡片
data-card-type="total-sales-with-cancel"
data-card-type="valid-order-count"
// ...

// 侧栏指标
data-metric-type="aov"
data-metric-type="repurchase-rate"
// ...
```

## 开发注意事项

### 1. 时间字段选择

不同指标使用不同的时间字段进行统计，需根据业务含义选择：

* **下单类指标**: 使用 `add_time`
* **完成类指标**: 使用 `collect_time` (签收) 或 `status = 4` (完成)
* **取消类指标**: 使用 `cancel_time`
* **拒收类指标**: 使用 `upd_time` (状态更新时间)
* **退款类指标**: 使用 `audit_time` (售后审核时间)

### 2. 订单状态过滤

**有效订单**: `status in [2, 3, 4]` (待发货、待收货、已完成)
**已取消订单**: `status = 5`
**退件订单**: `status in [7, 8]` (退件中、已退件)

### 3. 24小时时效考虑

计算COD复购率时，需考虑24小时取消时效：

* 统计时间范围的截止时间
* 排除在截止时间后取消的订单

### 4. 异常订单定义

购买数量超过5件的订单视为异常订单：

```php
HAVING SUM(buy_number) > 5
```

### 5. 时区处理

* 前端使用 `Date.getTimezoneOffset()` 获取时区偏移（分钟）
* 后端使用 `DateToUtcTimestamp()` 将本地日期转换为UTC时间戳
* 所有数据库查询使用UTC时间戳

### 6. 月末日期处理

当进行月环比时，如果当月有31日而上月只有30日：

* 自动调整为上月最后一天
* 确保对比天数尽可能一致

### 7. 待实现功能

以下指标标记为 `--`，待确认业务逻辑后实现：

* 揽收订单数
* 揽收订单商品总额
* 揽收的订单运费
* 访问UV（需接入访问统计）
* 平均佣金率（需确认佣金数据来源）

## 配置说明

### 插件配置

**文件**: `app/plugins/databoard/config.json`

```json
{
  "base": {
    "plugins": "databoard",
    "name": "数据看板",
    "version": "1.0.0"
  }
}
```

### 后台配置

* `logo_name`: 看板标题
* `interval_time`: 自动刷新间隔（秒）

## 相关文件清单

| 文件路径 | 类型 | 说明 |
|---------|------|------|
| [`app/plugins/databoard/service/StatsTemplate2Service.php`](app/plugins/databoard/service/StatsTemplate2Service.php) | Service | 统计服务层 |
| [`app/plugins/databoard/admin/Template2.php`](app/plugins/databoard/admin/Template2.php) | Controller | 后台控制器 |
| [`app/plugins/databoard/view/admin/template2/index.html`](app/plugins/databoard/view/admin/template2/index.html) | View | 看板视图 |
| `public/static/plugins/databoard/js/admin/template2/stats.js` | JS | 前端脚本 |
| `public/static/plugins/databoard/css/admin/template2/index.css` | CSS | 样式文件 |