对接牦牛资产档案

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

@@ -9,9 +9,22 @@ import com.ruoyi.web.modules.industryservice.support.FarmingDataSyncExecutor;
 import com.ruoyi.web.modules.industryservice.support.FarmingSyncRules;
 import com.ruoyi.web.modules.industryservice.support.ThirdPartyFarmEnclosureClient;
 
+/**
+ * 第三方<strong>养殖圈舍</strong>同步编排。
+ * <p>
+ * 接口：{@code GET /open-api/v1/farming/enclosures} → 落库 {@code biz_farm_enclosure}。
+ * 通常由 {@link LivestockFinanceMasterSyncService} 在养殖场同步之后调用；
+ * 也可在全量同步流程中单独作为第二步执行。
+ * </p>
+ * <p>
+ * 每条圈舍记录通过 {@link FarmEnclosureSyncTxService} 以 {@code REQUIRES_NEW} 独立事务写入，
+ * 单条失败计入 {@link YakAssetSyncResultVo#getFailCount()}，不影响同批其他圈舍。
+ * </p>
+ */
 @Service
 public class FarmEnclosureSyncService
 {
+    /** 防并发重入：同一时刻只允许一个圈舍同步任务 */
     private final AtomicBoolean syncing = new AtomicBoolean(false);
 
     @Autowired
@@ -20,6 +33,11 @@ public class FarmEnclosureSyncService
     @Autowired
     private FarmEnclosureSyncTxService farmEnclosureSyncTxService;
 
+    /**
+     * 从第三方拉取全量圈舍列表并 upsert 到本地。
+     *
+     * @return 新增/更新/失败条数及失败明细（key 为第三方 id）
+     */
     public YakAssetSyncResultVo syncFromThirdParty()
     {
         if (!syncing.compareAndSet(false, true))

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

@@ -15,6 +15,20 @@ import com.ruoyi.web.modules.industryservice.mapper.BizPastureMapper;
 import com.ruoyi.web.modules.industryservice.support.FarmingSyncRules;
 import com.ruoyi.web.modules.industryservice.support.FarmingSyncSupport;
 
+/**
+ * 单条养殖圈舍同步事务服务。
+ * <p>
+ * 将 {@link OpenFarmEnclosureDto}（OpenFarmEnclosureVo）映射为 {@link BizFarmEnclosure}，
+ * 按 {@code external_id} upsert 到 {@code biz_farm_enclosure}。
+ * 每条记录独立事务（REQUIRES_NEW），避免批量同步中单条失败拖垮整批。
+ * </p>
+ *
+ * <h3>关联解析</h3>
+ * <ul>
+ *   <li>{@code farmId} → {@code farm_external_id}，并尝试解析本地 {@code pasture_id}</li>
+ *   <li>若养殖场尚未同步，{@code pasture_id} 暂为 null，后续全量同步会先补全养殖场</li>
+ * </ul>
+ */
 @Service
 public class FarmEnclosureSyncTxService
 {
@@ -24,6 +38,13 @@ public class FarmEnclosureSyncTxService
     @Autowired
     private BizPastureMapper pastureMapper;
 
+    /**
+     * 持久化一条第三方圈舍记录。
+     *
+     * @param dto      OpenFarmEnclosureVo 单条数据
+     * @param syncTime 本次同步批次时间，写入 last_sync_time
+     * @return {@code true}=新增，{@code false}=更新
+     */
     @Transactional(propagation = Propagation.REQUIRES_NEW, rollbackFor = Exception.class)
     public boolean persistEnclosure(OpenFarmEnclosureDto dto, Date syncTime)
     {
@@ -38,6 +59,7 @@ public class FarmEnclosureSyncTxService
         BizFarmEnclosure row = new BizFarmEnclosure();
         row.setExternalId(dto.getId());
         row.setFarmExternalId(dto.getFarmId());
+        // 依赖 biz_pasture.external_id = farmId，需先同步养殖场
         row.setPastureId(FarmingSyncSupport.resolvePastureId(pastureMapper, dto.getFarmId()));
         row.setFarmName(StringUtils.trim(dto.getFarmName()));
         row.setEnclosureName(dto.getEnclosureName().trim());
@@ -45,6 +67,7 @@ public class FarmEnclosureSyncTxService
         row.setQrCode(StringUtils.trim(dto.getQrCode()));
         row.setSupervisor(StringUtils.trim(dto.getSupervisor()));
         row.setIntroduction(StringUtils.trim(dto.getIntroduction()));
+        // enclosureStatus: 0使用中 1空闲 2维护中
         row.setEnclosureStatus(StringUtils.trim(dto.getEnclosureStatus()));
         row.setAreaType(StringUtils.trim(dto.getAreaType()));
         row.setCattleQuantity(dto.getCattleQuantity());

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

@@ -9,6 +9,13 @@ import com.ruoyi.web.modules.industryservice.support.FarmingDataSyncExecutor;
 import com.ruoyi.web.modules.industryservice.support.FarmingSyncRules;
 import com.ruoyi.web.modules.industryservice.support.ThirdPartyFarmingBatchClient;
 
+/**
+ * 第三方<strong>养殖批次</strong>同步编排。
+ * <p>
+ * 接口：{@code GET /open-api/v1/farming/batches} → 落库 {@code biz_farming_batch}。
+ * 在全量同步中位于生产计划之后、入栏建档之前执行。
+ * </p>
+ */
 @Service
 public class FarmingBatchSyncService
 {
@@ -20,6 +27,9 @@ public class FarmingBatchSyncService
     @Autowired
     private FarmingBatchSyncTxService farmingBatchSyncTxService;
 
+    /**
+     * 从第三方拉取全量养殖批次并 upsert 到本地。
+     */
     public YakAssetSyncResultVo syncFromThirdParty()
     {
         if (!syncing.compareAndSet(false, true))

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

@@ -16,6 +16,13 @@ import com.ruoyi.web.modules.industryservice.mapper.BizPastureMapper;
 import com.ruoyi.web.modules.industryservice.support.FarmingSyncRules;
 import com.ruoyi.web.modules.industryservice.support.FarmingSyncSupport;
 
+/**
+ * 单条养殖批次同步事务服务。
+ * <p>
+ * 将 {@link OpenFarmingBatchDto} 映射为 {@link BizFarmingBatch}，按 {@code external_id} upsert。
+ * 批次编号 {@code batchNo} 与入栏建档接口的 {@code entryCycle} 对应，供牦牛资产关联查询。
+ * </p>
+ */
 @Service
 public class FarmingBatchSyncTxService
 {
@@ -28,6 +35,13 @@ public class FarmingBatchSyncTxService
     @Autowired
     private BizFarmEnclosureMapper farmEnclosureMapper;
 
+    /**
+     * 持久化一条第三方养殖批次。
+     *
+     * @param dto      开放接口单条批次
+     * @param syncTime 本次同步批次时间
+     * @return {@code true}=新增，{@code false}=更新
+     */
     @Transactional(propagation = Propagation.REQUIRES_NEW, rollbackFor = Exception.class)
     public boolean persistBatch(OpenFarmingBatchDto dto, Date syncTime)
     {

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

@@ -9,6 +9,13 @@ import com.ruoyi.web.modules.industryservice.support.FarmingDataSyncExecutor;
 import com.ruoyi.web.modules.industryservice.support.FarmingSyncRules;
 import com.ruoyi.web.modules.industryservice.support.ThirdPartyFarmingPlanClient;
 
+/**
+ * 第三方<strong>养殖生产计划</strong>同步编排。
+ * <p>
+ * 接口：{@code GET /open-api/v1/farming/plans} → 落库 {@code biz_farming_plan}。
+ * 在全量同步中位于圈舍同步之后、批次同步之前执行。
+ * </p>
+ */
 @Service
 public class FarmingPlanSyncService
 {
@@ -20,6 +27,9 @@ public class FarmingPlanSyncService
     @Autowired
     private FarmingPlanSyncTxService farmingPlanSyncTxService;
 
+    /**
+     * 从第三方拉取全量生产计划并 upsert 到本地。
+     */
     public YakAssetSyncResultVo syncFromThirdParty()
     {
         if (!syncing.compareAndSet(false, true))

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

@@ -16,6 +16,20 @@ import com.ruoyi.web.modules.industryservice.mapper.BizPastureMapper;
 import com.ruoyi.web.modules.industryservice.support.FarmingSyncRules;
 import com.ruoyi.web.modules.industryservice.support.FarmingSyncSupport;
 
+/**
+ * 单条养殖生产计划同步事务服务。
+ * <p>
+ * 将 {@link OpenFarmingPlanDto}（OpenFarmingPlanVo）映射为 {@link BizFarmingPlan}，
+ * 按 {@code external_id} upsert。
+ * </p>
+ *
+ * <h3>关联解析</h3>
+ * <ul>
+ *   <li>{@code farmId} → {@code pasture_id}</li>
+ *   <li>{@code farmEnclosureId} → {@code enclosure_id}（需圈舍已同步）</li>
+ *   <li>{@code planStatus}：0草稿 1已下发 2执行中 3已完成 4已取消（以第三方字典为准）</li>
+ * </ul>
+ */
 @Service
 public class FarmingPlanSyncTxService
 {
@@ -28,6 +42,13 @@ public class FarmingPlanSyncTxService
     @Autowired
     private BizFarmEnclosureMapper farmEnclosureMapper;
 
+    /**
+     * 持久化一条第三方生产计划。
+     *
+     * @param dto      OpenFarmingPlanVo 单条数据
+     * @param syncTime 本次同步批次时间
+     * @return {@code true}=新增，{@code false}=更新
+     */
     @Transactional(propagation = Propagation.REQUIRES_NEW, rollbackFor = Exception.class)
     public boolean persistPlan(OpenFarmingPlanDto dto, Date syncTime)
     {

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

@@ -5,14 +5,43 @@ import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Service;
 import com.ruoyi.common.exception.ServiceException;
 import com.ruoyi.web.modules.industryservice.domain.vo.LivestockFinanceSyncResultVo;
-import com.ruoyi.web.modules.industryservice.support.FarmingSyncRules;
 
 /**
- * 牧业金融生物资产同步编排：养殖场 → 圈舍 → 生产计划 → 批次 → 入栏建档。
+ * 牧业金融生物资产<strong>全量同步编排</strong>服务。
+ * <p>
+ * 由 {@code POST /dataModel/yakAsset/sync} 触发，按第三方数据依赖关系<strong>严格顺序</strong>执行五段同步，
+ * 确保入栏建档（牦牛资产）落库前，养殖场、圈舍、生产计划、批次等基础台账已就绪。
+ * </p>
+ *
+ * <h3>同步顺序与落库表</h3>
+ * <ol>
+ *   <li>养殖场 → {@code biz_pasture}（{@link PastureSyncService}）</li>
+ *   <li>养殖圈舍 → {@code biz_farm_enclosure}（{@link FarmEnclosureSyncService}）</li>
+ *   <li>养殖生产计划 → {@code biz_farming_plan}（{@link FarmingPlanSyncService}）</li>
+ *   <li>养殖批次 → {@code biz_farming_batch}（{@link FarmingBatchSyncService}）</li>
+ *   <li>入栏建档 → {@code biz_yak_asset}（{@link YakAssetSyncService}）</li>
+ * </ol>
+ *
+ * <h3>并发控制</h3>
+ * <p>
+ * 本类持有全局 {@link #syncLock}，同一时刻仅允许一个全量同步任务运行。
+ * 各子步骤另有独立的防重入标志（如 {@link PastureSyncService} 的 {@code AtomicBoolean}），
+ * 避免全量同步进行中用户单独触发某一步导致交叉写入。
+ * </p>
+ *
+ * <h3>失败策略</h3>
+ * <p>
+ * 任一步骤 HTTP 拉取失败（第三方不可用、鉴权失败等）会抛出 {@link ServiceException} 并<strong>中断后续步骤</strong>。
+ * 单条记录持久化失败由各子服务的「单条独立事务 + 失败计数」处理，不拖垮同批其他记录。
+ * </p>
+ *
+ * @see LivestockFinanceSyncResultVo
+ * @see com.ruoyi.web.modules.industryservice.service.impl.BizYakAssetServiceImpl#syncFromThirdParty()
  */
 @Service
 public class LivestockFinanceMasterSyncService
 {
+    /** 全量同步互斥锁，防止重复点击或并发请求 */
     private final Object syncLock = new Object();
 
     @Autowired
@@ -30,6 +59,11 @@ public class LivestockFinanceMasterSyncService
     @Autowired
     private YakAssetSyncService yakAssetSyncService;
 
+    /**
+     * 执行牧业金融生物资产全量同步（五段顺序执行）。
+     *
+     * @return 各步骤的新增/更新/失败统计；顶层 {@code insertCount} 等字段兼容旧前端，取自入栏建档步骤
+     */
     public LivestockFinanceSyncResultVo syncAll()
     {
         synchronized (syncLock)
@@ -38,10 +72,15 @@ public class LivestockFinanceMasterSyncService
             Date syncTime = new Date();
             try
             {
+                // 1. 养殖场：后续圈舍/计划/批次/牦牛均依赖 farmId → pasture_id 解析
                 result.setPasture(pastureSyncService.syncFromThirdParty());
+                // 2. 圈舍：计划与批次可关联 enclosure_id
                 result.setEnclosure(farmEnclosureSyncService.syncFromThirdParty());
+                // 3. 生产计划：批次可关联 plan_external_id
                 result.setPlan(farmingPlanSyncService.syncFromThirdParty());
+                // 4. 批次：入栏建档 entryCycle/batchId 与批次台账对应
                 result.setBatch(farmingBatchSyncService.syncFromThirdParty());
+                // 5. 入栏建档（牦牛生物资产主表）
                 result.setYakAsset(yakAssetSyncService.syncFromThirdParty());
             }
             catch (ServiceException e)

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

@@ -25,6 +25,28 @@ import com.ruoyi.web.modules.industryservice.mapper.BizYakReproductionRecordMapp
 import com.ruoyi.web.modules.industryservice.support.YakAssetRules;
 import com.ruoyi.web.modules.industryservice.support.YakAssetValidation;
 
+/**
+ * 单头牦牛资产同步事务服务。
+ * <p>
+ * 接收 {@link YakAssetBundleDto}（含主表 {@link BizYakAsset} 及可选子表列表），
+ * 按 {@code external_id}（第三方 cattleId）优先、其次 {@code yak_no} 进行 upsert。
+ * 每头牦牛独立事务（REQUIRES_NEW），单头失败不影响其他头。
+ * </p>
+ *
+ * <h3>主表合并策略</h3>
+ * <ul>
+ *   <li>先查 external_id，再查 yak_no</li>
+ *   <li>存在则 update，不存在则 insert</li>
+ *   <li>自动解析 pasture_id：farmId → biz_pasture.external_id，或牧场名称精确匹配</li>
+ * </ul>
+ *
+ * <h3>子表覆盖策略</h3>
+ * <p>
+ * bundle 中某子表列表为 {@code null} 表示<strong>本次不同步</strong>该子表（保留本地数据）；
+ * 非 null 时先 delete 再 batchInsert（全量覆盖该子表）。
+ * 当前入栏建档 OpenAPI 仅填充主表字段，子表列表默认为 null。
+ * </p>
+ */
 @Service
 public class YakAssetBundleSyncTxService
 {
@@ -46,6 +68,13 @@ public class YakAssetBundleSyncTxService
     @Autowired
     private BizYakFeedingRecordMapper feedingRecordMapper;
 
+    /**
+     * 持久化一头牦牛的同步数据包。
+     *
+     * @param bundle   含主表及可选子表
+     * @param syncTime 本次同步批次时间，写入 last_sync_time
+     * @return {@code true}=新增，{@code false}=更新
+     */
     @Transactional(propagation = Propagation.REQUIRES_NEW, rollbackFor = Exception.class)
     public boolean persistBundle(YakAssetBundleDto bundle, Date syncTime)
     {
@@ -94,6 +123,9 @@ public class YakAssetBundleSyncTxService
         return inserted;
     }
 
+    /**
+     * 解析本地已存在档案：优先 external_id（cattleId），其次 yak_no。
+     */
     private BizYakAsset resolveExisting(BizYakAsset incoming)
     {
         if (incoming.getExternalId() != null)
@@ -107,6 +139,9 @@ public class YakAssetBundleSyncTxService
         return bizYakAssetMapper.selectBizYakAssetByYakNo(incoming.getYakNo());
     }
 
+    /**
+     * 关联养殖场：优先 thirdPartyPastureCode（farmId），其次 pastureName 精确匹配。
+     */
     private void resolvePasture(BizYakAsset incoming, YakAssetBundleDto bundle)
     {
         BizPasture pasture = null;
@@ -137,6 +172,9 @@ public class YakAssetBundleSyncTxService
         }
     }
 
+    /**
+     * 子表「按需覆盖」：列表为 null 跳过；非 null 则 delete + batchInsert。
+     */
     private void replaceChildRows(Long yakAssetId, YakAssetBundleDto bundle)
     {
         if (bundle.getPhysioSeries() != null)

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

@@ -12,11 +12,29 @@ import com.ruoyi.web.modules.industryservice.support.ThirdPartyYakClient;
 import com.ruoyi.web.modules.industryservice.support.YakAssetStatusMapper;
 
 /**
- * 第三方档案同步编排（防并发重入；单头独立事务）。
+ * 第三方<strong>入栏建档（牦牛生物资产）</strong>同步编排。
+ * <p>
+ * 接口：{@code GET /open-api/v1/farming/entry-filings} → 落库 {@code biz_yak_asset} 及可选子表。
+ * 在全量同步中由 {@link LivestockFinanceMasterSyncService} 作为最后一步调用；
+ * 也可单独运行（前提是养殖场等基础数据已同步，否则 pasture_id 可能无法解析）。
+ * </p>
+ *
+ * <h3>处理流程</h3>
+ * <ol>
+ *   <li>{@link ThirdPartyYakClient#fetchAll()} 分页拉取并映射为 {@link YakAssetBundleDto}</li>
+ *   <li>逐头调用 {@link YakAssetBundleSyncTxService#persistBundle}（单头独立事务）</li>
+ *   <li>汇总 insert/update/fail 计数</li>
+ * </ol>
+ *
+ * <h3>并发与容错</h3>
+ * <p>
+ * {@link #syncLock} 防止同一服务实例并发同步；单头失败仅增加 failCount，已成功落库的头不回滚。
+ * </p>
  */
 @Service
 public class YakAssetSyncService
 {
+    /** 入栏建档同步互斥锁 */
     private final Object syncLock = new Object();
 
     @Autowired
@@ -25,6 +43,11 @@ public class YakAssetSyncService
     @Autowired
     private YakAssetBundleSyncTxService bundleSyncTxService;
 
+    /**
+     * 从第三方拉取全量入栏建档列表并逐头 upsert。
+     *
+     * @return 新增/更新/失败头数；失败明细 key 为 yakNo
+     */
     public YakAssetSyncResultVo syncFromThirdParty()
     {
         synchronized (syncLock)
@@ -75,6 +98,7 @@ public class YakAssetSyncService
         }
     }
 
+    /** 第三方状态码 → 本地 asset_status（供测试或扩展使用） */
     public static int mapThirdPartyStatus(String code)
     {
         return YakAssetStatusMapper.mapToLocalStatus(code);

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

@@ -9,7 +9,17 @@ import com.ruoyi.common.utils.StringUtils;
 import com.ruoyi.web.modules.industryservice.domain.vo.YakAssetSyncResultVo;
 
 /**
- * 第三方养殖基础数据批量同步执行器。
+ * 第三方养殖基础数据（圈舍/计划/批次等）批量同步执行器。
+ * <p>
+ * 封装「逐条 persist + 统计 insert/update/fail」的通用循环，
+ * 供 {@link com.ruoyi.web.modules.industryservice.service.FarmEnclosureSyncService} 等编排类复用。
+ * </p>
+ *
+ * <h3>容错</h3>
+ * <p>
+ * 单条 {@code persistFn} 抛异常时捕获并记入 {@link YakAssetSyncResultVo#getFailMessages()}，
+ * 继续处理后续记录；与 {@code REQUIRES_NEW} 事务配合，已成功落库的行不回滚。
+ * </p>
  */
 public final class FarmingDataSyncExecutor
 {
@@ -17,6 +27,14 @@ public final class FarmingDataSyncExecutor
     {
     }
 
+    /**
+     * 批量执行同步持久化。
+     *
+     * @param rows      第三方拉取的全量列表
+     * @param persistFn 单条持久化函数，返回 true=新增 false=更新
+     * @param keyFn     失败明细中的标识（通常为 external_id）
+     * @return 汇总结果
+     */
     public static <T> YakAssetSyncResultVo execute(List<T> rows, BiFunction<T, Date, Boolean> persistFn,
             Function<T, String> keyFn)
     {

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

@@ -1,12 +1,14 @@
 package com.ruoyi.web.modules.industryservice.support;
 
 /**
- * 养殖基础数据同步规则。
+ * 养殖基础数据同步规则与提示文案。
  */
 public final class FarmingSyncRules
 {
+    /** 并发同步进行中时的用户提示 */
     public static final String MSG_SYNC_IN_PROGRESS = "正在同步，请稍候";
 
+    /** 第三方 id 为空时的校验提示 */
     public static final String MSG_EXTERNAL_ID_REQUIRED = "第三方编号不能为空";
 
     private FarmingSyncRules()

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

@@ -12,11 +12,16 @@ import com.ruoyi.web.modules.industryservice.mapper.BizPastureMapper;
 
 /**
  * 养殖基础数据同步共用工具。
+ * <p>
+ * 提供第三方时间解析、本地关联 ID 解析等，供各 {@code *SyncTxService} 使用。
+ * </p>
  */
 public final class FarmingSyncSupport
 {
+    /** 写入各 biz_* 表的 data_source 字段 */
     public static final String DATA_SOURCE_THIRD_PARTY = "third_party";
 
+    /** 同步操作人标识，写入 create_by / update_by */
     public static final String SYNC_BY = "sync";
 
     private static final SimpleDateFormat THIRD_PARTY_TIME = createThirdPartyTimeFormat();
@@ -27,6 +32,12 @@ public final class FarmingSyncSupport
     {
     }
 
+    /**
+     * 解析第三方时间字符串，支持 {@code yyyy-MM-dd HH:mm:ss} 与 {@code yyyy-MM-dd}。
+     *
+     * @param value    原始字符串
+     * @param fallback 解析失败或为空时的默认值
+     */
     public static Date parseThirdPartyTime(String value, Date fallback)
     {
         if (StringUtils.isEmpty(value))
@@ -54,6 +65,11 @@ public final class FarmingSyncSupport
         }
     }
 
+    /**
+     * 根据第三方 farmId 解析本地养殖场主键。
+     *
+     * @return {@code biz_pasture.id}，未同步则 null
+     */
     public static Long resolvePastureId(BizPastureMapper pastureMapper, Long farmExternalId)
     {
         if (farmExternalId == null || pastureMapper == null)
@@ -64,6 +80,11 @@ public final class FarmingSyncSupport
         return pasture != null ? pasture.getId() : null;
     }
 
+    /**
+     * 根据第三方圈舍 id 解析本地圈舍主键。
+     *
+     * @return {@code biz_farm_enclosure.id}，未同步则 null
+     */
     public static Long resolveEnclosureId(BizFarmEnclosureMapper enclosureMapper, Long enclosureExternalId)
     {
         if (enclosureExternalId == null || enclosureMapper == null)

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

@@ -18,6 +18,10 @@ import com.ruoyi.common.exception.ServiceException;
 
 /**
  * 第三方生产管理系统 HTTP 调用共用工具。
+ * <p>
+ * 封装 RestTemplate 创建、OpenAPI 鉴权头（X-App-Key / X-App-Secret）、URL 拼接及 JSON 反序列化配置。
+ * 所有 {@code ThirdParty*ClientImpl} 均依赖本类，配置来源 {@link ThirdPartyFarmingProperties}。
+ * </p>
  */
 public final class ThirdPartyFarmingHttpSupport
 {
@@ -25,6 +29,7 @@ public final class ThirdPartyFarmingHttpSupport
     {
     }
 
+    /** 校验 base-url 已配置，否则抛出业务异常 */
     public static void requireBaseUrl(ThirdPartyFarmingProperties properties, String hint)
     {
         if (!StringUtils.hasText(properties.getBaseUrl()))
@@ -33,6 +38,7 @@ public final class ThirdPartyFarmingHttpSupport
         }
     }
 
+    /** 按配置创建 RestTemplate，含连接/读取超时 */
     public static RestTemplate createRestTemplate(ThirdPartyFarmingProperties properties)
     {
         SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
@@ -41,6 +47,7 @@ public final class ThirdPartyFarmingHttpSupport
         return new RestTemplate(factory);
     }
 
+    /** 构建开放接口鉴权请求头 */
     public static HttpHeaders buildOpenApiHeaders(ThirdPartyFarmingProperties properties)
     {
         HttpHeaders headers = new HttpHeaders();
@@ -56,6 +63,7 @@ public final class ThirdPartyFarmingHttpSupport
         return headers;
     }
 
+    /** baseUrl + path，baseUrl 末尾斜杠自动去除 */
     public static String resolveUrl(ThirdPartyFarmingProperties properties, String path)
     {
         return trimTrailingSlash(properties.getBaseUrl()) + path;
@@ -71,6 +79,13 @@ public final class ThirdPartyFarmingHttpSupport
         return url;
     }
 
+    /**
+     * 创建 JSON 反序列化器。
+     * <p>
+     * 注册 {@link FlexibleLongDeserializer}：第三方部分 int64 字段以字符串返回（如 {@code "2061327199252615170"}），
+     * 需兼容解析为 {@link Long}。
+     * </p>
+     */
     public static ObjectMapper createObjectMapper()
     {
         ObjectMapper mapper = new ObjectMapper();
@@ -85,6 +100,7 @@ public final class ThirdPartyFarmingHttpSupport
         return mapper;
     }
 
+    /** 兼容 JSON 数字与字符串形式的 Long 字段 */
     private static final class FlexibleLongDeserializer extends JsonDeserializer<Long>
     {
         @Override

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

@@ -23,7 +23,23 @@ import com.ruoyi.web.modules.industryservice.domain.dto.OpenApiPageResult;
 import com.ruoyi.web.modules.industryservice.domain.dto.OpenApiResponse;
 
 /**
- * 第三方养殖开放接口分页拉取共用逻辑。
+ * 第三方养殖开放接口<strong>分页拉取</strong>共用逻辑。
+ * <p>
+ * 开放接口统一返回 {@link OpenApiResponse}{@code <}{@link OpenApiPageResult}{@code <T>>}，
+ * 本类负责循环 {@code pageNum=1..N} 直至 records 为空或已达 total。
+ * </p>
+ *
+ * <h3>分页终止条件（满足任一即停止）</h3>
+ * <ul>
+ *   <li>当前页 records 为空</li>
+ *   <li>当前页条数 &lt; pageSize</li>
+ *   <li>已收集条数 &gt;= total</li>
+ * </ul>
+ *
+ * <h3>Stub 模式</h3>
+ * <p>
+ * {@link #fetchFromStub} 从 classpath JSON 读取全量列表，供 {@code third-party.farming.mode=stub} 联调。
+ * </p>
  */
 public final class ThirdPartyFarmingPageFetcher
 {
@@ -31,6 +47,13 @@ public final class ThirdPartyFarmingPageFetcher
     {
     }
 
+    /**
+     * HTTP 模式：分页拉取直至全量。
+     *
+     * @param listPath   开放接口路径，如 {@code /open-api/v1/farming/enclosures}
+     * @param responseType Jackson 泛型类型引用
+     * @param apiLabel   异常消息中的接口中文名
+     */
     public static <T> List<T> fetchAllPages(ThirdPartyFarmingProperties properties, ObjectMapper objectMapper,
             String listPath, TypeReference<OpenApiResponse<OpenApiPageResult<T>>> responseType, String apiLabel)
     {
@@ -39,6 +62,7 @@ public final class ThirdPartyFarmingPageFetcher
         HttpHeaders headers = ThirdPartyFarmingHttpSupport.buildOpenApiHeaders(properties);
         List<T> all = new ArrayList<>();
         int pageNum = 1;
+        // 接口上限 200，配置超出时截断
         int pageSize = Math.min(Math.max(properties.getPageSize(), 1), 200);
         Long total = null;
         while (true)
@@ -56,6 +80,7 @@ public final class ThirdPartyFarmingPageFetcher
                     throw new ServiceException(apiLabel + "接口返回异常");
                 }
                 OpenApiResponse<OpenApiPageResult<T>> body = objectMapper.readValue(response.getBody(), responseType);
+                // code=0 表示业务成功；401 鉴权失败；500 服务端错误
                 if (body == null || body.getCode() == null || body.getCode() != 0)
                 {
                     String msg = body != null && StringUtils.hasText(body.getMessage()) ? body.getMessage() : "业务失败";
@@ -97,6 +122,9 @@ public final class ThirdPartyFarmingPageFetcher
         return all;
     }
 
+    /**
+     * Stub 模式：读取 classpath 样例 JSON 数组。
+     */
     public static <T> List<T> fetchFromStub(ObjectMapper objectMapper, String stubResource,
             TypeReference<List<T>> listType, String apiLabel)
     {