外部接口

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

@@ -15,6 +15,7 @@ import com.ruoyi.web.modules.industryservice.domain.dto.OpenApiResponse;
 import com.ruoyi.web.modules.industryservice.research.domain.dto.ResearchTokenRequest;
 import com.ruoyi.web.modules.industryservice.research.domain.dto.ResearchTokenVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchCooperativeDevelopmentVo;
+import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchFamilyRanchVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchLivestockProductOutputVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchPastureVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakAssetVo;
@@ -196,4 +197,29 @@ public class ResearchOpenApiController
             return ResearchOpenApiSupport.error(code, ex.getMessage());
         }
     }
+
+    /**
+     * 家庭牧场数据列表。
+     */
+    @GetMapping("/family-ranches")
+    public OpenApiResponse<OpenApiPageResult<ResearchFamilyRanchVo>> listFamilyRanches(
+            @RequestParam(value = "pageNum", defaultValue = "1") int pageNum,
+            @RequestParam(value = "pageSize", defaultValue = "20") int pageSize,
+            @RequestParam(value = "statYear", required = false) Integer statYear,
+            @RequestParam(value = "statMonth", required = false) Integer statMonth,
+            @RequestParam(value = "townName", required = false) String townName,
+            @RequestParam(value = "villageName", required = false) String villageName,
+            @RequestParam(value = "enterpriseName", required = false) String enterpriseName)
+    {
+        try
+        {
+            return ResearchOpenApiSupport.success(researchOpenApiService.listFamilyRanches(
+                    pageNum, pageSize, statYear, statMonth, townName, villageName, enterpriseName));
+        }
+        catch (ServiceException ex)
+        {
+            int code = ex.getCode() != null ? ex.getCode() : 500;
+            return ResearchOpenApiSupport.error(code, ex.getMessage());
+        }
+    }
 }

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

