# 大屏 — 交易销售统计 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 大屏交易销售统计 |
| 使用场景 | 领导参观、指挥调度、对外展示等**大屏端**只读看板（交易销售专题页） |
| 目标 | 按**统计年份**集中展示**牦牛交易**订单规模、价格走势、销售去向与品质结构，以及**产地行情**近 7 日态势；并展示**农资商城**品类、订单、店铺、区域与评价词云；形成交易市场与供销态势一屏总览 |
| 数据来源 | **交易市场平台**（交易订单、供应商、承销商、市场行情登记等）、**畜牧流通资源管理**（交易市场主数据）；**农资商城**经 Open API 聚合（见 **§2.12**），本大屏**不直连**商城库表 |
| 修订依据 | 同目录 `大屏交易销售功能需求-草稿.md`、`Snipaste_2026-05-26_08-48-14.jpg`、`Snipaste_2026-05-26_10-30-51.jpg`；指标口径与《交易订单管理功能需求》《承销商管理功能需求》《市场行情登记功能需求》《供应商管理功能需求》及移动端《牦牛行情》业务说明对齐 |
| 关联维护 | 订单录入、完成支付、行情登记、承销商主数据维护须在对应业务后台完成；大屏刷新后展示最新结果 |

本文档仅描述**功能需求、业务规则与展示逻辑**，不涉及数据库结构、接口路径、请求体字段、统一响应格式及技术实现选型。

---

## 2. 术语与口径

### 2.1 统计年份

- 大屏顶部（或全局筛选区）提供**统计年份**选择，格式为自然年 **YYYY**（如 `2026`）。
- 进入大屏时默认选中**当前自然年**。
- 变更统计年份后，凡标注「与 **Y** 相关」的区块须**同步**按新年份重算；**不得**出现区块之间年份不一致。
- **产地行情（近 7 日）**与**主数据快照类**指标**不随 Y 切换**（见 **§2.4、§2.5**）。

### 2.2 统计日

记用户打开或刷新大屏时的系统日期为**统计日**（自然日，项目时区与后台一致，默认 `Asia/Shanghai`）。

### 2.3 统计月份（按月图表）

按月图表分两类，横轴规则**不同**：

| 类型 | 适用区块 | 横轴规则 |
| --- | --- | --- |
| **统计年 Y 内 1～12 月** | （本期无；店铺入驻等为年度/实时快照） | — |
| **滚动最近 12 个月** | **牦牛交易数额趋势**、**商城订单趋势** | 以服务器当前年月为锚点，取**含当月在内向前连续 12 个自然月**；**不**随页面「统计年份 **Y**」切换 |

**滚动最近 12 个月**

- 接口每条记录含 **`statYear`**、**`month`（1～12）**；按时间升序固定 **12** 条。
- 缺月指标为 **0**；**不**省略刻度。
- **前端横轴**仅展示月份；**鼠标悬停**展示 **YYYY年M月** 及数值。
- 切换 **Y** 时，上述两趋势图**仍展示同一滚动窗口**。

**农资订单量（总览）** = 滚动 12 月「商城订单趋势」各月 `orderCount` 之和（与趋势图窗口一致）。

### 2.4 指标类型与年份关系

| 指标类型 | 代表指标 | 与统计年份 **Y** 的关系 |
| --- | --- | --- |
| **年内累计（已完成订单）** | 订单数、交易量、交易额、销售去向、品质占比 | 仅统计 **Y** 年内满足 **§2.6** 的**已完成**交易订单 |
| **滚动最近 12 月** | 牦牛交易数额趋势（按月销量/销售额）、商城订单趋势 | **§2.3**；**不**随 **Y** 切换 |
| **滚动窗口（行情）** | 近 7 日均价/最低价/最高价、行情走势 | 以**统计日**为终点向前连续 **7** 个自然日；**与 Y 无关** |
| **主数据实时快照** | 入驻商铺数（供应商数） | **不随 Y** 变化；为当前有效主数据条数 |

### 2.5 牦牛交易订单纳入规则

对齐《交易订单管理功能需求》：

