外部接口

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.ResearchDisposableIncomeVo;
 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;
@@ -222,4 +223,25 @@ public class ResearchOpenApiController
             return ResearchOpenApiSupport.error(code, ex.getMessage());
         }
     }
+
+    /**
+     * 可支配收入数据列表（县级年度汇总）。
+     */
+    @GetMapping("/disposable-incomes")
+    public OpenApiResponse<OpenApiPageResult<ResearchDisposableIncomeVo>> listDisposableIncomes(
+            @RequestParam(value = "pageNum", defaultValue = "1") int pageNum,
+            @RequestParam(value = "pageSize", defaultValue = "20") int pageSize,
+            @RequestParam(value = "statYear", required = false) Integer statYear)
+    {
+        try
+        {
+            return ResearchOpenApiSupport.success(
+                    researchOpenApiService.listDisposableIncomes(pageNum, pageSize, statYear));
+        }
+        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/ResearchDisposableIncomeVo.java

@@ -0,0 +1,87 @@
+package com.ruoyi.web.modules.industryservice.research.domain.vo;
+
+import java.math.BigDecimal;
+
+/**
+ * 科研开放接口 — 可支配收入数据填报（县级年度汇总；不含操作人 / 备注）。
+ */
+public class ResearchDisposableIncomeVo
+{
+    /** 可支配收入记录 ID */
+    private Long incomeId;
+
+    /** 所属年份 */
+    private Integer statYear;
+
+    /** 农村居民人均可支配收入（元） */
+    private BigDecimal ruralDisposableIncome;
+
+    /** 脱贫人口人均纯收入（元） */
+    private BigDecimal povertyNetIncome;
+
+    /** 增幅（元）；公式=本年可支配收入-上年可支配收入 */
+    private BigDecimal incomeIncrease;
+
+    /** 增速（%）；公式=(增幅/上年可支配收入)×100，保留2位小数 */
+    private BigDecimal incomeGrowthRate;
+
+    public Long getIncomeId()
+    {
+        return incomeId;
+    }
+
+    public void setIncomeId(Long incomeId)
+    {
+        this.incomeId = incomeId;
+    }
+
+    public Integer getStatYear()
+    {
+        return statYear;
+    }
+
+    public void setStatYear(Integer statYear)
+    {
+        this.statYear = statYear;
+    }
+
+    public BigDecimal getRuralDisposableIncome()
+    {
+        return ruralDisposableIncome;
+    }
+
+    public void setRuralDisposableIncome(BigDecimal ruralDisposableIncome)
+    {
+        this.ruralDisposableIncome = ruralDisposableIncome;
+    }
+
+    public BigDecimal getPovertyNetIncome()
+    {
+        return povertyNetIncome;
+    }
+
+    public void setPovertyNetIncome(BigDecimal povertyNetIncome)
+    {
+        this.povertyNetIncome = povertyNetIncome;
+    }
+
+    public BigDecimal getIncomeIncrease()
+    {
+        return incomeIncrease;
+    }
+
+    public void setIncomeIncrease(BigDecimal incomeIncrease)
+    {
+        this.incomeIncrease = incomeIncrease;
+    }
+
+    public BigDecimal getIncomeGrowthRate()
+    {
+        return incomeGrowthRate;
+    }
+
+    public void setIncomeGrowthRate(BigDecimal incomeGrowthRate)
+    {
+        this.incomeGrowthRate = incomeGrowthRate;
+    }
+}

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.ResearchDisposableIncomeVo;
 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;
@@ -68,4 +69,11 @@ public interface IResearchOpenApiService
      */
     OpenApiPageResult<ResearchFamilyRanchVo> listFamilyRanches(int pageNum, int pageSize,
             Integer statYear, Integer statMonth, String townName, String villageName, String enterpriseName);
+
+    /**
+     * 可支配收入填报列表。
+     *
+     * @param statYear 所属年份精确匹配
+     */
+    OpenApiPageResult<ResearchDisposableIncomeVo> listDisposableIncomes(int pageNum, int pageSize, Integer statYear);
 }

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.BizDisposableIncome;
 import com.ruoyi.web.modules.industryservice.domain.BizFamilyRanch;
 import com.ruoyi.web.modules.industryservice.domain.BizLivestockProductOutput;
 import com.ruoyi.web.modules.industryservice.domain.BizPasture;
