@seeed-studio/solution-cli 0.3.1 → 0.4.0

package/lib/integration.js

@@ -0,0 +1,265 @@
+/**
+ * @file integration.js
+ * Integration contracts and system ingestion specifications for Solution CLI.
+ */
+
+export const INTEGRATION_CONTRACTS = {
+  fall_detection: {
+    solution_id: 'fall_detection',
+    protocols: ['mqtt', 'http', 'webhook', 'rtsp'],
+    interfaces: [
+      {
+        protocol: 'mqtt',
+        port: 1883,
+        topic: '<device_name>/fall-detection/results/<stream_id>',
+        direction: 'publish',
+        description: '实时人体姿态与跌倒识别结果，一路摄像头对应一个子主题。',
+        payload_example: {
+          state: 'fallen',
+          fall_detected: true,
+          fall_event: true,
+          event_id: 7,
+          person_count: 1,
+          fallen_count: 1,
+          persons: [
+            {
+              track_id: 3,
+              state: 'fallen',
+              bbox: [0.51, 0.72, 0.34, 0.21],
+              confidence: 0.94
+            }
+          ],
+          timestamp: 1788581337000
+        }
+      },
+      {
+        protocol: 'mqtt',
+        port: 1883,
+        topic: 'homeassistant/',
+        direction: 'publish',
+        description: 'Home Assistant MQTT Discovery 自动发现协议，跌倒传感器、事件编号会自动出现。'
+      },
+      {
+        protocol: 'webhook',
+        port: 8080,
+        endpoint: '配置中的 ALARM_WEBHOOK_URL',
+        direction: 'outbound_post',
+        description: '跌倒告警确认后向外部系统发送 HTTP POST 通知，附带防重复通知的幂等键。',
+        payload_example: {
+          id: 'a-17',
+          kind: 'fall',
+          zone_id: 'bedroom',
+          stream_id: 'cam-01',
+          state: 'notified',
+          event_timestamp: 1788581337237,
+          operator: 'duty-nurse'
+        }
+      },
+      {
+        protocol: 'http',
+        port: 8080,
+        endpoint: '/api/alarms',
+        direction: 'inbound_rest',
+        description: '告警面板 REST API，支持查询当前告警列表、执行确认 (confirm) 与驳回 (dismiss)。'
+      },
+      {
+        protocol: 'rtsp',
+        port: 8554,
+        endpoint: '/live0',
+        direction: 'stream',
+        description: '设备实时处理叠加视频流，支持 NVR 录像或第三方视频播放器调阅。'
+      }
+    ],
+    input_requirements: [
+      {
+        type: 'rtsp',
+        description: '标准 RTSP 摄像头流输入（如 rtsp://admin:pass@192.168.1.100:554/live/ch0），支持海康、大华等 IP 摄像头。'
+      }
+    ],
+    system_ingestion_guide: [
+      '1. 接入自建 MQTT Broker：在方案配置中将 MQTT_BROKER 改为自建服务器地址，订阅 fall-detection/results/# 获取每帧 JSON。',
+      '2. 接入业务告警中心：在告警面板中配置 Webhook 地址，有人跌倒经确认后会自动向该地址 POST 结构化事件。',
+      '3. 接入 Home Assistant：保证同一局域网下 MQTT Broker 互通，HA 会自动发现跌倒感应实体。'
+    ]
+  },
+
+  'edge-anpr-plate-recognition': {
+    solution_id: 'edge-anpr-plate-recognition',
+    protocols: ['mqtt', 'http', 'webhook', 'rtsp'],
+    interfaces: [
+      {
+        protocol: 'mqtt',
+        port: 1883,
+        topic: 'edge/anpr/results',
+        direction: 'publish',
+        description: '抓拍过车车牌识别结果上报。',
+        payload_example: {
+          plate_number: '粤B12345',
+          confidence: 0.98,
+          direction: 'inbound',
+          lane_id: 1,
+          timestamp: 1788581350000,
+          vehicle_color: 'white',
+          vehicle_type: 'sedan'
+        }
+      },
+      {
+        protocol: 'webhook',
+        endpoint: '配置中的 ANPR_WEBHOOK_URL',
+        direction: 'outbound_post',
+        description: '过车事件向停车计费或园区管理系统推送。'
+      },
+      {
+        protocol: 'rtsp',
+        direction: 'input',
+        description: 'IP 监控摄像头 RTSP 视频流接入。'
+      }
+    ],
+    system_ingestion_guide: [
+      '1. 订阅 MQTT topic "edge/anpr/results" 获取结构化车牌及进出方向。',
+      '2. 可配置道闸联动继电器或向道闸系统发送 HTTP 开闸指令。'
+    ]
+  },
+
+  smart_agriculture_sensing: {
+    solution_id: 'smart-agriculture-sensing',
+    protocols: ['lorawan', 'mqtt', 'modbus'],
+    interfaces: [
+      {
+        protocol: 'mqtt',
+        port: 1883,
+        topic: 'sensecap/data/telemetry',
+        direction: 'publish',
+        description: '农田微气象与土壤墒情周期上报。',
+        payload_example: {
+          station_id: 's700-01',
+          air_temperature: 24.5,
+          air_humidity: 65.2,
+          soil_moisture: 38.1,
+          soil_temperature: 21.0,
+          soil_ec: 1.2,
+          light_lux: 45000,
+          battery_pct: 95
+        }
+      },
+      {
+        protocol: 'modbus',
+        port: 'RS485',
+        direction: 'bus',
+        description: '标准 Modbus RTU 工业总线控制水泵与电磁阀组。'
+      }
+    ],
+    system_ingestion_guide: [
+      '1. LoRaWAN 测点通过 SenseCAP M2 网关汇聚，通过 MQTT 集中推送到企业平台。',
+      '2. 边缘网关就地根据阈值自动执行 Modbus 继电器启停，保证断网时本地闭环运行。'
+    ]
+  },
+
+  edge_inspection_surface: {
+    solution_id: 'edge_inspection_surface',
+    protocols: ['mqtt', 'gpio', 'http'],
+    interfaces: [
+      {
+        protocol: 'mqtt',
+        port: 1883,
+        topic: 'inspection/defect/events',
+        direction: 'publish',
+        description: '流水线工业质检缺陷判别事件。',
+        payload_example: {
+          part_id: 'part-20261015-081',
+          is_defective: true,
+          defect_type: 'scratch',
+          confidence: 0.96,
+          bbox: [120, 340, 45, 12],
+          timestamp: 1788581360000
+        }
+      },
+      {
+        protocol: 'gpio',
+        direction: 'digital_out',
+        description: '隔离数字量输出 (DO)，发现次品时直接输出 24V 脉冲联动气缸执行剔除。'
+      }
+    ],
+    system_ingestion_guide: [
+      '1. 订阅缺陷事件 MQTT 用于车间看板展示不良率与缺陷类别分布。',
+      '2. 硬件 DO 端子直接接入产线 PLC 计数或剔除机构。'
+    ]
+  }
+};
+
+/**
+ * Extracts or generates system integration contract for a given solution or reference design.
+ *
+ * @param {string} solutionId
+ * @param {Object} [options]
+ * @param {string} [options.guideText] - Deployment guide text for fallback scanning
+ * @returns {Object} Integration contract specification
+ */
+export function getIntegrationContract(solutionId, { guideText = '' } = {}) {
+  const normId = String(solutionId || '').replace(/-/g, '_').toLowerCase();
+  for (const [key, contract] of Object.entries(INTEGRATION_CONTRACTS)) {
+    const normKey = key.replace(/-/g, '_').toLowerCase();
+    if (normId === normKey || normId.includes(normKey) || normKey.includes(normId)) {
+      return contract;
+    }
+  }
+
+  // Fallback: smart heuristic scan over deployment guide text
+  const protocols = [];
+  const interfaces = [];
+  const g = String(guideText || '');
+
+  if (/mqtt/i.test(g)) {
+    protocols.push('mqtt');
+    interfaces.push({
+      protocol: 'mqtt',
+      port: 1883,
+      topic: `${solutionId}/results`,
+      direction: 'publish',
+      description: 'MQTT 业务结果与状态发布总线'
+    });
+  }
+  if (/webhook/i.test(g)) {
+    protocols.push('webhook');
+    interfaces.push({
+      protocol: 'webhook',
+      endpoint: '配置中的 WEBHOOK_URL',
+      direction: 'outbound_post',
+      description: '事件触发向外部系统推送 HTTP POST 回调'
+    });
+  }
+  if (/rtsp/i.test(g)) {
+    protocols.push('rtsp');
+    interfaces.push({
+      protocol: 'rtsp',
+      port: 8554,
+      direction: 'stream',
+      description: '视频流接入或实时画面分发'
+    });
+  }
+  if (/http|dashboard|api/i.test(g)) {
+    protocols.push('http');
+    interfaces.push({
+      protocol: 'http',
+      port: 8080,
+      endpoint: '/api',
+      direction: 'inbound_rest',
+      description: 'REST API 或管理控制面板'
+    });
+  }
+
+  if (protocols.length === 0) {
+    protocols.push('mqtt', 'http');
+  }
+
+  return {
+    solution_id: solutionId,
+    protocols,
+    interfaces,
+    input_requirements: [],
+    system_ingestion_guide: [
+      '1. 详情请查阅该方案的具体部署指南与环境变量说明。',
+      '2. 通过标准网络协议（MQTT/HTTP）完成与自有业务系统的对接。'
+    ]
+  };
+}