外部接口

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

@@ -17,6 +17,7 @@ import com.ruoyi.web.modules.industryservice.research.domain.dto.ResearchTokenVo
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchPastureVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakAssetVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakHerdInventoryVo;
+import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakOutboundReportVo;
 import com.ruoyi.web.modules.industryservice.research.service.IResearchOpenApiService;
 import com.ruoyi.web.modules.industryservice.research.support.ResearchOpenApiSupport;
 
@@ -120,4 +121,28 @@ public class ResearchOpenApiController
             return ResearchOpenApiSupport.error(code, ex.getMessage());
         }
     }
+
+    /**
+     * 牦牛出栏数据列表（村级汇总）。
+     */
+    @GetMapping("/yak-outbound-reports")
+    public OpenApiResponse<OpenApiPageResult<ResearchYakOutboundReportVo>> listYakOutboundReports(
+            @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)
+    {
+        try
+        {
+            return ResearchOpenApiSupport.success(researchOpenApiService.listYakOutboundReports(
+                    pageNum, pageSize, statYear, statMonth, townName, villageName));
+        }
+        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/dto/ResearchTokenVo.java

@@ -5,8 +5,10 @@ package com.ruoyi.web.modules.industryservice.research.domain.dto;
  */
 public class ResearchTokenVo
 {
+    /** 访问令牌（Bearer Token） */
     private String accessToken;
 
+    /** 令牌类型，固定为 Bearer */
     private String tokenType;
 
     /** 有效期（秒） */

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

@@ -8,12 +8,16 @@ public class ResearchPastureVo
     /** 本地牧场 ID（不含第三方编号） */
     private Long pastureId;
 
+    /** 牧场名称 */
     private String pastureName;
 
+    /** 牧场类型 */
     private String farmType;
 
+    /** 所属区县 */
     private String county;
 
+    /** 所属乡镇 */
     private String town;
 
     /** 区域摘要（区县+乡镇，不含详细地址） */
@@ -25,12 +29,16 @@ public class ResearchPastureVo
     /** 经度（约百米精度） */
     private Double longitude;
 
+    /** 建筑/占地面积 */
     private String floorArea;
 
+    /** 养殖规模 */
     private String scaleBreeding;
 
+    /** 养殖品种 */
     private String breedSpecies;
 
+    /** 简介 */
     private String introduction;
 
     /** 负责人（脱敏） */

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

@@ -7,35 +7,46 @@ import java.math.BigDecimal;
  */
 public class ResearchYakAssetVo
 {
-    /** 科研主体 pseudonym，非明文牦牛编号 */
+    /** 科研主体码（pseudonym，非明文牦牛编号） */
     private String subjectCode;
 
+    /** 所属牧场名称 */
     private String pastureName;
 
+    /** 所属圈舍名称 */
     private String enclosureName;
 
+    /** 性别（公/母） */
     private String gender;
 
+    /** 品种 */
     private String cattleVariety;
 
+    /** 月龄 */
     private Integer ageMonths;
 
     /** 出生年（不含具体日） */
     private Integer birthYear;
 
-    /** 出生月 1～12 */
+    /** 出生月（1～12） */
     private Integer birthMonth;
 
+    /** 资产状态：1正常 2死淘 3丢失 4出栏 */
     private Integer assetStatus;
 
+    /** 资产状态文案 */
     private String assetStatusLabel;
 
+    /** 入栏体重（公斤） */
     private BigDecimal entryWeightKg;
 
+    /** 来源 */
     private String source;
 
+    /** 养殖方式 */
     private String breedingMethod;
 
+    /** 入栏周期 */
     private String entryCycle;
 
     /** 体温快照（℃） */
@@ -47,10 +58,10 @@ public class ResearchYakAssetVo
     /** 环境温度快照（℃） */
     private BigDecimal envTemp;
 
-    /** 父系 pseudonym */
+    /** 父系科研主体码（pseudonym） */
     private String fatherSubjectCode;
 
-    /** 母系 pseudonym */
+    /** 母系科研主体码（pseudonym） */
     private String motherSubjectCode;
 
     public String getSubjectCode()

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

@@ -5,48 +5,70 @@ package com.ruoyi.web.modules.industryservice.research.domain.vo;
  */
 public class ResearchYakHerdInventoryVo
 {
+    /** 存栏记录 ID */
     private Long inventoryId;
 
+    /** 所属年份 */
     private Integer statYear;
 
+    /** 所属月份（1～12） */
     private Integer statMonth;
 
+    /** 所属乡镇名称 */
     private String townName;
 
+    /** 所属村名称 */
     private String villageName;
 
+    /** 村居数 */
     private Integer villageCount;
 
+    /** 牧户数 */
     private Integer herdsmanHouseholdCount;
 
+    /** 种公牛存栏数 */
     private Integer breedingBullCount;
 
+    /** 公牛/阉畜存栏数 */
     private Integer bullCastratedCount;
 
+    /** 公牛总存栏数（种公牛 + 公牛/阉畜） */
     private Integer bullTotal;
 
+    /** 0～1.5 岁幼畜存栏数（不包括 1.5 岁） */
     private Integer cowYoungCount;
 
+    /** 1.5 岁以上成畜存栏数（包括 1.5 岁） */
     private Integer cowAdultCount;
 
+    /** 母牛总存栏数（幼畜 + 成畜） */
     private Integer cowTotal;
 
+    /** 产奶母牛存栏数 */
     private Integer milkingCowCount;
 
+    /** 能繁母牛存栏数 */
     private Integer fertileCowCount;
 
+    /** 奶牛总存栏数（产奶母牛 + 能繁母牛） */
     private Integer dairyTotal;
 
+    /** 羊总存栏数 */
     private Integer sheepTotal;
 
+    /** 产奶羊存栏数 */
     private Integer milkingSheepCount;
 
+    /** 保险牦牛存栏数 */
     private Integer insuredYakCount;
 
+    /** 牦牛总存栏数（公牛 + 母牛 + 保险） */
     private Integer yakTotal;
 
+    /** 总存栏数（牦牛 + 奶牛 + 羊） */
     private Integer grandTotal;
 
+    /** 总量（牦牛 + 羊） */
     private Integer yakSheepTotal;
 
     public Long getInventoryId()

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

@@ -0,0 +1,215 @@
+package com.ruoyi.web.modules.industryservice.research.domain.vo;
+
+/**
+ * 科研开放接口 — 牦牛出栏填报记录（村级汇总，无个体敏感字段）。
+ */
+public class ResearchYakOutboundReportVo
+{
+    /** 出栏记录 ID */
+    private Long outboundId;
+
+    /** 所属年份 */
+    private Integer statYear;
+
+    /** 所属月份（1～12） */
+    private Integer statMonth;
+
+    /** 所属乡镇名称 */
+    private String townName;
+
+    /** 所属村名称 */
+    private String villageName;
+
+    /** 农牧户数 */
+    private Integer farmerHouseholdCount;
+
+    /** 农牧人数 */
+    private Integer farmerPopulationCount;
+
+    /** 牦牛出栏数 */
+    private Integer yakOutboundCount;
+
+    /** 黄牛/奶牛/犏牛出栏数 */
+    private Integer cattleOutboundCount;
+
+    /** 绵羊出栏数 */
+    private Integer sheepOutboundCount;
+
+    /** 山羊出栏数 */
+    private Integer goatOutboundCount;
+
+    /** 马骡出栏数 */
+    private Integer horseMuleOutboundCount;
+
+    /** 驴出栏数 */
+    private Integer donkeyOutboundCount;
+
+    /** 自食牛数 */
+    private Integer selfConsumptionCattleCount;
+
+    /** 自食绵羊数 */
+    private Integer selfConsumptionSheepCount;
+
+    /** 自食山羊数 */
+    private Integer selfConsumptionGoatCount;
+
+    public Long getOutboundId()
+    {
+        return outboundId;
+    }
+
+    public void setOutboundId(Long outboundId)
+    {
+        this.outboundId = outboundId;
+    }
+
+    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 Integer getFarmerHouseholdCount()
+    {
+        return farmerHouseholdCount;
+    }
+
+    public void setFarmerHouseholdCount(Integer farmerHouseholdCount)
+    {
+        this.farmerHouseholdCount = farmerHouseholdCount;
+    }
+
+    public Integer getFarmerPopulationCount()
+    {
+        return farmerPopulationCount;
+    }
+
+    public void setFarmerPopulationCount(Integer farmerPopulationCount)
+    {
+        this.farmerPopulationCount = farmerPopulationCount;
+    }
+
+    public Integer getYakOutboundCount()
+    {
+        return yakOutboundCount;
+    }
+
+    public void setYakOutboundCount(Integer yakOutboundCount)
+    {
+        this.yakOutboundCount = yakOutboundCount;
+    }
+
+    public Integer getCattleOutboundCount()
+    {
+        return cattleOutboundCount;
+    }
+
+    public void setCattleOutboundCount(Integer cattleOutboundCount)
+    {
+        this.cattleOutboundCount = cattleOutboundCount;
+    }
+
+    public Integer getSheepOutboundCount()
+    {
+        return sheepOutboundCount;
+    }
+
+    public void setSheepOutboundCount(Integer sheepOutboundCount)
+    {
+        this.sheepOutboundCount = sheepOutboundCount;
+    }
+
+    public Integer getGoatOutboundCount()
+    {
+        return goatOutboundCount;
+    }
+
+    public void setGoatOutboundCount(Integer goatOutboundCount)
+    {
+        this.goatOutboundCount = goatOutboundCount;
+    }
+
+    public Integer getHorseMuleOutboundCount()
+    {
+        return horseMuleOutboundCount;
+    }
+
+    public void setHorseMuleOutboundCount(Integer horseMuleOutboundCount)
+    {
+        this.horseMuleOutboundCount = horseMuleOutboundCount;
+    }
+
+    public Integer getDonkeyOutboundCount()
+    {
+        return donkeyOutboundCount;
+    }
+
+    public void setDonkeyOutboundCount(Integer donkeyOutboundCount)
+    {
+        this.donkeyOutboundCount = donkeyOutboundCount;
+    }
+
+    public Integer getSelfConsumptionCattleCount()
+    {
+        return selfConsumptionCattleCount;
+    }
+
+    public void setSelfConsumptionCattleCount(Integer selfConsumptionCattleCount)
+    {
+        this.selfConsumptionCattleCount = selfConsumptionCattleCount;
+    }
+
+    public Integer getSelfConsumptionSheepCount()
+    {
+        return selfConsumptionSheepCount;
+    }
+
+    public void setSelfConsumptionSheepCount(Integer selfConsumptionSheepCount)
+    {
+        this.selfConsumptionSheepCount = selfConsumptionSheepCount;
+    }
+
+    public Integer getSelfConsumptionGoatCount()
+    {
+        return selfConsumptionGoatCount;
+    }
+
+    public void setSelfConsumptionGoatCount(Integer selfConsumptionGoatCount)
+    {
+        this.selfConsumptionGoatCount = selfConsumptionGoatCount;
+    }
+}

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

@@ -5,6 +5,7 @@ import com.ruoyi.web.modules.industryservice.research.domain.dto.ResearchTokenVo
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchPastureVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakAssetVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakHerdInventoryVo;
+import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakOutboundReportVo;
 
 /**
  * 科研开放数据接口服务。
@@ -26,4 +27,13 @@ public interface IResearchOpenApiService
      */
     OpenApiPageResult<ResearchYakHerdInventoryVo> listYakHerdInventories(int pageNum, int pageSize,
             Integer statYear, Integer statMonth, String townName, String villageName);
+
+    /**
+     * 牦牛出栏填报列表。
+     *
+     * @param townName 所属乡镇名称模糊匹配
+     * @param villageName 所属村名称模糊匹配
+     */
+    OpenApiPageResult<ResearchYakOutboundReportVo> listYakOutboundReports(int pageNum, int pageSize,
+            Integer statYear, Integer statMonth, String townName, String villageName);
 }

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

@@ -11,13 +11,16 @@ import com.ruoyi.common.utils.StringUtils;
 import com.ruoyi.web.modules.industryservice.domain.BizPasture;
 import com.ruoyi.web.modules.industryservice.domain.BizYakAsset;
 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.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.ResearchPastureVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakAssetVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakHerdInventoryVo;
+import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakOutboundReportVo;
 import com.ruoyi.web.modules.industryservice.research.service.IResearchOpenApiService;
 import com.ruoyi.web.modules.industryservice.research.support.ResearchOpenApiSupport;
 import com.ruoyi.web.modules.industryservice.research.support.ResearchOpenApiTokenService;
@@ -42,6 +45,9 @@ public class ResearchOpenApiServiceImpl implements IResearchOpenApiService
     @Autowired
     private BizYakHerdInventoryMapper bizYakHerdInventoryMapper;
 
+    @Autowired
+    private BizYakOutboundReportMapper bizYakOutboundReportMapper;
+
     @Override
     public ResearchTokenVo authenticate(String appKey, String appSecret)
     {
@@ -110,6 +116,33 @@ public class ResearchOpenApiServiceImpl implements IResearchOpenApiService
                 rows.stream().map(ResearchOpenApiSupport::toYakHerdInventoryVo).collect(Collectors.toList()));
     }
 
+    @Override
+    public OpenApiPageResult<ResearchYakOutboundReportVo> listYakOutboundReports(int pageNum, int pageSize,
+            Integer statYear, Integer statMonth, String townName, String villageName)
+    {
+        tokenService.assertEnabled();
+        int safePageNum = normalizePageNum(pageNum);
+        int safePageSize = normalizePageSize(pageSize);
+        BizYakOutboundReport query = new BizYakOutboundReport();
+        query.setStatYear(statYear);
+        query.setStatMonth(statMonth);
+        if (StringUtils.isNotEmpty(townName))
+        {
+            query.setTownName(townName.trim());
+        }
+        if (StringUtils.isNotEmpty(villageName))
+        {
+            query.setVillageName(villageName.trim());
+        }
+        // 开放接口无登录上下文，清空 dataScope，避免走填报部门权限
+        query.getParams().put("dataScope", "");
+        PageHelper.startPage(safePageNum, safePageSize);
+        List<BizYakOutboundReport> rows = bizYakOutboundReportMapper.selectBizYakOutboundReportList(query);
+        PageInfo<BizYakOutboundReport> page = new PageInfo<>(rows);
+        return toPageResult(safePageNum, safePageSize, page.getTotal(),
+                rows.stream().map(ResearchOpenApiSupport::toYakOutboundReportVo).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

@@ -5,10 +5,12 @@ import java.util.UUID;
 import com.ruoyi.web.modules.industryservice.domain.BizPasture;
 import com.ruoyi.web.modules.industryservice.domain.BizYakAsset;
 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.ResearchPastureVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakAssetVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakHerdInventoryVo;
+import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakOutboundReportVo;
 
 /**
  * 科研开放接口响应组装与实体脱敏转换。
@@ -124,4 +126,30 @@ public final class ResearchOpenApiSupport
         vo.setYakSheepTotal(row.getYakSheepTotal());
         return vo;
     }
+
+    public static ResearchYakOutboundReportVo toYakOutboundReportVo(BizYakOutboundReport row)
+    {
+        if (row == null)
+        {
+            return null;
+        }
+        ResearchYakOutboundReportVo vo = new ResearchYakOutboundReportVo();
+        vo.setOutboundId(row.getId());
+        vo.setStatYear(row.getStatYear());
+        vo.setStatMonth(row.getStatMonth());
+        vo.setTownName(row.getTownName());
+        vo.setVillageName(row.getVillageName());
+        vo.setFarmerHouseholdCount(row.getFarmerHouseholdCount());
+        vo.setFarmerPopulationCount(row.getFarmerPopulationCount());
+        vo.setYakOutboundCount(row.getYakOutboundCount());
+        vo.setCattleOutboundCount(row.getCattleOutboundCount());
+        vo.setSheepOutboundCount(row.getSheepOutboundCount());
+        vo.setGoatOutboundCount(row.getGoatOutboundCount());
+        vo.setHorseMuleOutboundCount(row.getHorseMuleOutboundCount());
+        vo.setDonkeyOutboundCount(row.getDonkeyOutboundCount());
+        vo.setSelfConsumptionCattleCount(row.getSelfConsumptionCattleCount());
+        vo.setSelfConsumptionSheepCount(row.getSelfConsumptionSheepCount());
+        vo.setSelfConsumptionGoatCount(row.getSelfConsumptionGoatCount());
+        return vo;
+    }
 }

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

@@ -82,6 +82,12 @@
             <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>
             ${params.dataScope}
         </where>
         order by r.stat_year desc, r.stat_month desc, d.order_num asc, r.village_dept_id asc, r.id desc

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

@@ -23,6 +23,7 @@ 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.ResearchPastureVo;
 import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakHerdInventoryVo;
+import com.ruoyi.web.modules.industryservice.research.domain.vo.ResearchYakOutboundReportVo;
 import com.ruoyi.web.modules.industryservice.research.service.IResearchOpenApiService;
 
 @ExtendWith(MockitoExtension.class)
@@ -109,4 +110,33 @@ class ResearchOpenApiControllerApiTest
                 .andExpect(jsonPath("$.data.records[0].townName").value("雅安镇"))
                 .andExpect(jsonPath("$.data.records[0].villageName").value("荣嘎村"));
     }
+
+    @Test
+    @DisplayName("GET /yak-outbound-reports 成功")
+    void listYakOutboundReports() throws Exception
+    {
+        ResearchYakOutboundReportVo row = new ResearchYakOutboundReportVo();
+        row.setOutboundId(1L);
+        row.setStatYear(2026);
+        row.setStatMonth(5);
+        row.setTownName("雅安镇");
+        row.setVillageName("荣嘎村");
+        OpenApiPageResult<ResearchYakOutboundReportVo> page = new OpenApiPageResult<>();
+        page.setPageNum(1);
+        page.setPageSize(20);
+        page.setTotal(1L);
+        page.setRecords(Collections.singletonList(row));
+        when(researchOpenApiService.listYakOutboundReports(anyInt(), anyInt(), any(), any(), any(), any()))
+                .thenReturn(page);
+
+        mockMvc.perform(get("/open-api/v1/research/yak-outbound-reports")
+                .param("statYear", "2026")
+                .param("statMonth", "5")
+                .param("townName", "雅安")
+                .param("villageName", "荣嘎"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.records[0].townName").value("雅安镇"))
+                .andExpect(jsonPath("$.data.records[0].villageName").value("荣嘎村"));
+    }
 }

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

@@ -29,6 +29,7 @@
 | 牧场列表 | 分页返回脱敏牧场数据 |
 | 牦牛资产档案列表 | 分页返回脱敏档案数据（种群健康研究字段） |
 | 牦牛存栏数据列表 | 分页返回村级存栏填报汇总 |
+| 牦牛出栏数据列表 | 分页返回村级出栏填报汇总 |
 
 **本期不实现：**
 
@@ -129,6 +130,20 @@ sequenceDiagram
 
 **不返回**：部门 ID、创建人、备注等内部字段。
 
+### 6.5 牦牛出栏数据列表
+
+| 项 | 说明 |
+| --- | --- |
+| 方法 | GET |
+| 路径 | `/yak-outbound-reports` |
+| 鉴权 | Bearer Token |
+| 分页 | 同 §6.2 |
+| 筛选 | `statYear`（所属年份）、`statMonth`（所属月份）、`townName`（所属乡镇模糊）、`villageName`（所属村模糊） |
+
+**返回字段**：`outboundId`、`statYear`、`statMonth`、`townName`、`villageName`、农牧户/人口及各类出栏数量（牦牛/牛/绵羊/山羊/马骡/驴、自食牛羊等）。
+
+**不返回**：部门 ID、创建人、备注等内部字段。
+
 ---
 
 ## 7. 脱敏规则摘要
@@ -167,6 +182,7 @@ sequenceDiagram
 | 牧场管理 | 数据源 `biz_pasture` |
 | 牦牛资产档案管理 | 数据源 `biz_yak_asset` |
 | 牦牛存栏数据填报 | 数据源 `biz_yak_herd_inventory` |
+| 牦牛出栏数据填报 | 数据源 `biz_yak_outbound_report` |
 | 若依权限体系 | **无**关联；开放接口走独立 Token |
 
 ---
@@ -179,5 +195,6 @@ sequenceDiagram
 | 牧场列表 | §6.2、§7 |
 | 牦牛档案列表 | §6.3、§7 |
 | 牦牛存栏列表 | §6.4 |
+| 牦牛出栏列表 | §6.5 |
 | 脱敏合规 | §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_pasture`、`biz_yak_asset`、`biz_yak_herd_inventory`、`biz_yak_outbound_report` |
 | **鉴权** | 独立 JWT + Servlet Filter；`@Anonymous` 绕过若依登录，Filter 校验 Bearer Token |
 | **响应** | `OpenApiResponse<T>` + `OpenApiPageResult<T>`（与第三方 farming OpenAPI 同结构） |
 
@@ -143,6 +143,19 @@ Authorization: Bearer <accessToken>
 
 实现说明：直接查 `BizYakHerdInventoryMapper`（**不**走填报 Service 的部门数据权限）。
 
+### 3.5 牦牛出栏数据列表
+
+```
+GET /open-api/v1/research/yak-outbound-reports?pageNum=1&pageSize=20&statYear=2026&statMonth=5&townName=&villageName=
+Authorization: Bearer <accessToken>
+```
+
+**查询参数：** 同 §3.4（`statYear` / `statMonth` / `townName` / `villageName` / 分页）。
+
+**`records[]` 元素（ResearchYakOutboundReportVo）：** 含 `outboundId`、年月、乡镇村名及出栏汇总数量；**不含**部门 ID、操作人、备注。
+
+实现说明：直接查 `BizYakOutboundReportMapper`（清空 `params.dataScope`）。
+
 ---
 
 ## 4. 鉴权流程
@@ -165,8 +178,9 @@ Token 申请：`appKey`/`appSecret` 与配置项精确匹配后签发 JWT（HS51
 | 牧场列表 | `IBizPastureService.selectBizPastureList` | `biz_pasture` | `del_flag=0` |
 | 档案列表 | `IBizYakAssetService.selectBizYakAssetList` | `biz_yak_asset` | `del_flag=0`；支持 `assetStatus`、`gender`、`pastureId` |
 | 存栏列表 | `BizYakHerdInventoryMapper.selectBizYakHerdInventoryList` | `biz_yak_herd_inventory` | 年/月精确；乡镇/村名模糊；清空 `params.dataScope` |
+| 出栏列表 | `BizYakOutboundReportMapper.selectBizYakOutboundReportList` | `biz_yak_outbound_report` | 同上 |
 
-实体 → VO：`ResearchOpenApiSupport.toPastureVo` / `toYakAssetVo` / `toYakHerdInventoryVo`。
+实体 → VO：`ResearchOpenApiSupport.toPastureVo` / `toYakAssetVo` / `toYakHerdInventoryVo` / `toYakOutboundReportVo`。
 
 ---
 
@@ -215,6 +229,10 @@ curl "http://localhost:8010/open-api/v1/research/yak-assets?pageNum=1&pageSize=1
 # 4. 牦牛存栏
 curl "http://localhost:8010/open-api/v1/research/yak-herd-inventories?pageNum=1&pageSize=10&statYear=2026&townName=雅安" \
   -H "Authorization: Bearer <accessToken>"
+
+# 5. 牦牛出栏
+curl "http://localhost:8010/open-api/v1/research/yak-outbound-reports?pageNum=1&pageSize=10&statYear=2026&townName=雅安" \
+  -H "Authorization: Bearer <accessToken>"
 ```
 
 ---
@@ -237,6 +255,7 @@ curl "http://localhost:8010/open-api/v1/research/yak-herd-inventories?pageNum=1&
 | §6.2 牧场 | **§3.2**、**§5** BizPasture |
 | §6.3 档案 | **§3.3**、**§5** BizYakAsset |
 | §6.4 存栏 | **§3.4**、**§5** BizYakHerdInventory |
+| §6.5 出栏 | **§3.5**、**§5** BizYakOutboundReport |
 | §7 脱敏 | **§6** Masking |
 | §3 不实现机构区分 | 单一 app-key/secret，JWT 无 clientId |
 
@@ -246,5 +265,6 @@ curl "http://localhost:8010/open-api/v1/research/yak-herd-inventories?pageNum=1&
 
 | 版本 | 日期 | 说明 |
 | --- | --- | --- |
+| 1.2 | 2026-07-22 | 新增牦牛出栏开放列表（年/月/乡镇村模糊+分页） |
 | 1.1 | 2026-07-22 | 新增牦牛存栏开放列表（年/月/乡镇村模糊+分页） |
 | 1.0 | 2026-07-04 | 初版：Token + 牧场/档案脱敏列表；全局一对凭证 |

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

@@ -45,6 +45,8 @@
 | KYKF-API-012 | 脱敏 | 响应无敏感原文字段 | 接口测试 | curl | §7 | 库含手机/编号 | GET 两接口 | JSON 无 `yakNo`、`earTagNumber`、`externalId`、`detailAddress` |
 | KYKF-API-013 | 存栏 | 分页列表 | 接口测试 | curl | §6.4 | 有效 Token；库有存栏数据 | GET `/yak-herd-inventories?pageNum=1&pageSize=10` | `code=200`；含 `statYear`/`townName` 等；无部门 ID |
 | KYKF-API-014 | 存栏 | 年/月/乡镇村筛选 | 接口测试 | curl | §6.4 | 已知年月与乡镇名片段 | GET `statYear=&statMonth=&townName=&villageName=` | 条件生效；名称模糊匹配 |
+| KYKF-API-015 | 出栏 | 分页列表 | 接口测试 | curl | §6.5 | 有效 Token；库有出栏数据 | GET `/yak-outbound-reports?pageNum=1&pageSize=10` | `code=200`；含出栏汇总字段；无部门 ID |
+| KYKF-API-016 | 出栏 | 年/月/乡镇村筛选 | 接口测试 | curl | §6.5 | 已知年月与村名片段 | GET 带筛选参数 | 条件生效；名称模糊匹配 |
 
 ---
 
@@ -56,11 +58,12 @@
 | §6.2 牧场列表 | UT-003 | API-005～006 |
 | §6.3 档案列表 | UT-004 | API-007～009 |
 | §6.4 存栏列表 | — | API-013～014 |
+| §6.5 出栏列表 | — | API-015～016 |
 | §7 脱敏 | UT-001～004 | API-012 |
 | §2 分页 | — | API-010 |
 | §3 无机构区分 | UT-005 | API-001（单一凭证） |
 
-**用例统计**：单元 **6**、接口 **14**，合计 **20** 条。
+**用例统计**：单元 **6**、接口 **16**，合计 **22** 条。
 
 ---
 
@@ -76,6 +79,7 @@ TOKEN=$(curl -s -X POST "$BASE/auth/token" \
 curl -s "$BASE/pastures?pageNum=1&pageSize=5" -H "Authorization: Bearer $TOKEN"
 curl -s "$BASE/yak-assets?pageNum=1&pageSize=5&assetStatus=1" -H "Authorization: Bearer $TOKEN"
 curl -s "$BASE/yak-herd-inventories?pageNum=1&pageSize=5&statYear=2026" -H "Authorization: Bearer $TOKEN"
+curl -s "$BASE/yak-outbound-reports?pageNum=1&pageSize=5&statYear=2026" -H "Authorization: Bearer $TOKEN"
 ```
 
 （Windows 环境可用 PowerShell `Invoke-RestMethod`，见技术方案 **§8**。）