@@ -0,0 +1,464 @@
+package com.ruoyi.web.modules.industryservice.research.domain.vo;
+
+import java.math.BigDecimal;
+
+/**
+ * 科研开放接口 — 家庭牧场填报记录（脱敏法人姓名；不含部门 ID / 备注）。
+ */
+public class ResearchFamilyRanchVo
+{
+    /** 家庭牧场记录 ID */
+    private Long ranchId;
+
+    /** 所属年份 */
+    private Integer statYear;
+
+    /** 所属月份（1～12） */
+    private Integer statMonth;
+
+    /** 所属乡镇名称 */
+    private String townName;
+
+    /** 所属村名称 */
+    private String villageName;
+
+    /** 企业名称 */
+    private String enterpriseName;
+
+    /** 法定代表人（脱敏） */
+    private String legalRepresentative;
+
+    /** 企业类型 */
+    private String enterpriseType;
+
+    /** 注册资本（万元） */
+    private BigDecimal registeredCapital;
+
+    /** 成立时间（yyyy-MM-dd） */
+    private String establishDate;
+
+    /** 从事畜牧业生产经营劳力人员 */
+    private Integer livestockLaborCount;
+
+    /** 年底牲畜存栏小计（牛+羊） */
+    private Integer stockSubtotal;
+
+    /** 牛年底存栏 */
+    private Integer cattleYearEndStock;
+
+    /** 牛能繁母畜 */
+    private Integer cattleBreedingFemaleStock;
+
+    /** 羊年底存栏 */
+    private Integer sheepYearEndStock;
+
+    /** 羊能繁母畜 */
+    private Integer sheepBreedingFemaleStock;
+
+    /** 牛出栏 */
+    private Integer cattleOutbound;
+
+    /** 羊出栏 */
+    private Integer sheepOutbound;
+
+    /** 草场面积小计（亩） */
+    private BigDecimal grasslandAreaSubtotal;
+
+    /** 草畜平衡面积（亩） */
+    private BigDecimal grassBalanceArea;
+
+    /** 流转经营草地面积（亩） */
+    private BigDecimal transferGrassArea;
+
+    /** 核定年末草畜平衡载畜量（绵羊单位） */
+    private BigDecimal approvedCarryingCapacity;
+
+    /** 年底牲畜存栏（绵羊单位） */
+    private BigDecimal yearEndStockSheepUnit;
+
+    /** 是否草畜平衡户（是/否） */
+    private String isGrassBalanced;
+
+    /** 年度经营总收入（万元） */
+    private BigDecimal income;
+
+    /** 年度经营总支出（万元） */
+    private BigDecimal expense;
+
+    /** 利润（万元）= 收入 - 支出 */
+    private BigDecimal profit;
+
+    /** 家庭牧场补助资金年份 */
+    private Integer subsidyYear;
+
+    /** 是否享受补助（是/否） */
+    private String hasSubsidy;
+
+    /** 补贴资金（万元） */
+    private BigDecimal subsidyAmount;
+
+    /** 是否有注册商标（是/否） */
+    private String hasTrademark;
+
+    /** 是否通过农产品质量认证（是/否） */
+    private String hasQualityCert;
+
+    /** 产品销售渠道 */
+    private String salesChannel;
+
+    /** 带动人数 */
+    private Integer drivenPopulation;
+
+    /** 发放工资（万元） */
+    private BigDecimal wagePaid;
+
+    public Long getRanchId()
+    {
+        return ranchId;
+    }
+
+    public void setRanchId(Long ranchId)
+    {
+        this.ranchId = ranchId;
+    }
+
+    public Integer getStatYear()
+    {
+        return statYear;
+    }
+
+    public void setStatYear(Integer statYear)
+    {
+        this.statYear = statYear;
+    }
+
+    public Integer getStatMonth()
+    {
+        return statMonth;
+    }
+
+    public void setStatMonth(Integer statMonth)
+    {
+        this.statMonth = statMonth;
+    }
+
+    public String getTownName()
+    {
+        return townName;
+    }
+
+    public void setTownName(String townName)
+    {
+        this.townName = townName;
+    }
+
+    public String getVillageName()
+    {
+        return villageName;
+    }
+
+    public void setVillageName(String villageName)
+    {
+        this.villageName = villageName;
+    }
+
+    public String getEnterpriseName()
+    {
+        return enterpriseName;
+    }
+
+    public void setEnterpriseName(String enterpriseName)
+    {
+        this.enterpriseName = enterpriseName;
+    }
+
+    public String getLegalRepresentative()
+    {
+        return legalRepresentative;
+    }
+
+    public void setLegalRepresentative(String legalRepresentative)
+    {
+        this.legalRepresentative = legalRepresentative;
+    }
+
+    public String getEnterpriseType()
+    {
+        return enterpriseType;
+    }
+
+    public void setEnterpriseType(String enterpriseType)
+    {
+        this.enterpriseType = enterpriseType;
+    }
+
+    public BigDecimal getRegisteredCapital()
+    {
+        return registeredCapital;
+    }
+
+    public void setRegisteredCapital(BigDecimal registeredCapital)
+    {
+        this.registeredCapital = registeredCapital;
+    }
+
+    public String getEstablishDate()
+    {
+        return establishDate;
+    }
+
+    public void setEstablishDate(String establishDate)
+    {
+        this.establishDate = establishDate;
+    }
+
+    public Integer getLivestockLaborCount()
+    {
+        return livestockLaborCount;
+    }
+
+    public void setLivestockLaborCount(Integer livestockLaborCount)
+    {
+        this.livestockLaborCount = livestockLaborCount;
+    }
+
+    public Integer getStockSubtotal()
+    {
+        return stockSubtotal;
+    }
+
+    public void setStockSubtotal(Integer stockSubtotal)
+    {
+        this.stockSubtotal = stockSubtotal;
+    }
+
+    public Integer getCattleYearEndStock()
+    {
+        return cattleYearEndStock;
+    }
+
+    public void setCattleYearEndStock(Integer cattleYearEndStock)
+    {
+        this.cattleYearEndStock = cattleYearEndStock;
+    }
+
+    public Integer getCattleBreedingFemaleStock()
+    {
+        return cattleBreedingFemaleStock;
+    }
+
+    public void setCattleBreedingFemaleStock(Integer cattleBreedingFemaleStock)
+    {
+        this.cattleBreedingFemaleStock = cattleBreedingFemaleStock;
+    }
+
+    public Integer getSheepYearEndStock()
+    {
+        return sheepYearEndStock;
+    }
+
+    public void setSheepYearEndStock(Integer sheepYearEndStock)
+    {
+        this.sheepYearEndStock = sheepYearEndStock;
+    }
+
+    public Integer getSheepBreedingFemaleStock()
+    {
+        return sheepBreedingFemaleStock;
+    }
+
+    public void setSheepBreedingFemaleStock(Integer sheepBreedingFemaleStock)
+    {
+        this.sheepBreedingFemaleStock = sheepBreedingFemaleStock;
+    }
+
+    public Integer getCattleOutbound()
+    {
+        return cattleOutbound;
+    }
+
+    public void setCattleOutbound(Integer cattleOutbound)
+    {
+        this.cattleOutbound = cattleOutbound;
+    }
+
+    public Integer getSheepOutbound()
+    {
+        return sheepOutbound;
+    }
+
+    public void setSheepOutbound(Integer sheepOutbound)
+    {
+        this.sheepOutbound = sheepOutbound;
+    }
+
+    public BigDecimal getGrasslandAreaSubtotal()
+    {
+        return grasslandAreaSubtotal;
+    }
+
+    public void setGrasslandAreaSubtotal(BigDecimal grasslandAreaSubtotal)
+    {
+        this.grasslandAreaSubtotal = grasslandAreaSubtotal;
+    }
+
+    public BigDecimal getGrassBalanceArea()
+    {
+        return grassBalanceArea;
+    }
+
+    public void setGrassBalanceArea(BigDecimal grassBalanceArea)
+    {
+        this.grassBalanceArea = grassBalanceArea;
+    }
+
+    public BigDecimal getTransferGrassArea()
+    {
+        return transferGrassArea;
+    }
+
+    public void setTransferGrassArea(BigDecimal transferGrassArea)
+    {
+        this.transferGrassArea = transferGrassArea;
+    }
+
+    public BigDecimal getApprovedCarryingCapacity()
+    {
+        return approvedCarryingCapacity;
+    }
+
+    public void setApprovedCarryingCapacity(BigDecimal approvedCarryingCapacity)
+    {
+        this.approvedCarryingCapacity = approvedCarryingCapacity;
+    }
+
+    public BigDecimal getYearEndStockSheepUnit()
+    {
+        return yearEndStockSheepUnit;
+    }
+
+    public void setYearEndStockSheepUnit(BigDecimal yearEndStockSheepUnit)
+    {
+        this.yearEndStockSheepUnit = yearEndStockSheepUnit;
+    }
+
+    public String getIsGrassBalanced()
+    {
+        return isGrassBalanced;
+    }
+
+    public void setIsGrassBalanced(String isGrassBalanced)
+    {
+        this.isGrassBalanced = isGrassBalanced;
+    }
+
+    public BigDecimal getIncome()
+    {
+        return income;
+    }
+
+    public void setIncome(BigDecimal income)
+    {
+        this.income = income;
+    }
+
+    public BigDecimal getExpense()
+    {
+        return expense;
+    }
+
+    public void setExpense(BigDecimal expense)
+    {
+        this.expense = expense;
+    }
+
+    public BigDecimal getProfit()
+    {
+        return profit;
+    }
+
+    public void setProfit(BigDecimal profit)
+    {
+        this.profit = profit;
+    }
+
+    public Integer getSubsidyYear()
+    {
+        return subsidyYear;
+    }
+
+    public void setSubsidyYear(Integer subsidyYear)
+    {
+        this.subsidyYear = subsidyYear;
+    }
+
+    public String getHasSubsidy()
+    {
+        return hasSubsidy;
+    }
+
+    public void setHasSubsidy(String hasSubsidy)
+    {
+        this.hasSubsidy = hasSubsidy;
+    }
+
+    public BigDecimal getSubsidyAmount()
+    {
+        return subsidyAmount;
+    }
+
+    public void setSubsidyAmount(BigDecimal subsidyAmount)
+    {
+        this.subsidyAmount = subsidyAmount;
+    }
+
+    public String getHasTrademark()
+    {
+        return hasTrademark;
+    }
+
+    public void setHasTrademark(String hasTrademark)
+    {
+        this.hasTrademark = hasTrademark;
+    }
+
+    public String getHasQualityCert()
+    {
+        return hasQualityCert;
+    }
+
+    public void setHasQualityCert(String hasQualityCert)
+    {
+        this.hasQualityCert = hasQualityCert;
+    }
+
+    public String getSalesChannel()
+    {
+        return salesChannel;
+    }
+
+    public void setSalesChannel(String salesChannel)
+    {
+        this.salesChannel = salesChannel;
+    }
+
+    public Integer getDrivenPopulation()
+    {
+        return drivenPopulation;
+    }
+
+    public void setDrivenPopulation(Integer drivenPopulation)
+    {
+        this.drivenPopulation = drivenPopulation;
+    }
+
+    public BigDecimal getWagePaid()
+    {
+        return wagePaid;
+    }
+
+    public void setWagePaid(BigDecimal wagePaid)
+    {
+        this.wagePaid = wagePaid;
+    }
+}

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