| 项 | 规则 |
| --- | --- |
| 统计对象 | **交易订单**主档 |
| 有效记录 | `del_flag` 为未删除（与项目逻辑删除约定一致） |
| **已完成** | 订单状态为**已完成**（已上传支付凭证并完成支付） |
| **待支付** | **不参与**任何大屏统计（草稿中凡写「已完成的交易订单」处均指本行） |
| 时间归属（按年） | **订单完成时间**（`finish_time`）的日期部分落在统计年份 **Y** 年内（`Y-01-01`～`Y-12-31`，含起止日） |
| 时间归属（按月） | **订单完成时间**落在该自然月内 |
| 交易量（头） | 订单**交易总头数**（= 采购明细行数） |
| 交易额（元） | 订单**交易总金额**（= 明细金额之和） |

### 2.6 产地行情（日度）纳入规则

对齐《市场行情登记功能需求》：

| 项 | 规则 |
| --- | --- |
| 统计对象 | **日度行情**登记记录 |
| 有效记录 | 未逻辑删除 |
| 渠道范围 | 默认统计县域**主交易市场**「**巴青牦牛交易市场**」（与《牦牛行情》移动端一致）；若登记时市场名称不一致，实施前须统一主数据名称或配置默认市场 |
| 近 7 日窗口 | 区间：**[统计日 − 6 日, 统计日]**，共 **7** 个自然日（含统计日当天） |
| 单日多维度 | 同一行情日、同一渠道下若存在多条不同品类维度（公母、重量档等）的日度记录，当日聚合规则见 **§2.7** |

### 2.7 行情聚合与单位

对 **§2.6** 渠道范围内、落在近 7 日窗口内的日度行情，按**行情日期**分组后：

| 聚合项 | 计算规则 |
| --- | --- |
| 当日最低价 | 取该日各条记录 **最低价** 的**最小值** |
| 当日最高价 | 取该日各条记录 **最高价** 的**最大值** |
| 当日均价 | 取该日各条记录 **均价** 的**算术平均**（条数为 0 的日期不参与） |
| 价格单位展示 | 优先取该日**最近创建**的一条记录的单位（元/头、元/斤）；若 7 日内单位不一致，以**最近一次行情日**的单位展示，并在图例或脚注说明「单位：××」（与产品定稿一致） |

**近 7 日汇总卡片（区块二上部指标）：**

| 指标 | 计算 |
| --- | --- |
| 7 日均价 | 7 个自然日内「当日均价」有效值的**算术平均** |
| 7 日最低价 | 7 日内「当日最低价」的**最小值** |
| 7 日最高价 | 7 日内「当日最高价」的**最大值** |
| 最近一次行情日期 | 7 日窗口内存在日度记录的最大**行情日期**；无记录时为 **—** 或空态 |

### 2.8 销售去向（承销商维度）

| 项 | 规则 |
| --- | --- |
| 归属 | 取订单关联**承销商**主档上的**销售去向**（本市 / 本省 / 外省），与《承销商管理功能需求》**§2.3** 一致 |
| 统计量 | 对 **§2.5** 纳入的已完成订单，按承销商 `distributor_id` 取销售去向后，汇总 **交易总头数**（非订单笔数） |
| 展示 | 三档固定展示；某档无数据时该档为 **0** 头、占比 **0%** |

### 2.9 品质等级（订单明细维度）

| 项 | 规则 |
| --- | --- |
| 统计对象 | **已完成**订单的**采购明细**行（一行一头） |
| 等级来源 | 明细 `grade_code`、`grade_name`（保存订单时由服务端按重量匹配 `biz_grade_weight_config` 写入，见《交易订单管理功能需求》§3.4） |
| 统计量 | 按 `grade_code` 分组计数（头）；占比 = 该等级头数 ÷ 当年已完成订单明细总行数 |
| 展示 | 饼图/环形图；展示名称优先取明细 `grade_name` 快照（如一级、二级） |

> 等级编码与名称以配置表为准（A/B/C/D 等）；大屏**不维护**等级字典。

### 2.10 入驻商铺数（本期牦牛侧口径）

草稿「入驻商铺数」原拟对接农资商城。本期仅上线牦牛交易时，该指标收束为：

