# 市场行情登记 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 市场行情登记（交易市场平台） |
| 目标 | 在业务后台按日登记**活畜（牛）市场行情**（产地、渠道、品类维度、价格区间、出栏与预测信息等），支撑价格分析、趋势研判及后续报表引用 |
| 关联系统 | 业务后台；**渠道**联动「畜牧流通资源管理 · 交易市场管理」主数据；**产地**采用省/市/县三级区划；本模块为行情**台账登记**，不替代自动采集、外部行情接口对接、复杂定价模型 |
| 修订依据 | 同目录 `市场行情登记-草稿.md`、界面原型（`市场行情登记.png`） |

本文档仅描述**功能需求与业务规则**，不涉及库表结构、接口路径、请求体字段命名、HTTP 报文及技术栈选型。

---

## 2. 术语与业务对象

### 2.1 日度行情（一条登记记录）

- 表示在**某一行情日期**，针对**特定产地、渠道（交易市场）及牛只品类维度**登记的一条**日度市场行情**快照。  
- 由运营人员在后台**新增与维护**；保存成功后出现在日度行情列表，供查询、修改、删除及后续统计引用。  
- 单条记录包含：**行情日期**、**产地（三级区划）**、**渠道**、**公母**、**重量档**、**生长阶段**、**月龄档**、**膘情**、**价格区间与单位**、**均价**、**出栏情况**、**变化因素**、**涨跌预测概率**、**出栏建议**及审计信息等。

### 2.2 行情日期

- **必填**；格式 **YYYY-MM-DD**（日期选择器，不含时分秒）。  
- **新增默认值**：系统日期的**前一天**（「昨天」）；用户可改选其他合法日期。  
- **不宜**选择未来日期（**默认建议**禁止或提示「行情日期不能晚于今天」，与业务录入习惯一致）。

### 2.3 产地（三级区划）

- **必填**；采用**省、市、县（区）**三级行政区划**级联单选**，须选至**县级**（与牧场管理等模块一致）。  
- 列表、详情展示为省/市/县名称拼接或分级展示（与项目展示惯例一致）。  
- **本期不提供**乡镇、村及以下粒度。

### 2.4 渠道（交易市场）

- **必填**；**单选**下拉（或等效选择器）。  
- 选项来源：「**畜牧流通资源管理 · 交易市场管理**」中**未逻辑删除**的交易市场主数据（展示**市场名称**，保存关联主键或编码，具体绑定方式由技术方案实现）。  
- **默认建议**仅展示运营状态为「**正常**」的市场；停业、注销市场**不可选**或置灰并说明原因。  
- 若主数据为空，新增时应提示「请先在交易市场管理中维护市场」。

### 2.5 品类与体征维度（单选枚举）

以下字段均为**单选**；除特别说明外，草稿未标「必填」的维度**本期按选填**处理（录入员可按实际成交品类填写；若产品要求全部必填，评审后统一改为必填）。

| 字段 | 选项（与草稿、原型一致） | 必填 | 默认 |
| --- | --- | --- | --- |
| **公母** | 公牛 / 母牛 / 公母混合 | **是** | **公牛** |
| **重量** | 50斤以下 / 50-100斤 / 100-200斤 / 200-300斤 / 300-500斤 / 500-800斤 / 800斤以上 | 否 | — |
| **生长阶段** | 犊牛 / 架子牛 / 屠宰牛 | 否 | — |
| **月龄** | 1月龄 / 2-3月龄 / 4-5月龄 / 6-7月龄 / 8-9月龄 / 10-11月龄 / 12月龄 | 否 | — |
| **膘情** | 43% / 45% / 50% / 53% | 否 | — |

### 2.6 价格、单位与均价

| 字段 | 规则 |
| --- | --- |
| **最低价、最高价** | **必填**；均为**正数**（>0）；**最低价 ≤ 最高价**；支持小数位数与项目金额字段惯例一致（**默认建议**最多 2 位小数） |
| **单位** | **必填**；**单选**：**元/头**、**元/斤**；**默认 元/斤** |
| **均价** | **必填**；由系统根据最低价、最高价**自动计算**并展示（用户**不可手工改均价**，除非产品明确要求可覆盖——**本期按不可改**） |

**均价计算规则（本期）**

- 公式：**均价 = (最低价 + 最高价) ÷ 2**  
- 在最低价、最高价任一变更且均合法时**实时重算**；未填全或非法时不展示有效均价，保存时若均价无效则拒绝提交。  
- 展示时带单位后缀（与所选「单位」一致，如 `12.50 元/斤`）。