@@ -3,6 +3,7 @@ package com.ruoyi.web.modules.industryservice.research.service;
 import com.ruoyi.web.modules.industryservice.domain.dto.OpenApiPageResult;
 import com.ruoyi.web.modules.industryservice.research.domain.dto.ResearchTokenVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchCooperativeDevelopmentVo;
+import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchFamilyRanchVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchLivestockProductOutputVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchPastureVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakAssetVo;
@@ -57,4 +58,14 @@ public interface IResearchOpenApiService
      */
     OpenApiPageResult<ResearchLivestockProductOutputVo> listLivestockProductOutputs(int pageNum, int pageSize,
             Integer statYear, Integer statMonth, String townName, String villageName);
+
+    /**
+     * 家庭牧场填报列表。
+     *
+     * @param townName 所属乡镇名称模糊匹配
+     * @param villageName 所属村名称模糊匹配
+     * @param enterpriseName 企业名称模糊匹配
+     */
+    OpenApiPageResult<ResearchFamilyRanchVo> listFamilyRanches(int pageNum, int pageSize,
+            Integer statYear, Integer statMonth, String townName, String villageName, String enterpriseName);
 }

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

@@ -9,6 +9,7 @@ import com.github.pagehelper.PageInfo;
 import com.ruoyi.common.exception.ServiceException;
 import com.ruoyi.common.utils.StringUtils;
 import com.ruoyi.web.modules.industryservice.domain.BizCooperativeDevelopment;