| 指标 | 口径 |
| --- | --- |
| 入驻商铺数 | 《供应商管理》中**未逻辑删除**的有效**供应商**条数（家） |
| 与 **Y** | **实时快照**，切换年份不变 |

农资商城上线后，可改为「农资店铺数」或拆分为两个指标，须单独立项修订。

### 2.11 比率与单位

| 项 | 约定 |
| --- | --- |
| 头 | 交易量、销售去向、品质结构 |
| 单 | 订单笔数 |
| 元 | 交易额；大屏展示可带千分位；大额是否换算「万元」以原型为准，全文统一 |
| 家 | 供应商（入驻商铺） |
| % | 占比；品质、销售去向占比建议保留 **1** 位小数或整数 **%**，全文统一 |
| 价格 | 产地行情与走势；标注元/头或元/斤 |
| 件 | 农资品类销量（与商城 quantity 一致） |
| 万元 | 消费区域排名金额 |

### 2.12 农资商城统计（Open API 口径）

对齐商城项目《商城数据统计功能需求》及 Open API 技术方案；**统计口径以商城侧为准**，大屏只读展示。

| 区块 | 与 **Y** / 统计日关系 | 口径摘要 |
| --- | --- | --- |
| 农资品类销售、热销 Top5 | **Y**（统计年；当年已完成单按 `finish_time` 归属 **Y**，一级品类销量） | 饼图占比 + Top5 排行 |
| 商城订单趋势 | **滚动 12 月**；按月计数 | 非删除订单按 `create_time` 归属月；跨年时合并两年 Open API 数据 |
| 店铺入驻 | **Y**；按月占比饼图 | 按店铺 `create_time` 归属月 |
| 消费区域 Top5 | **Y**；已完成单实付按收货城市 | 金额万元，Top5 |
| 消费者评价词云 | **与 Y 无关**（全量评价 Top50） | 词频降序 |
| 总览·农资订单量 | **Y** | 当年各月订单数**求和** |
| 总览·农资销售额 | **Y** | **v1.1**：商城 Open API **未提供**年度销售总额；有接口后对接，否则展示 **—** |

**未接入或调用失败**：右栏各区块空态；`mallStatsAvailable=false`；牦牛区块不受影响。

---

## 3. 功能范围与边界

### 3.1 范围内（v1.1）

- 统计年份筛选与整页刷新；
- **交易总览**（牦牛三项 + 入驻商铺数 + **农资订单量**；农资销售额有数据则展示，否则 **—**）；
- **产地行情**（近 7 日指标 + 三曲线走势）；
- **牦牛交易数额趋势**（按月销售量、销售额双系列）；
- **牦牛销售去向**（三档去向头数及占比）；
- **品质等级占比**（按明细行分档占比）；
- **农资品类销售占比**（饼图）、**热销农资 Top5**（排行）；
- **商城订单趋势**（按月曲线）、**店铺入驻**（按月饼图）；
- **消费区域排名 Top5**、**消费者评价词云**；
- 无数据、加载中、加载失败、商城未接入等状态展示。

### 3.2 范围外 / 依赖外部

| 项 | 说明 |
| --- | --- |
| 商城 Open API 不可用 | 农资区块空态；不伪造数据 |
| 农资年度销售总额 | 待商城 API 扩展；见 **§2.12** |
| 商城侧订单/店铺/评价维护 | 在农资商城后台完成 |

### 3.3 其他范围外（不变）

- 交易订单、行情、供应商/承销商的增删改、支付、结算；
- 导出、打印；下钻后台维护菜单（若后续增加外链须单独评审）；
- 按供应商、承销商、市场等多维筛选（本期仅**统计年份**全局筛选）；
- 技术栈、接口、异常响应 `code/msg/data`（属技术方案，**不写入**本文档）；
- 大屏端权限与网关策略（由部署约定）。

---

## 4. 业务流程概览

```mermaid
flowchart TD
    A[打开大屏交易销售页] --> B[默认当前统计年份 Y]
    B --> C[加载各区块数据]
    C --> D[渲染总览/图表]
    J[用户切换统计年份] --> C
    K[后台完成支付/登记行情等] --> L[刷新或重新进入大屏]
    L --> C
```

