平台对接 — 流程编排设计说明

厘清流程编排的边界：什么时候需要它，什么时候不需要它

一、先回答核心问题

用户的质疑是对的：实时推送数据只需要调一个接口，根本不需要流程编排。

流程编排解决的是另一类问题：多个接口必须按顺序调用，且上一步的返回值是下一步的入参。

把这两类场景混在一起设计，会让系统过度复杂。下面把它们彻底分开。

二、对接 DCP 的四个阶段

阶段一
初始化
平台初始化 一次性 获取并保存 userId、projectId 等平台侧的基础信息。这些信息不会变，保存到数据库后后续直接读取，不再重复调用。
阶段二
设备入网
设备注册到 DCP 每设备一次 在 DCP 侧创建测点 → 绑定传感器 → 获得 DCP deviceId，保存到设备绑定表。同一设备只做一次，之后实时推送直接用这个 deviceId。
阶段三
Token刷新
Token 自动续期 自动触发 Token 过期时自动调用认证接口，更新 access_token。这是一个单步操作，不需要流程编排，由系统在每次 HTTP 调用前自动检查处理。
阶段四
实时推送
设备数据实时推送 每次上报 设备上报数据 → 按字段映射转换 → 调用一个推送接口。单步，无编排，直接执行。

三、流程编排只解决哪类问题

痛点：多步串联，出参传入参

创建测点返回 pointId，绑定传感器时需要传 pointId。如果写死在代码里，换个平台就要改代码。

流程编排解决：可配置的串联调用

在 UI 里配置"第1步的出参 id → 第2步的入参 pointId"，引擎自动完成传递，无需改代码。

痛点：初始化步骤因平台而异

DCP 需要先获取 userId 再获取 projectId，另一个平台可能直接返回 projectId。每个平台都写一套代码难以维护。

流程编排解决：平台差异配置化

每个平台配置自己的初始化流程，引擎统一执行，业务代码不感知平台差异。

⚠️ 流程编排不适合的场景：实时数据推送。每次设备上报都走流程引擎会引入不必要的开销和复杂度。实时推送是高频操作，应该走最短路径：字段映射 → 直接 HTTP 调用。

四、优化后的执行模式划分

场景 触发方式 执行模式 需要流程编排 频率
平台初始化（获取userId/projectId） 手动点击 流程引擎 ✓ 需要 一次性
设备入网（创建测点+绑定传感器） 手动点击 流程引擎 ✓ 需要 每设备一次
Token 刷新 自动（过期前） 单接口调用 — 不需要 按需
实时数据推送 设备上报触发 直接调用 ✗ 不需要 高频
定时批量推送 Quartz 定时 直接调用 ✗ 不需要 定时

五、三个流程的具体设计

流程 1：平台初始化（手动执行一次）

Step 1
获取 Token
POST /connect/token
→ 出参: access_token
→
Step 2
获取用户ID
GET /api/app/user/user-id
→ 出参: userId
→
Step 3
获取项目列表
GET /project/by-user-id/{userId}
→ 出参: projectId

执行完成后，userId 和 projectId 自动保存到 platform_instance 的 extra_config 字段，后续所有操作直接读取，不再重复调用。

流程 2：设备入网（每个设备执行一次）

Step 1
创建测点
POST /api/app/point
→ 出参: pointId
→
Step 2
绑定传感器
POST /api/app/inclino-sensor
→ 出参: deviceId

Step 2 的入参 projectId 自动从 Step 1 的出参获取。执行完成后，DCP deviceId 自动回填到 platform_device_mapping 表，设备状态变为"已入网"。

不同传感器类型（倾角/轴力/雨量/静力水准）配置不同的 Step 2 接口，其余逻辑相同。

实时推送：不走流程，直接调用

触发
设备上报
MQTT / HTTP
→
转换
字段映射
identifier → DCP字段
→
推送
调用推送接口
POST /inclino-data/many
→
记录
写推送日志
platform_push_log

全程只有一次 HTTP 调用。Token 检查在调用前自动完成（过期则先刷新），对业务逻辑透明。

六、关键数据的存储与流转

数据何时获取存储位置后续如何使用
access_token 初始化 / 过期自动刷新 platform_instance.access_token 每次 HTTP 请求自动注入 Authorization 头
userId 初始化流程 Step 2 platform_instance.extra_config 设备入网流程中作为固定入参
projectId 初始化流程 Step 3 platform_instance.extra_config 设备入网流程中作为固定入参
DCP deviceId 设备入网流程 Step 2 platform_device_mapping.platform_device_id 实时推送时作为 deviceId 字段
DCP pointId 设备入网流程 Step 1 platform_device_mapping.platform_point_id 重新绑定时使用，一般不再需要

七、前端操作流程（用户视角）

第一步：新建平台

填写平台名称、baseURL、账号密码 → 保存。系统自动内置 DCP 的所有接口定义，无需手动配置接口。

第二步：初始化平台

点击"初始化"按钮 → 系统自动执行初始化流程（获取Token → userId → projectId）→ 成功后显示"已初始化，项目：XXX"。

第三步：绑定设备

在设备绑定页面，搜索选择 FastBee 设备 → 选择传感器类型 → 配置字段映射（物模型字段下拉选择，DCP字段根据传感器类型预填建议值）→ 点击"入网"按钮 → 系统自动执行入网流程 → 成功后显示 DCP deviceId。

第四步：开始推送

设备绑定完成后，设备上报数据时自动推送，无需任何操作。在推送日志页面可查看每次推送的详情。

八、流程编排 UI 的简化设计

流程编排 UI 只服务于"初始化"和"设备入网"两类场景，不需要做成通用的可视化拖拽编辑器（过度设计）。

简化方案：步骤列表 + 字段映射

每个流程展示有序步骤列表，每步配置：

对于 DCP，系统内置两个流程的默认配置，用户开箱即用，不需要手动编排。流程编排 UI 是给高级用户或对接新平台时使用的。

九、设计总结

设计决策原因
实时推送不走流程引擎 高频操作，单步调用，流程引擎引入不必要开销
初始化和入网走流程引擎 多步串联，出参传入参，不同平台步骤不同，配置化解决
Token 刷新不是流程步骤 是横切关注点，在 HTTP 调用前自动处理，对业务透明
userId/projectId 保存到 extra_config 一次获取，永久复用，不重复调用
DCP 内置接口和流程定义 降低用户配置成本，开箱即用
字段映射用下拉选择，不手填 物模型字段和 DCP 字段都有固定枚举，选择比输入更可靠