对接牦牛资产档案

baqing-admin/src/main/java/com/ruoyi/web/modules/industryservice/controller/BizYakAssetController.java

@@ -65,6 +65,9 @@ public class BizYakAssetController extends BaseController
         return success(bizYakAssetService.selectDetailById(id));
     }
 
+    /**
+     * 触发牧业金融生物资产全量同步：养殖场 → 圈舍 → 生产计划 → 批次 → 入栏建档。
+     */
     @PreAuthorize("@ss.hasPermi('dataModel:yakAsset:sync')")
     @Log(title = "牦牛资产档案", businessType = BusinessType.OTHER)
     @PostMapping("/sync")

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

@@ -1,12 +1,17 @@
 package com.ruoyi.web.modules.industryservice.domain.dto;
 
 /**
- * 第三方「查询养殖圈舍列表」单条记录。
- * GET /open-api/v1/farming/enclosures
+ * 第三方「查询养殖圈舍列表」单条记录 DTO。
+ * <p>
+ * 对应 OpenAPI Schema {@code OpenFarmEnclosureVo}；
+ * 接口 {@code GET /open-api/v1/farming/enclosures}，落库 {@code biz_farm_enclosure}。
+ * </p>
  */
 public class OpenFarmEnclosureDto
 {
+    /** 第三方圈舍编号，落库 external_id */
     private Long id;
+    /** 第三方养殖场 ID，落库 farm_external_id 并解析 pasture_id */
     private Long farmId;
     private String farmName;
     private String enclosureName;

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

@@ -1,12 +1,17 @@
 package com.ruoyi.web.modules.industryservice.domain.dto;
 
 /**
- * 第三方「查询养殖批次列表」单条记录。
- * GET /open-api/v1/farming/batches
+ * 第三方「查询养殖批次列表」单条记录 DTO。
+ * <p>
+ * 接口 {@code GET /open-api/v1/farming/batches}，落库 {@code biz_farming_batch}。
+ * {@code batchNo} 与入栏建档 {@code entryCycle} 对应。
+ * </p>
  */
 public class OpenFarmingBatchDto
 {
+    /** 第三方批次主键 */
     private Long id;
+    /** 批次编号，业务唯一标识 */
     private String batchNo;
     private String batchName;
     private Long farmId;

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

@@ -1,12 +1,17 @@
 package com.ruoyi.web.modules.industryservice.domain.dto;
 
 /**
- * 第三方「查询养殖生产计划列表」单条记录。
- * GET /open-api/v1/farming/plans
+ * 第三方「查询养殖生产计划列表」单条记录 DTO。
+ * <p>
+ * 对应 {@code OpenFarmingPlanVo}；
+ * 接口 {@code GET /open-api/v1/farming/plans}，落库 {@code biz_farming_plan}。
+ * </p>
  */
 public class OpenFarmingPlanDto
 {
+    /** 第三方计划编号 */
     private Long id;
+    /** 所属养殖场 ID */
     private Long farmId;
     private Long regionId;
     private String regionName;

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

@@ -8,21 +8,36 @@ import com.ruoyi.web.modules.industryservice.domain.BizYakPhysioSeries;
 import com.ruoyi.web.modules.industryservice.domain.BizYakReproductionRecord;
 
 /**
- * 第三方同步单头牦牛数据包。
+ * 第三方同步「单头牦牛」数据包。
+ * <p>
+ * 由 {@link com.ruoyi.web.modules.industryservice.support.YakEntryOpenApiMapper} 从入栏建档 OpenAPI 构建，
+ * 经 {@link com.ruoyi.web.modules.industryservice.service.YakAssetBundleSyncTxService#persistBundle} 落库。
+ * </p>
+ *
+ * <h3>子表 null 语义</h3>
+ * <p>
+ * 各 List 字段为 {@code null} 表示本次同步<strong>不覆盖</strong>对应子表；
+ * 非 null（含空列表）则先删后插。当前入栏建档接口仅填充 {@link #asset}。
+ * </p>
  */
 public class YakAssetBundleDto
 {
+    /** 牦牛主表字段（biz_yak_asset） */
     private BizYakAsset asset;
 
+    /** 第三方养殖场 ID（farmId 字符串），用于解析 pasture_id */
     private String thirdPartyPastureCode;
 
-    /** null 表示本次同步不覆盖该子表 */
+    /** 生理时序；null=不同步 */
     private List<BizYakPhysioSeries> physioSeries;
 
+    /** 生长记录；null=不同步 */
     private List<BizYakGrowthRecord> growthRecords;
 
+    /** 繁殖记录；null=不同步 */
     private List<BizYakReproductionRecord> reproductionRecords;
 
+    /** 饲喂记录；null=不同步 */
     private List<BizYakFeedingRecord> feedingRecords;
 
     public BizYakAsset getAsset()

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

@@ -4,20 +4,44 @@ import java.util.Date;
 import com.fasterxml.jackson.annotation.JsonFormat;
 
 /**
- * 牧业金融生物资产全量同步结果（含基础数据 + 入栏建档）。
+ * 牧业金融生物资产<strong>全量同步</strong>结果 VO。
+ * <p>
+ * 由 {@link com.ruoyi.web.modules.industryservice.service.LivestockFinanceMasterSyncService#syncAll()} 返回，
+ * 包含五个步骤各自的新增/更新/失败统计。
+ * </p>
+ *
+ * <h3>字段说明</h3>
+ * <ul>
+ *   <li>{@code pasture} — 养殖场同步（biz_pasture）</li>
+ *   <li>{@code enclosure} — 圈舍同步（biz_farm_enclosure）</li>
+ *   <li>{@code plan} — 生产计划同步（biz_farming_plan）</li>
+ *   <li>{@code batch} — 批次同步（biz_farming_batch）</li>
+ *   <li>{@code yakAsset} — 入栏建档同步（biz_yak_asset）</li>
+ * </ul>
+ *
+ * <p>
+ * 顶层 {@link #getInsertCount()} 等 getter 为<strong>兼容旧前端</strong>，
+ * 取值自 {@code yakAsset} 步骤，便于列表页继续展示「新增/更新/失败头数」。
+ * </p>
  */
 public class LivestockFinanceSyncResultVo
 {
+    /** 步骤1：养殖场 */
     private YakAssetSyncResultVo pasture;
 
+    /** 步骤2：养殖圈舍 */
     private YakAssetSyncResultVo enclosure;
 
+    /** 步骤3：养殖生产计划 */
     private YakAssetSyncResultVo plan;
 
+    /** 步骤4：养殖批次 */
     private YakAssetSyncResultVo batch;
 
+    /** 步骤5：入栏建档（牦牛生物资产） */
     private YakAssetSyncResultVo yakAsset;
 
+    /** 全量同步开始时间 */
     @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
     private Date syncTime;
 
@@ -34,17 +58,19 @@ public class LivestockFinanceSyncResultVo
     public Date getSyncTime() { return syncTime; }
     public void setSyncTime(Date syncTime) { this.syncTime = syncTime; }
 
-    /** 兼容旧前端：汇总入栏建档同步条数 */
+    /** 兼容旧前端：入栏建档新增条数 */
     public int getInsertCount()
     {
         return yakAsset != null ? yakAsset.getInsertCount() : 0;
     }
 
+    /** 兼容旧前端：入栏建档更新条数 */
     public int getUpdateCount()
     {
         return yakAsset != null ? yakAsset.getUpdateCount() : 0;
     }
 
+    /** 兼容旧前端：入栏建档失败条数 */
     public int getFailCount()
     {
         return yakAsset != null ? yakAsset.getFailCount() : 0;

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

@@ -6,18 +6,27 @@ import java.util.List;
 import com.fasterxml.jackson.annotation.JsonFormat;
 
 /**
- * 第三方同步结果摘要。
+ * 第三方同步结果摘要（单步骤通用）。
+ * <p>
+ * 用于养殖场、圈舍、计划、批次、入栏建档等任一步骤的统计；
+ * 全量同步时嵌套在 {@link LivestockFinanceSyncResultVo} 各字段中。
+ * </p>
  */
 public class YakAssetSyncResultVo
 {
+    /** 本次同步新增条数 */
     private int insertCount;
 
+    /** 本次同步更新条数 */
     private int updateCount;
 
+    /** 本次同步失败条数（单条事务回滚，不影响已成功记录） */
     private int failCount;
 
+    /** 失败明细，格式：{@code 标识: 错误原因} */
     private List<String> failMessages = new ArrayList<>();
 
+    /** 本步骤同步完成时间 */
     @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
     private Date syncTime;
 

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

@@ -14,7 +14,15 @@ import com.ruoyi.web.modules.industryservice.support.PastureSyncRules;
 import com.ruoyi.web.modules.industryservice.support.ThirdPartyFarmClient;
 
 /**
- * 第三方养殖场同步编排。
+ * 第三方<strong>养殖场</strong>同步编排。
+ * <p>
+ * 接口：{@code GET /open-api/v1/farming/farms} → 落库 {@code biz_pasture}。
+ * 既可由牧场管理页 {@code POST /dataModel/pasture/sync} 单独触发，
+ * 也是 {@link LivestockFinanceMasterSyncService} 全量同步的<strong>第一步</strong>。
+ * </p>
+ * <p>
+ * 牦牛/圈舍/批次等数据的 {@code pasture_id} 解析均依赖本步骤先写入养殖场台账。
+ * </p>
  */
 @Service
 public class PastureSyncService
@@ -27,6 +35,9 @@ public class PastureSyncService
     @Autowired
     private PastureSyncTxService pastureSyncTxService;
 
+    /**
+     * 从第三方拉取全量养殖场并 upsert。
+     */
     public YakAssetSyncResultVo syncFromThirdParty()
     {
         if (!syncing.compareAndSet(false, true))

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

@@ -113,6 +113,11 @@ public class BizYakAssetServiceImpl implements IBizYakAssetService
         return chart;
     }
 
+    /**
+     * 牧业金融生物资产全量同步（含基础数据 + 入栏建档）。
+     *
+     * @see LivestockFinanceMasterSyncService#syncAll()
+     */
     @Override
     public LivestockFinanceSyncResultVo syncFromThirdParty()
     {

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

@@ -3,7 +3,12 @@ package com.ruoyi.web.modules.industryservice.support;
 import java.util.List;
 import com.ruoyi.web.modules.industryservice.domain.dto.OpenFarmEnclosureDto;
 
+/**
+ * 第三方养殖圈舍 HTTP 客户端。
+ * <p>接口：{@code GET /open-api/v1/farming/enclosures}</p>
+ */
 public interface ThirdPartyFarmEnclosureClient
 {
+    /** 分页拉取全量圈舍列表 */
     List<OpenFarmEnclosureDto> fetchAll();
 }

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

@@ -10,11 +10,20 @@ 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.OpenFarmEnclosureDto;
 
+/**
+ * 第三方养殖圈舍客户端实现。
+ * <p>
+ * {@code mode=http} 时调用 {@link ThirdPartyFarmingPageFetcher} 分页拉取；
+ * {@code mode=stub} 时读取 {@value #STUB_RESOURCE}。
+ * </p>
+ */
 @Component
 public class ThirdPartyFarmEnclosureClientImpl implements ThirdPartyFarmEnclosureClient
 {
+    /** Stub 样例：classpath:thirdparty/stub-farm-enclosures.json */
     private static final String STUB_RESOURCE = "thirdparty/stub-farm-enclosures.json";
 
+    /** 查询养殖圈舍列表（Apifox 开放接口） */
     private static final String LIST_PATH = "/open-api/v1/farming/enclosures";
 
     private final ObjectMapper objectMapper = ThirdPartyFarmingHttpSupport.createObjectMapper();

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

@@ -3,7 +3,12 @@ package com.ruoyi.web.modules.industryservice.support;
 import java.util.List;
 import com.ruoyi.web.modules.industryservice.domain.dto.OpenFarmingBatchDto;
 
+/**
+ * 第三方养殖批次 HTTP 客户端。
+ * <p>接口：{@code GET /open-api/v1/farming/batches}</p>
+ */
 public interface ThirdPartyFarmingBatchClient
 {
+    /** 分页拉取全量批次列表 */
     List<OpenFarmingBatchDto> fetchAll();
 }

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

@@ -10,6 +10,9 @@ 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.OpenFarmingBatchDto;
 
+/**
+ * 第三方养殖批次客户端实现。
+ */
 @Component
 public class ThirdPartyFarmingBatchClientImpl implements ThirdPartyFarmingBatchClient
 {

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

@@ -3,7 +3,12 @@ package com.ruoyi.web.modules.industryservice.support;
 import java.util.List;
 import com.ruoyi.web.modules.industryservice.domain.dto.OpenFarmingPlanDto;
 
+/**
+ * 第三方养殖生产计划 HTTP 客户端。
+ * <p>接口：{@code GET /open-api/v1/farming/plans}</p>
+ */
 public interface ThirdPartyFarmingPlanClient
 {
+    /** 分页拉取全量生产计划列表 */
     List<OpenFarmingPlanDto> fetchAll();
 }

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

@@ -10,6 +10,9 @@ 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.OpenFarmingPlanDto;
 
+/**
+ * 第三方养殖生产计划客户端实现。
+ */
 @Component
 public class ThirdPartyFarmingPlanClientImpl implements ThirdPartyFarmingPlanClient
 {

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

@@ -4,9 +4,14 @@ import java.util.List;
 import com.ruoyi.web.modules.industryservice.domain.dto.YakAssetBundleDto;
 
 /**
- * 第三方牦牛档案数据拉取。
+ * 第三方牦牛入栏建档 HTTP 客户端。
+ * <p>
+ * 接口：{@code GET /open-api/v1/farming/entry-filings}，
+ * 拉取后由 {@link YakEntryOpenApiMapper} 转为 {@link YakAssetBundleDto} 列表。
+ * </p>
  */
 public interface ThirdPartyYakClient
 {
+    /** 分页拉取全量入栏建档并映射为同步数据包 */
     List<YakAssetBundleDto> fetchAll();
 }

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

@@ -15,7 +15,27 @@ import com.ruoyi.web.modules.industryservice.domain.dto.OpenYakEntryDto;
 import com.ruoyi.web.modules.industryservice.domain.dto.YakAssetBundleDto;
 
 /**
- * 将第三方入栏建档 OpenAPI 记录映射为本地同步数据包。
+ * 将第三方入栏建档 OpenAPI 记录映射为本地同步数据包 {@link YakAssetBundleDto}。
+ * <p>
+ * 接口：{@code GET /open-api/v1/farming/entry-filings}，单条 Schema 为 {@link OpenYakEntryDto}。
+ * </p>
+ *
+ * <h3>主表字段映射（OpenYakEntryDto → BizYakAsset）</h3>
+ * <ul>
+ *   <li>cattleId / id → externalId</li>
+ *   <li>earTagNumber（优先）/ cattleNo → yakNo</li>
+ *   <li>farmId → thirdPartyPastureCode（字符串，供 pasture_id 解析）</li>
+ *   <li>farmName → pastureName</li>
+ *   <li>entryCycle（优先）/ batchId → batchNo</li>
+ *   <li>farmEnclosureName → penLocation</li>
+ *   <li>farmLocation → location</li>
+ *   <li>cattleSex → gender（规范为 公/母）</li>
+ *   <li>cattleSource → source</li>
+ *   <li>weight → entryWeightKg</li>
+ *   <li>entryTime / birthDate → entryDate / birthDate</li>
+ *   <li>fatherNumber / motherNumber → fatherYakNo / motherYakNo</li>
+ *   <li>remark → statusChangeReason</li>
+ * </ul>
  */
 public final class YakEntryOpenApiMapper
 {
@@ -27,6 +47,12 @@ public final class YakEntryOpenApiMapper
     {
     }
 
+    /**
+     * 单条入栏建档 → 同步数据包。
+     *
+     * @param dto 开放接口 records 中单条
+     * @return 含主表 asset 及 thirdPartyPastureCode；子表列表均为 null
+     */
     public static YakAssetBundleDto toBundle(OpenYakEntryDto dto)
     {
         if (dto == null)
@@ -38,6 +64,7 @@ public final class YakEntryOpenApiMapper
         {
             throw new ServiceException("牦牛编号不能为空");
         }
+        // external_id：优先 cattleId，其次档案 id
         Long externalId = dto.getCattleId() != null ? dto.getCattleId() : dto.getId();
         if (externalId == null)
         {
@@ -70,6 +97,7 @@ public final class YakEntryOpenApiMapper
         return bundle;
     }
 
+    /** 耳标号优先，其次牛只编号 */
     private static String resolveYakNo(OpenYakEntryDto dto)
     {
         if (StringUtils.isNotEmpty(dto.getEarTagNumber()))
@@ -83,6 +111,7 @@ public final class YakEntryOpenApiMapper
         return null;
     }
 
+    /** 入栏周期优先，其次 batchId 转字符串 */
     private static String resolveBatchNo(OpenYakEntryDto dto)
     {
         if (StringUtils.isNotEmpty(dto.getEntryCycle()))