### 2.7 出栏情况（单选，必填）

| 选项 | 含义概要 |
| --- | --- |
| 货源充足 | 当期出栏/到货相对充足 |
| 货源减少 | 相对前期或预期，货源偏紧 |
| 货源增多 | 相对前期或预期，货源增加 |

### 2.8 变化因素（多选，必填）

- **至少选择 1 项**；可多选。  
- 选项：天气 / 节日 / 政策 / 供大于求 / 供不应求 / 其他产地冲击 / 产地抬价 / 其他  
- 列表、详情以中文标签展示，多项以顿号、逗号或标签组展示（与项目惯例一致）。

### 2.9 预测概率（三项，必填）

| 字段 | 规则 |
| --- | --- |
| **预测看涨概率** | **必填**；**正数**；单位为 **%**（界面标注「%」）；取值范围 **(0, 100]** |
| **预测看平概率** | 同上 |
| **预测看跌概率** | 同上 |
| **合计约束** | **看涨% + 看平% + 看跌% = 100%**（**默认建议**允许 ±0.01 浮点误差；或统一按整数百分比且合计必须为 100） |

- 任一项变更时，宜**实时校验合计**；不等 100% 时拒绝保存并提示「看涨、看平、看跌概率之和须为 100%」。  
- 草稿写「相加等于 1」在百分比语境下理解为 **100%**，本节以此为准。

### 2.10 出栏建议

- **必填**；多行文本（`textarea`）。  
- **默认建议**长度 **1～500** 字（去除首尾空白后计数）；仅空白视为未填。

### 2.11 删除与可见性

- 删除采用与项目其他业务台账一致的**逻辑删除**：删除后默认不在列表与常规查询中展示。  
- **本期不提供**回收站。  
- 若日度行情已被报表固化、分析任务引用等下游引用，**宜禁止删除**并提示原因（**默认建议禁止**）。

### 2.12 列表筛选项与记录字段的关系

| 筛选项 | 与记录字段关系 |
| --- | --- |
| 行情日期 | 选填；对「行情日期」**精确**匹配指定日，或提供**起止日期**区间（产品择一，**默认建议**支持单日 + 可选结束日区间） |
| 渠道（交易市场） | 选填；对登记时所选**渠道****精确**匹配 |
| 产地 | 选填；对省/市/县编码**精确**至所选层级，或按县编码精确（与级联组件回传一致） |

> **说明：** 草稿第 2 条「栏位编号模糊匹配、分页列市场栏位列表」为**笔误**（与市场栏位管理混淆），以原型及本节为准：列表对象为**日度行情**，筛选维度为**行情日期、渠道、产地**等（原型若另有筛选项，以原型增补）。

支持多条件**组合筛选**（同时满足）。

### 2.13 重复登记（业务约束）

**默认建议**：同一 **行情日期 + 产地（至县）+ 渠道 + 公母 + 重量 + 生长阶段 + 月龄 + 膘情** 组合在未删除记录中**仅允许一条**；重复保存时提示「该维度组合当日行情已存在」。  
若产品允许多条并存（如分时段报价），须评审后单独放开并更新本节。

---

## 3. 功能范围

**本期实现：**

| 能力 | 说明 |
| --- | --- |
| 日度行情列表 | 日期/渠道/产地等筛选；分页；见 **§5.2** |
| 新增日度行情 | 录入全部业务字段；见 **§5.1** |
| 修改日度行情 | 各业务字段均可改；见 **§5.3** |
| 查看详情 | 只读展示；见 **§5.4** |
| 删除日度行情 | 单条逻辑删除；见 **§5.5** |
| 工具栏 | 搜索、重置、新增 |

**本期不实现（除非后续单独立项）：**

- 行情自动采集、爬虫、第三方行情 API  
- 批量导入/导出、图表看板、同比环比自动分析  
- 按重量/月龄/膘情等多维度的列表筛选（原型未要求可不做）  
- 预测概率自动归一（用户须自行凑满 100%）  
- 与交易订单、结算单价自动回写  

---

## 4. 业务流程概览

### 4.1 总览

