# 牦牛资产档案管理 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 牦牛资产档案管理（牧业金融 · 生物资产） |
| 目标 | 集中检索、同步与查阅单头牦牛资产档案及多维生产数据，支撑牧业金融生物资产监管、风险识别与第三方生产管理系统对接 |
| 关联系统 | 业务后台；档案数据主要来自**第三方生产管理系统**同步，所属牧场与「牧场管理」等主数据宜建立映射展示 |
| 修订依据 | 同目录 `牦牛资产档案管理功能需求-草稿.md`、界面原型（`Snipaste_2026-05-19_12-31-33.jpg` 列表；`Snipaste_2026-05-19_19-20-06.jpg` 等详情） |

本文档仅描述**功能需求与业务规则**，不涉及库表结构、接口路径、请求体字段命名、技术栈选型及实现方案。

---

## 2. 术语与枚举

### 2.1 牦牛资产档案

- 以**单头牦牛**为粒度的一条档案；业务主键为**牦牛编号**（与第三方一致，本系统内宜唯一）。  
- 档案由第三方同步写入/更新；本模块以**查询、同步、只读详情**为主，**不提供**在界面手工新建、编辑、删除整头档案（本地补录若需要须单独需求）。  
- 列表展示**摘要指标**；详情按**八个信息块**展开（见 **§5.5**）：基础、系谱、个体生理、生长性状、繁殖性能、饲喂数据、牦牛圈舍、牦牛批次。

### 2.2 资产状态

用于列表筛选与详情「基础信息」展示；取值与第三方映射关系在技术方案中维护。

| 状态 | 含义概要 |
| --- | --- |
| 正常 | 在栏饲养，档案有效 |
| 死淘 | 死亡或淘汰，资产业务终止 |
| 丢失 | 丢失或无法追踪 |
| 出栏 | 已出栏或出售离场 |

**字典约定（与草稿一致）**：性别为公/母；来源为自繁/外购/引进；养殖方式为半舍饲/散养/圈养（与第三方同步，展示以同步值为准）。

### 2.3 第三方与指标扩展

- **第三方生产管理系统**：外部牦牛/牧场生产平台；用户点击「**同步**」拉取或更新档案及子表数据。  
- **指标非最终版**：原型与草稿均说明，当前列表与详情字段**不一定是最终对接的全部指标**；后续对接可增加、删减或改名，系统宜支持配置化展示（见 **§3、§8**）。

### 2.4 列表字段含义

| 字段 | 说明 |
| --- | --- |
| 牦牛编号 | 唯一编号 |
| 所属牧场 | 当前归属牧场名称 |
| 性别 | 公/母等（与第三方字典一致） |
| 月龄 | 单位**月**；宜由出生日期与当前日期计算，与第三方冲突时以产品约定为准（默认：展示优先系统计算，同步可覆盖） |
| 实时体温 | 最近体温，**℃** |
| 实时运动量 | 最近运动量，**步**（或第三方单位，界面须标注） |
| 资产状态 | **§2.2** |
| 变更日期 | 资产状态最近变更日 **YYYY-MM-DD**；无单独状态流水时可为最近同步/更新时间 |

---

## 3. 功能范围

**本期实现：**

| 能力 | 说明 |
| --- | --- |
| 档案列表 | 牦牛编号模糊、资产状态精确筛选；分页；列见 **§5.1** |
| 同步 | 从第三方拉取/更新档案及子数据，见 **§5.3** |
| 查看详情 | 只读；八块信息 + 图表，见 **§5.4、§5.5** |
| 工具栏 | 搜索、重置、同步 |

**本期不实现：**

- 本模块内手工维护整头档案（增删改表单）  
- 抵押/投保/出栏等业务流程审批（仅展示状态）  
- 与信贷、保单系统联动下单  
- 电子围栏、轨迹回放等高级物联能力（「位置」仅文本/坐标展示除外）  

---

## 4. 业务流程

```mermaid
flowchart TD
    T[第三方生产管理系统] -->|用户触发同步| S[本系统档案库]
    S --> L[列表检索]
    L -->|查看| D[档案详情]
    D --> B1[基础信息/系谱/个体生理]
    D --> B2[生长性状/繁殖性能]
    D --> B3[饲喂数据]
    L -->|再次同步| S
```

1. 授权用户执行**同步**，写入或更新档案及多维子数据。  
2. 按编号、状态筛选，浏览列表摘要。  
3. 进入**详情**，分块查看基础、系谱、生理曲线、生长、繁殖、饲喂；生长性状支持列表与曲线（含预测）切换。  
4. 需要时再次**同步**刷新数据。

---

## 5. 详细功能需求

### 5.1 档案列表

**筛选**

| 条件 | 规则 |
| --- | --- |
| 牦牛编号 | 选填；**模糊**匹配；空则不过滤 |
| 资产状态 | 选填；**精确**匹配 **§2.2**；空则不过滤 |

**列表规则**

