交易市场平台（供应商）

baqing-admin/src/main/java/com/ruoyi/web/modules/industryservice/domain/BizYakAsset.java

@@ -14,6 +14,9 @@ public class BizYakAsset extends BaseEntity
 
     private Long id;
 
+    /** 第三方牛只唯一 ID（OpenYakEntryDto.cattleId） */
+    private Long externalId;
+
     private String yakNo;
 
     private Long pastureId;
@@ -85,6 +88,16 @@ public class BizYakAsset extends BaseEntity
         this.id = id;
     }
 
+    public Long getExternalId()
+    {
+        return externalId;
+    }
+
+    public void setExternalId(Long externalId)
+    {
+        this.externalId = externalId;
+    }
+
     public String getYakNo()
     {
         return yakNo;

baqing-admin/src/main/java/com/ruoyi/web/modules/industryservice/domain/dto/OpenYakEntryDto.java

@@ -0,0 +1,312 @@
+package com.ruoyi.web.modules.industryservice.domain.dto;
+
+/**
+ * 第三方开放接口「查询入栏建档列表」单条记录 DTO。
+ * <p>
+ * 响应路径 {@code data.records[]}（分页包装 {@code OpenApiPageResult}）。
+ * 接口：{@code GET /open-api/v1/farming/entry-filings}。
+ * </p>
+ *
+ * @see com.ruoyi.web.modules.industryservice.domain.BizYakAsset
+ */
+public class OpenYakEntryDto
+{
+    /** 档案主键 ID */
+    private Long id;
+
+    /** 所属农场 ID，落库关联 biz_pasture.external_id */
+    private Long farmId;
+
+    /** 农场名称，落库 pasture_name */
+    private String farmName;
+
+    /** 所属圈舍 ID */
+    private Long farmEnclosureId;
+
+    /** 圈舍名称，落库 pen_location */
+    private String farmEnclosureName;
+
+    /** 所属养殖批次 ID */
+    private Long batchId;
+
+    /** 入栏批次周期，落库 batch_no（优先于 batchId） */
+    private String entryCycle;
+
+    /** 农场地理位置，落库 location */
+    private String farmLocation;
+
+    /** 牛只唯一 ID，落库 external_id */
+    private Long cattleId;
+
+    /** 场内牛只编号 */
+    private String cattleNo;
+
+    /** 耳标编号（溯源标识），落库 yak_no（优先于 cattleNo） */
+    private String earTagNumber;
+
+    /** 牛只品种 */
+    private String cattleVariety;
+
+    /** 牛只性别，落库 gender */
+    private String cattleSex;
+
+    /** 牛只来源（自繁/外购），落库 source */
+    private String cattleSource;
+
+    /** 父牛谱系编号，落库 father_yak_no */
+    private String fatherNumber;
+
+    /** 母牛谱系编号，落库 mother_yak_no */
+    private String motherNumber;
+
+    /** 当前体重，落库 entry_weight_kg */
+    private Double weight;
+
+    /** 牛只照片 URL（本期不落库） */
+    private String cattlePicture;
+
+    /** 档案登记人（本期不落库） */
+    private String registrant;
+
+    /** 入栏时间，落库 entry_date */
+    private String entryTime;
+
+    /** 出生日期，落库 birth_date */
+    private String birthDate;
+
+    /** 档案创建时间 */
+    private String createTime;
+
+    /** 备注，落库 status_change_reason */
+    private String remark;
+
+    public Long getId()
+    {
+        return id;
+    }
+
+    public void setId(Long id)
+    {
+        this.id = id;
+    }
+
+    public Long getFarmId()
+    {
+        return farmId;
+    }
+
+    public void setFarmId(Long farmId)
+    {
+        this.farmId = farmId;
+    }
+
+    public String getFarmName()
+    {
+        return farmName;
+    }
+
+    public void setFarmName(String farmName)
+    {
+        this.farmName = farmName;
+    }
+
+    public Long getFarmEnclosureId()
+    {
+        return farmEnclosureId;
+    }
+
+    public void setFarmEnclosureId(Long farmEnclosureId)
+    {
+        this.farmEnclosureId = farmEnclosureId;
+    }
+
+    public String getFarmEnclosureName()
+    {
+        return farmEnclosureName;
+    }
+
+    public void setFarmEnclosureName(String farmEnclosureName)
+    {
+        this.farmEnclosureName = farmEnclosureName;
+    }
+
+    public Long getBatchId()
+    {
+        return batchId;
+    }
+
+    public void setBatchId(Long batchId)
+    {
+        this.batchId = batchId;
+    }
+
+    public String getEntryCycle()
+    {
+        return entryCycle;
+    }
+
+    public void setEntryCycle(String entryCycle)
+    {
+        this.entryCycle = entryCycle;
+    }
+
+    public String getFarmLocation()
+    {
+        return farmLocation;
+    }
+
+    public void setFarmLocation(String farmLocation)
+    {
+        this.farmLocation = farmLocation;
+    }
+
+    public Long getCattleId()
+    {
+        return cattleId;
+    }
+
+    public void setCattleId(Long cattleId)
+    {
+        this.cattleId = cattleId;
+    }
+
+    public String getCattleNo()
+    {
+        return cattleNo;
+    }
+
+    public void setCattleNo(String cattleNo)
+    {
+        this.cattleNo = cattleNo;
+    }
+
+    public String getEarTagNumber()
+    {
+        return earTagNumber;
+    }
+
+    public void setEarTagNumber(String earTagNumber)
+    {
+        this.earTagNumber = earTagNumber;
+    }
+
+    public String getCattleVariety()
+    {
+        return cattleVariety;
+    }
+
+    public void setCattleVariety(String cattleVariety)
+    {
+        this.cattleVariety = cattleVariety;
+    }
+
+    public String getCattleSex()
+    {
+        return cattleSex;
+    }
+
+    public void setCattleSex(String cattleSex)
+    {
+        this.cattleSex = cattleSex;
+    }
+
+    public String getCattleSource()
+    {
+        return cattleSource;
+    }
+
+    public void setCattleSource(String cattleSource)
+    {
+        this.cattleSource = cattleSource;
+    }
+
+    public String getFatherNumber()
+    {
+        return fatherNumber;
+    }
+
+    public void setFatherNumber(String fatherNumber)
+    {
+        this.fatherNumber = fatherNumber;
+    }
+
+    public String getMotherNumber()
+    {
+        return motherNumber;
+    }
+
+    public void setMotherNumber(String motherNumber)
+    {
+        this.motherNumber = motherNumber;
+    }
+
+    public Double getWeight()
+    {
+        return weight;
+    }
+
+    public void setWeight(Double weight)
+    {
+        this.weight = weight;
+    }
+
+    public String getCattlePicture()
+    {
+        return cattlePicture;
+    }
+
+    public void setCattlePicture(String cattlePicture)
+    {
+        this.cattlePicture = cattlePicture;
+    }
+
+    public String getRegistrant()
+    {
+        return registrant;
+    }
+
+    public void setRegistrant(String registrant)
+    {
+        this.registrant = registrant;
+    }
+
+    public String getEntryTime()
+    {
+        return entryTime;
+    }
+
+    public void setEntryTime(String entryTime)
+    {
+        this.entryTime = entryTime;
+    }
+
+    public String getBirthDate()
+    {
+        return birthDate;
+    }
+
+    public void setBirthDate(String birthDate)
+    {
+        this.birthDate = birthDate;
+    }
+
+    public String getCreateTime()
+    {
+        return createTime;
+    }
+
+    public void setCreateTime(String createTime)
+    {
+        this.createTime = createTime;
+    }
+
+    public String getRemark()
+    {
+        return remark;
+    }
+
+    public void setRemark(String remark)
+    {
+        this.remark = remark;
+    }
+}

baqing-admin/src/main/java/com/ruoyi/web/modules/industryservice/domain/dto/YakAssetBundleDto.java

@@ -1,6 +1,5 @@
 package com.ruoyi.web.modules.industryservice.domain.dto;
 
-import java.util.ArrayList;
 import java.util.List;
 import com.ruoyi.web.modules.industryservice.domain.BizYakAsset;
 import com.ruoyi.web.modules.industryservice.domain.BizYakBatchRel;
@@ -19,17 +18,18 @@ public class YakAssetBundleDto
 
     private String thirdPartyPastureCode;
 
-    private List<BizYakPhysioSeries> physioSeries = new ArrayList<>();
+    /** null 表示本次同步不覆盖该子表 */
+    private List<BizYakPhysioSeries> physioSeries;
 
-    private List<BizYakGrowthRecord> growthRecords = new ArrayList<>();
+    private List<BizYakGrowthRecord> growthRecords;
 
-    private List<BizYakReproductionRecord> reproductionRecords = new ArrayList<>();
+    private List<BizYakReproductionRecord> reproductionRecords;
 
-    private List<BizYakFeedingRecord> feedingRecords = new ArrayList<>();
+    private List<BizYakFeedingRecord> feedingRecords;
 
-    private List<BizYakPenRel> penRecords = new ArrayList<>();
+    private List<BizYakPenRel> penRecords;
 
-    private List<BizYakBatchRel> batchRecords = new ArrayList<>();
+    private List<BizYakBatchRel> batchRecords;
 
     public BizYakAsset getAsset()
     {

baqing-admin/src/main/java/com/ruoyi/web/modules/industryservice/mapper/BizYakAssetMapper.java

@@ -9,6 +9,8 @@ public interface BizYakAssetMapper
 
     BizYakAsset selectBizYakAssetByYakNo(String yakNo);
 
+    BizYakAsset selectBizYakAssetByExternalId(Long externalId);
+
     List<BizYakAsset> selectBizYakAssetList(BizYakAsset query);
 
     int insertBizYakAsset(BizYakAsset row);

baqing-admin/src/main/java/com/ruoyi/web/modules/industryservice/service/YakAssetBundleSyncTxService.java

@@ -77,7 +77,7 @@ public class YakAssetBundleSyncTxService
             incoming.setAssetStatus(YakAssetStatusMapper.normalizeLegacyNumericStatus(incoming.getAssetStatus()));
             YakAssetValidation.validateAssetStatus(incoming.getAssetStatus());
         }
-        resolvePasture(incoming);
+        resolvePasture(incoming, bundle);
         if (incoming.getBirthDate() != null)
         {
             incoming.setAgeMonths(YakAssetValidation.resolveAgeMonths(incoming.getBirthDate(), syncTime));
@@ -85,7 +85,7 @@ public class YakAssetBundleSyncTxService
         incoming.setLastSyncTime(syncTime);
         incoming.setDelFlag(YakAssetRules.DEL_FLAG_NORMAL);
 
-        BizYakAsset existing = bizYakAssetMapper.selectBizYakAssetByYakNo(yakNo);
+        BizYakAsset existing = resolveExisting(incoming);
         Long yakAssetId;
         boolean inserted;
         if (existing == null)
@@ -105,10 +105,35 @@ public class YakAssetBundleSyncTxService
         return inserted;
     }
 
-    private void resolvePasture(BizYakAsset incoming)
+    private BizYakAsset resolveExisting(BizYakAsset incoming)
+    {
+        if (incoming.getExternalId() != null)
+        {
+            BizYakAsset byExternal = bizYakAssetMapper.selectBizYakAssetByExternalId(incoming.getExternalId());
+            if (byExternal != null)
+            {
+                return byExternal;
+            }
+        }
+        return bizYakAssetMapper.selectBizYakAssetByYakNo(incoming.getYakNo());
+    }
+
+    private void resolvePasture(BizYakAsset incoming, YakAssetBundleDto bundle)
     {
         BizPasture pasture = null;
-        if (StringUtils.isNotEmpty(incoming.getPastureName()))
+        if (bundle != null && StringUtils.isNotEmpty(bundle.getThirdPartyPastureCode()))
+        {
+            try
+            {
+                Long farmId = Long.parseLong(bundle.getThirdPartyPastureCode().trim());
+                pasture = bizPastureMapper.selectBizPastureByExternalId(farmId);
+            }
+            catch (NumberFormatException ignored)
+            {
+                // 非数字编码时回退名称匹配
+            }
+        }
+        if (pasture == null && StringUtils.isNotEmpty(incoming.getPastureName()))
         {
             pasture = bizPastureMapper.selectBizPastureByExactName(incoming.getPastureName().trim());
         }
@@ -125,12 +150,30 @@ public class YakAssetBundleSyncTxService
 
     private void replaceChildRows(Long yakAssetId, YakAssetBundleDto bundle)
     {
-        physioSeriesMapper.deleteByYakAssetId(yakAssetId);
-        growthRecordMapper.deleteByYakAssetId(yakAssetId);
-        reproductionRecordMapper.deleteByYakAssetId(yakAssetId);
-        feedingRecordMapper.deleteByYakAssetId(yakAssetId);
-        penRelMapper.deleteByYakAssetId(yakAssetId);
-        batchRelMapper.deleteByYakAssetId(yakAssetId);
+        if (bundle.getPhysioSeries() != null)
+        {
+            physioSeriesMapper.deleteByYakAssetId(yakAssetId);
+        }
+        if (bundle.getGrowthRecords() != null)
+        {
+            growthRecordMapper.deleteByYakAssetId(yakAssetId);
+        }
+        if (bundle.getReproductionRecords() != null)
+        {
+            reproductionRecordMapper.deleteByYakAssetId(yakAssetId);
+        }
+        if (bundle.getFeedingRecords() != null)
+        {
+            feedingRecordMapper.deleteByYakAssetId(yakAssetId);
+        }
+        if (bundle.getPenRecords() != null || StringUtils.isNotEmpty(bundle.getAsset().getPenLocation()))
+        {
+            penRelMapper.deleteByYakAssetId(yakAssetId);
+        }
+        if (bundle.getBatchRecords() != null || StringUtils.isNotEmpty(bundle.getAsset().getBatchNo()))
+        {
+            batchRelMapper.deleteByYakAssetId(yakAssetId);
+        }
 
         if (!CollectionUtils.isEmpty(bundle.getPhysioSeries()))
         {

baqing-admin/src/main/java/com/ruoyi/web/modules/industryservice/support/ThirdPartyYakClientImpl.java

@@ -2,6 +2,7 @@ package com.ruoyi.web.modules.industryservice.support;
 
 import java.io.InputStream;
 import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -11,23 +12,29 @@ import org.springframework.http.HttpHeaders;
 import org.springframework.http.HttpMethod;
 import org.springframework.http.ResponseEntity;
 import org.springframework.stereotype.Component;
+import org.springframework.util.CollectionUtils;
 import org.springframework.util.StreamUtils;
+import org.springframework.util.StringUtils;
 import org.springframework.web.client.RestClientException;
 import org.springframework.web.client.RestTemplate;
+import org.springframework.web.util.UriComponentsBuilder;
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.ruoyi.common.exception.ServiceException;
+import com.ruoyi.web.modules.industryservice.domain.dto.OpenApiPageResult;
+import com.ruoyi.web.modules.industryservice.domain.dto.OpenApiResponse;
+import com.ruoyi.web.modules.industryservice.domain.dto.OpenYakEntryDto;
 import com.ruoyi.web.modules.industryservice.domain.dto.YakAssetBundleDto;
 
 /**
- * 第三方牦牛资产客户端：stub 读取 classpath JSON；http 调用同源开放接口。
+ * 第三方牦牛资产客户端：stub 读取 OpenAPI 样例；http 分页调用入栏建档列表。
  */
 @Component
 public class ThirdPartyYakClientImpl implements ThirdPartyYakClient
 {
-    private static final String STUB_RESOURCE = "thirdparty/stub-yak-bundles.json";
+    private static final String STUB_RESOURCE = "thirdparty/stub-yak-entries.json";
 
-    /** 入栏建档列表（与牧场接口同平台，路径以 Apifox 文档为准） */
+    /** 查询入栏建档列表（Apifox 文档） */
     private static final String LIST_PATH = "/open-api/v1/farming/entry-filings";
 
     private final ObjectMapper objectMapper = ThirdPartyFarmingHttpSupport.createObjectMapper();
@@ -42,14 +49,19 @@ public class ThirdPartyYakClientImpl implements ThirdPartyYakClient
         {
             throw new ServiceException("第三方牦牛数据同步未启用");
         }
+        List<OpenYakEntryDto> entries;
         if ("http".equalsIgnoreCase(properties.getMode()))
         {
-            return fetchFromHttp();
+            entries = fetchFromHttp();
         }
-        return fetchFromStub();
+        else
+        {
+            entries = fetchFromStub();
+        }
+        return YakEntryOpenApiMapper.toBundles(entries);
     }
 
-    private List<YakAssetBundleDto> fetchFromStub()
+    private List<OpenYakEntryDto> fetchFromStub()
     {
         try
         {
@@ -61,49 +73,86 @@ public class ThirdPartyYakClientImpl implements ThirdPartyYakClient
             try (InputStream in = resource.getInputStream())
             {
                 String json = StreamUtils.copyToString(in, StandardCharsets.UTF_8);
-                return objectMapper.readValue(json, new TypeReference<List<YakAssetBundleDto>>()
+                return objectMapper.readValue(json, new TypeReference<List<OpenYakEntryDto>>()
                 {
                 });
             }
         }
+        catch (ServiceException e)
+        {
+            throw e;
+        }
         catch (Exception e)
         {
             throw new ServiceException("读取第三方样例数据失败：" + e.getMessage());
         }
     }
 
-    private List<YakAssetBundleDto> fetchFromHttp()
+    private List<OpenYakEntryDto> fetchFromHttp()
     {
         ThirdPartyFarmingHttpSupport.requireBaseUrl(properties, "第三方生产管理系统 base-url 未配置");
         RestTemplate restTemplate = ThirdPartyFarmingHttpSupport.createRestTemplate(properties);
         HttpHeaders headers = ThirdPartyFarmingHttpSupport.buildOpenApiHeaders(properties);
-        String url = ThirdPartyFarmingHttpSupport.resolveUrl(properties, LIST_PATH);
-        try
+        List<OpenYakEntryDto> all = new ArrayList<>();
+        int pageNum = 1;
+        int pageSize = Math.min(Math.max(properties.getPageSize(), 1), 200);
+        Long total = null;
+        while (true)
         {
-            ResponseEntity<String> response = restTemplate.exchange(
-                    url,
-                    HttpMethod.GET,
-                    new HttpEntity<>(headers),
-                    String.class);
-            if (!response.getStatusCode().is2xxSuccessful() || response.getBody() == null)
+            String url = UriComponentsBuilder.fromHttpUrl(ThirdPartyFarmingHttpSupport.resolveUrl(properties, LIST_PATH))
+                    .queryParam("pageNum", pageNum)
+                    .queryParam("pageSize", pageSize)
+                    .toUriString();
+            try
             {
-                throw new ServiceException("第三方接口返回异常");
+                ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.GET,
+                        new HttpEntity<>(headers), String.class);
+                if (!response.getStatusCode().is2xxSuccessful() || response.getBody() == null)
+                {
+                    throw new ServiceException("第三方接口返回异常");
+                }
+                OpenApiResponse<OpenApiPageResult<OpenYakEntryDto>> body = objectMapper.readValue(response.getBody(),
+                        new TypeReference<OpenApiResponse<OpenApiPageResult<OpenYakEntryDto>>>()
+                        {
+                        });
+                if (body == null || body.getCode() == null || body.getCode() != 0)
+                {
+                    String msg = body != null && StringUtils.hasText(body.getMessage()) ? body.getMessage() : "业务失败";
+                    throw new ServiceException("第三方接口：" + msg);
+                }
+                OpenApiPageResult<OpenYakEntryDto> page = body.getData();
+                if (page == null || CollectionUtils.isEmpty(page.getRecords()))
+                {
+                    break;
+                }
+                all.addAll(page.getRecords());
+                if (total == null && page.getTotal() != null)
+                {
+                    total = page.getTotal();
+                }
+                if (page.getRecords().size() < pageSize)
+                {
+                    break;
+                }
+                if (total != null && all.size() >= total)
+                {
+                    break;
+                }
+                pageNum++;
             }
-            return objectMapper.readValue(response.getBody(), new TypeReference<List<YakAssetBundleDto>>()
+            catch (ServiceException e)
             {
-            });
-        }
-        catch (RestClientException e)
-        {
-            throw new ServiceException("第三方服务不可用：" + e.getMessage());
-        }
-        catch (ServiceException e)
-        {
-            throw e;
-        }
-        catch (Exception e)
-        {
-            throw new ServiceException("解析第三方数据失败：" + e.getMessage());
+                throw e;
+            }
+            catch (RestClientException e)
+            {
+                throw new ServiceException("第三方服务不可用：" + e.getMessage());
+            }
+            catch (Exception e)
+            {
+                throw new ServiceException("解析第三方数据失败：" + e.getMessage());
+            }
         }
+        return all;
     }
 }

baqing-admin/src/main/java/com/ruoyi/web/modules/industryservice/support/YakEntryOpenApiMapper.java

@@ -0,0 +1,214 @@
+package com.ruoyi.web.modules.industryservice.support;
+
+import java.math.BigDecimal;
+import java.text.ParseException;
+import java.text.SimpleDateFormat;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Date;
+import java.util.List;
+import java.util.TimeZone;
+import com.ruoyi.common.exception.ServiceException;
+import com.ruoyi.common.utils.StringUtils;
+import com.ruoyi.web.modules.industryservice.domain.BizYakAsset;
+import com.ruoyi.web.modules.industryservice.domain.BizYakBatchRel;
+import com.ruoyi.web.modules.industryservice.domain.BizYakPenRel;
+import com.ruoyi.web.modules.industryservice.domain.dto.OpenYakEntryDto;
+import com.ruoyi.web.modules.industryservice.domain.dto.YakAssetBundleDto;
+
+/**
+ * 将第三方入栏建档 OpenAPI 记录映射为本地同步数据包。
+ */
+public final class YakEntryOpenApiMapper
+{
+    private static final SimpleDateFormat DATE_TIME = createDateTimeFormat();
+
+    private static final SimpleDateFormat DATE_ONLY = createDateOnlyFormat();
+
+    private YakEntryOpenApiMapper()
+    {
+    }
+
+    public static YakAssetBundleDto toBundle(OpenYakEntryDto dto)
+    {
+        if (dto == null)
+        {
+            throw new ServiceException("同步数据无效");
+        }
+        String yakNo = resolveYakNo(dto);
+        if (StringUtils.isEmpty(yakNo))
+        {
+            throw new ServiceException("牦牛编号不能为空");
+        }
+        Long externalId = dto.getCattleId() != null ? dto.getCattleId() : dto.getId();
+        if (externalId == null)
+        {
+            throw new ServiceException("第三方牛只 ID 不能为空");
+        }
+
+        BizYakAsset asset = new BizYakAsset();
+        asset.setExternalId(externalId);
+        asset.setYakNo(yakNo);
+        asset.setPastureName(trimToNull(dto.getFarmName()));
+        asset.setBatchNo(resolveBatchNo(dto));
+        asset.setGender(normalizeGender(dto.getCattleSex()));
+        asset.setBirthDate(parseDate(dto.getBirthDate()));
+        asset.setEntryDate(parseDate(dto.getEntryTime()));
+        asset.setEntryWeightKg(toBigDecimal(dto.getWeight()));
+        asset.setSource(trimToNull(dto.getCattleSource()));
+        asset.setPenLocation(trimToNull(dto.getFarmEnclosureName()));
+        asset.setLocation(trimToNull(dto.getFarmLocation()));
+        asset.setFatherYakNo(trimToNull(dto.getFatherNumber()));
+        asset.setMotherYakNo(trimToNull(dto.getMotherNumber()));
+        asset.setStatusChangeReason(trimToNull(dto.getRemark()));
+        asset.setAssetStatus(YakAssetRules.ASSET_STATUS_MIN);
+
+        YakAssetBundleDto bundle = new YakAssetBundleDto();
+        bundle.setAsset(asset);
+        if (dto.getFarmId() != null)
+        {
+            bundle.setThirdPartyPastureCode(String.valueOf(dto.getFarmId()));
+        }
+        bundle.setPenRecords(buildPenRecords(dto));
+        bundle.setBatchRecords(buildBatchRecords(dto, asset.getBatchNo()));
+        return bundle;
+    }
+
+    private static String resolveYakNo(OpenYakEntryDto dto)
+    {
+        if (StringUtils.isNotEmpty(dto.getEarTagNumber()))
+        {
+            return dto.getEarTagNumber().trim();
+        }
+        if (StringUtils.isNotEmpty(dto.getCattleNo()))
+        {
+            return dto.getCattleNo().trim();
+        }
+        return null;
+    }
+
+    private static String resolveBatchNo(OpenYakEntryDto dto)
+    {
+        if (StringUtils.isNotEmpty(dto.getEntryCycle()))
+        {
+            return dto.getEntryCycle().trim();
+        }
+        if (dto.getBatchId() != null)
+        {
+            return String.valueOf(dto.getBatchId());
+        }
+        return null;
+    }
+
+    private static String normalizeGender(String cattleSex)
+    {
+        if (StringUtils.isEmpty(cattleSex))
+        {
+            return null;
+        }
+        String sex = cattleSex.trim();
+        if ("1".equals(sex) || "M".equalsIgnoreCase(sex) || "公".equals(sex))
+        {
+            return "公";
+        }
+        if ("2".equals(sex) || "F".equalsIgnoreCase(sex) || "母".equals(sex))
+        {
+            return "母";
+        }
+        return sex;
+    }
+
+    private static List<BizYakPenRel> buildPenRecords(OpenYakEntryDto dto)
+    {
+        if (StringUtils.isEmpty(dto.getFarmEnclosureName()))
+        {
+            return null;
+        }
+        BizYakPenRel pen = new BizYakPenRel();
+        pen.setPenName(dto.getFarmEnclosureName().trim());
+        return Collections.singletonList(pen);
+    }
+
+    private static List<BizYakBatchRel> buildBatchRecords(OpenYakEntryDto dto, String batchNo)
+    {
+        String resolved = batchNo;
+        if (StringUtils.isEmpty(resolved))
+        {
+            return null;
+        }
+        BizYakBatchRel batch = new BizYakBatchRel();
+        batch.setBatchNo(resolved);
+        return Collections.singletonList(batch);
+    }
+
+    public static List<YakAssetBundleDto> toBundles(List<OpenYakEntryDto> entries)
+    {
+        if (entries == null || entries.isEmpty())
+        {
+            return Collections.emptyList();
+        }
+        List<YakAssetBundleDto> bundles = new ArrayList<>(entries.size());
+        for (OpenYakEntryDto entry : entries)
+        {
+            bundles.add(toBundle(entry));
+        }
+        return bundles;
+    }
+
+    private static BigDecimal toBigDecimal(Double value)
+    {
+        return value == null ? null : BigDecimal.valueOf(value);
+    }
+
+    private static String trimToNull(String value)
+    {
+        if (StringUtils.isEmpty(value))
+        {
+            return null;
+        }
+        return value.trim();
+    }
+
+    private static Date parseDate(String value)
+    {
+        if (StringUtils.isEmpty(value))
+        {
+            return null;
+        }
+        String text = value.trim();
+        try
+        {
+            synchronized (DATE_TIME)
+            {
+                if (text.length() > 10)
+                {
+                    return DATE_TIME.parse(text);
+                }
+            }
+            synchronized (DATE_ONLY)
+            {
+                return DATE_ONLY.parse(text);
+            }
+        }
+        catch (ParseException e)
+        {
+            return null;
+        }
+    }
+
+    private static SimpleDateFormat createDateTimeFormat()
+    {
+        SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
+        df.setTimeZone(TimeZone.getTimeZone("GMT+8"));
+        df.setLenient(false);
+        return df;
+    }
+
+    private static SimpleDateFormat createDateOnlyFormat()
+    {
+        SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd");
+        df.setTimeZone(TimeZone.getTimeZone("GMT+8"));
+        df.setLenient(false);
+        return df;
+    }
+}

baqing-admin/src/main/resources/mapper/industryservice/BizYakAssetMapper.xml

@@ -4,6 +4,7 @@
 
     <resultMap type="com.ruoyi.web.modules.industryservice.domain.BizYakAsset" id="BizYakAssetResult">
         <id     property="id"                 column="id"/>
+        <result property="externalId"         column="external_id"/>
         <result property="yakNo"              column="yak_no"/>
         <result property="pastureId"          column="pasture_id"/>
         <result property="pastureName"        column="pasture_name"/>
@@ -35,7 +36,7 @@
     </resultMap>
 
     <sql id="selectVo">
-        select id, yak_no, pasture_id, pasture_name, batch_no, gender, birth_date, age_months,
+        select id, external_id, yak_no, pasture_id, pasture_name, batch_no, gender, birth_date, age_months,
                entry_date, entry_weight_kg, source, breeding_method, asset_status, status_change_date,
                status_change_reason, pen_location, expected_out_date, supplement_plan,
                realtime_temp, realtime_steps, env_temp, location, physio_collect_time,
@@ -53,6 +54,11 @@
         where yak_no = #{yakNo} and del_flag = '0'
     </select>
 
+    <select id="selectBizYakAssetByExternalId" parameterType="long" resultMap="BizYakAssetResult">
+        <include refid="selectVo"/>
+        where external_id = #{externalId} and del_flag = '0'
+    </select>
+
     <select id="selectBizYakAssetList" parameterType="com.ruoyi.web.modules.industryservice.domain.BizYakAsset" resultMap="BizYakAssetResult">
         <include refid="selectVo"/>
         <where>
@@ -69,13 +75,13 @@
 
     <insert id="insertBizYakAsset" parameterType="com.ruoyi.web.modules.industryservice.domain.BizYakAsset" useGeneratedKeys="true" keyProperty="id">
         insert into biz_yak_asset (
-            yak_no, pasture_id, pasture_name, batch_no, gender, birth_date, age_months,
+            external_id, yak_no, pasture_id, pasture_name, batch_no, gender, birth_date, age_months,
             entry_date, entry_weight_kg, source, breeding_method, asset_status, status_change_date,
             status_change_reason, pen_location, expected_out_date, supplement_plan,
             realtime_temp, realtime_steps, env_temp, location, physio_collect_time,
             father_yak_no, mother_yak_no, last_sync_time, del_flag, create_time
         ) values (
-            #{yakNo}, #{pastureId}, #{pastureName}, #{batchNo}, #{gender}, #{birthDate}, #{ageMonths},
+            #{externalId}, #{yakNo}, #{pastureId}, #{pastureName}, #{batchNo}, #{gender}, #{birthDate}, #{ageMonths},
             #{entryDate}, #{entryWeightKg}, #{source}, #{breedingMethod}, #{assetStatus}, #{statusChangeDate},
             #{statusChangeReason}, #{penLocation}, #{expectedOutDate}, #{supplementPlan},
             #{realtimeTemp}, #{realtimeSteps}, #{envTemp}, #{location}, #{physioCollectTime},
@@ -85,6 +91,8 @@
 
     <update id="updateBizYakAsset" parameterType="com.ruoyi.web.modules.industryservice.domain.BizYakAsset">
         update biz_yak_asset set
+            external_id = #{externalId},
+            yak_no = #{yakNo},
             pasture_id = #{pastureId},
             pasture_name = #{pastureName},
             batch_no = #{batchNo},

baqing-admin/src/main/resources/thirdparty/stub-yak-bundles.json

@@ -1,78 +0,0 @@
-[
-  {
-    "thirdPartyPastureCode": "P001",
-    "asset": {
-      "yakNo": "YAK20250001",
-      "pastureName": "示范牧场",
-      "batchNo": "B2025-01",
-      "gender": "母",
-      "birthDate": "2023-06-01",
-      "entryDate": "2023-08-01",
-      "entryWeightKg": 85.5,
-      "source": "自繁",
-      "breedingMethod": "半舍饲",
-      "assetStatus": 1,
-      "statusChangeDate": "2025-05-01",
-      "statusChangeReason": "入栏饲养",
-      "penLocation": "1号圈舍",
-      "expectedOutDate": "2026-10-01",
-      "supplementPlan": "冬季补饲青贮+精料",
-      "realtimeTemp": 38.6,
-      "realtimeSteps": 3200,
-      "envTemp": 12.5,
-      "location": "东经91.0,北纬32.0",
-      "fatherYakNo": "YAK-F001",
-      "motherYakNo": "YAK-M001"
-    },
-    "physioSeries": [
-      {
-        "collectTime": "2025-05-18 08:00:00",
-        "bodyTemp": 38.5,
-        "steps": 3100,
-        "envTemp": 11.0
-      }
-    ],
-    "growthRecords": [
-      {
-        "dayAge": 365,
-        "weightKg": 220.0,
-        "heightCm": 120.0,
-        "chestCm": 150.0,
-        "lengthCm": 130.0,
-        "collectTime": "2025-05-01 10:00:00",
-        "dataKind": 1
-      },
-      {
-        "dayAge": 400,
-        "weightKg": 235.0,
-        "collectTime": "2025-06-01 10:00:00",
-        "dataKind": 2
-      }
-    ],
-    "reproductionRecords": [
-      {
-        "calvingDate": "2024-08-15",
-        "dayAge": 300,
-        "parity": 1,
-        "calvingIntervalDays": 0,
-        "calfCount": 1,
-        "liveCalfCount": 1,
-        "calfSurvivalRate": 1.0,
-        "calfBirthWeightKg": 25.0,
-        "dystociaFlag": "0"
-      }
-    ],
-    "feedingRecords": [
-      {
-        "feedTarget": "个体",
-        "startDayAge": 0,
-        "endDayAge": 90,
-        "feedType": "青贮",
-        "totalSupplementKg": 45.0,
-        "dailySupplementKg": 0.5
-      }
-    ],
-    "penRecords": [{ "penName": "1号圈舍" }],
-    "batchRecords": [{ "batchNo": "B2025-01" }]
-  }
-]

baqing-admin/src/main/resources/thirdparty/stub-yak-entries.json

@@ -0,0 +1,25 @@
+[
+  {
+    "id": 1001,
+    "farmId": 1,
+    "farmName": "示范牧场",
+    "farmEnclosureId": 11,
+    "farmEnclosureName": "1号圈舍",
+    "batchId": 202501,
+    "entryCycle": "B2025-01",
+    "farmLocation": "东经91.0,北纬32.0",
+    "cattleId": 90001,
+    "cattleNo": "YAK20250001",
+    "earTagNumber": "YAK20250001",
+    "cattleVariety": "牦牛",
+    "cattleSex": "母",
+    "cattleSource": "自繁",
+    "fatherNumber": "YAK-F001",
+    "motherNumber": "YAK-M001",
+    "weight": 220.0,
+    "entryTime": "2023-08-01 10:00:00",
+    "birthDate": "2023-06-01",
+    "createTime": "2023-08-01 10:00:00",
+    "remark": "入栏建档样例"
+  }
+]

baqing-admin/src/test/java/com/ruoyi/web/modules/industryservice/support/YakEntryOpenApiMapperTest.java

@@ -0,0 +1,57 @@
+package com.ruoyi.web.modules.industryservice.support;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+
+import java.math.BigDecimal;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import com.ruoyi.web.modules.industryservice.domain.BizYakAsset;
+import com.ruoyi.web.modules.industryservice.domain.dto.OpenYakEntryDto;
+import com.ruoyi.web.modules.industryservice.domain.dto.YakAssetBundleDto;
+
+@DisplayName("YakEntryOpenApiMapper")
+class YakEntryOpenApiMapperTest
+{
+    @Test
+    @DisplayName("OpenAPI 字段映射到 biz_yak_asset")
+    void mapsOpenApiFields()
+    {
+        OpenYakEntryDto dto = new OpenYakEntryDto();
+        dto.setCattleId(90001L);
+        dto.setEarTagNumber("ET-001");
+        dto.setCattleNo("CN-001");
+        dto.setFarmId(1L);
+        dto.setFarmName("示范牧场");
+        dto.setFarmEnclosureName("1号圈舍");
+        dto.setEntryCycle("B2025-01");
+        dto.setFarmLocation("东经91.0,北纬32.0");
+        dto.setCattleSex("母");
+        dto.setCattleSource("自繁");
+        dto.setFatherNumber("F-01");
+        dto.setMotherNumber("M-01");
+        dto.setWeight(220.5);
+        dto.setEntryTime("2023-08-01 10:00:00");
+        dto.setBirthDate("2023-06-01");
+        dto.setRemark("测试备注");
+
+        YakAssetBundleDto bundle = YakEntryOpenApiMapper.toBundle(dto);
+        BizYakAsset asset = bundle.getAsset();
+        assertNotNull(asset);
+        assertEquals(90001L, asset.getExternalId());
+        assertEquals("ET-001", asset.getYakNo());
+        assertEquals("示范牧场", asset.getPastureName());
+        assertEquals("B2025-01", asset.getBatchNo());
+        assertEquals("母", asset.getGender());
+        assertEquals("自繁", asset.getSource());
+        assertEquals("1号圈舍", asset.getPenLocation());
+        assertEquals("东经91.0,北纬32.0", asset.getLocation());
+        assertEquals("F-01", asset.getFatherYakNo());
+        assertEquals("M-01", asset.getMotherYakNo());
+        assertEquals(new BigDecimal("220.5"), asset.getEntryWeightKg());
+        assertEquals("测试备注", asset.getStatusChangeReason());
+        assertEquals("1", bundle.getThirdPartyPastureCode());
+        assertEquals(1, bundle.getPenRecords().size());
+        assertEquals(1, bundle.getBatchRecords().size());
+    }
+}

doc/产业数据模型及服务/牧业金融生物资产管理/牦牛资产档案管理功能需求.md

@@ -133,12 +133,14 @@ flowchart TD
 | --- | --- |
 | 触发 | 用户点击「同步」；定时任务是否启用另定 |
 | 权限 | 仅同步权限角色可执行 |
-| 合并键 | 以**牦牛编号**为准：有则更新，无则新增 |
-| 范围 | 默认拉取授权范围内档案；是否按牧场勾选同步，评审确认 |
+| 数据源 | 第三方生产管理系统开放接口 `GET /open-api/v1/farming/entry-filings`（入栏建档列表，字段见草稿 `20260611111807_455_398.jpg`） |
+| 鉴权 | 与牧场管理同源：`third-party.farming` 配置 `base-url`、`app-key`、`app-secret` |
+| 合并键 | 优先以第三方 **cattleId**（`external_id`）upsert；辅以 **耳标编号 earTagNumber**（无则 cattleNo）作为 `yak_no` |
+| 范围 | 分页拉取（`pageNum`/`pageSize`≤200）直至取完 |
 | 反馈 | 结束提示成功/失败及摘要（新增/更新/失败条数） |
-| 牧场映射 | 「所属牧场」与牧场主数据或第三方编码映射；无法映射时展示第三方名称或「未关联」 |
+| 牧场映射 | `farmId` 关联 `biz_pasture.external_id`；失败则冗余 `farmName`，展示「未关联」 |
 | 失败 | 第三方超时、鉴权失败等须明确提示，**不得**误删或清空已有档案 |
-| 子数据 | 同步宜覆盖详情八块相关数据（基础、系谱、生理时序、生长、繁殖、饲喂、圈舍、批次） |
+| 子数据 | **本期列表接口**同步主表 + 圈舍/批次关联；生理/生长/繁殖/饲喂等子表待详情接口对接后增量覆盖（未返回的子表不清空） |
 
 同步成功后，列表与详情展示最近一次成功结果；列表宜可展示「数据截至：最近同步时间」类提示（**§8**）。
 
@@ -324,6 +326,7 @@ flowchart TD
 | 生长「切换+预测」 | §5.5（4）曲线模式单独说明 |
 | 生理与曲线图关系 | §5.5（3）区分当前值与近一月曲线 |
 | 列表缺分页、重置 | §5.1、§5.2 |
+| 入栏建档 OpenAPI 对接 | §5.3 明确 `entry-filings` 接口、字段映射与 `external_id` 合并键 |
 
 ---
 

doc/产业数据模型及服务/牧业金融生物资产管理/牦牛资产档案管理技术方案.md

@@ -36,7 +36,8 @@
 | 字段 | 类型 | 非空 | 说明 |
 | --- | --- | --- | --- |
 | `id` | `bigint(20)` | Y | 主键 |
-| `yak_no` | `varchar(64)` | Y | 牦牛编号，**唯一** |
+| `external_id` | `bigint(20)` | N | 第三方牛只 ID（`OpenYakEntryDto.cattleId`），**唯一** |
+| `yak_no` | `varchar(64)` | Y | 牦牛编号（优先 `earTagNumber`），**唯一** |
 | `pasture_id` | `bigint(20)` | N | 关联 `biz_pasture.id`（映射成功时） |
 | `pasture_name` | `varchar(128)` | N | 所属牧场名称（同步冗余展示） |
 | `batch_no` | `varchar(64)` | N | 批次编号 |
@@ -64,7 +65,30 @@
 | `del_flag` | `char(1)` | Y | `0` 存在 `2` 删除 |
 | `create_time` / `update_time` | datetime | — | 审计 |
 
-**索引**：`UNIQUE uk_yak_no (yak_no)`；`KEY idx_asset_status`；`KEY idx_pasture_id`；`KEY idx_status_change_date`；`KEY idx_last_sync_time`；`KEY idx_del_flag`。
+**索引**：`UNIQUE uk_external_id (external_id)`；`UNIQUE uk_yak_no (yak_no)`；`KEY idx_asset_status`；`KEY idx_pasture_id`；`KEY idx_status_change_date`；`KEY idx_last_sync_time`；`KEY idx_del_flag`。
+
+#### 2.1.1 第三方入栏建档字段映射（`OpenYakEntryDto` → `biz_yak_asset`）
+
+| OpenAPI 字段 | 库字段 | 说明 |
+| --- | --- | --- |
+| `cattleId` | `external_id` | 同步 upsert 主键 |
+| `earTagNumber` / `cattleNo` | `yak_no` | 优先耳标 |
+| `farmId` | `pasture_id` | 经 `biz_pasture.external_id` 解析 |
+| `farmName` | `pasture_name` | 冗余展示 |
+| `entryCycle` / `batchId` | `batch_no` | 优先 `entryCycle` |
+| `farmEnclosureName` | `pen_location` | 并写入 `biz_yak_pen_rel` |
+| `farmLocation` | `location` | |
+| `cattleSex` | `gender` | 归一公/母 |
+| `cattleSource` | `source` | |
+| `fatherNumber` | `father_yak_no` | |
+| `motherNumber` | `mother_yak_no` | |
+| `weight` | `entry_weight_kg` | 当前体重 |
+| `entryTime` | `entry_date` | |
+| `birthDate` | `birth_date` | 月龄由同步时计算写入 `age_months` |
+| `remark` | `status_change_reason` | |
+| `id` / `cattlePicture` / `registrant` / `cattleVariety` | — | 本期不落库 |
+
+列表接口未返回的字段（`asset_status`、实时体温/运动量等）保持库内原值或默认「正常」。
 
 ### 2.2 子表 `biz_yak_physio_series`（生理时序，曲线图）
 
@@ -253,13 +277,14 @@ CREATE TABLE `biz_yak_asset` (
 
 | 项 | 说明 |
 | --- | --- |
-| 配置 | `application.yml`：`third-party.farming`（与牧场管理同源：`base-url`、`app-key`、`app-secret`、超时） |
-| 客户端 | `ThirdPartyYakClient.fetchAll()` → `List<YakAssetBundleDTO>`（主表+子表） |
-| 映射 | `YakAssetStatusMapper`：第三方状态码 → `asset_status` |
-| 牧场 | 第三方牧场编码 → `biz_pasture`；失败则仅写 `pasture_name` |
-| 事务 | 每头牦牛一个事务：更新主表 → 删子表 → 批量插子表 |
-| 并发 | 同步接口加分布式锁或 `synchronized`，防止重复点击并发同步 |
-| 异步 | 数据量大时改 `@Async` + 轮询任务状态（可选，需求层建议） |
+| 配置 | `application.yml`：`third-party.farming`（与牧场管理同源） |
+| 接口 | `GET /open-api/v1/farming/entry-filings`；分页 `OpenApiPageResult<OpenYakEntryDto>` |
+| 客户端 | `ThirdPartyYakClientImpl` → `YakEntryOpenApiMapper.toBundles()` → `YakAssetBundleSyncTxService` |
+| 映射 | 字段对照 **§2.1.1**；`YakAssetStatusMapper` 供后续含状态字段的接口 |
+| 牧场 | `farmId` → `biz_pasture.external_id`；失败则仅写 `farmName` |
+| 事务 | 每头牦牛独立事务（`REQUIRES_NEW`）；子表仅当 bundle 携带对应列表时覆盖 |
+| Stub | `thirdparty/stub-yak-entries.json`（OpenAPI 记录样例） |
+| 并发 | `synchronized` 防重复点击 |
 
 ### 3.8 查询约定
 
@@ -296,3 +321,4 @@ CREATE TABLE `biz_yak_asset` (
 | 版本 | 说明 |
 | --- | --- |
 | 1.0 | 初稿：主表+四子表；只读查询+同步接口；生长实测/预测分 `data_kind`；对接可配置 |
+| 1.1 | 对齐入栏建档 OpenAPI：`OpenYakEntryDto`、`external_id`、分页拉取、字段映射 **§2.1.1** |

doc/产业数据模型及服务/牧业金融生物资产管理/牦牛资产档案管理测试用例.md

@@ -3,9 +3,9 @@
 > 依据：`牦牛资产档案管理功能需求.md`、`牦牛资产档案管理技术方案.md`  
 > **接口 Base Path（示例）**：`/dataModel/yakAsset`；若含 `context-path` 或网关前缀须补齐。鉴权与若依一致（Cookie / Token）。
 
-**通用前置（无特殊说明）**：具备本模块菜单与按钮权限的账号已登录；库中已有经同步或造数的档案样本（主表 `biz_yak_asset`，`del_flag=0`）。**资产状态**（`asset_status`）：`1` 正常、`2` 死淘、`3` 丢失、`4` 出栏。**生长数据种类**（`data_kind`）：`1` 实测、`2` 预测。详情含扩展基础字段及 `penRecords`、`batchRecords`。
+**通用前置（无特殊说明）**：具备本模块菜单与按钮权限的账号已登录；开发环境 `third-party.farming.mode=stub` 可使用 `stub-yak-entries.json`。库中已有经同步或造数的档案样本（主表 `biz_yak_asset`，`del_flag=0`）。**资产状态**（`asset_status`）：`1` 正常、`2` 死淘、`3` 丢失、`4` 出栏。
 
-**样本约定（示例）**：`yakNo=YAK20250001`；`assetStatus=2`；父编号 `YAK-F001`、母编号 `YAK-M001` 且库内存在可跳转；至少一头含生理时序、生长实测+预测、繁殖、饲喂子表数据。
+**样本约定（示例）**：`externalId=90001`，`yakNo=YAK20250001`（耳标）；`farmId=1` 对应已同步牧场；父编号 `YAK-F001`、母编号 `YAK-M001`。
 
 **界面（UI）测试**：**Playwright** + **Chromium**（`channel: 'chrome'` 使用本机 **Google Chrome**）。菜单路径以 `livestockFinance/yakAsset/index` 为准。
 
@@ -19,8 +19,9 @@
 | ZCZX-MYNZDA-UT-002 | 状态映射 | 非法本地状态 | 单元测试 | JUnit5 | 1～4 | 无 | `assetStatus` 为 0、5、null | 列表入参校验失败 |
 | ZCZX-MYNZDA-UT-003 | 月龄计算 | 由出生日期计算 | 单元测试 | JUnit5 | §2.4 | `birthDate=2024-01-15` | `resolveAgeMonths(固定今日)` | 月龄与约定算法一致（月差或四舍五入规则固定） |
 | ZCZX-MYNZDA-UT-004 | 列表校验 | 关键字 trim | 单元测试 | JUnit5 | 模糊查询 | 无 | `keyword` 含前后空格 | trim 后参与 `LIKE` |
-| ZCZX-MYNZDA-UT-005 | 同步合并 | 按 yak_no 新增 | 单元测试 | JUnit5+Mockito | §5.3 | DB 无该编号 | `syncBundle(yakNo 新)` | `insert` 主表；子表批量插入 |
-| ZCZX-MYNZDA-UT-006 | 同步合并 | 按 yak_no 更新 | 单元测试 | JUnit5+Mockito | §5.3 | DB 已有同编号 | `syncBundle` 字段变更 | `update` 主表；子表先删后插 |
+| ZCZX-MYNZDA-UT-005 | 同步合并 | 按 external_id 新增 | 单元测试 | JUnit5+Mockito | §5.3 | DB 无该 cattleId | `syncBundle` 新记录 | `insert` 主表；圈舍/批次关联写入 |
+| ZCZX-MYNZDA-UT-006 | 同步合并 | 按 external_id 更新 | 单元测试 | JUnit5+Mockito | §5.3 | DB 已有同 cattleId | `syncBundle` 字段变更 | `update` 主表；圈舍/批次覆盖 |
+| ZCZX-MYNZDA-UT-006A | OpenAPI 映射 | 入栏建档字段 | 单元测试 | JUnit5 | §2.1.1 | `OpenYakEntryDto` 样例 | `YakEntryOpenApiMapper.toBundle` | `yak_no`=耳标；`farmId`→牧场编码；字段与表一致 |
 | ZCZX-MYNZDA-UT-007 | 同步安全 | 失败不清库 | 单元测试 | JUnit5+Mockito | §5.3 | 已有档案 A | Mock 第三方抛超时；执行 sync | 档案 A 主表及子表条数不变 |
 | ZCZX-MYNZDA-UT-008 | 同步安全 | 单头失败不回滚全局 | 单元测试 | JUnit5+Mockito | 事务边界 | 批次含 2 头，第 2 头校验失败 | `syncAll` | 第 1 头成功落库；`failCount≥1`；第 1 头数据保留 |
 | ZCZX-MYNZDA-UT-009 | 牧场映射 | 映射成功写 pasture_id | 单元测试 | JUnit5+Mockito | §5.3 | `biz_pasture` 有匹配编码 | 同步带第三方牧场码 | `pasture_id` 非空；`pasture_name` 与主数据一致 |

sql/biz_yak_asset.sql

@@ -3,7 +3,8 @@ SET NAMES utf8mb4;
 
 CREATE TABLE IF NOT EXISTS `biz_yak_asset` (
   `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
-  `yak_no` varchar(64) NOT NULL COMMENT '牦牛编号',
+  `external_id` bigint(20) DEFAULT NULL COMMENT '第三方牛只唯一ID OpenYakEntryDto.cattleId',
+  `yak_no` varchar(64) NOT NULL COMMENT '牦牛编号（优先耳标 earTagNumber）',
   `pasture_id` bigint(20) DEFAULT NULL COMMENT '牧场ID',
   `pasture_name` varchar(128) DEFAULT NULL COMMENT '所属牧场名称',
   `batch_no` varchar(64) DEFAULT NULL COMMENT '批次编号',
@@ -32,6 +33,7 @@ CREATE TABLE IF NOT EXISTS `biz_yak_asset` (
   `create_time` datetime DEFAULT NULL COMMENT '创建时间',
   `update_time` datetime DEFAULT NULL COMMENT '更新时间',
   PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_external_id` (`external_id`),
   UNIQUE KEY `uk_yak_no` (`yak_no`),
   KEY `idx_asset_status` (`asset_status`),
   KEY `idx_pasture_id` (`pasture_id`),