```mermaid
flowchart TD
    A[进入市场行情登记] --> B{用户操作}
    B -->|检索| C[选择日期/渠道/产地等]
    C --> D[搜索列表]
    B -->|登记| E[新增日度行情]
    E --> F[填写维度与价格等]
    F --> G{校验}
    G -->|通过| H[保存并刷新列表]
    G -->|未通过| E
    D --> I{行操作}
    I -->|查看| J[只读详情]
    I -->|编辑| K[修改表单]
    K --> G
    I -->|删除| L[二次确认]
    L -->|允许| M[逻辑删除]
    L -->|有关联| N[提示不可删]
    M --> D
    J --> D
    B -->|重置| O[清空筛选]
    O --> D
```

### 4.2 典型使用顺序

1. 维护好「交易市场管理」主数据后，运营人员按日 **新增** 行情：选昨天或指定日期、产地、渠道，填写牛只维度与价格、预测及出栏建议。  
2. 系统根据最低价、最高价 **自动计算均价**；录入三项预测概率并保证 **合计 100%**。  
3. 日常按 **日期、渠道、产地** 查询历史行情。  
4. 信息有误时 **修改** 对应记录（均价随价格区间联动重算）。  
5. 确认无下游引用后 **删除** 无效记录；需要完整字段时 **查看** 详情。

---

## 5. 详细功能需求

### 5.1 新增日度行情

#### 5.1.1 业务字段汇总

| 字段 | 必填 | 规则摘要 |
| --- | --- | --- |
| 行情日期 | 是 | YYYY-MM-DD；默认昨天；不宜晚于今天 |
| 产地 | 是 | 省/市/县三级，须选至县 |
| 渠道 | 是 | 单选；联动交易市场管理；宜仅可选「正常」市场 |
| 公母 | 是 | 公牛/母牛/公母混合；默认公牛 |
| 重量 | 否 | 七档重量单选 |
| 生长阶段 | 否 | 犊牛/架子牛/屠宰牛 |
| 月龄 | 否 | 七档月龄单选 |
| 膘情 | 否 | 43%/45%/50%/53% |
| 最低价、最高价 | 是 | 正数；最低价 ≤ 最高价 |
| 单位 | 是 | 元/头 或 元/斤；默认元/斤 |
| 均价 | 是 | 自动计算，不可手改（本期） |
| 出栏情况 | 是 | 货源充足/减少/增多 |
| 变化因素 | 是 | 多选，至少 1 项 |
| 预测看涨/看平/看跌概率 | 是 | 正数%；三者之和 = 100% |
| 出栏建议 | 是 | textarea；1～500 字（建议） |

#### 5.1.2 界面行为（与原型一致）

| 用户操作 | 界面行为 |
| --- | --- |
| 打开新增 | 行情日期默认「昨天」；公母默认「公牛」；单位默认「元/斤」；渠道下拉加载交易市场 |
| 选择渠道 | 展示市场名称；不可选停业/注销（默认建议） |
| 填写最低价/最高价 | 实时计算并展示均价 |
| 填写三项概率 | 实时或失焦校验合计是否为 100% |
| 变化因素 | 多选勾选；至少一项 |
| 保存 | 全部校验通过后提交 |

#### 5.1.3 保存与取消

| 操作 | 行为 |
| --- | --- |
| **确定** | 校验通过后保存；关闭弹窗并**刷新列表** |
| **取消** | 关闭弹窗，不保存 |

#### 5.1.4 校验摘要

| 规则 | 说明 |
| --- | --- |
| 必填与格式 | 见 **§5.1.1**；空白、非法日期、区划未选至县、渠道未选则拒绝 |
| 价格 | 正数；最低价 ≤ 最高价；均价有效 |
| 概率合计 | 看涨 + 看平 + 看跌 = 100% |
| 变化因素 | 至少 1 项 |
| 维度重复 | 符合 **§2.13** 时拒绝并提示 |

---

### 5.2 查询日度行情列表

#### 5.2.1 筛选

| 条件 | 规则 |
| --- | --- |
| 行情日期 | 选填；精确日或日期区间（**§2.12**） |
| 渠道 | 选填；精确匹配 |
| 产地 | 选填；与级联选定层级一致 |

#### 5.2.2 列表规则

- 默认每页 **20** 条。  
- 默认排序：**行情日期倒序**，同日按 **创建时间倒序**（**默认建议**）。  
- 工具栏：**搜索**、**重置**、**新增**。

#### 5.2.3 展示列（与原型一致，宜包含）

行情日期、产地（简写）、渠道（市场名称）、公母、重量、生长阶段、月龄、膘情、价格区间（最低价～最高价 + 单位）、均价、出栏情况、操作。

