# 牧场管理 — 技术方案

> 依据：同目录 `牧场管理功能需求.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. 交付清单

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

---

## 6. 修订记录

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