+import com.ruoyi.web.modules.industryservice.domain.BizFamilyRanch;
 import com.ruoyi.web.modules.industryservice.domain.BizLivestockProductOutput;
 import com.ruoyi.web.modules.industryservice.domain.BizPasture;
 import com.ruoyi.web.modules.industryservice.domain.BizYakAsset;
@@ -16,12 +17,14 @@ import com.ruoyi.web.modules.industryservice.domain.BizYakHerdInventory;
 import com.ruoyi.web.modules.industryservice.domain.BizYakOutboundReport;
 import com.ruoyi.web.modules.industryservice.domain.dto.OpenApiPageResult;
 import com.ruoyi.web.modules.industryservice.mapper.BizCooperativeDevelopmentMapper;
+import com.ruoyi.web.modules.industryservice.mapper.BizFamilyRanchMapper;
 import com.ruoyi.web.modules.industryservice.mapper.BizLivestockProductOutputMapper;
 import com.ruoyi.web.modules.industryservice.mapper.BizYakHerdInventoryMapper;
 import com.ruoyi.web.modules.industryservice.mapper.BizYakOutboundReportMapper;
 import com.ruoyi.web.modules.industryservice.research.config.ResearchOpenApiProperties;
 import com.ruoyi.web.modules.industryservice.research.domain.dto.ResearchTokenVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchCooperativeDevelopmentVo;
+import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchFamilyRanchVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchLivestockProductOutputVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchPastureVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakAssetVo;
@@ -60,6 +63,9 @@ public class ResearchOpenApiServiceImpl implements IResearchOpenApiService
     @Autowired
     private BizLivestockProductOutputMapper bizLivestockProductOutputMapper;
 
+    @Autowired
+    private BizFamilyRanchMapper bizFamilyRanchMapper;
+
     @Override
     public ResearchTokenVo authenticate(String appKey, String appSecret)
     {
@@ -213,6 +219,37 @@ public class ResearchOpenApiServiceImpl implements IResearchOpenApiService
                 rows.stream().map(ResearchOpenApiSupport::toLivestockProductOutputVo).collect(Collectors.toList()));
     }
 