- 默认每页 **20** 条；默认排序：**变更日期倒序**（或与「最近同步时间」统一，评审确认一项）。  
- 支持**重置**筛选。  
- 无实时物联数据时，体温、运动量显示「—」或「暂无」。  
- 操作列仅 **查看**；无编辑、删除。

**展示列（与列表原型一致）**  
牦牛编号、所属牧场、性别、月龄（月）、实时体温、实时运动量、资产状态、变更日期、操作。

---

### 5.2 列表工具栏

| 按钮 | 行为 |
| --- | --- |
| 搜索 | 按当前条件刷新列表 |
| 重置 | 清空筛选 |
| 同步 | **§5.3**；执行中防重复提交；需独立权限 |

---

### 5.3 第三方同步（手动 — 生物资产全量）

| 项 | 要求 |
| --- | --- |
| 触发 | 用户点击列表「**同步**」；**不**包含 IoT 物联数据 |
| 权限 | 仅同步权限角色可执行 |
| 范围 | **五段顺序**全量：养殖场 → 圈舍 → 生产计划 → 批次 → **入栏建档（牦牛档案）** |
| 入栏接口 | `GET /open-api/v1/farming/entry-filings`（字段见草稿 `20260611111807_455_398.jpg`） |
| 鉴权 | 与牧场管理同源：`third-party.farming` 配置 `base-url`、`app-key`、`app-secret` |
| 合并键 | 优先 **cattleId**（`external_id`）；辅以 **cattleNo** 作为 `yak_no`；**earTagNumber** 独立落库 `ear_tag_number` |
| 分页 | `pageNum`/`pageSize`≤200 直至取完 |
| 反馈 | 提示成功/失败；摘要含各段及入栏建档新增/更新/失败头数（前端兼容顶层 `insertCount` 等） |
| 牧场映射 | `farmId` → `biz_pasture.external_id`；失败则冗余 `farmName` |
| 失败 | 第三方不可用须明确提示，**不得**误删已有档案 |
| 子数据 | 入栏列表同步主表；生理/生长等子表待详情接口对接后增量覆盖 |

### 5.3.1 IoT 数据定时同步（后台）

| 项 | 要求 |
| --- | --- |
| 触发 | **定时任务**每日凌晨 **1:00**；**无**列表页按钮 |
| 数据 | 牛只称重、耳标温度步数、牦牛定位项圈、环境监测 |
| 接口 | `/open-api/v1/iot/weighings`、`/ear-tags`、`/collar-locations`、`/env-monitoring` |
| 全量条件 | 对应本地表 `biz_yak_weighing_record` / `biz_yak_ear_tag_record` / `biz_yak_collar_location` / `biz_env_monitoring_record` **无任何行**（`count(*)=0`，含逻辑删除行） |
| 增量条件 | 表内有数据时，按事件时间与配置水印增量拉取 |
| 初始化 | 执行 `sql/biz_sys_job_iot_data_incremental_sync.sql` 并在「系统管理-定时任务」启用 |

同步成功后，列表与详情展示最近一次**入栏建档**手动同步结果；IoT 数据供详情/预警等模块读取，宜标注数据来源与采集时间（**§8**）。

---

### 5.4 详情页总体

| 项 | 要求 |
| --- | --- |
| 入口 | 列表「查看」 |
| 权限 | 查询权限即可 |
| 模式 | **只读**；不提供保存、编辑按钮 |
| 布局 | 建议顶部摘要条：牦牛编号、所属牧场、资产状态、性别、月龄；下方分块展示 **§5.5**（与详情原型一致，可滚动单页或多 Tab） |
| 系谱跳转 | 父亲编号、母亲编号若在本系统存在，宜可跳转其详情（新窗口或路由切换） |

---

### 5.5 详情信息块

#### （1）基础信息

| 字段 | 格式/单位 |
| --- | --- |
| 牦牛编号 | — |
| 所属牧场 | — |
| 批次编号 | — |
| 性别 | 公/母 |
| 出生日期 | YYYY-MM-DD |
| 月龄 | 月 |
| 入栏日期 | YYYY-MM-DD |
| 入栏体重 | kg |
| 来源 | 自繁/外购/引进 |
| 养殖方式 | 半舍饲/散养/圈养 |
| 资产状态 | **§2.2** |
| 状态变更原因 | 文字 |
| 圈舍位置 | — |
| 预计出栏日期 | YYYY-MM-DD |
| 补饲方案 | 文字 |

#### （2）系谱信息

| 字段 | 说明 |
| --- | --- |
| 牦牛编号 | 当前个体 |
| 父亲编号 | 无则「—」 |
| 母亲编号 | 无则「—」 |

#### （3）个体生理 + 曲线图

**当前值（与原型「个体生理」区一致）**

| 字段 | 单位 |
| --- | --- |
| 实时体温 | ℃ |
| 实时运动量 | 步（或第三方单位） |
| 环境温度 | ℃ |
| 位置 | 文字或坐标描述 |
| 采集时间 | 上述实时值对应时间 |

**曲线图（原型底部「曲线图」区域）**

- 展示**近一个月**体温、运动量、环境温度的趋势。  
- 支持图例区分指标；无数据时段断点或留空。  
- 时间粒度与第三方一致（按日/按采集点）。

