huimv-baqing/doc/产业数据模型及服务/牧场管理/牧场管理技术方案.md

牧场管理 — 技术方案

依据：同目录 牧场管理功能需求.md。第三方同步 + 分页列表 + 只读详情；不含手工 CRUD、地图标点。

---

1. 技术架构

项	说明
后端	RuoYi v3.9.2（springboot2 分支）：JDK 8、Spring Boot 2.x、Spring MVC、MyBatis、Druid
数据库	MySQL 5.7.39，InnoDB，utf8mb4
前端	若依 Vue2
第三方	生产管理系统开放接口 GET /open-api/v1/farming/farms（Apifox 文档见需求草稿）

分层：Controller → Service（列表/详情）→ PastureSyncService（同步编排）→ PastureSyncTxService（单条事务）→ ThirdPartyFarmClient → Mapper/XML。

代码位置：baqing-admin → com.ruoyi.web.modules.industryservice（BizPasture*、PastureSync*、ThirdPartyFarm*）。

业务摘要

场景	行为
同步	分页拉取第三方养殖场；按 external_id upsert；data_source=third_party
列表/详情	del_flag=0；排序 create_time DESC, id DESC；可按角色脱敏手机
并发	AtomicBoolean 防重入；重复同步抛「正在同步，请稍候」

配置（application.yml → third-party.farming，与牦牛资产等同源）

键	说明
enabled	是否启用同步
mode	stub：classpath thirdparty/stub-farms.json；http：远程接口
base-url	第三方根地址（http 模式）
app-key / app-secret	请求头 X-App-Key / X-App-Secret
page-size	分页大小，最大 200

---

2. 数据库设计

2.1 表 biz_pasture（类型对齐 OpenFarmVo）

接口字段	OpenAPI 类型	库字段	MySQL 类型
id	integer / int64	external_id	bigint(20)
farmName	string	pasture_name	varchar(128)
farmType	string	farm_type	varchar(64)
introduction	string	introduction	text
latitude	number	latitude	double
longitude	number	longitude	double
address	string	detail_address	varchar(512)
person	string	person_in_charge	varchar(64)
contactPhone	string	contact_phone	varchar(32)
county	string	county	varchar(128)
town	string	town	varchar(128)
floorArea	string	floor_area	varchar(128)
scaleBreeding	string	scale_breeding	varchar(128)
breedSpecies	string	breed_species	varchar(256)
createTime	string	create_time	datetime
remarks	string	remark	varchar(1000)

本地字段：id（自增主键）、data_source、last_sync_time、del_flag、审计字段。

DDL：sql/biz_pasture.sql（新库）；已有旧表先 sql/biz_pasture_sync_alter.sql 加列，再 sql/biz_pasture_drop_legacy_columns.sql 删历史列；刷新注释用 sql/biz_pasture_comment_alter.sql。

索引：uk_external_id；idx_pasture_name、idx_farm_type、idx_create_time。

---

3. 接口设计

统一响应：AjaxResult（code / msg / data）或分页 TableDataInfo（rows、total）。

权限标识：dataModel:pasture:list|query|sync

Base Path：/dataModel/pasture

#	说明	Method	URI	权限	要点
3.1	分页列表	GET	/list	dataModel:pasture:list	Query 3.1.1
3.2	详情	GET	/{id}	dataModel:pasture:query	全字段
3.3	同步	POST	/sync	dataModel:pasture:sync	返回 YakAssetSyncResultVo 结构

3.1.1 列表 Query

参数	类型	必填	说明
pageNum / pageSize	int	N	默认 1 / 20
keyword	string	N	牧场名称模糊
farmType	string	N	1 / 2 精确（对应 OpenFarmVo.farmType）

3.3.1 同步响应 data

字段	说明
insertCount	新增条数
updateCount	更新条数
failCount	失败条数
failMessages	失败明细
syncTime	同步完成时间

3.4 第三方开放接口（对接）

项	值
Method	GET
Path	/open-api/v1/farming/farms
Query	pageNum、pageSize（≤200）、可选 updatedAfter、farmName、farmType
Header	X-App-Key、X-App-Secret
响应	code=0 成功；data.records 为 OpenFarmVo 列表

---

4. 菜单与权限（示例）

类型	名称	权限标识
菜单	牧场管理	dataModel:pasture:list
按钮	查询	dataModel:pasture:query
按钮	同步	dataModel:pasture:sync

组件路径：dataModel/pasture/index。

---

5. 交付清单

• sql/biz_pasture.sql、sql/biz_pasture_sync_alter.sql
• BizPasture Domain / Mapper / Service / Controller
• ThirdPartyFarmClient、PastureSyncService、PastureSyncTxService
• thirdparty/stub-farms.json、third-party.farming 配置
• 单元测试 / MockMvc（列表、详情、同步）

---

6. 修订记录

版本	说明
1.0	初稿：本地 CRUD + 逻辑删除
2.0	对齐草稿：第三方同步；扩展表字段；移除 add/edit/remove 接口