| 列 | 展示说明 |
| --- | --- |
| 价格 | 如 `10.00～12.00 元/斤` 或分列展示 |
| 均价 | 展示自动计算结果及单位 |
| 变化因素/概率/出栏建议 | 列表可省略或摘要；**详情**展示全量 |
| 操作 | 查看、编辑、删除 |

---

### 5.3 修改日度行情

| 项 | 要求 |
| --- | --- |
| 入口 | 列表「编辑」；详情可提供「编辑」 |
| 可改范围 | **§5.1.1** 全部字段（含行情日期、渠道、价格与概率） |
| 均价 | 随最低价、最高价变更**重新自动计算** |
| 校验 | 同 **§5.1.4**（含维度重复时排除自身 id） |
| 保存 | **确定** 保存并刷新；**取消** 放弃 |

---

### 5.4 查看日度行情详情

| 项 | 要求 |
| --- | --- |
| 展示内容 | **§5.1.1** 全部字段；变化因素完整标签；三项概率及合计；出栏建议全文 |
| 只读 | 全部不可编辑 |
| 操作 | 可提供 **编辑**、**删除**；**关闭** 返回 |
| 审计信息 | 宜含创建人、创建时间、修改人、修改时间 |

---

### 5.5 删除日度行情

| 项 | 要求 |
| --- | --- |
| 入口 | 列表「删除」；详情可提供「删除」 |
| 确认 | 删除前**二次确认**（宜展示行情日期 + 渠道 + 产地摘要） |
| 删除方式 | **逻辑删除**（**§2.11**） |
| 关联约束 | 存在下游引用时**拒绝删除** |
| 批量删除 | **本期不提供** |

---

## 6. 操作与权限矩阵（汇总）

在**已授权**前提下：

| 操作 | 列表/详情 | 说明 |
| --- | --- | --- |
| 查询列表、筛选 | 列表页 | 需列表查询权限 |
| 新增 | 「新增」 | 需新增权限 |
| 查看 | 行内/详情 | 需查看权限 |
| 修改 | 行内/详情 | 需修改权限 |
| 删除 | 行内/详情 | 需删除权限 |

无权限的按钮**不展示或禁用**（与若依按钮权限惯例一致）。

---

## 7. 与相关模块对照（便于评审）

| 维度 | 交易市场管理（畜牧流通） | 市场栏位管理 | 市场行情登记（本模块） |
| --- | --- | --- | --- |
| 数据性质 | 市场主档 | 栏位编号主档 | **按日行情快照** |
| 核心内容 | 名称、地址、状态 | 编号、备注 | 日期、产地、渠道、品类维度、价格、预测 |
| 外部联动 | — | — | **渠道**依赖交易市场主数据 |
| 区划 | 详细地址文本 | 无 | **省/市/县三级** |
| 计算字段 | 无 | 无 | **均价**自动计算 |
| 列表筛选 | 名称+状态 | 栏位编号模糊 | **日期+渠道+产地** |

---

## 8. 异常与提示（业务侧）

| 场景 | 提示方向（示例） |
| --- | --- |
| 行情日期为空/未来 | 请选择行情日期 / 行情日期不能晚于今天 |
| 产地未选至县 | 请选择至县级产地 |
| 渠道未选 | 请选择渠道（交易市场） |
| 无可用市场 | 请先在交易市场管理中维护正常状态的市场 |
| 价格非法 | 请输入有效的最低价和最高价 / 最低价不能大于最高价 |
| 均价无效 | 请完善价格区间以生成均价 |
| 概率合计≠100% | 看涨、看平、看跌概率之和须为 100% |
| 变化因素未选 | 请至少选择一项变化因素 |
| 出栏建议为空/超长 | 请输入出栏建议 / 出栏建议不能超过 N 字 |
| 维度重复 | 该维度组合当日行情已存在 |
| 删除受阻 | 存在关联业务，无法删除 |

**本期不涉及** HTTP 响应结构、错误码表等技术约定。

---

## 9. 非功能需求（摘要）

| 项 | 要求 |
| --- | --- |
| 易用性 | 新增默认昨天、公牛、元/斤；均价与概率校验有即时反馈 |
| 一致性 | 区划组件、逻辑删除、分页与项目其他模块一致 |
| 准确性 | 均价公式、概率合计规则在界面有说明或错误提示 |

---

## 10. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初稿：依据草稿与原型；日度行情 CRUD；渠道联动交易市场管理；均价=(最低+最高)/2；概率合计100%；修正草稿列表筛选笔误；剔除技术栈与接口格式 |