科研开放数据接口功能需求.md 13KB
科研开放数据接口 — 功能需求
1. 文档说明
| 项 | 说明 |
|---|---|
| 模块名称 | 科研开放数据接口 |
| 目标 | 为高校、研究机构提供符合规范的脱敏牦牛种群健康、牧场管理等科研数据集，助力高原牧业关键技术攻关 |
| 关联系统 | 对外 HTTP 开放接口（无管理后台页面、无若依登录） |
| 修订依据 | 产业数据模型及服务建设需求 |
本文档仅描述功能需求与业务规则；接口路径、字段命名、实现细节见同目录 科研开放数据接口技术方案.md。
2. 业务背景
县域牦牛产业数据汇聚于「产业数据模型及服务」模块（牧场管理、牦牛资产档案等）。科研合作方需要只读拉取结构化数据，且不得获取可直接识别个人或个体的敏感信息。
3. 功能范围
本期实现：
| 能力 | 说明 |
|---|---|
| 访问令牌 | 使用全局 appKey + appSecret 申请 Bearer Token |
| 牧场列表 | 分页返回脱敏牧场数据 |
| 牦牛资产档案列表 | 分页返回脱敏档案数据（种群健康研究字段） |
| 牦牛存栏数据列表 | 分页返回村级存栏填报汇总 |
| 牦牛出栏数据列表 | 分页返回村级出栏填报汇总 |
| 合作社发展数据列表 | 分页返回合作社发展填报；法人姓名脱敏 |
| 畜牧产品产量登记列表 | 分页返回村级肉/奶产量 |
| 家庭牧场数据列表 | 分页返回家庭牧场填报；法人姓名脱敏 |
| 可支配收入数据列表 | 分页返回县级年度可支配收入填报 |
| 农牧户数据列表 | 分页返回村级农牧户填报 |
| 共同富裕项目列表 | 分页返回共同富裕项目 |
| 养殖大户数据列表 | 分页返回养殖大户填报；法人姓名脱敏 |
| 疫苗接种数据列表 | 分页返回村级疫苗接种填报 |
| 有无畜户数据列表 | 分页返回村级有无畜户填报 |
| 农村三资数据列表 | 分页返回村级农村三资填报 |
本期不实现：
- 按机构/高校区分凭证或配额
- 管理后台维护客户端
- 数据导出任务、订阅推送、Webhook
- 明细子表（生理时序、生长曲线等）下钻接口
- 若依用户 JWT 或菜单权限访问本开放接口
4. 访问流程
sequenceDiagram
participant Client as 科研调用方
participant API as 开放接口
participant DB as 产业数据库
Client->>API: POST /auth/token (appKey, appSecret)
API-->>Client: accessToken (Bearer)
Client->>API: GET /pastures 或 /yak-assets + Authorization
API->>DB: 查询 biz_pasture / biz_yak_asset
API-->>Client: 脱敏分页 JSON
- 调用方使用配置的 appKey / appSecret 申请 Token。
- 在 Token 有效期内，请求头携带
Authorization: Bearer <accessToken>访问数据接口。 - 服务端返回已脱敏字段；不区分具体合作机构。
5. 认证与安全
| 项 | 要求 |
|---|---|
| 凭证 | 全局一对 app-key / app-secret（application.yml 配置） |
| Token | JWT，独立于若依用户登录 Token |
| 有效期 | 默认 120 分钟，可配置 |
| 数据接口 | 除 Token 申请外，必须携带有效 Bearer Token，否则 401 |
| 开关 | research-open-api.enabled=false 时接口返回 503 |
| 生产 | 须修改默认 app-key、app-secret、token-secret |
6. 数据接口
Base Path：/open-api/v1/research
6.1 申请 Token
| 项 | 说明 |
|---|---|
| 方法 | POST |
| 路径 | /auth/token |
| 请求体 | appKey、appSecret（JSON，小驼峰） |
| 响应 | accessToken、tokenType（Bearer）、expiresIn（秒） |
6.2 牧场列表
| 项 | 说明 |
|---|---|
| 方法 | GET |
| 路径 | /pastures |
| 鉴权 | Bearer Token |
| 分页 | pageNum（默认 1）、pageSize（默认 20，最大 200） |
| 筛选 | keyword（牧场名称模糊）、farmType |
返回字段（脱敏后）：pastureId、pastureName、farmType、county、town、regionSummary、latitude、longitude（约百米精度）、floorArea、scaleBreeding、breedSpecies、introduction、personInCharge（脱敏）、contactPhone（脱敏）。
不返回：第三方编号、详细门牌地址、同步元数据、操作人等。
6.3 牦牛资产档案列表
| 项 | 说明 |
|---|---|
| 方法 | GET |
| 路径 | /yak-assets |
| 鉴权 | Bearer Token |
| 分页 | 同 §6.2 |
| 筛选 | assetStatus（1正常 2死淘 3丢失 4出栏）、gender（公/母）、pastureId |
返回字段（脱敏后）：subjectCode（科研主体 pseudonym，替代明文牦牛编号）、pastureName、enclosureName、gender、cattleVariety、ageMonths、birthYear、birthMonth、assetStatus、assetStatusLabel、entryWeightKg、source、breedingMethod、entryCycle、realtimeTemp、realtimeSteps、envTemp、fatherSubjectCode、motherSubjectCode。
不返回：yakNo、耳标号、第三方 ID、登记人、照片 URL、精确 GPS、备注等。
6.4 牦牛存栏数据列表
| 项 | 说明 |
|---|---|
| 方法 | GET |
| 路径 | /yak-herd-inventories |
| 鉴权 | Bearer Token |
| 分页 | 同 §6.2 |
| 筛选 | statYear（所属年份）、statMonth（所属月份）、townName（所属乡镇模糊）、villageName（所属村模糊） |
返回字段：inventoryId、statYear、statMonth、townName、villageName、畜群结构汇总数量字段（公牛/母牛/奶牛/羊/保险及各类合计等）。
不返回：部门 ID、创建人、备注等内部字段。
6.5 牦牛出栏数据列表
| 项 | 说明 |
|---|---|
| 方法 | GET |
| 路径 | /yak-outbound-reports |
| 鉴权 | Bearer Token |
| 分页 | 同 §6.2 |
| 筛选 | statYear（所属年份）、statMonth（所属月份）、townName（所属乡镇模糊）、villageName（所属村模糊） |
返回字段：outboundId、statYear、statMonth、townName、villageName、农牧户/人口及各类出栏数量（牦牛/牛/绵羊/山羊/马骡/驴、自食牛羊等）。
不返回：部门 ID、创建人、备注等内部字段。
6.6 合作社发展数据列表
| 项 | 说明 |
|---|---|
| 方法 | GET |
| 路径 | /cooperative-developments |
| 鉴权 | Bearer Token |
| 分页 | 同 §6.2 |
| 筛选 | statYear、statMonth、townName（乡镇模糊）、villageName（村模糊）、cooperativeName（合作社名称模糊） |
返回字段：cooperativeId、年月、乡镇村、合作社信息、入社/入股/效益/就业/存出栏/认证/培训/经营等业务字段；legalRepresentative 脱敏。
不返回：部门 ID、创建人、备注等内部字段。
6.7 畜牧产品产量登记列表
| 项 | 说明 |
|---|---|
| 方法 | GET |
| 路径 | /livestock-product-outputs |
| 鉴权 | Bearer Token |
| 分页 | 同 §6.2 |
| 筛选 | statYear、statMonth、townName（乡镇模糊）、villageName（村模糊） |
返回字段：outputId、statYear、statMonth、townName、villageName、meatOutput（万吨）、milkOutput（万吨）。
不返回：部门 ID、创建人、备注等内部字段。
6.8 家庭牧场数据列表
| 项 | 说明 |
|---|---|
| 方法 | GET |
| 路径 | /family-ranches |
| 鉴权 | Bearer Token |
| 分页 | 同 §6.2 |
| 筛选 | statYear、statMonth、townName（乡镇模糊）、villageName（村模糊）、enterpriseName（企业名称模糊） |
返回字段：ranchId、年月、乡镇村、企业信息、存出栏、草场、经营收支、补助与认证等；legalRepresentative 脱敏。
不返回：部门 ID、创建人、备注等内部字段。
6.9 可支配收入数据列表
| 项 | 说明 |
|---|---|
| 方法 | GET |
| 路径 | /disposable-incomes |
| 鉴权 | Bearer Token |
| 分页 | 同 §6.2 |
| 筛选 | statYear（所属年份精确） |
返回字段：incomeId、statYear、ruralDisposableIncome、povertyNetIncome、incomeIncrease、incomeGrowthRate。
不返回：创建人、备注等内部字段。
6.10 农牧户数据列表
| 项 | 说明 |
|---|---|
| 方法 | GET |
| 路径 | /farmer-households |
| 鉴权 | Bearer Token |
| 分页 | 同 §6.2 |
| 筛选 | statYear、statMonth、townName（乡镇模糊）、villageName（村模糊） |
返回字段：householdId、年月、乡镇村、户数人数、草场面积与载畜量、户类型标识、补助奖励等。
不返回：部门 ID、创建人、备注等内部字段。
6.11 共同富裕项目列表
| 项 | 说明 |
|---|---|
| 方法 | GET |
| 路径 | /common-prosperity-projects |
| 鉴权 | Bearer Token |
| 分页 | 同 §6.2 |
| 筛选 | projectName（项目名称模糊）、projectType（项目类型精确，1～3）、implYear（实施年限精确） |
返回字段：projectId、projectName、projectType、简介与内容、投资金额、实施年限与情况、媒体 URL、发布状态、运营图片数量等。
不返回：本地文件路径、创建人、备注等内部字段。
6.12 养殖大户数据列表
| 项 | 说明 |
|---|---|
| 方法 | GET |
| 路径 | /large-livestock-farmers |
| 鉴权 | Bearer Token |
| 分页 | 同 §6.2 |
| 筛选 | statYear、statMonth、townName（乡镇模糊）、villageName（村模糊）、enterpriseName（企业名称模糊） |
返回字段：farmerId、年月、乡镇村、企业信息、存出栏、草场、经营收支、补助与认证等；legalRepresentative 脱敏。
不返回：部门 ID、创建人、备注等内部字段。
6.13 疫苗接种数据列表
| 项 | 说明 |
|---|---|
| 方法 | GET |
| 路径 | /vaccination-data |
| 鉴权 | Bearer Token |
| 分页 | 同 §6.2 |
| 筛选 | statYear、statMonth、townName（乡镇模糊）、villageName（村模糊） |
返回字段：vaccinationId、年月、乡镇村、shouldVaccinateCount、actualVaccinateCount、immunityRate。
不返回：部门 ID、创建人、备注等内部字段。
6.14 有无畜户数据列表
| 项 | 说明 |
|---|---|
| 方法 | GET |
| 路径 | /livestock-ownership-households |
| 鉴权 | Bearer Token |
| 分页 | 同 §6.2 |
| 筛选 | statYear、statMonth、townName（乡镇模糊）、villageName（村模糊） |
返回字段：ownershipId、年月、乡镇村、有畜户/无畜户户数人数劳动力及有畜户牲畜数。
不返回：部门 ID、创建人、备注等内部字段。
6.15 农村三资数据列表
| 项 | 说明 |
|---|---|
| 方法 | GET |
| 路径 | /rural-three-assets |
| 鉴权 | Bearer Token |
| 分页 | 同 §6.2 |
| 筛选 | townName（乡镇模糊）、villageName（村模糊） |
返回字段：assetsId、乡镇村、operatingFixedAssets、nonOperatingFixedAssets、fixedAssets。
不返回：部门 ID、创建人、备注等内部字段。
7. 脱敏规则摘要
| 类型 | 规则 |
|---|---|
| 手机号 | 保留前 3 + 后 4，中间 **** |
| 负责人姓名 | 保留首字 + * |
| 地址 | 仅区县 + 乡镇摘要，不含详细门牌 |
| 经纬度 | 保留 3 位小数（约百米） |
| 牦牛个体 | subjectCode = YS + 8 位本地 ID；系谱用 YP/YM + 哈希短码 |
| 出生日期 | 仅返回 birthYear、birthMonth |
8. 响应格式
统一 envelope（与第三方 OpenAPI 风格一致）：
| 字段 | 说明 |
|---|---|
code |
200 成功；401 未授权；400 参数错误；503 未启用 |
message |
提示文案 |
requestId |
请求追踪 ID |
data |
业务数据 |
timestamp |
ISO 时间戳 |
列表类 data 为分页对象：pageNum、pageSize、total、records[]。
9. 与其他模块关系
| 模块 | 关系 |
|---|---|
| 牧场管理 | 数据源 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 |
| 若依权限体系 | 无关联；开放接口走独立 Token |
10. 需求追溯
| 能力 | 章节 |
|---|---|
| Token 认证 | §4、§5、§6.1 |
| 牧场列表 | §6.2、§7 |
| 牦牛档案列表 | §6.3、§7 |
| 牦牛存栏列表 | §6.4 |
| 牦牛出栏列表 | §6.5 |
| 合作社发展列表 | §6.6 |
| 畜牧产品产量列表 | §6.7 |
| 家庭牧场列表 | §6.8 |
| 可支配收入列表 | §6.9 |
| 农牧户列表 | §6.10 |
| 共同富裕项目列表 | §6.11 |
| 养殖大户列表 | §6.12 |
| 疫苗接种列表 | §6.13 |
| 有无畜户列表 | §6.14 |
| 农村三资列表 | §6.15 |
| 脱敏合规 | §7 |
| 本期不实现 | §3 |