# 交易市场管理 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 交易市场管理（畜牧流通资源管理） |
| 目标 | 在业务后台维护**交易市场主数据**（名称、地址、负责人、联系方式、运营状态及市场照片等），支撑畜牧流通、进场登记、市场检索及后续业务按市场引用 |
| 关联系统 | 业务后台；本模块为交易市场**主档维护**，不替代场内交易开单、收费结算、与第三方地图服务深度集成等流程（若需联动，另出集成需求） |
| 修订依据 | 同目录 `交易市场管理-草稿.md`、界面原型（`交易市场管理.png`） |

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

---

## 2. 术语与业务对象

### 2.1 交易市场（一条台账记录）

- 表示畜牧流通体系中开展**活畜或相关产品交易活动**的一个**固定市场或管理单元**（如县级集散地、定点交易市场等）。  
- 由运营人员在后台**登记与维护**；保存成功后出现在交易市场列表，供后续业务按名称或主键引用。  
- 单条记录包含：**市场名称**、**详细地址**、**负责人**、**联系方式**、**运营状态**、**市场照片**（选填）及审计信息等。

### 2.2 运营状态（单选，必填）

表示市场当前是否对外开展交易及相关服务（与草稿、原型一致）：

| 运营状态 | 含义概要 | 默认 |
| --- | --- | --- |
| **正常** | 市场在营，可作为业务选点或展示为可用 | **是**（新增默认） |
| **停业** | 暂停营业，宜在列表中区分展示；下游宜限制新业务挂靠（规则由关联模块定义） |
| **注销** | 市场终止运营，宜在列表中区分展示；下游宜禁止新业务挂靠 |

- 界面以**下拉单选**展示；新增时默认 **正常**；修改时可切换。  
- 列表、详情展示对应中文标签。

### 2.3 市场照片

- **选填**；通过**单图上传**组件维护，一条记录对应 **0 或 1** 张展示用照片。  
- 允许后缀（白名单）：`jpg`、`jpeg`、`png`（`jpeg` 与 `jpg` 均允许）；单文件大小 ≤ **10 MB**。  
- 格式或大小不符时拒绝上传并提示；详情、编辑回显已上传图片（缩略图或预览）。  
- 删除记录或用户替换/清除照片时，宜同步清理已存储文件（与项目文件管理惯例一致）。

### 2.4 联系方式

- **必填**；**中国大陆手机号**格式校验（与项目全局规则一致，如 11 位、1 开头等）。

### 2.5 删除与可见性

- 删除采用与项目其他业务台账一致的**逻辑删除**：删除后默认不在列表与常规查询中展示，数据保留供审计。  
- **本期不提供**回收站界面。  
- 删除时**宜同时删除**关联的市场照片文件。  
- 若交易市场已被进场登记、流通单据、栏位挂靠等下游业务引用，**宜禁止删除**并提示「存在关联业务，无法删除」（**默认建议禁止**）。

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

| 筛选项 | 与记录字段关系 |
| --- | --- |
| 市场名称 | 选填；对「市场名称」**模糊**匹配（包含输入片段即可；空则不过滤） |
| 运营状态 | 选填；对「运营状态」**精确**匹配（下拉单选；空则不过滤） |

> **说明：** 草稿第 2 条「分页列检疫站列表」为笔误，以原型及本节为准，列表对象为**交易市场**，筛选维度为**市场名称 + 运营状态**。

支持**名称 + 运营状态**组合筛选（同时满足）。

---

## 3. 功能范围

**本期实现：**

| 能力 | 说明 |
| --- | --- |
| 交易市场列表 | 名称模糊、运营状态精确筛选；分页；见 **§5.2** |
| 新增交易市场 | 录入业务字段及可选照片；见 **§5.1** |
| 修改交易市场 | 各业务字段及照片均可改；见 **§5.3** |
| 查看详情 | 只读展示全部字段；见 **§5.4** |
| 删除交易市场 | 单条逻辑删除；见 **§5.5** |
| 工具栏 | 搜索、重置、新增 |

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

- **地图标点**、经纬度采集与地图展示（原型操作列若含入口，见 **§5.6**）  
- 批量导入/导出、多张照片相册  
- 与场内交易开单、收费结算自动联动  
- 按详细地址、负责人维度的列表筛选  
- 运营状态变更审批流  

---

## 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. 日常按**名称模糊**或**运营状态**查询台账。  
3. 市场信息变更（含停业、注销）时 **修改** 对应字段或更换照片。  
4. 确认无下游引用后 **删除** 无效市场。  
5. 核对完整信息时 **查看** 详情（含照片预览与审计信息）。

---

## 5. 详细功能需求

### 5.1 新增交易市场

#### 5.1.1 业务字段

| 字段 | 必填 | 规则摘要 |
| --- | --- | --- |
| 市场名称 | 是 | **1～10** 个字符；去除首尾空白后非空 |
| 详细地址 | 是 | 多行文本（`textarea`）；**1～200** 字（有内容时按 1～200 校验，评审可调） |
| 负责人 | 是 | **1～10** 个字符 |
| 联系方式 | 是 | 中国大陆手机号格式 |
| 运营状态 | 是 | **正常** / **停业** / **注销**；默认 **正常** |
| 市场照片 | 否 | 单图；`jpg`/`jpeg`/`png`；≤10 MB |

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

| 用户操作 | 界面行为 |
| --- | --- |
| 打开新增 | 运营状态默认「正常」；照片区域为空 |
| 上传照片 | 仅允许选择一张；超限或格式错误即时提示 |
| 保存 | 必填项、格式、长度校验通过后提交 |

