数据看板template2

约 2473 字大约 8 分钟

2026-02-03

概述

本文档规定了 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)

// 前端传递的时区偏移（分钟）
// 例如：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阶段）。

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

StatsTemplate2Service::SideMetrics()

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

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

StatsTemplate2Service::HotGoodsRanking()

获取热卖商品排行。

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

StatsTemplate2Service::CartAddRanking()

获取商品加购排行。

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

StatsTemplate2Service::RegionRanking()

获取地区购买排行。

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

StatsTemplate2Service::PeriodRangeInfo()

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

[
    '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)

[
    '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小时取消时效。

逻辑:

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

前端集成

日期选择器

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

自动刷新

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

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

数据卡片类型映射

// 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件的订单视为异常订单：

HAVING SUM(buy_number) > 5

5. 时区处理

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

6. 月末日期处理

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

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

7. 待实现功能

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

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

配置说明

插件配置

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

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

后台配置

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

文件路径	类型	说明
`app/plugins/databoard/service/StatsTemplate2Service.php`（在新窗口打开）	Service	统计服务层
`app/plugins/databoard/admin/Template2.php`（在新窗口打开）	Controller	后台控制器
`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	样式文件