农产品溯源与数字农业平台技术白皮书

适用平台：ThingLinks-Community（RuoYi 风格中台，Spring Boot 2.7 / MyBatis-Plus / MySQL） 本文界定模块边界、数据模型、与平台能力的关系，以及规则策略的三种落地方式。

1. 目标与范围

在通用物联网平台之上构建农业行业应用层，把"设备能力"封装为"农事业务能力"。本期覆盖四大子域：

1. 基地与资产管理：地块 / 大棚 / 鸡舍 / 分区 / 作物 / 批次。
2. 水肥一体化：灌溉规则、执行记录、水肥统计。
3. 养鸡自动化：饮水 / 喂料 / 清粪规则、集群档案。
4. 监控与报表：实时曲线、大屏、告警、成本报表。

2. 依赖原则

• 应用模块 → 依赖 thinglinks-business、common、framework。
• thinglinks-business 不依赖任何应用模块（保持平台中立）。
• 应用模块不直接操作 MQTT/TCP，所有下行统一走 DeviceDownUtils.functionDown。

3. 数据模型（核心实体）

基地与资产（base）

• agri_base 基地、agri_zone 地块/分区（多级）、agri_crop 作物、agri_batch 批次、agri_asset 资产绑定（device_sn 为唯一桥接字段）。

水肥一体化（fertigation）

• fert_irrigation_rule 灌溉规则（阈值/定时/手动 + 滞回参数）、agri_exec_record 执行记录（通用）、fert_consumption 水肥统计。

养鸡自动化（poultry）

• poultry_drink_rule / poultry_feed_rule / poultry_clean_rule、 poultry_flock 集群档案。

监控与报表（monitor）

• 实时曲线直查 thinglinks_device_ts_data；agri_alarm 业务告警；agri_report_cost 成本报表；大屏纯前端聚合。

4. 与平台能力对接

应用层需求	复用平台	怎么调
下发开/关阀、喂料、清粪	DeviceDownUtils.functionDown	传 device_sn + 指令码 + 参数
阈值自动触发	平台告警规则 或 应用层规则引擎	配置界面填值
实时曲线	thinglinks_device_ts_data	应用层 Service 只读
设备状态	thinglinks_device	展示用

5. 规则策略：三种落地方式

策略	含义	复杂度
A. 配置界面	页面填阈值/时段/指令存 *_rule	低
B. 默认值模板	作物推荐参数一键套用	低
C. 自动学习	历史数据动态建议阈值	高

建议路线：V1 用 A 为主 + B 为辅；C 留作 V2，且 C 的输出仍是"生成一条 A 型规则"。

6. 平台设备建模（水肥一体化）

thinglinks 采用 协议 → 组件 → 产品 → 设备 四层模型。本方案用 groupCode 把同一节点（DTU + PLC + 阀门 + 传感器）归为一组，弥补 thinglinks_device 无 parent_id、不支持树形层级的特点。

7. 关键约束

1. 单向依赖：应用模块依赖 business，business 绝不反向依赖。
2. 下行统一出口：指令必须经 functionDown，禁止直连 MQTT/TCP。
3. 指令码一致性：*_rule 的 function_code 必须与设备指令表一致。
4. 滞回防抖：阈值类规则必须配滞回区间。
5. 时序数据源单一：曲线与统计统一读 thinglinks_device_ts_data。