huimv-baqing/doc/app/交易市场平台（承销商）/首页接口说明.md

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

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

2.1 请求

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

2.2 统计口径

• 仅统计 distributor_id = 当前承销商 且 del_flag = 0 的订单。
• 时段按订单 create_time（下单时间）落在对应自然日区间内统计。
• 7日：[今日-6日, 今日] 共 7 个自然日；30日：[今日-29日, 今日] 共 30 个自然日。

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	采购总金额（元）
totalHeads	已购牦牛数（头）
completionRate	订单完成率（%），已完成数 ÷ 下单数，order_status=1 为已完成；下单数为 0 时为 0
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,
      "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. 前端对接要点

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