西藏巴青项目

科研开放数据接口 — 技术方案

依据：同目录 科研开放数据接口功能需求.md。对外只读开放 API；无前端页面、无新表。

1. 技术架构

项	说明
后端	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_disposable_income`、`biz_farmer_household`、`biz_common_prosperity_project`、`biz_large_livestock_farmer`、`biz_vaccination_data`、`biz_livestock_ownership_household`、`biz_rural_three_assets`、`biz_three_assets_problem_report`、`biz_tech_service_personnel`
鉴权	独立 JWT + Servlet Filter；`@Anonymous` 绕过若依登录，Filter 校验 Bearer Token
响应	`OpenApiResponse<T>` + `OpenApiPageResult<T>`（与第三方 farming OpenAPI 同结构）

代码包：baqing-admin → com.ruoyi.web.modules.industryservice.research

类	职责
`ResearchOpenApiController`	HTTP 入口
`ResearchOpenApiServiceImpl`	分页查询 + 脱敏 VO 转换
`ResearchOpenApiTokenService`	签发/校验 JWT
`ResearchOpenApiAuthFilter`	除 `/auth/token` 外校验 Token
`ResearchOpenApiMasking` / `ResearchOpenApiSupport`	脱敏与响应组装

2. 配置

application.yml → research-open-api：

键	说明
`enabled`	是否启用；`false` 时返回 503
`app-key`	申请 Token 用（全局唯一）
`app-secret`	申请 Token 用
`token-secret`	JWT 签名密钥（仅服务端，勿下发）
`token-expire-minutes`	Token 有效期，默认 120
`max-page-size`	单页上限，默认 200

示例：

research-open-api:
  enabled: true
  app-key: research-open-demo-key
  app-secret: research-open-demo-secret-change-me
  token-secret: research-open-api-change-me-in-production
  token-expire-minutes: 120
  max-page-size: 200

3. 接口设计

Base Path：/open-api/v1/research

3.1 申请 Token

POST /open-api/v1/research/auth/token
Content-Type: application/json

{"appKey":"research-open-demo-key","appSecret":"research-open-demo-secret-change-me"}

成功响应 data：

{
  "accessToken": "eyJhbGciOiJIUzUxMiJ9...",
  "tokenType": "Bearer",
  "expiresIn": 7200
}

JWT Claims：type=research_open_api；不含机构 ID。

3.2 牧场列表

GET /open-api/v1/research/pastures?pageNum=1&pageSize=20&keyword=
Authorization: Bearer <accessToken>

records[] 元素（ResearchPastureVo）：

字段	类型	说明
`pastureId`	long	本地牧场 ID
`pastureName`	string	牧场名称
`farmType`	string	类型
`county` / `town`	string	区县、乡镇
`regionSummary`	string	区县+乡镇摘要
`latitude` / `longitude`	number	约百米精度
`floorArea` / `scaleBreeding` / `breedSpecies`	string	规模类
`introduction`	string	简介
`personInCharge`	string	脱敏负责人
`contactPhone`	string	脱敏手机

3.3 牦牛资产档案列表

GET /open-api/v1/research/yak-assets?pageNum=1&pageSize=20&assetStatus=1&gender=母&pastureId=
Authorization: Bearer <accessToken>

records[] 元素（ResearchYakAssetVo）：

字段	类型	说明
`subjectCode`	string	科研主体码，如 `YS00000088`
`pastureName` / `enclosureName`	string	牧场、圈舍名称
`gender` / `cattleVariety`	string	性别、品种
`ageMonths`	int	月龄
`birthYear` / `birthMonth`	int	出生年月
`assetStatus`	int	1～4
`assetStatusLabel`	string	正常/死淘/丢失/出栏
`entryWeightKg`	decimal	入栏体重
`source` / `breedingMethod` / `entryCycle`	string	来源、养殖方式、周期
`realtimeTemp` / `realtimeSteps` / `envTemp`	number	IoT 快照
`fatherSubjectCode` / `motherSubjectCode`	string	系谱 pseudonym

3.4 牦牛存栏数据列表

GET /open-api/v1/research/yak-herd-inventories?pageNum=1&pageSize=20&statYear=2026&statMonth=5&townName=&villageName=
Authorization: Bearer <accessToken>

查询参数：

参数	说明
`statYear`	所属年份（精确）
`statMonth`	所属月份（精确）
`townName`	所属乡镇名称模糊匹配
`villageName`	所属村名称模糊匹配
`pageNum` / `pageSize`	分页，同牧场列表

records[] 元素（ResearchYakHerdInventoryVo）： 含 inventoryId、statYear、statMonth、townName、villageName 及畜群汇总数量字段；不含 townDeptId / villageDeptId、操作人、备注。

实现说明：直接查 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）。

3.6 合作社发展数据列表

GET /open-api/v1/research/cooperative-developments?pageNum=1&pageSize=20&statYear=2026&statMonth=5&townName=&villageName=&cooperativeName=
Authorization: Bearer <accessToken>

查询参数： statYear / statMonth（精确）；townName / villageName / cooperativeName（模糊）；分页同前。

records[] 元素（ResearchCooperativeDevelopmentVo）： 合作社发展业务字段；legalRepresentative 脱敏；不含部门 ID、操作人、备注。

实现说明：直接查 BizCooperativeDevelopmentMapper（清空 params.dataScope）。

3.7 畜牧产品产量登记列表

GET /open-api/v1/research/livestock-product-outputs?pageNum=1&pageSize=20&statYear=2026&statMonth=5&townName=&villageName=
Authorization: Bearer <accessToken>

查询参数： statYear / statMonth（精确）；townName / villageName（模糊）；分页同前。

records[] 元素（ResearchLivestockProductOutputVo）： outputId、年月、乡镇村、meatOutput/milkOutput（万吨）；不含部门 ID、操作人、备注。

实现说明：直接查 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）。

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。

3.10 农牧户数据列表

GET /open-api/v1/research/farmer-households?pageNum=1&pageSize=20&statYear=2026&statMonth=5&townName=&villageName=
Authorization: Bearer <accessToken>

查询参数： statYear / statMonth（精确）；townName / villageName（模糊）；分页同前。

records[] 元素（ResearchFarmerHouseholdVo）： 农牧户业务字段；不含部门 ID、操作人、备注。

实现说明：直接查 BizFarmerHouseholdMapper（清空 params.dataScope）。

3.11 共同富裕项目列表

GET /open-api/v1/research/common-prosperity-projects?pageNum=1&pageSize=20&projectName=&projectType=1&implYear=2025
Authorization: Bearer <accessToken>

查询参数： projectName（模糊）；projectType / implYear（精确）；分页同前。

records[] 元素（ResearchCommonProsperityProjectVo）： 项目业务字段与媒体 URL；不含本地文件路径、操作人、备注。

实现说明：直接查 BizCommonProsperityProjectMapper.selectBizCommonProsperityProjectList。

3.12 养殖大户数据列表

GET /open-api/v1/research/large-livestock-farmers?pageNum=1&pageSize=20&statYear=2026&statMonth=5&townName=&villageName=&enterpriseName=
Authorization: Bearer <accessToken>

查询参数： statYear / statMonth（精确）；townName / villageName / enterpriseName（模糊）；分页同前。

records[] 元素（ResearchLargeLivestockFarmerVo）： 养殖大户业务字段；legalRepresentative 脱敏；不含部门 ID、操作人、备注。

实现说明：直接查 BizLargeLivestockFarmerMapper（清空 params.dataScope）。

3.13 疫苗接种数据列表

GET /open-api/v1/research/vaccination-data?pageNum=1&pageSize=20&statYear=2026&statMonth=5&townName=&villageName=
Authorization: Bearer <accessToken>

查询参数： statYear / statMonth（精确）；townName / villageName（模糊）；分页同前。

records[] 元素（ResearchVaccinationDataVo）： vaccinationId、年月、乡镇村、应免/实免数、免疫率；不含部门 ID、操作人、备注。

实现说明：直接查 BizVaccinationDataMapper（清空 params.dataScope）。

3.14 有无畜户数据列表

GET /open-api/v1/research/livestock-ownership-households?pageNum=1&pageSize=20&statYear=2026&statMonth=5&townName=&villageName=
Authorization: Bearer <accessToken>

查询参数： statYear / statMonth（精确）；townName / villageName（模糊）；分页同前。

records[] 元素（ResearchLivestockOwnershipHouseholdVo）： 有畜户/无畜户统计字段；不含部门 ID、操作人、备注。

实现说明：直接查 BizLivestockOwnershipHouseholdMapper（清空 params.dataScope）。

3.15 农村三资数据列表

GET /open-api/v1/research/rural-three-assets?pageNum=1&pageSize=20&townName=&villageName=
Authorization: Bearer <accessToken>

查询参数： townName / villageName（模糊）；分页同前。

records[] 元素（ResearchRuralThreeAssetsVo）： 固定资产相关字段；不含部门 ID、操作人、备注。

实现说明：直接查 BizRuralThreeAssetsMapper（清空 params.dataScope）。

3.16 三资具体问题列表

GET /open-api/v1/research/three-assets-problem-reports?pageNum=1&pageSize=20&townName=&villageName=&problemType=fund&beginReportTime=2026-01-01&endReportTime=2026-12-31
Authorization: Bearer <accessToken>

查询参数： townName / villageName（模糊）；problemType（精确）；beginReportTime / endReportTime（yyyy-MM-dd，同时有值才按上报日期区间过滤）；分页同前。

records[] 元素（ResearchThreeAssetsProblemReportVo）： 上报时间、乡镇村、问题类型/等级、详情、处理结果；不含部门 ID、操作人、备注。

实现说明：直接查 BizThreeAssetsProblemReportMapper（清空 params.dataScope）。

3.17 科技服务人员详情

GET /open-api/v1/research/tech-service-personnel
Authorization: Bearer <accessToken>

查询参数： 无（单例配置）。

data（ResearchTechServicePersonnelVo）： 科技特派员与农业事业单位各级人数及合计；不含操作人、更新时间。未配置时 data 可为 null。

实现说明：复用 IBizTechServicePersonnelService.getCurrentConfig()。

4. 鉴权流程

ResearchOpenApiController 标注 @Anonymous → Spring Security 放行。
ResearchOpenApiAuthFilter 拦截 /open-api/v1/research/*（排除 /auth/token）。
解析 Authorization: Bearer …，ResearchOpenApiTokenService.validateToken 验签与过期。
失败返回 JSON { code:401, message:"..." }，HTTP 401。

Token 申请：appKey/appSecret 与配置项精确匹配后签发 JWT（HS512 + token-secret）。

5. 数据查询

复用既有 Service / Mapper：

接口	Service	表	条件
牧场列表	`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`	同上
合作社列表	`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`	年份精确
农牧户列表	`BizFarmerHouseholdMapper.selectBizFarmerHouseholdList`	`biz_farmer_household`	年/月精确；乡镇/村名模糊；清空 `params.dataScope`
共同富裕项目列表	`BizCommonProsperityProjectMapper.selectBizCommonProsperityProjectList`	`biz_common_prosperity_project`	项目名模糊；类型/实施年限精确
养殖大户列表	`BizLargeLivestockFarmerMapper.selectBizLargeLivestockFarmerList`	`biz_large_livestock_farmer`	年/月精确；乡镇/村/企业名模糊；清空 `params.dataScope`
疫苗接种列表	`BizVaccinationDataMapper.selectBizVaccinationDataList`	`biz_vaccination_data`	年/月精确；乡镇/村名模糊；清空 `params.dataScope`
有无畜户列表	`BizLivestockOwnershipHouseholdMapper.selectBizLivestockOwnershipHouseholdList`	`biz_livestock_ownership_household`	年/月精确；乡镇/村名模糊；清空 `params.dataScope`
农村三资列表	`BizRuralThreeAssetsMapper.selectBizRuralThreeAssetsList`	`biz_rural_three_assets`	乡镇/村名模糊；清空 `params.dataScope`
三资具体问题列表	`BizThreeAssetsProblemReportMapper.selectBizThreeAssetsProblemReportList`	`biz_three_assets_problem_report`	乡镇/村名模糊；类型精确；上报起止日期同时有值；清空 `params.dataScope`
科技服务人员详情	`IBizTechServicePersonnelService.getCurrentConfig`	`biz_tech_service_personnel`	单例 id=1；无筛选参数

实体 → VO：ResearchOpenApiSupport.toPastureVo / toYakAssetVo / toYakHerdInventoryVo / toYakOutboundReportVo / toCooperativeDevelopmentVo / toLivestockProductOutputVo / toFamilyRanchVo / toDisposableIncomeVo / toFarmerHouseholdVo / toCommonProsperityProjectVo / toLargeLivestockFarmerVo / toVaccinationDataVo / toLivestockOwnershipHouseholdVo / toRuralThreeAssetsVo / toThreeAssetsProblemReportVo / toTechServicePersonnelVo。

6. 脱敏实现

方法	说明
`maskPhone`	复用 `SubsidyGrantRecordMasking.maskPhone`
`maskPersonName`	首字 + `*`
`regionSummary`	区县 + 乡镇
`roundCoordinate`	经纬度 3 位小数
`subjectCode`	`YS` + 8 位 `id`
`pseudonymCode`	系谱编号哈希短码

7. 异常码

code	HTTP	场景
200	200	成功
401	401	appKey/appSecret 错误、Token 缺失/无效/过期
400	200*	pageSize 超限（body.code=400）
503	503	`enabled=false` 或未配置凭证

* 业务错误仍返回 JSON body，HTTP 状态与 code 一致（Filter 401/503；Controller 内 ServiceException 写入 body.code）。

8. 调用示例

# 1. 申请 Token
curl -X POST "http://localhost:8010/open-api/v1/research/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"appKey":"research-open-demo-key","appSecret":"research-open-demo-secret-change-me"}'

# 2. 牧场列表
curl "http://localhost:8010/open-api/v1/research/pastures?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer <accessToken>"

# 3. 牦牛档案
curl "http://localhost:8010/open-api/v1/research/yak-assets?pageNum=1&pageSize=10&assetStatus=1" \
  -H "Authorization: Bearer <accessToken>"

# 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>"

# 6. 合作社发展
curl "http://localhost:8010/open-api/v1/research/cooperative-developments?pageNum=1&pageSize=10&statYear=2026&cooperativeName=合作" \
  -H "Authorization: Bearer <accessToken>"

# 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>"

# 9. 可支配收入
curl "http://localhost:8010/open-api/v1/research/disposable-incomes?pageNum=1&pageSize=10&statYear=2025" \
  -H "Authorization: Bearer <accessToken>"

# 10. 农牧户
curl "http://localhost:8010/open-api/v1/research/farmer-households?pageNum=1&pageSize=10&statYear=2026&townName=雅安" \
  -H "Authorization: Bearer <accessToken>"

# 11. 共同富裕项目
curl "http://localhost:8010/open-api/v1/research/common-prosperity-projects?pageNum=1&pageSize=10&projectName=和美&implYear=2025" \
  -H "Authorization: Bearer <accessToken>"

# 12. 养殖大户
curl "http://localhost:8010/open-api/v1/research/large-livestock-farmers?pageNum=1&pageSize=10&statYear=2026&enterpriseName=养殖" \
  -H "Authorization: Bearer <accessToken>"

# 13. 疫苗接种
curl "http://localhost:8010/open-api/v1/research/vaccination-data?pageNum=1&pageSize=10&statYear=2026&townName=雅安" \
  -H "Authorization: Bearer <accessToken>"

# 14. 有无畜户
curl "http://localhost:8010/open-api/v1/research/livestock-ownership-households?pageNum=1&pageSize=10&statYear=2026&townName=雅安" \
  -H "Authorization: Bearer <accessToken>"

# 15. 农村三资
curl "http://localhost:8010/open-api/v1/research/rural-three-assets?pageNum=1&pageSize=10&townName=雅安" \
  -H "Authorization: Bearer <accessToken>"

# 16. 三资具体问题
curl "http://localhost:8010/open-api/v1/research/three-assets-problem-reports?pageNum=1&pageSize=10&problemType=fund&beginReportTime=2026-01-01&endReportTime=2026-12-31" \
  -H "Authorization: Bearer <accessToken>"

# 17. 科技服务人员详情
curl "http://localhost:8010/open-api/v1/research/tech-service-personnel" \
  -H "Authorization: Bearer <accessToken>"

9. 测试

见同目录 科研开放数据接口测试用例.md。单元测试：

ResearchOpenApiMaskingTest
ResearchOpenApiTokenServiceTest
ResearchOpenApiControllerApiTest

10. 需求追溯

功能需求	技术落点
§5 认证	§2 配置、§4 Filter + TokenService
§6.2 牧场	§3.2、§5 BizPasture
§6.3 档案	§3.3、§5 BizYakAsset
§6.4 存栏	§3.4、§5 BizYakHerdInventory
§6.5 出栏	§3.5、§5 BizYakOutboundReport
§6.6 合作社	§3.6、§5 BizCooperativeDevelopment
§6.7 产量	§3.7、§5 BizLivestockProductOutput
§6.8 家庭牧场	§3.8、§5 BizFamilyRanch
§6.9 可支配收入	§3.9、§5 BizDisposableIncome
§6.10 农牧户	§3.10、§5 BizFarmerHousehold
§6.11 共同富裕项目	§3.11、§5 BizCommonProsperityProject
§6.12 养殖大户	§3.12、§5 BizLargeLivestockFarmer
§6.13 疫苗接种	§3.13、§5 BizVaccinationData
§6.14 有无畜户	§3.14、§5 BizLivestockOwnershipHousehold
§6.15 农村三资	§3.15、§5 BizRuralThreeAssets
§6.16 三资具体问题	§3.16、§5 BizThreeAssetsProblemReport
§6.17 科技服务人员	§3.17、§5 IBizTechServicePersonnelService
§7 脱敏	§6 Masking
§3 不实现机构区分	单一 app-key/secret，JWT 无 clientId

11. 修订记录

版本	日期	说明
1.14	2026-07-22	新增科技服务人员管理详情开放接口（单例、无参）
1.13	2026-07-22	新增三资具体问题开放列表（乡镇村模糊/类型精确/上报起止日期同时有值+分页）
1.12	2026-07-22	新增农村三资开放列表（乡镇村模糊+分页）
1.11	2026-07-22	新增有无畜户开放列表（年/月/乡镇村模糊+分页）
1.10	2026-07-22	新增疫苗接种开放列表（年/月/乡镇村模糊+分页）
1.9	2026-07-22	新增养殖大户开放列表（年/月/乡镇村/企业名模糊+分页；法人脱敏）
1.8	2026-07-22	新增共同富裕项目开放列表（项目名模糊/类型与实施年限精确+分页）
1.7	2026-07-22	新增农牧户开放列表（年/月/乡镇村模糊+分页）
1.6	2026-07-22	新增可支配收入开放列表（年份精确+分页）
1.5	2026-07-22	新增家庭牧场开放列表（年/月/乡镇村/企业名模糊+分页；法人脱敏）
1.4	2026-07-22	新增畜牧产品产量登记开放列表（年/月/乡镇村模糊+分页）
1.3	2026-07-22	新增合作社发展开放列表（年/月/乡镇村/名称模糊+分页；法人脱敏）
1.2	2026-07-22	新增牦牛出栏开放列表（年/月/乡镇村模糊+分页）
1.1	2026-07-22	新增牦牛存栏开放列表（年/月/乡镇村模糊+分页）
1.0	2026-07-04	初版：Token + 牧场/档案脱敏列表；全局一对凭证

科研开放数据接口技术方案.md 23KB Histórico Raw

科研开放数据接口 — 技术方案

1. 技术架构

2. 配置

3. 接口设计

3.1 申请 Token

3.2 牧场列表

3.3 牦牛资产档案列表

3.4 牦牛存栏数据列表

3.5 牦牛出栏数据列表

3.6 合作社发展数据列表

3.7 畜牧产品产量登记列表

3.8 家庭牧场数据列表

3.9 可支配收入数据列表

3.10 农牧户数据列表

3.11 共同富裕项目列表

3.12 养殖大户数据列表

3.13 疫苗接种数据列表

3.14 有无畜户数据列表

3.15 农村三资数据列表

3.16 三资具体问题列表

3.17 科技服务人员详情

4. 鉴权流程

5. 数据查询

6. 脱敏实现

7. 异常码

8. 调用示例

9. 测试

10. 需求追溯

11. 修订记录

科研开放数据接口技术方案.md 23KB

Histórico Raw