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

## 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、备注等。

---

## 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` |
| 若依权限体系 | **无**关联；开放接口走独立 Token |

---

## 10. 需求追溯

| 能力 | 章节 |
| --- | --- |
| Token 认证 | §4、§5、§6.1 |
| 牧场列表 | §6.2、§7 |
| 牦牛档案列表 | §6.3、§7 |
| 脱敏合规 | §7 |
| 本期不实现 | §3 |