牦牛资产档案管理 — 功能需求
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. 业务流程
flowchart TD
T[第三方生产管理系统] -->|用户触发同步| S[本系统档案库]
S --> L[列表检索]
L -->|查看| D[档案详情]
D --> B1[基础信息/系谱/个体生理]
D --> B2[生长性状/繁殖性能]
D --> B3[饲喂数据]
L -->|再次同步| S
- 授权用户执行同步，写入或更新档案及多维子数据。
- 按编号、状态筛选，浏览列表摘要。
- 进入详情，分块查看基础、系谱、生理曲线、生长、繁殖、饲喂；生长性状支持列表与曲线（含预测）切换。
- 需要时再次同步刷新数据。
5. 详细功能需求
5.1 档案列表
筛选
| 条件 |
规则 |
| 牦牛编号 |
选填；模糊匹配；空则不过滤 |
| 资产状态 |
选填；精确匹配 §2.2；空则不过滤 |
列表规则
- 默认每页 20 条；默认排序：变更日期倒序（或与「最近同步时间」统一，评审确认一项）。
- 支持重置筛选。
- 无实时物联数据时，体温、运动量显示「—」或「暂无」。
- 操作列仅 查看；无编辑、删除。
展示列（与列表原型一致）
牦牛编号、所属牧场、性别、月龄（月）、实时体温、实时运动量、资产状态、变更日期、操作。
5.2 列表工具栏
| 按钮 |
行为 |
| 搜索 |
按当前条件刷新列表 |
| 重置 |
清空筛选 |
| 同步 |
§5.3；执行中防重复提交；需独立权限 |
5.3 第三方同步
| 项 |
要求 |
| 触发 |
用户点击「同步」；定时任务是否启用另定 |
| 权限 |
仅同步权限角色可执行 |
| 数据源 |
第三方生产管理系统开放接口 GET /open-api/v1/farming/entry-filings（入栏建档列表，字段见草稿 20260611111807_455_398.jpg） |
| 鉴权 |
与牧场管理同源：third-party.farming 配置 base-url、app-key、app-secret |
| 合并键 |
优先以第三方 cattleId（external_id）upsert；辅以 耳标编号 earTagNumber（无则 cattleNo）作为 yak_no |
| 范围 |
分页拉取（pageNum/pageSize≤200）直至取完 |
| 反馈 |
结束提示成功/失败及摘要（新增/更新/失败条数） |
| 牧场映射 |
farmId 关联 biz_pasture.external_id；失败则冗余 farmName，展示「未关联」 |
| 失败 |
第三方超时、鉴权失败等须明确提示，不得误删或清空已有档案 |
| 子数据 |
本期列表接口同步主表 + 圈舍/批次关联；生理/生长/繁殖/饲喂等子表待详情接口对接后增量覆盖（未返回的子表不清空） |
同步成功后，列表与详情展示最近一次成功结果；列表宜可展示「数据截至：最近同步时间」类提示（§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 合并键 |
10. 需求追溯
| 能力 |
章节 |
| 列表筛选 |
§5.1 |
| 资产状态 |
§2.2 |
| 同步 |
§5.3 |
| 详情八块 |
§5.5 |
| 生理曲线 |
§5.5（3） |
| 生长列表/曲线/预测 |
§5.5（4） |
| 繁殖、饲喂 |
§5.5（5）（6） |
| 圈舍、批次 |
§5.5（7）（8） |
| 第三方与扩展 |
§2.3、§8 |