+    @Override
+    public OpenApiPageResult<ResearchFamilyRanchVo> listFamilyRanches(int pageNum, int pageSize,
+            Integer statYear, Integer statMonth, String townName, String villageName, String enterpriseName)
+    {
+        tokenService.assertEnabled();
+        int safePageNum = normalizePageNum(pageNum);
+        int safePageSize = normalizePageSize(pageSize);
+        BizFamilyRanch query = new BizFamilyRanch();
+        query.setStatYear(statYear);
+        query.setStatMonth(statMonth);
+        if (StringUtils.isNotEmpty(townName))
+        {
+            query.setTownName(townName.trim());
+        }
+        if (StringUtils.isNotEmpty(villageName))
+        {
+            query.setVillageName(villageName.trim());
+        }
+        if (StringUtils.isNotEmpty(enterpriseName))
+        {
+            query.setEnterpriseName(enterpriseName.trim());
+        }
+        // 开放接口无登录上下文，清空 dataScope，避免走填报部门权限
+        query.getParams().put("dataScope", "");
+        PageHelper.startPage(safePageNum, safePageSize);
+        List<BizFamilyRanch> rows = bizFamilyRanchMapper.selectBizFamilyRanchList(query);
+        PageInfo<BizFamilyRanch> page = new PageInfo<>(rows);
+        return toPageResult(safePageNum, safePageSize, page.getTotal(),
+                rows.stream().map(ResearchOpenApiSupport::toFamilyRanchVo).collect(Collectors.toList()));
+    }
+
     private int normalizePageNum(int pageNum)
     {
         return pageNum > 0 ? pageNum : 1;

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

@@ -3,6 +3,7 @@ package com.ruoyi.web.modules.industryservice.research.support;
 import java.time.Instant;
 import java.util.UUID;
 import com.ruoyi.web.modules.industryservice.domain.BizCooperativeDevelopment;
+import com.ruoyi.web.modules.industryservice.domain.BizFamilyRanch;
 import com.ruoyi.web.modules.industryservice.domain.BizLivestockProductOutput;
 import com.ruoyi.web.modules.industryservice.domain.BizPasture;
 import com.ruoyi.web.modules.industryservice.domain.BizYakAsset;
@@ -10,6 +11,7 @@ import com.ruoyi.web.modules.industryservice.domain.BizYakHerdInventory;
 import com.ruoyi.web.modules.industryservice.domain.BizYakOutboundReport;
 import com.ruoyi.web.modules.industryservice.domain.dto.OpenApiResponse;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchCooperativeDevelopmentVo;
+import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchFamilyRanchVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchLivestockProductOutputVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchPastureVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakAssetVo;
@@ -225,4 +227,49 @@ public final class ResearchOpenApiSupport
         vo.setMilkOutput(row.getMilkOutput());
         return vo;
     }
+
+    public static ResearchFamilyRanchVo toFamilyRanchVo(BizFamilyRanch row)
+    {
+        if (row == null)
+        {
+            return null;
+        }
+        ResearchFamilyRanchVo vo = new ResearchFamilyRanchVo();
+        vo.setRanchId(row.getId());
+        vo.setStatYear(row.getStatYear());
+        vo.setStatMonth(row.getStatMonth());
+        vo.setTownName(row.getTownName());
+        vo.setVillageName(row.getVillageName());
+        vo.setEnterpriseName(row.getEnterpriseName());
+        vo.setLegalRepresentative(ResearchOpenApiMasking.maskPersonName(row.getLegalRepresentative()));
+        vo.setEnterpriseType(row.getEnterpriseType());
+        vo.setRegisteredCapital(row.getRegisteredCapital());
+        vo.setEstablishDate(row.getEstablishDate());
+        vo.setLivestockLaborCount(row.getLivestockLaborCount());
+        vo.setStockSubtotal(row.getStockSubtotal());
+        vo.setCattleYearEndStock(row.getCattleYearEndStock());
+        vo.setCattleBreedingFemaleStock(row.getCattleBreedingFemaleStock());
+        vo.setSheepYearEndStock(row.getSheepYearEndStock());
+        vo.setSheepBreedingFemaleStock(row.getSheepBreedingFemaleStock());
+        vo.setCattleOutbound(row.getCattleOutbound());
+        vo.setSheepOutbound(row.getSheepOutbound());
+        vo.setGrasslandAreaSubtotal(row.getGrasslandAreaSubtotal());
+        vo.setGrassBalanceArea(row.getGrassBalanceArea());
+        vo.setTransferGrassArea(row.getTransferGrassArea());
+        vo.setApprovedCarryingCapacity(row.getApprovedCarryingCapacity());
+        vo.setYearEndStockSheepUnit(row.getYearEndStockSheepUnit());
+        vo.setIsGrassBalanced(row.getIsGrassBalanced());
+        vo.setIncome(row.getIncome());
+        vo.setExpense(row.getExpense());
+        vo.setProfit(row.getProfit());
+        vo.setSubsidyYear(row.getSubsidyYear());
+        vo.setHasSubsidy(row.getHasSubsidy());
+        vo.setSubsidyAmount(row.getSubsidyAmount());
+        vo.setHasTrademark(row.getHasTrademark());
+        vo.setHasQualityCert(row.getHasQualityCert());
+        vo.setSalesChannel(row.getSalesChannel());
+        vo.setDrivenPopulation(row.getDrivenPopulation());
+        vo.setWagePaid(row.getWagePaid());
+        return vo;
+    }
 }

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