@@ -17,6 +18,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.OpenApiPageResult;
 import com.ruoyi.web.modules.industryservice.mapper.BizCooperativeDevelopmentMapper;
+import com.ruoyi.web.modules.industryservice.mapper.BizDisposableIncomeMapper;
 import com.ruoyi.web.modules.industryservice.mapper.BizFamilyRanchMapper;
 import com.ruoyi.web.modules.industryservice.mapper.BizLivestockProductOutputMapper;
 import com.ruoyi.web.modules.industryservice.mapper.BizYakHerdInventoryMapper;
@@ -24,6 +26,7 @@ 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.ResearchDisposableIncomeVo;
 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;
@@ -66,6 +69,9 @@ public class ResearchOpenApiServiceImpl implements IResearchOpenApiService
     @Autowired
     private BizFamilyRanchMapper bizFamilyRanchMapper;
 
+    @Autowired
+    private BizDisposableIncomeMapper bizDisposableIncomeMapper;
+
     @Override
     public ResearchTokenVo authenticate(String appKey, String appSecret)
     {
@@ -250,6 +256,22 @@ public class ResearchOpenApiServiceImpl implements IResearchOpenApiService
                 rows.stream().map(ResearchOpenApiSupport::toFamilyRanchVo).collect(Collectors.toList()));
     }
 
+    @Override
+    public OpenApiPageResult<ResearchDisposableIncomeVo> listDisposableIncomes(int pageNum, int pageSize,
+            Integer statYear)
+    {
+        tokenService.assertEnabled();
+        int safePageNum = normalizePageNum(pageNum);
+        int safePageSize = normalizePageSize(pageSize);
+        BizDisposableIncome query = new BizDisposableIncome();
+        query.setStatYear(statYear);
+        PageHelper.startPage(safePageNum, safePageSize);
+        List<BizDisposableIncome> rows = bizDisposableIncomeMapper.selectBizDisposableIncomeList(query);
+        PageInfo<BizDisposableIncome> page = new PageInfo<>(rows);
+        return toPageResult(safePageNum, safePageSize, page.getTotal(),
+                rows.stream().map(ResearchOpenApiSupport::toDisposableIncomeVo).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.BizDisposableIncome;
 import com.ruoyi.web.modules.industryservice.domain.BizFamilyRanch;
 import com.ruoyi.web.modules.industryservice.domain.BizLivestockProductOutput;
 import com.ruoyi.web.modules.industryservice.domain.BizPasture;
@@ -11,6 +12,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.ResearchDisposableIncomeVo;
 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;
@@ -272,4 +274,20 @@ public final class ResearchOpenApiSupport
         vo.setWagePaid(row.getWagePaid());
         return vo;
     }
+
+    public static ResearchDisposableIncomeVo toDisposableIncomeVo(BizDisposableIncome row)
+    {
+        if (row == null)
+        {
+            return null;
+        }
+        ResearchDisposableIncomeVo vo = new ResearchDisposableIncomeVo();
+        vo.setIncomeId(row.getId());
+        vo.setStatYear(row.getStatYear());
+        vo.setRuralDisposableIncome(row.getRuralDisposableIncome());
+        vo.setPovertyNetIncome(row.getPovertyNetIncome());
+        vo.setIncomeIncrease(row.getIncomeIncrease());
+        vo.setIncomeGrowthRate(row.getIncomeGrowthRate());
+        return vo;
+    }
 }

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.ResearchDisposableIncomeVo;
 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;
@@ -231,4 +232,25 @@ class ResearchOpenApiControllerApiTest
                 .andExpect(jsonPath("$.code").value(200))
                 .andExpect(jsonPath("$.data.records[0].enterpriseName").value("测试牧场"));
     }