**典型使用顺序：**

1. 用户进入大屏交易销售页，系统默认 **Y = 当前年**，加载牦牛交易类区块及近 7 日行情。  
2. 用户切换 **Y** → 全页 Loading → 与 **Y** 相关的区块重算（行情区块仍按**统计日**近 7 日）。  
3. 运营人员在后台完成订单支付、登记日度行情、维护承销商销售去向后，大屏通过**重新进入、手动刷新或约定轮播周期**更新。

### 4.1 数据汇聚关系

```mermaid
flowchart TB
    subgraph trade [交易市场平台]
        O[交易订单/明细]
        Q[市场行情登记]
        SUP[供应商]
        DIS[承销商]
    end
    subgraph mall [农资商城 Open API]
        M[overview 六项统计]
    end
    subgraph screen [大屏交易销售]
        H[各统计区块]
    end
    O --> H
    Q --> H
    SUP --> H
    DIS --> H
    M --> H
```

---

## 5. 页面结构与区块需求

布局以原型 `Snipaste_2026-05-26_08-48-14.jpg`、`Snipaste_2026-05-26_10-30-51.jpg` 为准。

### 5.1 全局：统计年份

| 项 | 规则 |
| --- | --- |
| 统计年份 | 见 **§2.1**；变更后**整页**重载（行情近 7 日仍按 **§2.2** 统计日计算） |
| 只读 | 无维护类按钮；可有**刷新** |

---

### 5.2 区块一：交易总览

以**指标卡片**横向排列（与原型一致）。

#### 5.2.1 展示项（共 6 项）

| 序号 | 指标名称 | 单位 | 统计口径 |
| --- | --- | --- | --- |
| 1 | 牦牛交易订单数 | 单 | **§2.5** 已完成订单**笔数** |
| 2 | 牦牛交易量 | 头 | **§2.5** 已完成订单 **交易总头数** 合计 |
| 3 | 牦牛交易总额 | 元 | **§2.5** 已完成订单 **交易总金额** 合计 |
| 4 | 入驻商铺数 | 家 | **§2.10** 有效供应商数（实时快照） |
| 5 | 农资订单量 | 单 | **§2.12** 当年商城订单趋势各月求和；未接入为 **—** |
| 6 | 农资销售额 | 元 | **§2.12** 年度总额（待商城 API）；未接入或无数据为 **—** |

**无数据：** **Y** 年无已完成牦牛订单时，前三项为 **0**；供应商数为 0 时第四项为 **0**；农资项按 **§2.12** 空态规则。

---

### 5.3 区块二：产地行情

#### 5.3.1 近 7 日指标卡片

| 项 | 规则 |
| --- | --- |
| 统计窗口 | **§2.6、§2.7**；与 **Y** 无关 |
| 展示项 | 7 日均价、7 日最低价、7 日最高价、**最近一次行情日期** |
| 单位 | 价格项须标注单位（元/头或元/斤） |

#### 5.3.2 近 7 日走势

| 项 | 规则 |
| --- | --- |
| 图表类型 | **折线图**（或面积图，以原型为准） |
| 横轴 | 近 7 个自然日（建议 `MM-dd`）；缺日无登记时该点三系列均为 **0** 或该日不参与连线（与产品定稿一致，**默认**缺日显示 0） |
| 数据系列 | ① 当日最低价；② 当日最高价；③ 当日均价（均为 **§2.7** 当日聚合值） |
| 图例 | 三系列名称与颜色区分 |
| 交互 | 悬停展示日期 + 三个价格 |

**无数据：** 7 日内无任何日度行情时，指标区与图表走 **§7.1** 空态。

---

### 5.4 区块三：牦牛交易数额趋势

| 项 | 规则 |
| --- | --- |
| 图表类型 | **柱状图 + 折线图**组合，或双轴图（以原型为准） |
| 数据范围 | **§2.3** 滚动最近 **12** 个自然月 |
| 横轴 | 12 刻度，**仅显示月份**；悬停显 **YYYY年M月** |
| 系列一 | **销售量（头）**：该月 **§2.5** 已完成订单的 **交易总头数** 合计 |
| 系列二 | **销售额（元）**：该月 **§2.5** 已完成订单的 **交易总金额** 合计 |
| 缺月 | 窗口内无完成单的月份为 **0** |
| 与 **Y** | **不**随 **Y** 切换 |

