# 牧场管理 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 牧场管理 |
| 目标 | 从第三方生产管理系统同步养殖场（牧场）基础信息，提供分页查询与只读详情，支撑产业数据体系中的主体台账与下游业务关联 |
| 关联系统 | 业务后台；第三方生产管理系统（开放接口） |
| 修订依据 | 同目录 `牧场管理功能需求-草稿.md`；字段参考 `20260611111807_454_398.jpg` |

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

---

## 2. 术语与枚举

### 2.1 牧场 / 养殖场

- 本模块以**第三方同步**的养殖主体为数据来源，单条记录表示一个养殖场（牧场）。  
- 本地**不提供**界面内手工新增、修改、删除；数据通过**同步**拉取或更新。  
- 删除采用**逻辑删除**字段保留能力；第三方同步写入时恢复为有效（`del_flag=0`）。

### 2.2 牧场性质 / 农场类型

第三方字段 `farmType` 为字符串；当取值为 `1`、`2` 时，分别对应：

| 取值 | 含义 |
| --- | --- |
| **1** | 个体 |
| **2** | 企业 |

列表筛选「牧场性质」按解析后的枚举**精确**匹配；无法解析时列表展示原始 `farmType` 文本。

### 2.3 字段对照（业务含义）

| 业务展示名 | 第三方字段 | 说明 |
| --- | --- | --- |
| 农场名称 | `farmName` | 列表关键字模糊匹配 |
| 农场类型 | `farmType` | 见 **§2.2** |
| 农场简介 | `introduction` | 详情只读 |
| 经度 / 纬度 | `longitude` / `latitude` | 详情只读；地图标点本期不做 |
| 详细地址 | `address` | 详情只读 |
| 负责人 | `person` | 可脱敏展示 |
| 联系电话 | `contactPhone` | 可脱敏展示 |
| 区县 / 乡镇 | `county` / `town` | 列表与详情展示 |
| 占地面积 | `floorArea` | 文本，第三方原样 |
| 养殖规模 | `scaleBreeding` | 文本，第三方原样 |
| 养殖品种 | `breedSpecies` | 文本，第三方原样 |
| 创建时间 | `createTime` | 首次同步写入；更新时保留原创建时间 |
| 备注 | `remarks` | 详情只读 |

### 2.4 数据来源

| 来源 | 说明 |
| --- | --- |
| 第三方生产管理系统 | **唯一写入来源**；用户点击**同步**全量分页拉取（接口：`GET /open-api/v1/farming/farms`） |
| 本系统手工维护 | **本期不提供** |

### 2.5 地图标点

**本期不实现**经纬度采集、地图展示与标点操作（见 **§3、§5.4**）。

---

## 3. 功能范围

**本期实现：**

| 能力 | 说明 |
| --- | --- |
| 牧场列表 | 牧场名称关键字模糊、牧场性质精确筛选；分页；见 **§5.1** |
| 查看详情 | 只读展示全部业务字段；见 **§5.2** |
| 数据同步 | 从第三方拉取/更新；见 **§5.3** |

**本期不实现：**

- 手工新增、修改、删除、照片上传、经营状态维护  
- 地图标点、坐标编辑  
- 导出（若需开放须单独约定）

---

## 4. 业务流程概览

```mermaid
flowchart LR
    A[同步第三方数据] --> B[列表查询/筛选]
    B --> C[查看详情]
    A --> B
```

1. **同步**：具备权限用户点击「同步」→ 调用第三方开放接口分页拉取 → 按第三方编号 upsert 本地台账。  
2. **查询**：按名称关键字、牧场性质筛选，分页浏览。  
3. **查阅**：查看单条记录全部字段（只读弹窗/抽屉）。

---

## 5. 详细功能需求

### 5.1 查询牧场列表

- **关键字：** 对「农场名称」（`farmName`）**模糊**匹配；为空不按名称过滤。  
- **农场类型：** **精确**匹配（`farmType` 为 `1`/`2` 时对应个体/企业）；未选不按类型过滤。  
- **逻辑删除：** 默认**不展示** `del_flag=2` 记录。  
- **分页：** 默认每页 **20** 条；支持重置查询条件。  
- **排序：** 默认按 **创建时间倒序**（`createTime DESC`）。  

**列表宜展示：** 农场名称、农场类型、区县、乡镇、负责人、联系方式（可脱敏）、创建时间、操作（查看）。

### 5.2 查看牧场详情

**须展示（只读）：** 农场名称、农场类型、农场简介、经度、纬度、详细地址、负责人、联系电话、区县、乡镇、占地面积、养殖规模、养殖品种、创建时间、备注；宜展示最近同步时间、数据来源。

- 敏感信息是否脱敏按项目安全规范与角色权限约定。  
- **不提供**从详情进入编辑。

### 5.3 数据同步

- **触发：** 列表页「同步」按钮；须 `dataModel:pasture:sync` 权限。  
- **行为：** 调用第三方 `GET /open-api/v1/farming/farms`，按 `pageNum`/`pageSize`（最大 200）分页直至取完；请求头携带 `X-App-Key`、`X-App-Secret`（由部署配置）。  
- **落库：** 以第三方 `id` 为唯一键 upsert；同名不同 id 视为不同主体。  
- **并发：** 同一时刻仅允许一次同步进行中；重复点击提示「正在同步，请稍候」。  
- **结果反馈：** 返回新增条数、更新条数、失败条数及同步完成时间；失败明细宜记录单条原因。  
- **第三方不可用：** 提示「第三方服务不可用」或接口返回的业务错误信息。

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

列表或详情**不展示**地图标点入口；经纬度字段仅作只读展示，供后续扩展。

---

## 6. 操作权限矩阵

| 操作 | 说明 |
| --- | --- |
| 查看列表 | `dataModel:pasture:list` |
| 查看详情 | `dataModel:pasture:query` |
| 同步 | `dataModel:pasture:sync` |
| 新增 / 修改 / 删除 | 本期无 |

---

## 7. 错误与提示约定

- 业务与校验错误采用项目统一的 **`code`、`msg`、`data`** 结构。  
- 常见提示：同步进行中、第三方不可用、同步结果摘要（新增/更新/失败）。

---

## 8. 非功能需求（建议）

| 类别 | 建议 |
| --- | --- |
| 权限 | 菜单与按钮：查询、同步 |
| 审计 | 同步操作记操作日志 |
| 性能 | 列表筛选满足后台通用体验；同步分页拉取避免单次过大 |
| 双语 | 字段标签符合项目 i18n（汉语 + 藏文） |
| 扩展 | 地图标点、增量 `updatedAfter` 同步、导出 |

---

## 9. 修订说明（相对上一版）

| 变更 | 处理 |
| --- | --- |
| 由本地 CRUD 改为第三方同步 | **§2.4、§3、§5.3** 明确唯一写入来源 |
| 字段集对齐开放接口 | **§2.3** 增加字段对照 |
| 去掉身份证、区划级联、照片、经营状态维护 | 自 **§5** 移除相关手工录入需求 |
| 新增同步按钮与权限 | **§5.3、§6** |
| 地图标点仍不做 | **§2.5、§5.4** |