西藏巴青项目

牧场管理 — 功能需求

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. 业务流程概览

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

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

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

牧场管理功能需求.md 6.6KB Историја Датотека