#### 5.1.3 保存与取消

| 操作 | 行为 |
| --- | --- |
| **确定** | 校验通过后保存；关闭弹窗并**刷新列表** |
| **取消** | 关闭弹窗，不保存（已选未提交的照片不生效） |

#### 5.1.4 校验摘要

| 规则 | 说明 |
| --- | --- |
| 必填 | 名称、地址、负责人、联系方式、运营状态为空或仅空白时拒绝保存 |
| 名称唯一 | **默认建议**未删除记录间市场名称不可重复；重复时提示「市场名称已存在」 |
| 照片 | 后缀与大小符合 **§2.3** |

---

### 5.2 查询交易市场列表

#### 5.2.1 筛选

| 条件 | 规则 |
| --- | --- |
| 市场名称 | 选填；**模糊**匹配（**§2.6**） |
| 运营状态 | 选填；**精确**匹配 |

#### 5.2.2 列表规则

- 默认每页 **20** 条。  
- 默认排序：**创建时间倒序**（或 **市场名称升序**，产品择一后全文一致；**默认建议创建时间倒序**）。  
- 工具栏：**搜索**、**重置**、**新增**。

#### 5.2.3 展示列（与原型一致）

市场名称、详细地址、负责人、联系方式、运营状态、操作。

| 列 | 展示说明 |
| --- | --- |
| 市场名称 | 过长省略；详情可看全 |
| 详细地址 | 过长省略 |
| 运营状态 | 中文：正常 / 停业 / 注销 |
| 联系方式 | 是否脱敏按项目统一规范 |
| 操作 | 查看、编辑、删除；**地图标点**见 **§5.6** |

---

### 5.3 修改交易市场

| 项 | 要求 |
| --- | --- |
| 入口 | 列表「编辑」；详情可提供「编辑」 |
| 可改范围 | **§5.1.1** 全部字段（含运营状态、照片替换或清除） |
| 校验 | 同 **§5.1.4** |
| 保存 | **确定** 保存并刷新；**取消** 放弃 |

---

### 5.4 查看交易市场详情

| 项 | 要求 |
| --- | --- |
| 展示内容 | **§5.1.1** 全部字段；照片可预览；运营状态中文标签 |
| 只读 | 全部不可编辑 |
| 操作 | 可提供 **编辑**、**删除**（与列表权限一致）；**关闭** 返回 |
| 审计信息 | 宜含创建人、创建时间、修改人、修改时间 |

---

### 5.5 删除交易市场

| 项 | 要求 |
| --- | --- |
| 入口 | 列表「删除」；详情可提供「删除」 |
| 确认 | 删除前**二次确认**（宜展示市场名称） |
| 删除方式 | **逻辑删除**（**§2.5**） |
| 关联约束 | 存在下游引用时**拒绝删除**并提示原因 |
| 批量删除 | **本期不提供** |

---

### 5.6 地图标点（本期不实现）

- 列表操作列原型若含「**地图标点**」；**本期不实现**点位采集、地图展示与坐标存储。  
- 实施阶段操作列**不展示**该入口，或展示为置灰并提示「暂未开放」（与检疫站、牧场/草场管理惯例一致）。

---

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

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

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

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

---

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

| 维度 | 检疫站管理（同平台） | 交易市场平台·栏位/圈位类 | 交易市场管理（本模块） |
| --- | --- | --- | --- |
| 所属目录 | 畜牧流通资源管理 | 交易市场平台 | 畜牧流通资源管理 |
| 业务对象 | 检疫服务站点 | 场内编号资源（栏位、圈位等） | **交易市场实体** |
| 主键展示 | 用户录入名称 | 2 位自动编号 | **市场名称**（用户录入） |
| 核心字段 | 地址、负责人、手机、状态、照片 | 编号 + 备注（或隔离天数配置） | 地址、负责人、手机、状态、照片 |
| 列表筛选 | 名称模糊 + 状态精确 | 编号模糊 | 名称模糊 + 状态精确 |
| 附件 | 单图 ≤10 MB | 通常无 | **单图** ≤10 MB |

> **边界说明：** 「交易市场管理」维护的是**可独立引用的市场主档**；「交易市场平台」下模块维护的是**某一市场运营场景内的编号、供应商、承销商等**，二者不宜混为同一台账，引用关系由后续集成需求定义。

---

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

| 场景 | 提示方向（示例） |
| --- | --- |
| 名称超长/为空 | 市场名称为 1～10 个字符 / 请输入市场名称 |
| 地址为空/超长 | 请输入详细地址 / 详细地址长度不能超过 N 个字符 |
| 负责人为空/超长 | 请输入负责人 / 负责人长度为 1～10 个字符 |
| 手机号错误 | 请输入正确的手机号码 |
| 未选运营状态 | 请选择运营状态 |
| 名称重复 | 市场名称已存在 |
| 照片格式/大小 | 仅支持 jpg、jpeg、png / 图片大小不能超过 10MB |
| 删除受阻 | 存在关联业务，无法删除 |

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

---

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

| 项 | 要求 |
| --- | --- |
| 易用性 | 运营状态默认「正常」；照片上传限制在界面有明确提示 |
| 一致性 | 逻辑删除、分页、手机号校验与项目其他台账（含检疫站管理）一致 |
| 安全 | 联系方式、地址是否脱敏按项目统一规范 |

---

## 10. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初稿：依据草稿与原型；市场名称/地址/负责人/手机/运营状态/照片；列表名称模糊+状态精确；地图标点本期不做；剔除草稿中技术栈与接口格式描述；修正「检疫站列表」笔误 |