西藏巴青项目

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

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

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

10. 需求追溯

能力	章节
Token 认证	§4、§5、§6.1
牧场列表	§6.2、§7
牦牛档案列表	§6.3、§7
牦牛存栏列表	§6.4
牦牛出栏列表	§6.5
合作社发展列表	§6.6
畜牧产品产量列表	§6.7
脱敏合规	§7
本期不实现	§3

科研开放数据接口功能需求.md 8.3KB Historia Czysty

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

1. 文档说明

2. 业务背景

3. 功能范围

4. 访问流程

5. 认证与安全

6. 数据接口

6.1 申请 Token

6.2 牧场列表

6.3 牦牛资产档案列表

6.4 牦牛存栏数据列表

6.5 牦牛出栏数据列表

6.6 合作社发展数据列表

6.7 畜牧产品产量登记列表

7. 脱敏规则摘要

8. 响应格式

9. 与其他模块关系

10. 需求追溯

科研开放数据接口功能需求.md 8.3KB

Historia Czysty