**无数据：** 滚动窗口内无任何已完成订单时，图表空态或 12 槽位均为 0（与 **§7.1** 协调）。

---

### 5.5 区块四：牦牛销售去向

| 项 | 规则 |
| --- | --- |
| 图表类型 | 饼图/环形图（以原型为准） |
| 分档 | **本市**、**本省**、**外省**（**§2.8**） |
| 展示内容 | 各档**头数**及占当年已完成订单总头数的**占比** |
| 无去向数据 | 三档均为 0；占比 0% |

---

### 5.6 区块五：品质等级占比

| 项 | 规则 |
| --- | --- |
| 图表类型 | 饼图/环形图（以原型为准） |
| 统计对象 | **§2.9** 已完成订单明细行 |
| 展示内容 | 各品质等级**头数**及**占比** |
| 无等级或全空 | 当年无已完成明细，或明细均无品质等级时 **§7.1** 空态 |

---

### 5.7 区块六：农资品类销售 + 热销 Top5（右栏上部）

| 项 | 规则 |
| --- | --- |
| 品类占比 | **饼图**；各一级品类**当年**销量占 `totalQty` 比例（**§2.12**） |
| 热销 Top5 | 列表：排名、品类名、销量；与饼图同 **statYear**（统计年 **Y**） |
| 未接入 | 空态文案「商城统计未接入」或「暂无数据」 |

---

### 5.8 区块七：商城订单趋势

| 项 | 规则 |
| --- | --- |
| 图表类型 | **折线图**（面积图可选） |
| 数据范围 | **§2.3** 滚动最近 **12** 个自然月（商城 Open API 按年返回时服务端合并并补 `statYear`） |
| 横轴 | 12 刻度，**仅显示月份**；悬停显 **YYYY年M月** |
| 系列 | 每月商城订单数（单） |
| 与 **Y** | 切换年份同步更新 |

---

### 5.9 区块八：店铺入驻

| 项 | 规则 |
| --- | --- |
| 图表类型 | **饼图**（各月入驻数占当年 `yearTotal` 比例） |
| 与 **Y** | 切换年份同步更新 |

---

### 5.10 区块九：消费区域排名（前 5）

| 项 | 规则 |
| --- | --- |
| 图表类型 | **柱状图** |
| 指标 | 各城市农资销售额（**万元**）；Top5 |
| 与 **Y** | 切换年份同步更新 |

---

### 5.11 区块十：消费者评价

| 项 | 规则 |
| --- | --- |
| 展示 | **词云**；Top50 高频词 |
| 与 **Y** | **不随 Y 变**（全量评价缓存，见商城侧 TTL） |

---

## 6. 图表与展示通用规则

| 项 | 规则 |
| --- | --- |
| 单位 | 界面须标注 **§2.11** 约定单位 |
| 跨年 | 仅 **Y** 相关区块随年份切换；行情 7 日随**统计日**滚动 |
| 只读 | 无编辑、支付、登记类操作 |
| 一致性 | 总览「交易量」与趋势图按月销量合计、销售去向头数之和（三档）应与 **§2.5** 口径一致（允许四舍五入误差） |

---

## 7. 异常、空态与刷新

### 7.1 业务数据空态

| 场景 | 展示要求 |
| --- | --- |
| **Y** 年无已完成订单 | 总览前三项为 **0**；趋势图空态或全 0；销售去向、品质占比空态 |
| **Y** 年有订单但无明细品质 | 品质区块空态；其余区块正常 |
| 近 7 日无行情 | 产地行情指标 **—** 或 0；走势图空态 |
| 某销售去向档为 0 | 仍展示该档，占比 0% |
| 商城未接入 / 接口失败 | 右栏空态；`mallStatsAvailable=false`；左栏正常 |
| 商城某区块无数据 | 该图空态；不展示假数据 |

### 7.2 加载与失败

