# 科研开放数据接口 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 科研开放数据接口 |
| 目标 | 为高校、研究机构提供符合规范的**脱敏**牦牛种群健康、牧场管理等科研数据集，助力高原牧业关键技术攻关 |
| 关联系统 | 对外 HTTP 开放接口（**无**管理后台页面、**无**若依登录） |
| 修订依据 | 产业数据模型及服务建设需求 |

本文档仅描述**功能需求与业务规则**；接口路径、字段命名、实现细节见同目录 `科研开放数据接口技术方案.md`。

---

## 2. 业务背景

县域牦牛产业数据汇聚于「产业数据模型及服务」模块（牧场管理、牦牛资产档案等）。科研合作方需要**只读**拉取结构化数据，且不得获取可直接识别个人或个体的敏感信息。

---

## 3. 功能范围

**本期实现：**

| 能力 | 说明 |
| --- | --- |
| 访问令牌 | 使用全局 `appKey` + `appSecret` 申请 Bearer Token |
| 牧场列表 | 分页返回脱敏牧场数据 |
| 牦牛资产档案列表 | 分页返回脱敏档案数据（种群健康研究字段） |
| 牦牛存栏数据列表 | 分页返回村级存栏填报汇总 |
| 牦牛出栏数据列表 | 分页返回村级出栏填报汇总 |
| 合作社发展数据列表 | 分页返回合作社发展填报；法人姓名脱敏 |
| 畜牧产品产量登记列表 | 分页返回村级肉/奶产量 |
| 家庭牧场数据列表 | 分页返回家庭牧场填报；法人姓名脱敏 |
| 可支配收入数据列表 | 分页返回县级年度可支配收入填报 |
| 农牧户数据列表 | 分页返回村级农牧户填报 |
| 共同富裕项目列表 | 分页返回共同富裕项目 |
| 养殖大户数据列表 | 分页返回养殖大户填报；法人姓名脱敏 |
| 疫苗接种数据列表 | 分页返回村级疫苗接种填报 |
| 有无畜户数据列表 | 分页返回村级有无畜户填报 |
| 农村三资数据列表 | 分页返回村级农村三资填报 |
| 三资具体问题列表 | 分页返回三资具体问题上报 |
| 科技服务人员详情 | 返回科技服务人员管理单例配置 |

**本期不实现：**

- 按机构/高校区分凭证或配额
- 管理后台维护客户端
- 数据导出任务、订阅推送、Webhook
- 明细子表（生理时序、生长曲线等）下钻接口
- 若依用户 JWT 或菜单权限访问本开放接口

---

## 4. 访问流程

```mermaid
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
```

1. 调用方使用配置的 **appKey / appSecret** 申请 Token。  
2. 在 Token 有效期内，请求头携带 `Authorization: Bearer <accessToken>` 访问数据接口。  
3. 服务端返回已脱敏字段；**不区分**具体合作机构。

---

## 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、创建人、备注等内部字段。

### 6.16 三资具体问题列表

| 项 | 说明 |
| --- | --- |
| 方法 | GET |
| 路径 | `/three-assets-problem-reports` |
| 鉴权 | Bearer Token |
| 分页 | 同 §6.2 |
| 筛选 | `townName`（乡镇模糊）、`villageName`（村模糊）、`beginReportTime`+`endReportTime`（`yyyy-MM-dd`，**同时有值**时按上报日期区间过滤） |

**返回字段**：`problemId`、`reportTime`、乡镇村、问题等级、详情、处理结果。

**不返回**：部门 ID、创建人、备注等内部字段。

### 6.17 科技服务人员详情

| 项 | 说明 |
| --- | --- |
| 方法 | GET |
| 路径 | `/tech-service-personnel` |
| 鉴权 | Bearer Token |
| 参数 | 无（单例配置） |

**返回字段**：科技特派员男女/党员/合计人数，农业事业单位初级/员级/中级/副高/管理级/合计人数。

**不返回**：操作人、更新时间等内部字段。

---

## 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` |
| 三资具体问题上报 | 数据源 `biz_three_assets_problem_report` |
| 科技服务人员管理 | 数据源 `biz_tech_service_personnel`（单例） |
| 若依权限体系 | **无**关联；开放接口走独立 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 |
| 三资具体问题列表 | §6.16 |
| 科技服务人员详情 | §6.17 |
| 脱敏合规 | §7 |
| 本期不实现 | §3 |