西藏巴青项目

牧场管理功能需求.md 6.6KB

牧场管理 — 功能需求

1. 文档说明

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

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


2. 术语与枚举

2.1 牧场 / 养殖场

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

2.2 牧场性质 / 农场类型

第三方字段 farmType 为字符串;当取值为 12 时,分别对应:

取值 含义
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
  1. 同步:具备权限用户点击「同步」→ 调用第三方开放接口分页拉取 → 按第三方编号 upsert 本地台账。
  2. 查询:按名称关键字、牧场性质筛选,分页浏览。
  3. 查阅:查看单条记录全部字段(只读弹窗/抽屉)。

5. 详细功能需求

5.1 查询牧场列表

  • 关键字: 对「农场名称」(farmName模糊匹配;为空不按名称过滤。
  • 农场类型: 精确匹配(farmType1/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-KeyX-App-Secret(由部署配置)。
  • 落库: 以第三方 id 为唯一键 upsert;同名不同 id 视为不同主体。
  • 并发: 同一时刻仅允许一次同步进行中;重复点击提示「正在同步,请稍候」。
  • 结果反馈: 返回新增条数、更新条数、失败条数及同步完成时间;失败明细宜记录单条原因。
  • 第三方不可用: 提示「第三方服务不可用」或接口返回的业务错误信息。

5.4 地图标点(本期不实现)

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


6. 操作权限矩阵

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

7. 错误与提示约定

  • 业务与校验错误采用项目统一的 codemsgdata 结构。
  • 常见提示:同步进行中、第三方不可用、同步结果摘要(新增/更新/失败)。

8. 非功能需求(建议)

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

9. 修订说明(相对上一版)

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