#### （4）生长性状

**列表模式（默认）**

| 列 | 单位 |
| --- | --- |
| 日龄 | 天 |
| 体重 | kg |
| 体高 | cm |
| 胸围 | cm |
| 体长 | cm |
| 采集时间 | 日期时间 |

- 按采集时间或日龄**倒序**（最新在上）。  
- 区块右上角 **切换**：由列表变为**曲线图**。

**曲线模式（切换后）**

- 至少支持体重等指标曲线；可选展示体高、胸围、体长（有数据则展示）。  
- **实测**与**未来预测**同时展示，**不同颜色线段**区分（与原型红字说明一致）。  
- 无预测数据时仅展示实测。预测来源（第三方或内置模型）实施阶段与业务确认。

#### （5）繁殖性能

**列表展示**（可多行，按胎次/事件）

| 列 | 单位/说明 |
| --- | --- |
| 分娩日期 | YYYY-MM-DD |
| 日龄 | 天 |
| 胎次 | — |
| 产犊间隔 | 天 |
| 产犊数量 | 头 |
| 成活牦牛数量 | 头 |
| 犊牛成活率 | 百分比或比例，须标注口径 |
| 犊牛出生体重 | kg |
| 是否难产 | 是/否或字典 |

#### （6）饲喂数据

**列表展示**（可多行，按日龄区间）

| 列 | 单位 | 规则 |
| --- | --- | --- |
| 补饲对象 | — | 个体/圈舍群体/批次群体 |
| 开始日龄 | 天 | 开始日龄 ≤ 结束日龄 |
| 结束日龄 | 天 | — |
| 饲料类型 | 字典 | 与第三方一致 |
| 总补饲量 | kg | 正数 |
| 日补饲量 | kg | 正数 |

同一牦牛多条饲喂记录区间**是否允许重叠**默认允许（与第三方一致）；若需互斥校验另定需求。

#### （7）牦牛圈舍

| 列 | 说明 |
| --- | --- |
| 圈舍名称 | — |
| 牦牛编号 | 当前个体 |

#### （8）牦牛批次

| 列 | 说明 |
| --- | --- |
| 批次编号 | — |
| 牦牛编号 | 当前个体 |

---

## 6. 权限矩阵

| 操作 | 条件 |
| --- | --- |
| 查看列表 | 列表权限 |
| 查看详情 | 查询权限 |
| 同步 | 同步权限（建议独立于查询） |
| 新增/编辑/删除档案 | 本期无 |

---

## 7. 提示与错误约定

采用项目统一提示方式；**不约定** HTTP 字段。宜区分：

- 同步成功/失败/进行中；  
- 第三方不可用；  
- 无同步权限；  
- 列表无数据；  
- 详情某块暂无数据；  
- 系谱关联个体不存在时的跳转提示。

---

## 8. 非功能需求（建议）

| 类别 | 建议 |
| --- | --- |
| 性能 | 列表分页；大批量同步宜异步+进度 |
| 审计 | 记录同步操作人、时间、结果摘要 |
| 权限 | 按牧场/组织过滤可见档案 |
| 扩展 | 字段与 Tab 可配置；对接版本变更说明 |
| 时效 | 标注最近同步时间，避免误解实时性 |
| 双语 | i18n（汉语 + 藏文） |

---

## 9. 相对草稿的修订说明

| 草稿问题 | 处理 |
| --- | --- |
| 缺条目「2」、编号乱 | 重整为 §5 分节 |
| 技术栈、code/msg/data | 已移除 |
| 未区分列表/详情/同步 | §5.1～5.5 分列 |
| 指标非最终 | §2.3、§3、§8 |
| 详情六块分散 | 合并 §5.5；草稿增圈舍/批次及字段后扩展为八块 |
| 资产状态简化为 4 项 | §2.2 对齐草稿：正常/死淘/丢失/出栏 |
| 性别/来源/养殖方式 | §2.2、§5.5（1）补充草稿字典 |
| 生长「切换+预测」 | §5.5（4）曲线模式单独说明 |
| 生理与曲线图关系 | §5.5（3）区分当前值与近一月曲线 |
| 列表缺分页、重置 | §5.1、§5.2 |
| 入栏建档 OpenAPI 对接 | §5.3 明确 `entry-filings` 接口、字段映射与 `external_id` 合并键 |
| 全量/IoT 分离 | §5.3 手动五段全量；§5.3.1 IoT 定时 1:00、全量/增量策略 |

---

## 10. 需求追溯

| 能力 | 章节 |
| --- | --- |
| 列表筛选 | §5.1 |
| 资产状态 | §2.2 |
| 同步 | §5.3、§5.3.1 |
| 详情八块 | §5.5 |
| 生理曲线 | §5.5（3） |
| 生长列表/曲线/预测 | §5.5（4） |
| 繁殖、饲喂 | §5.5（5）（6） |
| 圈舍、批次 | §5.5（7）（8） |
| 第三方与扩展 | §2.3、§8 |