西藏巴青项目

承销商 — 首页（移动端 / 小程序）

1. 概述

项	说明
Base Path	`/app/distributor/home`
数据表	`biz_trade_order`、`biz_distributor`
鉴权	需登录（Token）
身份	当前登录 `sys_user.user_id` 须绑定 `biz_distributor.sys_user_id`（后台「分配账号」）

界面 Tab「实时 / 昨日 / 7日 / 30日」与接口 range 对应关系：

界面	`range`
实时（今日）	`TODAY`
昨日	`YESTERDAY`
7日	`DAYS_7`
30日	`DAYS_30`

2. 首页看板

GET /app/distributor/home/dashboard

一次请求返回当前 range 时段的汇总指标与金额趋势；小程序四个 Tab（今日 / 昨日 / 7日 / 30日）分别传对应 range 各请求一次。

需求项	实现
分时段查 `biz_trade_order`（承销商=本人）	`range` + 当前登录绑定的 `distributor_id`
累计下单数 / 采购总金额 / 已购牦牛数	`summary.orderCount` / `totalAmount` / `totalHeads`
订单完成率	`summary.completionRate`（已完成 ÷ 下单数）
成交供应商数	`summary.supplierCount`（已完成订单 `supplier_id` 去重）
近期交易均价	`summary.avgUnitPrice`（总金额 ÷ 头数）
今日/昨日金额趋势（按小时）	`trendGranularity=HOUR`，`amountTrend` 24 点
7日/30日金额趋势（按天）	`trendGranularity=DAY`，连续自然日补零

2.1 请求

参数	位置	必填	说明
`range`	Query	否	`TODAY`（默认）、`YESTERDAY`、`DAYS_7`、`DAYS_30`

2.2 统计口径

仅统计 biz_trade_order.distributor_id = 当前承销商 且 del_flag = 0 的订单。
时段按订单 create_time（下单时间）落在对应自然日区间内统计（今日/昨日为当日 00:00:00～23:59:59）。
7日：[今日-6日, 今日] 共 7 个自然日；30日：[今日-29日, 今日] 共 30 个自然日。
已完成：order_status = '1'。

2.3 响应 `data`

字段	类型	说明
`range`	string	请求时段编码
`rangeName`	string	中文：今日 / 昨日 / 7日 / 30日
`updatedAt`	string	统计刷新时间 `yyyy-MM-dd HH:mm:ss`
`trendGranularity`	string	`HOUR`（今日、昨日）或 `DAY`（7日、30日）
`summary`	object	汇总指标，见下表
`amountTrend`	array	交易金额趋势点，见下表

summary

字段	说明
`orderCount`	累计下单数（时段内全部订单笔数）
`totalAmount`	采购总金额（元，时段内 `total_amount` 合计）
`totalHeads`	已购牦牛数（头，时段内 `total_heads` 合计）
`completionRate`	订单完成率（%），已完成笔数 ÷ 下单数；下单数为 0 时为 0
`supplierCount`	成交供应商数（时段内已完成订单的 `supplier_id` 去重计数）
`avgUnitPrice`	近期交易均价（元/头），`totalAmount / totalHeads`；头数为 0 时为 0

amountTrend[]

字段	说明
`bucketLabel`	横轴：`HH:00`（按小时）或 `MM-dd`（按天）
`amount`	该时段内订单 `total_amount` 合计（元）

今日 / 昨日：固定 24 个小时桶（00:00～23:00），无数据补 0。
7日 / 30日：按自然日连续补点，无数据补 0。

2.4 示例

GET /app/distributor/home/dashboard?range=TODAY

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "range": "TODAY",
    "rangeName": "今日",
    "updatedAt": "2026-06-01 21:00:00",
    "trendGranularity": "HOUR",
    "summary": {
      "orderCount": 2,
      "totalAmount": 36800.00,
      "totalHeads": 3,
      "completionRate": 50.0,
      "supplierCount": 1,
      "avgUnitPrice": 12266.67
    },
    "amountTrend": [
      { "bucketLabel": "00:00", "amount": 0 },
      { "bucketLabel": "13:00", "amount": 36800.00 }
    ]
  }
}

2.5 常见失败

`msg`	说明
当前账号未绑定承销商，无法查看首页统计	登录用户未关联承销商主档
统计时段仅支持 TODAY、YESTERDAY、DAYS_7、DAYS_30	`range` 非法

3. 前端对接要点

切换 Tab 时带对应 range 重新请求本接口。
金额展示「万元」由前端将 totalAmount、amount 除以 10000 格式化；接口统一返回元。
折线图：trendGranularity=HOUR 用 amountTrend 画 24 小时轴；DAY 用按天序列。
关联模块见 README.md、行情接口说明.md。

首页接口说明.md 4.6KB 履歴 Raw