| 场景 | 展示要求 |
| --- | --- |
| 切换年份加载中 | 整页或分区块 Loading，避免显示上一年残留 |
| 业务数据加载失败 | 明确失败提示，支持**重试** |
| 部分区块失败 | 失败区块单独提示；已成功区块可保留（若产品要求整页失败则统一提示） |

### 7.3 数据刷新

- 大屏为**只读**；后台完成支付、行情登记后，须通过**重新进入、手动刷新或约定自动轮播周期**更新（周期建议 **1～5 分钟**，由实施配置）。
- **不要求**与后台变更秒级同步。

---

## 8. 验收要点（功能）

| 编号 | 场景 | 通过标准 |
| --- | --- | --- |
| SY-JY-01 | 默认年份 | 进入页默认当前年；与 **Y** 相关区块口径一致 |
| SY-JY-02 | 切换年份 | 切换 **Y** 后交易类区块同步更新；近 7 日行情仍按统计日 |
| SY-JY-03 | 交易总览 | 订单数/量/额与手工按 **§2.5** 核算一致；入驻商铺数不随 **Y** 变 |
| SY-JY-04 | 产地行情 | 7 日指标与走势图与 **§2.7** 一致；与 **Y** 无关 |
| SY-JY-05 | 数额趋势 | 滚动 12 月双系列；含 `statYear`+`month`；缺月 0；横轴仅月、悬停显年月；**不**随 **Y** |
| SY-JY-06 | 销售去向 | 三档头数之和 = 当年已完成总头数；占比合理 |
| SY-JY-07 | 品质占比 | 各等级占比之和为 100%（有明细时）；仅统计已完成订单明细 |
| SY-JY-08 | 农资区块 | 右栏六区块有数据或规范空态；与商城 Open API 口径一致 |
| SY-JY-09 | 后台补录后刷新 | 完成支付或登记行情后刷新可见；商城侧订单/评价变更后刷新可见农资区块 |
| SY-JY-10 | 只读 | 无业务维护按钮 |
| SY-JY-11 | 商城降级 | 商城 API 关闭或失败时牦牛区块正常、农资空态 |
| SY-JY-12 | 农资订单量 | 总览「农资订单量」= **滚动 12 月**商城订单趋势各月之和 |

---

## 9. 修订记录

| 版本 | 日期 | 说明 |
| --- | --- | --- |
| 1.0 | 2026-05-26 | 由草稿优化：补全流程、边界、五区块需求；农资商城整块标为范围外 |
| **1.1** | **2026-05-20** | **纳入农资商城 §8～13**：Open API 对接；总览增农资订单量；六区块右栏；**§2.12** 口径；农资年度销售额待商城 API |
| **1.2** | **2026-05-20** | 对齐商城 Open API **v1.2**：品类/热销/区域改为**统计年**口径；大屏请求 overview 仅传 `statYear`；右栏标题展示统计年 |
| **1.3** | **2026-07-04** | 牦牛交易数额趋势、商城订单趋势改为**滚动最近 12 月**；接口增 `statYear`+`month`；农资订单量与滚动趋势合计一致 |

---

## 10. 相对草稿的优化说明

| 草稿问题 | 处理方式 |
| --- | --- |
| 仅条目罗列 | 增加 **§3、§4、§7、§8** 与 mermaid 流程 |
| 「当前年份」与全局筛选 | 统一为 **§2.1** 统计年份 **Y**；默认当前年 |
| 已完成订单未写清 | **§2.5** 明确仅**已完成**、按**完成时间**归属 |
| 产地行情 7 日未写聚合 | **§2.6、§2.7** 补窗口、渠道、多维度聚合 |
| 销售去向未关联承销商 | **§2.8** 对齐承销商主档三档 |
| 品质等级无字段来源 | **§2.9** 对齐明细 `grade_code` + 配置表 `grade_name` |
| 入驻商铺与农资混杂 | **§2.10** 本期用供应商快照；农资指标 **§2.12** 独立口径 |
| 按月缺月、未来月未写 | **§2.3** |
| 技术栈、统一响应格式 | 不写入本文档（见技术方案 **v1.1**） |
| 草稿 8～13 条 | **v1.1 已实现**（Open API）；草稿 **§3** 农资两项部分实现（销售额待 API） |