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

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 大屏交易销售统计 |
| 使用场景 | 领导参观、指挥调度、对外展示等**大屏端**只读看板（交易销售专题页） |
| 目标 | 按**统计年份**集中展示**牦牛交易**订单规模、价格走势、销售去向与品质结构，以及**产地行情**近 7 日态势；形成交易市场与供销态势一屏总览 |
| 数据来源 | **交易市场平台**（交易订单、供应商、承销商、市场行情登记等）、**畜牧流通资源管理**（交易市场主数据）；**农资商城**相关能力**本期不纳入**（见 **§3.2**） |
| 修订依据 | 同目录 `大屏交易销售功能需求-草稿.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 个刻度。
- **缺月规则：** 该月在 **Y** 年内无任何纳入统计的业务记录时，当月指标按 **0** 展示；**不**省略刻度、**不**断线留空、**不**插值。
- **当前年未来月：** 当 **Y** 为当前年时，**晚于统计日** 的月份按 **0** 展示（与缺月规则统一）。

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

| 指标类型 | 代表指标 | 与统计年份 **Y** 的关系 |
| --- | --- | --- |
| **年内累计（已完成订单）** | 订单数、交易量、交易额、按月销量/销售额、销售去向、品质占比 | 仅统计 **Y** 年内满足 **§2.6** 的**已完成**交易订单 |
| **滚动窗口（行情）** | 近 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** 位小数或整数 **%**，全文统一 |
| 价格 | 产地行情与走势；标注元/头或元/斤 |

---

## 3. 功能范围与边界

### 3.1 范围内（本期）

- 统计年份筛选与整页刷新；
- **交易总览**（牦牛三项 + 入驻商铺数）；
- **产地行情**（近 7 日指标 + 三曲线走势）；
- **牦牛交易数额趋势**（按月销售量、销售额双系列）；
- **牦牛销售去向**（三档去向头数及占比）；
- **品质等级占比**（按明细行分档占比）；
- 无数据、加载中、加载失败等状态展示。

### 3.2 范围外（本期不实现 — 草稿已标注）

以下区块依赖**农资商城**设计及台账，**本期大屏不展示、不统计、不占位**（避免空壳或误导数据）：

| 草稿条目 | 说明 |
| --- | --- |
| 农资订单量、农资销售额 | 总览卡片 |
| 农资品类销售占比 | 饼图 |
| 热销农资排行（前 5） | 排行 |
| 商城订单趋势 | 按月曲线 |
| 店铺入驻（按月） | 饼图 |
| 消费区域排名（前 5） | 排行 |
| 消费者评价词云 | 词云 |

农资商城需求定稿后，可增刊《大屏交易销售功能需求》修订版单独成章。

### 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 screen [大屏交易销售]
        H[各统计区块]
    end
    O --> H
    Q --> H
    SUP --> H
    DIS --> 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 本期展示（共 4 项）

| 序号 | 指标名称 | 单位 | 统计口径 |
| --- | --- | --- | --- |
| 1 | 牦牛交易订单数 | 单 | **§2.5** 已完成订单**笔数** |
| 2 | 牦牛交易量 | 头 | **§2.5** 已完成订单 **交易总头数** 合计 |
| 3 | 牦牛交易总额 | 元 | **§2.5** 已完成订单 **交易总金额** 合计 |
| 4 | 入驻商铺数 | 家 | **§2.10** 有效供应商数（实时快照） |

#### 5.2.2 暂不展示（农资）

农资订单量、农资销售额等卡片**本期不出现**（见 **§3.2**）。

**无数据：** **Y** 年无已完成订单时，前三项为 **0**；供应商数为 0 时第四项为 **0**。

---

### 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** 1～12 月 |
| 系列一 | **销售量（头）**：该月 **§2.5** 已完成订单的 **交易总头数** 合计 |
| 系列二 | **销售额（元）**：该月 **§2.5** 已完成订单的 **交易总金额** 合计 |
| 缺月/未来月 | **§2.3** |
| 交互 | 悬停展示月份 + 头数 + 金额 |

**无数据：** **Y** 年无任何已完成订单时，图表空态或 12 个月均为 0（与 **§7.1** 协调）。

---

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

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

---

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

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

---

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

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

---

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

### 7.1 业务数据空态

| 场景 | 展示要求 |
| --- | --- |
| **Y** 年无已完成订单 | 总览前三项为 **0**；趋势图空态或全 0；销售去向、品质占比空态 |
| **Y** 年有订单但无明细品质 | 品质区块空态；其余区块正常 |
| 近 7 日无行情 | 产地行情指标 **—** 或 0；走势图空态 |
| 某销售去向档为 0 | 仍展示该档，占比 0% |

### 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 月双系列；缺月/未来月为 0；与 **§2.5** 按月核算一致 |
| SY-JY-06 | 销售去向 | 三档头数之和 = 当年已完成总头数；占比合理 |
| SY-JY-07 | 品质占比 | 各等级占比之和为 100%（有明细时）；仅统计已完成订单明细 |
| SY-JY-08 | 农资区块 | 页面**无**农资相关占位（**§3.2**） |
| SY-JY-09 | 后台补录后刷新 | 完成支付或登记行情后刷新可见 |
| SY-JY-10 | 只读 | 无业务维护按钮 |

---

## 9. 修订记录

| 版本 | 日期 | 说明 |
| --- | --- | --- |
| 1.0 | 2026-05-26 | 由草稿优化：补全流程、边界、五区块需求；对齐交易订单/行情/承销商口径；农资商城整块标为范围外；不涉及库表与接口；保留草稿不修改 |

---

## 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** 本期用供应商快照；农资整块 **§3.2** 排除 |
| 按月缺月、未来月未写 | **§2.3** |
| 技术栈、统一响应格式 | 不写入本文档 |
| 农资相关 6～13 条 | 收入 **§3.2**，本期不实现 |