+
+    @Test
+    @DisplayName("GET /disposable-incomes 成功")
+    void listDisposableIncomes() throws Exception
+    {
+        ResearchDisposableIncomeVo row = new ResearchDisposableIncomeVo();
+        row.setIncomeId(1L);
+        row.setStatYear(2025);
+        OpenApiPageResult<ResearchDisposableIncomeVo> page = new OpenApiPageResult<>();
+        page.setPageNum(1);
+        page.setPageSize(20);
+        page.setTotal(1L);
+        page.setRecords(Collections.singletonList(row));
+        when(researchOpenApiService.listDisposableIncomes(anyInt(), anyInt(), any())).thenReturn(page);
+
+        mockMvc.perform(get("/open-api/v1/research/disposable-incomes")
+                .param("statYear", "2025"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.records[0].statYear").value(2025));
+    }
 }

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

@@ -33,6 +33,7 @@
 | 合作社发展数据列表 | 分页返回合作社发展填报；法人姓名脱敏 |
 | 畜牧产品产量登记列表 | 分页返回村级肉/奶产量 |
 | 家庭牧场数据列表 | 分页返回家庭牧场填报；法人姓名脱敏 |
+| 可支配收入数据列表 | 分页返回县级年度可支配收入填报 |
 
 **本期不实现：**
 
@@ -189,6 +190,20 @@ sequenceDiagram
 
 **不返回**：部门 ID、创建人、备注等内部字段。
 
+### 6.9 可支配收入数据列表
+
+| 项 | 说明 |
+| --- | --- |
+| 方法 | GET |
+| 路径 | `/disposable-incomes` |
+| 鉴权 | Bearer Token |
+| 分页 | 同 §6.2 |
+| 筛选 | `statYear`（所属年份精确） |
+
+**返回字段**：`incomeId`、`statYear`、`ruralDisposableIncome`、`povertyNetIncome`、`incomeIncrease`、`incomeGrowthRate`。
+
+**不返回**：创建人、备注等内部字段。
+
 ---
 
 ## 7. 脱敏规则摘要
@@ -231,6 +246,7 @@ sequenceDiagram
 | 合作社发展数据填报 | 数据源 `biz_cooperative_development` |
 | 畜牧产品产量登记 | 数据源 `biz_livestock_product_output` |
 | 家庭牧场数据填报 | 数据源 `biz_family_ranch` |
+| 可支配收入数据填报 | 数据源 `biz_disposable_income` |
 | 若依权限体系 | **无**关联；开放接口走独立 Token |
 
 ---
@@ -247,5 +263,6 @@ sequenceDiagram
 | 合作社发展列表 | §6.6 |
 | 畜牧产品产量列表 | §6.7 |
 | 家庭牧场列表 | §6.8 |
+| 可支配收入列表 | §6.9 |
 | 脱敏合规 | §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_family_ranch` |
+| **数据库** | 只读查询既有表 `biz_pasture`、`biz_yak_asset`、`biz_yak_herd_inventory`、`biz_yak_outbound_report`、`biz_cooperative_development`、`biz_livestock_product_output`、`biz_family_ranch`、`biz_disposable_income` |
 | **鉴权** | 独立 JWT + Servlet Filter；`@Anonymous` 绕过若依登录，Filter 校验 Bearer Token |
 | **响应** | `OpenApiResponse<T>` + `OpenApiPageResult<T>`（与第三方 farming OpenAPI 同结构） |
 
@@ -195,6 +195,19 @@ Authorization: Bearer <accessToken>
 
 实现说明：直接查 `BizFamilyRanchMapper`（清空 `params.dataScope`）。
 
+### 3.9 可支配收入数据列表
+
+```
+GET /open-api/v1/research/disposable-incomes?pageNum=1&pageSize=20&statYear=2025
+Authorization: Bearer <accessToken>
+```
+
+**查询参数：** `statYear`（精确）；分页同前。
+
+**`records[]` 元素（ResearchDisposableIncomeVo）：** `incomeId`、`statYear`、`ruralDisposableIncome`、`povertyNetIncome`、`incomeIncrease`、`incomeGrowthRate`；**不含**操作人、备注。
+
+实现说明：直接查 `BizDisposableIncomeMapper.selectBizDisposableIncomeList`。
+
 ---
 
 ## 4. 鉴权流程
@@ -221,8 +234,9 @@ Token 申请：`appKey`/`appSecret` 与配置项精确匹配后签发 JWT（HS51
 | 合作社列表 | `BizCooperativeDevelopmentMapper.selectBizCooperativeDevelopmentList` | `biz_cooperative_development` | 年/月精确；乡镇/村/合作社名模糊；清空 `params.dataScope` |
 | 产量列表 | `BizLivestockProductOutputMapper.selectBizLivestockProductOutputList` | `biz_livestock_product_output` | 年/月精确；乡镇/村名模糊；清空 `params.dataScope` |
 | 家庭牧场列表 | `BizFamilyRanchMapper.selectBizFamilyRanchList` | `biz_family_ranch` | 年/月精确；乡镇/村/企业名模糊；清空 `params.dataScope` |
+| 可支配收入列表 | `BizDisposableIncomeMapper.selectBizDisposableIncomeList` | `biz_disposable_income` | 年份精确 |
 
-实体 → VO：`ResearchOpenApiSupport.toPastureVo` / `toYakAssetVo` / `toYakHerdInventoryVo` / `toYakOutboundReportVo` / `toCooperativeDevelopmentVo` / `toLivestockProductOutputVo` / `toFamilyRanchVo`。
+实体 → VO：`ResearchOpenApiSupport.toPastureVo` / `toYakAssetVo` / `toYakHerdInventoryVo` / `toYakOutboundReportVo` / `toCooperativeDevelopmentVo` / `toLivestockProductOutputVo` / `toFamilyRanchVo` / `toDisposableIncomeVo`。
 
 ---
 
@@ -287,6 +301,10 @@ curl "http://localhost:8010/open-api/v1/research/livestock-product-outputs?pageN
 # 8. 家庭牧场
 curl "http://localhost:8010/open-api/v1/research/family-ranches?pageNum=1&pageSize=10&statYear=2026&enterpriseName=牧场" \
   -H "Authorization: Bearer <accessToken>"
+
+# 9. 可支配收入
+curl "http://localhost:8010/open-api/v1/research/disposable-incomes?pageNum=1&pageSize=10&statYear=2025" \
+  -H "Authorization: Bearer <accessToken>"
 ```
 
 ---
@@ -313,6 +331,7 @@ curl "http://localhost:8010/open-api/v1/research/family-ranches?pageNum=1&pageSi
 | §6.6 合作社 | **§3.6**、**§5** BizCooperativeDevelopment |
 | §6.7 产量 | **§3.7**、**§5** BizLivestockProductOutput |
 | §6.8 家庭牧场 | **§3.8**、**§5** BizFamilyRanch |
+| §6.9 可支配收入 | **§3.9**、**§5** BizDisposableIncome |
 | §7 脱敏 | **§6** Masking |
 | §3 不实现机构区分 | 单一 app-key/secret，JWT 无 clientId |
 
@@ -322,6 +341,7 @@ curl "http://localhost:8010/open-api/v1/research/family-ranches?pageNum=1&pageSi
 
 | 版本 | 日期 | 说明 |
 | --- | --- | --- |
+| 1.6 | 2026-07-22 | 新增可支配收入开放列表（年份精确+分页） |
 | 1.5 | 2026-07-22 | 新增家庭牧场开放列表（年/月/乡镇村/企业名模糊+分页；法人脱敏） |
 | 1.4 | 2026-07-22 | 新增畜牧产品产量登记开放列表（年/月/乡镇村模糊+分页） |
 | 1.3 | 2026-07-22 | 新增合作社发展开放列表（年/月/乡镇村/名称模糊+分页；法人脱敏） |

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

@@ -53,6 +53,8 @@
 | 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 带筛选参数 | 条件生效；名称模糊匹配 |
+| KYKF-API-023 | 可支配收入 | 分页列表 | 接口测试 | curl | §6.9 | 有效 Token；库有收入数据 | GET `/disposable-incomes?pageNum=1&pageSize=10` | `code=200`；无操作人/备注 |
+| KYKF-API-024 | 可支配收入 | 年份筛选 | 接口测试 | curl | §6.9 | 已知年份 | GET 带 `statYear` | 仅返回该年记录 |
 
 ---
 
@@ -68,11 +70,12 @@
 | §6.6 合作社列表 | — | API-017～018 |
 | §6.7 产量列表 | — | API-019～020 |
 | §6.8 家庭牧场列表 | — | API-021～022 |
+| §6.9 可支配收入列表 | — | API-023～024 |
 | §7 脱敏 | UT-001～004 | API-012 |
 | §2 分页 | — | API-010 |
 | §3 无机构区分 | UT-005 | API-001（单一凭证） |
 
-**用例统计**：单元 **6**、接口 **22**，合计 **28** 条。
+**用例统计**：单元 **6**、接口 **24**，合计 **30** 条。
 
 ---
 
@@ -92,6 +95,7 @@ curl -s "$BASE/yak-outbound-reports?pageNum=1&pageSize=5&statYear=2026" -H "Auth
 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"
+curl -s "$BASE/disposable-incomes?pageNum=1&pageSize=5&statYear=2025" -H "Authorization: Bearer $TOKEN"
 ```
 
 （Windows 环境可用 PowerShell `Invoke-RestMethod`，见技术方案 **§8**。）