# 供应商 — 首页（移动端 / 小程序）

## 1. 概述

| 项 | 说明 |
| --- | --- |
| Base Path | `/app/supplier/home` |
| 数据表 | `biz_trade_order`、`biz_supplier_settlement`、`biz_entry_isolation`、`biz_entry_isolation_alloc`、`biz_isolation_patrol`、`biz_market_entry`、`biz_market_entry_ear_tag`、`biz_supplier` |
| 鉴权 | 需登录（Token） |
| 身份 | 当前登录 `sys_user.user_id` 须绑定 `biz_supplier.sys_user_id`（后台「分配账号」） |
| 界面参考 | [Snipaste_2026-06-01_21-03-22.jpg](./Snipaste_2026-06-01_21-03-22.jpg) |
| 模块索引 | [README.md](./README.md) |

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

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

## 2. 首页看板

`GET /app/supplier/home/dashboard`

### 2.1 请求

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

### 2.2 统计口径

**交易数据（随 `range` 切换）**

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

| 指标 | 规则 |
| --- | --- |
| 交易金额 | `sum(total_amount)` |
| 交易订单数 | `count(*)` |
| 支付买家数 | `count(distinct distributor_id)`，且 `order_status = 1`（已支付） |
| 交易牦牛数 | `sum(total_heads)` |

**结算数据（随 `range` 切换）**

- 表：`biz_supplier_settlement`，`supplier_id` = 当前供应商，`del_flag = 0`，**`settlement_status = 1`（已完成）**。
- 时段按 **`settle_finish_time`** 落在对应自然日区间内统计。

| 指标 | 规则 |
| --- | --- |
| 结算金额 | `sum(payable_amount)` |
| 服务费金额 | `sum(service_fee_amount)` |

**交易金额趋势（随 `range` 切换）**

- 数据源：`biz_trade_order`，按 **`create_time`** 汇总 `total_amount`。
- **今日 / 昨日**：按小时，固定 **24** 个桶（`00:00`～`23:00`），无数据补 0。
- **7日 / 30日**：按自然日连续补点，横轴 `MM-dd`，无数据补 0。

**实时牦牛状态（固定今日，不随 `range` 切换）**

| 字段 | 说明 |
| --- | --- |
| `tradedHeads` | 已交易：今日下单订单 `sum(total_heads)`（`create_time` 为今日） |
| `isolationEarTags` | 隔离中：当前处于隔离期内（`entry_time` 日期 ≤ 今日 ≤ `expected_release_date`）的入场隔离耳标去重计数，剔除该供应商关联栏位在 `biz_isolation_patrol` 中 **`sick_dead_qty > 0` 且填写了耳标** 的病死记录 |
| `enteredPenEarTags` | 已进栏：今日 `biz_market_entry.entry_time` 的进栏登记关联 `biz_market_entry_ear_tag` **去重耳标数** |
| `pendingPayHeads` | 待支付：当前供应商 **`order_status = 0`** 订单的 `sum(total_heads)` |

### 2.3 响应 `data`

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

**`tradeSummary`**

| 字段 | 说明 |
| --- | --- |
| `totalAmount` | 交易金额（元） |
| `orderCount` | 交易订单数 |
| `payingBuyerCount` | 支付买家数 |
| `totalHeads` | 交易牦牛数（头） |

**`settlementSummary`**

| 字段 | 说明 |
| --- | --- |
| `payableAmount` | 结算金额（元） |
| `serviceFeeAmount` | 服务费金额（元） |

**`amountTrend[]`**

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

**`yakStatus`**

| 字段 | 说明 |
| --- | --- |
| `tradedHeads` | 已交易（头） |
| `isolationEarTags` | 隔离中（耳标数） |
| `enteredPenEarTags` | 已进栏（耳标数） |
| `pendingPayHeads` | 待支付（头） |

### 2.4 示例

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

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "range": "TODAY",
    "rangeName": "今日",
    "updatedAt": "2026-05-26 16:00:00",
    "trendGranularity": "HOUR",
    "tradeSummary": {
      "totalAmount": 74300,
      "orderCount": 2,
      "payingBuyerCount": 2,
      "totalHeads": 6
    },
    "settlementSummary": {
      "payableAmount": 36500,
      "serviceFeeAmount": 600
    },
    "amountTrend": [
      { "bucketLabel": "00:00", "amount": 0 },
      { "bucketLabel": "16:00", "amount": 74300 }
    ],
    "yakStatus": {
      "tradedHeads": 129,
      "isolationEarTags": 0,
      "enteredPenEarTags": 30,
      "pendingPayHeads": 4
    }
  }
}
```

### 2.5 错误说明

| 场景 | 说明 |
| --- | --- |
| 未绑定供应商 | `当前账号未绑定供应商，无法查看首页统计` |
| 非法 `range` | `统计时段仅支持 TODAY、YESTERDAY、DAYS_7、DAYS_30` |