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

## 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 示例

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

```json
{
  "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. 前端对接要点

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