大屏修改

doc/产业数据模型及服务/科研开放数据接口/科研开放数据接口功能需求-草稿.md

@@ -0,0 +1,9 @@
+为高校、研究机构提供符合规范的脱敏牦牛种群健康、牧场管理等海量科研数据集，助力高原牧业关键技术攻关。
+
+对外提供数据接口：
+1. 提供牧场列表接口
+2. 牦牛资产档案列表接口
+3. 设计安全的 token 认证，避免未授权访问
+4. 符合规范、脱敏
+
+> 正式需求见同目录 `科研开放数据接口功能需求.md`（v1.0）。

doc/产业数据模型及服务/科研开放数据接口/科研开放数据接口功能需求.md

@@ -0,0 +1,166 @@
+# 科研开放数据接口 — 功能需求
+
+## 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 |

doc/产业数据模型及服务/科研开放数据接口/科研开放数据接口技术方案.md

@@ -0,0 +1,222 @@
+# 科研开放数据接口 — 技术方案
+
+> 依据：同目录 `科研开放数据接口功能需求.md`。对外只读开放 API；**无**前端页面、**无**新表。
+
+---
+
+## 1. 技术架构
+
+| 项 | 说明 |
+| --- | --- |
+| **后端** | RuoYi **v3.9.2**（**springboot2** 分支）：JDK 8、Spring MVC、MyBatis |
+| **数据库** | 只读查询既有表 `biz_pasture`、`biz_yak_asset` |
+| **鉴权** | 独立 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 |
+
+**示例：**
+
+```yaml
+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`：**
+
+```json
+{
+  "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 |
+
+---
+
+## 4. 鉴权流程
+
+1. `ResearchOpenApiController` 标注 `@Anonymous` → Spring Security 放行。  
+2. `ResearchOpenApiAuthFilter` 拦截 `/open-api/v1/research/*`（**排除** `/auth/token`）。  
+3. 解析 `Authorization: Bearer …`，`ResearchOpenApiTokenService.validateToken` 验签与过期。  
+4. 失败返回 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` |
+
+实体 → VO：`ResearchOpenApiSupport.toPastureVo` / `toYakAssetVo`（内部调用 `ResearchOpenApiMasking`）。
+
+---
+
+## 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. 调用示例
+
+```bash
+# 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>"
+```
+
+---
+
+## 9. 测试
+
+见同目录 `科研开放数据接口测试用例.md`。单元测试：
+
+- `ResearchOpenApiMaskingTest`
+- `ResearchOpenApiTokenServiceTest`
+- `ResearchOpenApiControllerApiTest`
+
+---
+
+## 10. 需求追溯
+
+| 功能需求 | 技术落点 |
+| --- | --- |
+| §5 认证 | **§2** 配置、**§4** Filter + TokenService |
+| §6.2 牧场 | **§3.2**、**§5** BizPasture |
+| §6.3 档案 | **§3.3**、**§5** BizYakAsset |
+| §7 脱敏 | **§6** Masking |
+| §3 不实现机构区分 | 单一 app-key/secret，JWT 无 clientId |
+
+---
+
+## 11. 修订记录
+
+| 版本 | 日期 | 说明 |
+| --- | --- | --- |
+| 1.0 | 2026-07-04 | 初版：Token + 牧场/档案脱敏列表；全局一对凭证 |

doc/产业数据模型及服务/科研开放数据接口/科研开放数据接口测试用例.md

@@ -0,0 +1,77 @@
+# 科研开放数据接口 — 测试用例
+
+> 依据：`科研开放数据接口功能需求.md`、`科研开放数据接口技术方案.md`  
+> **Base Path**：`/open-api/v1/research`（默认服务 `http://localhost:8010`）
+
+**通用前置**：`application.yml` 中 `research-open-api.enabled=true`，且已配置有效的 `app-key` / `app-secret` / `token-secret`。
+
+**测试凭证（示例，与配置一致）**：
+
+| 项 | 值 |
+| --- | --- |
+| appKey | `research-open-demo-key` |
+| appSecret | `research-open-demo-secret-change-me` |
+
+---
+
+## 一、单元测试用例
+
+| 用例编号 | 测试模块 | 测试项 | 测试类型 | 测试工具 | 测试目的 | 前置条件 | 测试步骤 | 预期结果 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| KYKF-UT-001 | 脱敏 | 手机号脱敏 | 单元测试 | JUnit5 | §7 | — | `maskPhone("13812345678")` | `138****5678` |
+| KYKF-UT-002 | 脱敏 | 负责人脱敏 | 单元测试 | JUnit5 | §7 | — | `maskPersonName("张三")` | `张*` |
+| KYKF-UT-003 | 脱敏 | 牧场 VO 无第三方 ID | 单元测试 | JUnit5 | §6.2 | 构造 BizPasture | `toPastureVo` | 含 `regionSummary`；无 `externalId`、无详细地址 |
+| KYKF-UT-004 | 脱敏 | 档案 subjectCode | 单元测试 | JUnit5 | §6.3 | id=88 | `toYakAssetVo` | `subjectCode=YS00000088`；无 `yakNo` |
+| KYKF-UT-005 | Token | 合法凭证签发校验 | 单元测试 | JUnit5 | §5 | enabled=true | `issueToken` → `validateToken` | 不抛异常 |
+| KYKF-UT-006 | Token | 错误 secret 拒绝 | 单元测试 | JUnit5 | §5 | — | `issueToken(key, wrong)` | 抛 ServiceException 401 |
+
+---
+
+## 二、接口测试用例
+
+| 用例编号 | 测试模块 | 测试项 | 测试类型 | 测试工具 | 测试目的 | 前置条件 | 测试步骤 | 预期结果 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| KYKF-API-001 | 认证 | 申请 Token 成功 | 接口测试 | curl/Postman | §6.1 | enabled=true | POST `/auth/token` 正确 body | `code=200`；`data.accessToken` 非空；`tokenType=Bearer` |
+| KYKF-API-002 | 认证 | 错误 appSecret | 接口测试 | curl | §5 | — | POST 错误 secret | `code=401` |
+| KYKF-API-003 | 认证 | 未带 Token 访问数据 | 接口测试 | curl | §5 | — | GET `/pastures` 无 Header | HTTP 401；`code=401` |
+| KYKF-API-004 | 认证 | 过期/伪造 Token | 接口测试 | curl | §5 | — | GET `/pastures` Bearer 无效串 | HTTP 401 |
+| KYKF-API-005 | 牧场 | 分页列表 | 接口测试 | curl | §6.2 | 有效 Token；库有数据 | GET `/pastures?pageNum=1&pageSize=10` | `code=200`；`data.records` 数组；字段符合 ResearchPastureVo |
+| KYKF-API-006 | 牧场 | keyword 筛选 | 接口测试 | curl | §6.2 | 已知牧场名 | GET `keyword=片段` | 仅匹配名称的记录 |
+| KYKF-API-007 | 档案 | 分页列表 | 接口测试 | curl | §6.3 | 有效 Token | GET `/yak-assets?pageNum=1&pageSize=10` | `code=200`；含 `subjectCode`；无明文编号字段 |
+| KYKF-API-008 | 档案 | assetStatus 筛选 | 接口测试 | curl | §6.3 | 有 status=1 数据 | GET `assetStatus=1` | 均为正常状态 |
+| KYKF-API-009 | 档案 | pastureId 筛选 | 接口测试 | curl | §6.3 | 已知 pastureId | GET `pastureId=` | 仅该牧场档案 |
+| KYKF-API-010 | 分页 | pageSize 超限 | 接口测试 | curl | 技术§2 | — | GET `pageSize=500` | `code=400` |
+| KYKF-API-011 | 开关 | enabled=false | 接口测试 | curl | §5 | 关闭 enabled 重启 | POST `/auth/token` | HTTP 503 或 `code=503` |
+| KYKF-API-012 | 脱敏 | 响应无敏感原文字段 | 接口测试 | curl | §7 | 库含手机/编号 | GET 两接口 | JSON 无 `yakNo`、`earTagNumber`、`externalId`、`detailAddress` |
+
+---
+
+## 三、需求追溯矩阵
+
+| 功能需求 | 单元 | 接口 |
+| --- | --- | --- |
+| §5 Token 认证 | UT-005～006 | API-001～004、011 |
+| §6.2 牧场列表 | UT-003 | API-005～006 |
+| §6.3 档案列表 | UT-004 | API-007～009 |
+| §7 脱敏 | UT-001～004 | API-012 |
+| §2 分页 | — | API-010 |
+| §3 无机构区分 | UT-005 | API-001（单一凭证） |
+
+**用例统计**：单元 **6**、接口 **12**，合计 **18** 条。
+
+---
+
+## 四、Postman / curl 快速脚本
+
+```bash
+BASE=http://localhost:8010/open-api/v1/research
+TOKEN=$(curl -s -X POST "$BASE/auth/token" \
+  -H "Content-Type: application/json" \
+  -d '{"appKey":"research-open-demo-key","appSecret":"research-open-demo-secret-change-me"}' \
+  | jq -r '.data.accessToken')
+
+curl -s "$BASE/pastures?pageNum=1&pageSize=5" -H "Authorization: Bearer $TOKEN"
+curl -s "$BASE/yak-assets?pageNum=1&pageSize=5&assetStatus=1" -H "Authorization: Bearer $TOKEN"
+```
+
+（Windows 环境可用 PowerShell `Invoke-RestMethod`，见技术方案 **§8**。）