@@ -88,6 +88,8 @@
             <if test="statMonth != null">and r.stat_month = #{statMonth}</if>
             <if test="townDeptId != null">and r.town_dept_id = #{townDeptId}</if>
             <if test="villageDeptId != null">and r.village_dept_id = #{villageDeptId}</if>
+            <if test="townName != null and townName != ''">and r.town_name like concat('%', #{townName}, '%')</if>
+            <if test="villageName != null and villageName != ''">and r.village_name like concat('%', #{villageName}, '%')</if>
             <if test="enterpriseName != null and enterpriseName != ''">and r.enterprise_name like concat('%', #{enterpriseName}, '%')</if>
             ${params.dataScope}
         </where>

baqing-admin/src/test/java/com/ruoyi/web/modules/industryservice/research/controller/ResearchOpenApiControllerApiTest.java

@@ -22,6 +22,7 @@ import org.springframework.test.web.servlet.setup.MockMvcBuilders;
 import com.ruoyi.web.modules.industryservice.domain.dto.OpenApiPageResult;
 import com.ruoyi.web.modules.industryservice.research.domain.dto.ResearchTokenVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchCooperativeDevelopmentVo;
+import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchFamilyRanchVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchLivestockProductOutputVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchPastureVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakHerdInventoryVo;
@@ -200,4 +201,34 @@ class ResearchOpenApiControllerApiTest
                 .andExpect(jsonPath("$.data.records[0].townName").value("雅安镇"))
                 .andExpect(jsonPath("$.data.records[0].villageName").value("荣嘎村"));
     }
+
+    @Test
+    @DisplayName("GET /family-ranches 成功")
+    void listFamilyRanches() throws Exception
+    {
+        ResearchFamilyRanchVo row = new ResearchFamilyRanchVo();
+        row.setRanchId(1L);
+        row.setStatYear(2026);
+        row.setStatMonth(5);
+        row.setTownName("雅安镇");
+        row.setVillageName("荣嘎村");
+        row.setEnterpriseName("测试牧场");
+        OpenApiPageResult<ResearchFamilyRanchVo> page = new OpenApiPageResult<>();
+        page.setPageNum(1);
+        page.setPageSize(20);
+        page.setTotal(1L);
+        page.setRecords(Collections.singletonList(row));
+        when(researchOpenApiService.listFamilyRanches(
+                anyInt(), anyInt(), any(), any(), any(), any(), any())).thenReturn(page);
+
+        mockMvc.perform(get("/open-api/v1/research/family-ranches")
+                .param("statYear", "2026")
+                .param("statMonth", "5")
+                .param("townName", "雅安")
+                .param("villageName", "荣嘎")
+                .param("enterpriseName", "测试"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.records[0].enterpriseName").value("测试牧场"));
+    }
 }

doc/产业数据模型及服务/科研开放数据接口/科研开放数据接口功能需求.md

@@ -32,6 +32,7 @@
 | 牦牛出栏数据列表 | 分页返回村级出栏填报汇总 |
 | 合作社发展数据列表 | 分页返回合作社发展填报；法人姓名脱敏 |
 | 畜牧产品产量登记列表 | 分页返回村级肉/奶产量 |
+| 家庭牧场数据列表 | 分页返回家庭牧场填报；法人姓名脱敏 |
 
 **本期不实现：**
 
@@ -174,6 +175,20 @@ sequenceDiagram
 
 **不返回**：部门 ID、创建人、备注等内部字段。
 
+### 6.8 家庭牧场数据列表
+
+| 项 | 说明 |
+| --- | --- |
+| 方法 | GET |
+| 路径 | `/family-ranches` |
+| 鉴权 | Bearer Token |
+| 分页 | 同 §6.2 |
+| 筛选 | `statYear`、`statMonth`、`townName`（乡镇模糊）、`villageName`（村模糊）、`enterpriseName`（企业名称模糊） |
+
+**返回字段**：`ranchId`、年月、乡镇村、企业信息、存出栏、草场、经营收支、补助与认证等；`legalRepresentative` 脱敏。
+
+**不返回**：部门 ID、创建人、备注等内部字段。
+
 ---
 
 ## 7. 脱敏规则摘要
@@ -215,6 +230,7 @@ sequenceDiagram
 | 牦牛出栏数据填报 | 数据源 `biz_yak_outbound_report` |
 | 合作社发展数据填报 | 数据源 `biz_cooperative_development` |
 | 畜牧产品产量登记 | 数据源 `biz_livestock_product_output` |
+| 家庭牧场数据填报 | 数据源 `biz_family_ranch` |
 | 若依权限体系 | **无**关联；开放接口走独立 Token |
 
 ---
@@ -230,5 +246,6 @@ sequenceDiagram
 | 牦牛出栏列表 | §6.5 |
 | 合作社发展列表 | §6.6 |
 | 畜牧产品产量列表 | §6.7 |
+| 家庭牧场列表 | §6.8 |
 | 脱敏合规 | §7 |
 | 本期不实现 | §3 |

doc/产业数据模型及服务/科研开放数据接口/科研开放数据接口技术方案.md

@@ -9,7 +9,7 @@
 | 项 | 说明 |
 | --- | --- |
 | **后端** | RuoYi **v3.9.2**（**springboot2** 分支）：JDK 8、Spring MVC、MyBatis |
-| **数据库** | 只读查询既有表 `biz_pasture`、`biz_yak_asset`、`biz_yak_herd_inventory`、`biz_yak_outbound_report`、`biz_cooperative_development`、`biz_livestock_product_output` |
+| **数据库** | 只读查询既有表 `biz_pasture`、`biz_yak_asset`、`biz_yak_herd_inventory`、`biz_yak_outbound_report`、`biz_cooperative_development`、`biz_livestock_product_output`、`biz_family_ranch` |
 | **鉴权** | 独立 JWT + Servlet Filter；`@Anonymous` 绕过若依登录，Filter 校验 Bearer Token |
 | **响应** | `OpenApiResponse<T>` + `OpenApiPageResult<T>`（与第三方 farming OpenAPI 同结构） |
 
@@ -182,6 +182,19 @@ Authorization: Bearer <accessToken>
 
 实现说明：直接查 `BizLivestockProductOutputMapper`（清空 `params.dataScope`）。
 
+### 3.8 家庭牧场数据列表
+
+```
+GET /open-api/v1/research/family-ranches?pageNum=1&pageSize=20&statYear=2026&statMonth=5&townName=&villageName=&enterpriseName=
+Authorization: Bearer <accessToken>
+```
+
+**查询参数：** `statYear` / `statMonth`（精确）；`townName` / `villageName` / `enterpriseName`（模糊）；分页同前。
+
+**`records[]` 元素（ResearchFamilyRanchVo）：** 家庭牧场业务字段；`legalRepresentative` 脱敏；**不含**部门 ID、操作人、备注。
+
+实现说明：直接查 `BizFamilyRanchMapper`（清空 `params.dataScope`）。
+
 ---
 
 ## 4. 鉴权流程
@@ -207,8 +220,9 @@ Token 申请：`appKey`/`appSecret` 与配置项精确匹配后签发 JWT（HS51
 | 出栏列表 | `BizYakOutboundReportMapper.selectBizYakOutboundReportList` | `biz_yak_outbound_report` | 同上 |
 | 合作社列表 | `BizCooperativeDevelopmentMapper.selectBizCooperativeDevelopmentList` | `biz_cooperative_development` | 年/月精确；乡镇/村/合作社名模糊；清空 `params.dataScope` |
 | 产量列表 | `BizLivestockProductOutputMapper.selectBizLivestockProductOutputList` | `biz_livestock_product_output` | 年/月精确；乡镇/村名模糊；清空 `params.dataScope` |
+| 家庭牧场列表 | `BizFamilyRanchMapper.selectBizFamilyRanchList` | `biz_family_ranch` | 年/月精确；乡镇/村/企业名模糊；清空 `params.dataScope` |
 
-实体 → VO：`ResearchOpenApiSupport.toPastureVo` / `toYakAssetVo` / `toYakHerdInventoryVo` / `toYakOutboundReportVo` / `toCooperativeDevelopmentVo` / `toLivestockProductOutputVo`。
+实体 → VO：`ResearchOpenApiSupport.toPastureVo` / `toYakAssetVo` / `toYakHerdInventoryVo` / `toYakOutboundReportVo` / `toCooperativeDevelopmentVo` / `toLivestockProductOutputVo` / `toFamilyRanchVo`。
 
 ---
 
@@ -269,6 +283,10 @@ curl "http://localhost:8010/open-api/v1/research/cooperative-developments?pageNu
 # 7. 畜牧产品产量
 curl "http://localhost:8010/open-api/v1/research/livestock-product-outputs?pageNum=1&pageSize=10&statYear=2026&townName=雅安" \
   -H "Authorization: Bearer <accessToken>"
+
+# 8. 家庭牧场
+curl "http://localhost:8010/open-api/v1/research/family-ranches?pageNum=1&pageSize=10&statYear=2026&enterpriseName=牧场" \
+  -H "Authorization: Bearer <accessToken>"
 ```
 
 ---
@@ -294,6 +312,7 @@ curl "http://localhost:8010/open-api/v1/research/livestock-product-outputs?pageN
 | §6.5 出栏 | **§3.5**、**§5** BizYakOutboundReport |
 | §6.6 合作社 | **§3.6**、**§5** BizCooperativeDevelopment |
 | §6.7 产量 | **§3.7**、**§5** BizLivestockProductOutput |
+| §6.8 家庭牧场 | **§3.8**、**§5** BizFamilyRanch |
 | §7 脱敏 | **§6** Masking |
 | §3 不实现机构区分 | 单一 app-key/secret，JWT 无 clientId |
 
@@ -303,6 +322,7 @@ curl "http://localhost:8010/open-api/v1/research/livestock-product-outputs?pageN
 
 | 版本 | 日期 | 说明 |
 | --- | --- | --- |
+| 1.5 | 2026-07-22 | 新增家庭牧场开放列表（年/月/乡镇村/企业名模糊+分页；法人脱敏） |
 | 1.4 | 2026-07-22 | 新增畜牧产品产量登记开放列表（年/月/乡镇村模糊+分页） |
 | 1.3 | 2026-07-22 | 新增合作社发展开放列表（年/月/乡镇村/名称模糊+分页；法人脱敏） |
 | 1.2 | 2026-07-22 | 新增牦牛出栏开放列表（年/月/乡镇村模糊+分页） |

doc/产业数据模型及服务/科研开放数据接口/科研开放数据接口测试用例.md

@@ -51,6 +51,8 @@
 | KYKF-API-018 | 合作社 | 年/月/乡镇村/名称筛选 | 接口测试 | curl | §6.6 | 已知合作社名片段 | GET 带筛选参数 | 条件生效；名称模糊匹配 |
 | KYKF-API-019 | 产量 | 分页列表 | 接口测试 | curl | §6.7 | 有效 Token；库有产量数据 | GET `/livestock-product-outputs?pageNum=1&pageSize=10` | `code=200`；含肉/奶产量；无部门 ID |
 | KYKF-API-020 | 产量 | 年/月/乡镇村筛选 | 接口测试 | curl | §6.7 | 已知年月与乡镇名片段 | GET 带筛选参数 | 条件生效；名称模糊匹配 |
+| KYKF-API-021 | 家庭牧场 | 分页列表 | 接口测试 | curl | §6.8 | 有效 Token；库有牧场数据 | GET `/family-ranches?pageNum=1&pageSize=10` | `code=200`；法人已脱敏；无部门 ID |
+| KYKF-API-022 | 家庭牧场 | 年/月/乡镇村/企业名筛选 | 接口测试 | curl | §6.8 | 已知企业名片段 | GET 带筛选参数 | 条件生效；名称模糊匹配 |
 
 ---
 
@@ -65,11 +67,12 @@
 | §6.5 出栏列表 | — | API-015～016 |
 | §6.6 合作社列表 | — | API-017～018 |
 | §6.7 产量列表 | — | API-019～020 |
+| §6.8 家庭牧场列表 | — | API-021～022 |
 | §7 脱敏 | UT-001～004 | API-012 |
 | §2 分页 | — | API-010 |
 | §3 无机构区分 | UT-005 | API-001（单一凭证） |
 
-**用例统计**：单元 **6**、接口 **20**，合计 **26** 条。
+**用例统计**：单元 **6**、接口 **22**，合计 **28** 条。
 
 ---
 
@@ -88,6 +91,7 @@ curl -s "$BASE/yak-herd-inventories?pageNum=1&pageSize=5&statYear=2026" -H "Auth
 curl -s "$BASE/yak-outbound-reports?pageNum=1&pageSize=5&statYear=2026" -H "Authorization: Bearer $TOKEN"
 curl -s "$BASE/cooperative-developments?pageNum=1&pageSize=5&statYear=2026" -H "Authorization: Bearer $TOKEN"
 curl -s "$BASE/livestock-product-outputs?pageNum=1&pageSize=5&statYear=2026" -H "Authorization: Bearer $TOKEN"
+curl -s "$BASE/family-ranches?pageNum=1&pageSize=5&statYear=2026" -H "Authorization: Bearer $TOKEN"
 ```
 
 （Windows 环境可用 PowerShell `Invoke-RestMethod`，见技术方案 **§8**。）