# 平台对接需求与技术设计

## 1. 背景

需求目录 `docs/platform/` 中目前包含 DCP 雨量计、倾角、静力水准、轴力计接口文档。DCP 是当前优先落地的平台，但平台对接能力不能只服务一个平台、一个租户。平台一旦完成接入，后续其他租户应复用同一套平台定义、接口定义、流程编排、适配器和推送执行能力；租户只需要维护自己的第三方账号/用户、项目、设备、字段映射和推送任务。

当前 FastBee 已具备以下基础能力：

- 设备、产品、物模型：设备通过 `iot_device` 管理，物模型通过产品和设备编号查询。
- 设备上报处理：设备数据解析后进入原有入库和规则处理链路。
- 历史数据查询：数据中心接口支持按设备、时间窗口和物模型标识符查询历史数据。
- 数据桥接：现有 `bridge`、`iot_script`、`iot_script_bridge` 支持 HTTP、MQTT、数据库桥接。
- 定时任务：系统已有 Quartz 任务体系，可复用为定时推送和补偿任务触发器。
- 多租户：IoT 主要业务表已有 `tenant_id`、`tenant_name` 约定，平台对接也应按租户隔离业务映射和推送数据。

因此推荐建设系统级 **平台对接 / iPaaS Connector** 能力：平台基础接入可复用，租户业务映射可隔离，DCP 等复杂平台通过专用适配器补充规则。

## 2. 核心目标

平台对接需要同时满足“平台共用”和“租户隔离”：

- 平台接入人员只需维护一次第三方平台模板：认证方式、接口、字段、流程、适配器。
- 多个租户可启用同一个平台模板，不重复配置接口和流程。
- 每个租户维护自己的第三方账号/用户授权、项目映射、设备绑定、字段映射和推送任务。
- 设备上报后按租户和设备绑定匹配推送目标，生成推送记录并异步执行。
- 支持定时推送和按时间范围补推，复用现有历史数据查询能力。
- 支持幂等、失败重试、手动重推、推送日志和审计。
- DCP 这类平台保留专用适配器，处理 token、项目、测点、设备、传感器、雨量递增等平台规则。
- DCP 必须遵守 **一个测点对应一个 FastBee 设备**，不能将测点设计为平台级或产品级共享资源。

## 3. 分层模型

平台对接按三层拆分：

```text
平台模板层（全局/系统级，可复用）
  -> 平台定义、接口定义、字段定义、流程编排、适配器

租户接入层（租户级，隔离）
  -> 租户平台实例、第三方账号/用户、项目映射、资源映射、设备绑定、字段映射、推送任务

执行审计层（租户级，隔离）
  -> 推送记录 outbox、推送尝试日志、重试、重推、补偿
```

### 3.1 平台模板层

平台模板层由平台管理员维护，配置一次、多租户复用。

包含：

- 第三方平台类型，例如 DCP、通用 HTTP、通用 MQTT、通用数据库。
- 认证方式，例如无认证、固定 Token、Basic、Bearer、OAuth2、自定义 Token 接口。
- 接口定义，例如获取用户、获取项目、创建测点、创建设备、绑定传感器、推送数据。
- 接口字段定义，用于页面展示和字段映射。
- 流程编排，例如“获取用户 -> 获取项目 -> 确保测点 -> 确保设备 -> 推送数据”。
- 适配器编码，例如 `genericHttp`、`dcp`。

### 3.2 租户接入层

租户接入层由租户管理员或实施人员维护。

包含：

- 租户启用哪个平台模板。
- 租户自己的第三方账号、token、clientId/clientSecret 等授权配置。
- 租户第三方用户和项目映射。
- FastBee 设备与第三方资源的绑定。
- FastBee 物模型字段与第三方接口字段的映射。
- 实时/定时推送任务和补推策略。

同一个平台模板下，不同租户的数据必须隔离：授权配置、项目、用户、资源映射、设备绑定、推送记录都必须带 `tenant_id`。

### 3.3 执行审计层

执行审计层面向运行时。

```text
设备上报 / Quartz 定时任务 / 手动补推
  -> 标准上报快照 PlatformReport
  -> 按 tenant_id + device_id 匹配启用绑定
  -> 加载租户平台实例和流程
  -> 字段映射与数据转换
  -> 资源检查/懒加载
  -> 生成推送记录 iot_platform_push_record
  -> worker 异步执行
  -> 写推送尝试日志 iot_platform_push_attempt
```

## 4. 与现有系统功能的关系

| 现有能力 | 复用方式 |
| --- | --- |
| 设备管理 `iot_device` | 设备绑定引用 `device_id`、`serial_number`、`product_id`、`tenant_id`。 |
| 产品物模型 | 绑定页面通过现有物模型接口展示字段，字段映射使用物模型 `identifier`。 |
| 设备实时上报链路 | 在原有数据处理完成后发布平台推送事件，不改变协议解析逻辑。 |
| 数据中心历史查询 | 定时推送和手动补推按设备、时间窗口、identifier 取历史数据。 |
| 规则引擎和数据桥接 | 保留给轻量 HTTP/MQTT/DB 转发；平台对接面向多步骤、多租户、可重推场景。 |
| Quartz 定时任务 | 平台推送任务可复用 sys_job/Quartz 触发。 |
| Redis/Redisson | 缓存 token，资源创建时做并发锁。 |
| 若依权限体系 | 继续使用菜单、角色、`@PreAuthorize` 权限控制。 |

现有数据桥接仍保留。它适合“固定 URL + 固定模板 + 脚本触发”的轻量转发；平台对接用于第三方平台长期集成，需要多租户账号、项目、设备映射、流程编排、资源幂等、失败重试和审计。

## 5. 前端功能设计

一级菜单：**平台对接**。

建议菜单：

```text
平台对接
  平台模板
  接口配置
  流程编排
  租户接入
  设备绑定
  推送任务
  推送记录
```

### 5.1 平台模板

平台模板是系统级可复用配置。

主要字段：

| 字段 | 说明 |
| --- | --- |
| 平台名称 | 用户可读名称，例如 DCP。 |
| 平台编码 | 全局唯一，例如 `DCP`。 |
| 平台类型 | DCP、GENERIC_HTTP、GENERIC_MQTT、GENERIC_DB。 |
| 适配器编码 | dcp、genericHttp 等。 |
| 基础地址模板 | 可作为租户实例默认 baseUrl。 |
| 认证方式 | OAuth2、自定义 Token、固定 Token 等。 |
| 默认请求配置 | 超时、重试、Content-Type 等。 |
| 启用状态 | 启用、停用。 |

### 5.2 接口配置

接口配置属于平台模板，可被所有租户复用。

接口类型：

| 类型 | 说明 |
| --- | --- |
| TOKEN | 获取或刷新 token。 |
| QUERY | 查询第三方基础数据，如用户、项目。 |
| RESOURCE_CREATE | 创建外部资源，如测点、设备、传感器。 |
| RESOURCE_BIND | 绑定外部资源。 |
| PUSH | 推送设备数据。 |

配置项：

- 请求方法：GET、POST、PUT、DELETE。
- URL 模板：支持 `${变量}`。
- Header、Query、Body 模板。
- Content-Type。
- 成功条件：HTTP 状态码、响应 JSONPath。
- 响应变量提取：例如 `$.id -> pointId`。
- 超时和重试策略。

### 5.3 接口字段

接口字段用于设备绑定页面右侧展示，帮助租户配置字段映射。

| 字段 | 说明 |
| --- | --- |
| 接口 | 所属接口。 |
| 方向 | REQUEST、RESPONSE。 |
| 字段路径 | JSONPath 或表单字段名。 |
| 字段名称 | 展示名称。 |
| 数据类型 | string、number、boolean、array、object。 |
| 是否必填 | 是否必填。 |
| 默认值 | 默认值。 |
| 示例值 | 示例值。 |

### 5.4 流程编排

流程属于平台模板，用于将多个接口和适配器方法组成可复用业务流程。

示例：DCP 数据推送流程。

```text
获取/刷新 token
  -> 获取用户 userId
  -> 获取/选择项目 projectId
  -> 确保测点 pointId
  -> 确保设备 dcpDeviceId
  -> 确保传感器/附属资源
  -> 构造 payload
  -> 推送数据
```

流程步骤类型：

| 步骤类型 | 说明 |
| --- | --- |
| API | 调用平台接口配置。 |
| ADAPTER | 调用专用适配器方法。 |
| CONDITION | 条件判断。 |
| TRANSFORM | 数据转换。 |

流程模板可以被多个租户复用；步骤执行时使用当前租户的授权配置、项目映射、设备绑定和资源映射。

### 5.5 租户接入

租户接入表示某个租户启用某个平台模板。

主要字段：

| 字段 | 说明 |
| --- | --- |
| 租户 | 当前租户。 |
| 平台模板 | 选择 DCP 等平台模板。 |
| 实例名称 | 租户内展示名。 |
| baseUrl | 可覆盖模板默认地址。 |
| 授权配置 | 租户自己的账号、clientId、secret、token 等。 |
| 默认第三方用户 | DCP userId 或其他平台用户。 |
| 默认项目 | DCP projectId 或其他平台项目。 |
| 启用状态 | 启用、停用。 |

租户接入配置完成后，该租户才能建立设备绑定、推送任务和资源映射。

### 5.6 设备绑定

设备绑定是租户级配置。

绑定内容：

```text
租户平台实例 + FastBee 设备 + 平台流程 + 第三方用户/项目 + 字段映射 + 推送模式
```

绑定页面左侧使用现有 FastBee 产品、设备、物模型；右侧使用平台模板的接口字段和租户的第三方用户/项目/资源。

绑定支持：新增、修改、启用、停用、解绑、初始化资源、查看资源映射、查看推送记录。

DCP 绑定规则：

```text
FastBee 一个设备 = DCP 一个测点 = DCP 一个设备资源
```

DCP 的 `pointId`、`dcpDeviceId`、sensor/module/virtual 等必须按租户设备绑定保存，不能平台级共享。

### 5.7 字段映射

字段映射按设备绑定维护，也可以支持从平台模板复制默认映射。

映射来源：

| 来源类型 | 说明 |
| --- | --- |
| THING_MODEL | 物模型字段，例如 rainfall。 |
| SYSTEM | 系统字段，例如 serialNumber、deviceName、reportTime。 |
| CONSTANT | 常量。 |
| RESOURCE | 外部资源映射，例如 pointId、dcpDeviceId。 |
| JSONPATH | 从 rawPayload 中取值。 |
| EXPRESSION | 受限表达式，后续增强。 |

第一阶段转换能力建议支持：直接映射、时间格式化、单位换算、数值倍率、枚举转换、默认值。表达式必须受限，不能执行任意代码。

### 5.8 推送任务与推送记录

推送任务是租户级配置，支持：

- 实时推送：设备上报后生成推送记录。
- 定时推送：按 Quartz/sys_job 触发，从历史数据按窗口生成推送记录。
- 手动补推：按设备和时间范围生成推送记录。

推送记录展示业务层面的推送状态：

- 按租户、平台、流程、设备、状态、时间筛选。
- 查看最终 payload、幂等 key、请求响应、错误信息。
- 失败重推、批量重推、成功记录强制重推。

## 6. 标准上报快照

字段映射不要直接依赖原始 MQTT/HTTP payload。系统应先把设备数据整理成统一快照。

```json
{
  "tenantId": 1,
  "productId": 10,
  "deviceId": 1001,
  "serialNumber": "ABC001",
  "deviceName": "雨量计-001",
  "reportTime": "2026-05-27 10:00:00",
  "sourceRefId": "device_log_id_or_history_id",
  "values": {
    "rainfall": {
      "value": 12.3,
      "unit": "mm",
      "ts": "2026-05-27 10:00:00"
    },
    "temperature": {
      "value": 22.1,
      "unit": "℃",
      "ts": "2026-05-27 10:00:00"
    }
  },
  "rawPayload": {}
}
```

`values` 的 key 使用物模型 `identifier`，便于复用现有物模型和历史数据查询能力。

## 7. DCP 适配设计

DCP 通过平台模板 + 流程编排 + 专用适配器落地。

### 7.1 DCP 平台模板

DCP 平台模板包含：

- token 接口：`POST /connect/token`。
- 用户接口：获取 userId。
- 项目接口：按 userId 获取项目。
- 资源接口：创建测点、创建设备、创建/绑定传感器等。
- 推送接口：雨量、倾角、静力水准、轴力计数据推送。
- DCP 专用适配器：处理 token 缓存、资源幂等、payload 构造、特殊规则。

这些配置由系统维护一次，所有租户复用。

### 7.2 DCP 租户映射

每个租户需要维护自己的 DCP 映射：

```text
租户
  -> DCP 租户平台实例
  -> DCP 账号/用户 userId
  -> DCP 项目 projectId
  -> FastBee 设备绑定 DCP 测点 pointId
  -> FastBee 设备绑定 DCP 设备 dcpDeviceId
  -> 设备附属 sensor/module/virtual
```

同一个 DCP 平台模板下，不同租户可以使用不同 DCP 账号、用户和项目。资源映射必须按 `tenant_id` 隔离。

### 7.3 DCP 一测点一设备约束

DCP 资源映射必须按“一测点一设备”建模：

```text
FastBee Device(serialNumber)
  -> DCP Project(projectId)
  -> DCP Point(pointId)
  -> DCP Device(dcpDeviceId)
  -> DCP Sensor/Module/Virtual(按设备类型可选)
```

规则：

- `PROJECT` 可以是租户平台实例级默认资源，也可以绑定级覆盖。
- `USER`、`PROJECT` 是租户级或绑定级映射，不是全局共享。
- `POINT` 必须是设备级资源，一个 FastBee 设备对应一个 DCP 测点。
- `DEVICE` 必须是设备级资源，一个 FastBee 设备对应一个 DCP 设备资源。
- `SENSOR`、`MODULE`、`VIRTUAL` 是设备附属资源，按绑定保存。
- 静力水准 payload 中可包含多条 `sensorData`，但仍归属同一个 FastBee 设备对应的 DCP 测点和 DCP 设备下。

### 7.4 DCP 运行流程

```text
设备上报或定时任务
  -> 匹配租户 DCP 设备绑定
  -> 加载租户 DCP 授权配置
  -> 获取/刷新 token
  -> 加载 userId/projectId 映射
  -> 加载 pointId/dcpDeviceId/sensor 映射
  -> 资源缺失时按流程懒加载或手动初始化
  -> 构造对应设备类型 payload
  -> 调用 DCP 数据接口
  -> 写推送记录和尝试日志
```

资源创建必须幂等。并发上报同一设备时，使用 Redis/Redisson 锁：

```text
platform:dcp:resource:{tenantId}:{tenantChannelId}:{serialNumber}
```

### 7.5 DCP 特殊规则

- 雨量 `value` 为累计降雨量，DCP 要求新值大于历史值。系统使用绑定的 `last_success_value` 或资源扩展字段记录最近成功值；不满足时记录为 `SKIPPED`，不反复重试。
- 倾角需要同一时间的 x、y、z 和温度，必须按一次设备快照组包，不能拆成多个单字段推送。
- 静力水准的 `sensorData` 可包含多条传感器数据，但这些数据属于同一个 FastBee 设备对应的 DCP 设备资源。
- 轴力计按独立设备类型处理，字段映射和 payload 由 `DcpPlatformAdapter` 中对应 builder 负责。
- DCP token 缓存在 Redis，key 建议：`platform:dcp:token:{tenantId}:{tenantChannelId}`。
- 401 或 token 过期时刷新 token 后重试一次，再失败则记录错误。

## 8. 表设计

表名前缀使用 `iot_platform_`，避免和现有 `iot_social_platform` 混淆。

### 8.1 表清单

| 表名 | 层级 | 说明 |
| --- | --- | --- |
| `iot_platform_template` | 平台模板层 | 平台模板，全局可复用。 |
| `iot_platform_api` | 平台模板层 | 第三方接口定义。 |
| `iot_platform_api_field` | 平台模板层 | 接口字段定义。 |
| `iot_platform_flow` | 平台模板层 | 流程模板。 |
| `iot_platform_flow_step` | 平台模板层 | 流程步骤。 |
| `iot_platform_tenant_channel` | 租户接入层 | 租户启用的平台实例和授权配置。 |
| `iot_platform_resource_mapping` | 租户接入层 | 用户、项目、测点、设备、传感器等资源映射。 |
| `iot_platform_binding` | 租户接入层 | FastBee 设备与平台流程/项目/资源绑定。 |
| `iot_platform_field_mapping` | 租户接入层 | 绑定级字段映射。 |
| `iot_platform_push_task` | 租户接入层 | 定时推送任务。 |
| `iot_platform_task_binding` | 租户接入层 | 推送任务与绑定关系。 |
| `iot_platform_push_record` | 执行审计层 | 推送记录，兼 outbox。 |
| `iot_platform_push_attempt` | 执行审计层 | 每次推送尝试日志。 |

### 8.2 iot_platform_template

平台模板，全局可复用。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint | 主键 |
| platform_code | varchar(64) | 平台编码，全局唯一 |
| platform_name | varchar(128) | 平台名称 |
| platform_type | varchar(32) | DCP、GENERIC_HTTP、GENERIC_MQTT、GENERIC_DB |
| adapter_code | varchar(64) | dcp、genericHttp 等 |
| base_url_template | varchar(512) | 默认基础地址模板 |
| auth_type | varchar(32) | 认证类型 |
| auth_schema | json | 授权配置字段定义，用于租户填写 |
| request_config | json | 默认超时、重试、TLS 等 |
| status | tinyint | 0停用，1启用 |
| create_time | datetime | 创建时间 |
| update_time | datetime | 更新时间 |
| remark | varchar(500) | 备注 |

建议索引：

```text
uk_platform_code(platform_code)
idx_platform_type(platform_type)
```

### 8.3 iot_platform_api

第三方接口定义，属于平台模板。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint | 主键 |
| template_id | bigint | 平台模板 id |
| api_code | varchar(64) | 接口编码 |
| api_name | varchar(128) | 接口名称 |
| api_type | varchar(32) | TOKEN、QUERY、PUSH、RESOURCE_CREATE、RESOURCE_BIND |
| method | varchar(16) | GET、POST、PUT、DELETE |
| path_template | varchar(512) | URL 路径模板 |
| content_type | varchar(64) | application/json、form-urlencoded |
| header_template | json | Header 模板 |
| query_template | json | Query 模板 |
| body_template | json | Body 模板 |
| success_condition | json | 成功条件 |
| response_mapping | json | 响应变量提取规则 |
| retry_policy | json | 接口级重试策略 |
| timeout_ms | int | 超时时间 |
| status | tinyint | 0停用，1启用 |
| create_time | datetime | 创建时间 |
| update_time | datetime | 更新时间 |

建议索引：

```text
uk_template_api_code(template_id, api_code)
idx_template_api_type(template_id, api_type)
```

### 8.4 iot_platform_api_field

接口字段定义，用于页面展示和字段映射。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint | 主键 |
| api_id | bigint | 接口 id |
| direction | varchar(16) | REQUEST、RESPONSE |
| field_path | varchar(256) | JSONPath 或表单字段名 |
| field_name | varchar(128) | 字段名称 |
| data_type | varchar(32) | string、number、boolean、array、object |
| required | tinyint | 是否必填 |
| default_value | varchar(512) | 默认值 |
| example_value | varchar(512) | 示例值 |
| description | varchar(500) | 说明 |
| sort_order | int | 排序 |

建议索引：

```text
idx_api_direction(api_id, direction)
```

### 8.5 iot_platform_flow

流程模板，属于平台模板。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint | 主键 |
| template_id | bigint | 平台模板 id |
| flow_code | varchar(64) | 流程编码 |
| flow_name | varchar(128) | 流程名称 |
| flow_type | varchar(32) | PUSH、QUERY、RESOURCE_SYNC |
| adapter_code | varchar(64) | 可覆盖平台适配器 |
| status | tinyint | 0停用，1启用 |
| create_time | datetime | 创建时间 |
| update_time | datetime | 更新时间 |
| remark | varchar(500) | 备注 |

建议索引：

```text
uk_template_flow_code(template_id, flow_code)
```

### 8.6 iot_platform_flow_step

流程步骤。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint | 主键 |
| flow_id | bigint | 流程 id |
| step_code | varchar(64) | 步骤编码 |
| step_name | varchar(128) | 步骤名称 |
| step_type | varchar(32) | API、ADAPTER、CONDITION、TRANSFORM |
| api_id | bigint | API 步骤引用接口 id |
| adapter_method | varchar(128) | 适配器方法，例如 ensurePoint |
| input_mapping | json | 步骤入参映射 |
| output_mapping | json | 步骤输出变量映射 |
| condition_expr | varchar(512) | 执行条件 |
| on_fail | varchar(32) | STOP、SKIP、RETRY |
| sort_order | int | 执行顺序 |
| status | tinyint | 0停用，1启用 |

建议索引：

```text
idx_flow_sort(flow_id, sort_order)
```

### 8.7 iot_platform_tenant_channel

租户启用平台模板后的平台实例。授权配置、baseUrl、默认用户/项目属于租户级。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint | 主键 |
| tenant_id | bigint | 租户 id |
| tenant_name | varchar(64) | 租户名称 |
| template_id | bigint | 平台模板 id |
| channel_code | varchar(64) | 租户内平台实例编码 |
| channel_name | varchar(128) | 租户内平台实例名称 |
| base_url | varchar(512) | 实际基础地址 |
| auth_config | json | 租户授权配置，敏感值加密 |
| default_user_id | varchar(128) | 默认第三方用户 id |
| default_project_id | varchar(128) | 默认第三方项目 id |
| config_json | json | 租户级扩展配置 |
| status | tinyint | 0停用，1启用 |
| del_flag | char(1) | 0正常，2删除 |
| create_by | varchar(64) | 创建者 |
| create_time | datetime | 创建时间 |
| update_by | varchar(64) | 更新者 |
| update_time | datetime | 更新时间 |
| remark | varchar(500) | 备注 |

建议索引：

```text
uk_tenant_channel_code(tenant_id, channel_code, del_flag)
idx_tenant_template(tenant_id, template_id)
```

### 8.8 iot_platform_resource_mapping

外部资源映射，租户级隔离。DCP 的 user、project、point、device、sensor 等都保存在这里。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint | 主键 |
| tenant_id | bigint | 租户 id |
| tenant_channel_id | bigint | 租户平台实例 id |
| binding_id | bigint | 绑定 id，用户/项目可为空 |
| resource_scope | varchar(32) | TENANT、PROJECT、DEVICE、BINDING |
| resource_type | varchar(64) | USER、PROJECT、POINT、DEVICE、SENSOR、MODULE、VIRTUAL |
| local_key | varchar(128) | 本地唯一键，设备级使用 serialNumber |
| external_id | varchar(128) | 外部资源 id |
| external_code | varchar(128) | 外部资源编码 |
| external_name | varchar(128) | 外部资源名称 |
| resource_payload | json | 外部资源详情 |
| status | tinyint | 0失效，1有效 |
| create_time | datetime | 创建时间 |
| update_time | datetime | 更新时间 |

建议索引：

```text
uk_resource(tenant_channel_id, binding_id, resource_type, local_key)
idx_resource_tenant_type(tenant_id, tenant_channel_id, resource_type)
idx_external_id(tenant_channel_id, resource_type, external_id)
```

### 8.9 iot_platform_binding

设备绑定，租户级配置。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint | 主键 |
| tenant_id | bigint | 租户 id |
| tenant_channel_id | bigint | 租户平台实例 id |
| flow_id | bigint | 平台流程 id |
| product_id | bigint | 产品 id |
| product_name | varchar(128) | 产品名称冗余 |
| device_id | bigint | FastBee 设备 id |
| device_name | varchar(128) | FastBee 设备名称 |
| serial_number | varchar(64) | FastBee 设备编号 |
| external_user_id | varchar(128) | 绑定级第三方用户 id，可为空 |
| external_project_id | varchar(128) | 绑定级第三方项目 id，可为空 |
| external_device_type | varchar(32) | 第三方设备类型，例如 DCP RAIN、INCLINO |
| binding_name | varchar(128) | 绑定名称 |
| push_mode | varchar(16) | REALTIME、SCHEDULED、BOTH |
| config_json | json | 绑定级配置 |
| last_success_time | datetime | 最近成功推送时间 |
| last_success_value | varchar(128) | 最近成功值，雨量递增等场景使用 |
| status | tinyint | 0停用，1启用 |
| del_flag | char(1) | 0正常，2删除 |
| create_time | datetime | 创建时间 |
| update_time | datetime | 更新时间 |

建议索引：

```text
idx_binding_device(tenant_id, product_id, serial_number)
idx_binding_channel_flow(tenant_channel_id, flow_id)
uk_binding(tenant_channel_id, flow_id, serial_number, del_flag)
```

### 8.10 iot_platform_field_mapping

字段映射，按绑定维护。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint | 主键 |
| tenant_id | bigint | 租户 id |
| binding_id | bigint | 绑定 id |
| target_path | varchar(256) | 外部目标字段路径 |
| target_name | varchar(128) | 外部字段名称 |
| source_type | varchar(32) | THING_MODEL、SYSTEM、CONSTANT、JSONPATH、EXPRESSION、RESOURCE |
| source_key | varchar(256) | 物模型 identifier、系统字段、表达式等 |
| source_name | varchar(128) | 内部字段名称 |
| transform_type | varchar(32) | DIRECT、DATE_FORMAT、UNIT_CONVERT、ENUM、NUMBER_SCALE、TEMPLATE、EXPRESSION |
| transform_config | json | 转换配置 |
| default_value | varchar(512) | 默认值 |
| required | tinyint | 是否必填 |
| sort_order | int | 排序 |
| status | tinyint | 0停用，1启用 |

建议索引：

```text
idx_mapping_binding(binding_id)
```

### 8.11 iot_platform_push_task

定时推送任务，租户级。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint | 主键 |
| tenant_id | bigint | 租户 id |
| tenant_channel_id | bigint | 租户平台实例 id |
| flow_id | bigint | 流程 id |
| task_name | varchar(128) | 任务名称 |
| cron_expression | varchar(128) | Cron 表达式 |
| window_type | varchar(32) | LAST_SUCCESS、RECENT_MINUTES、CUSTOM |
| window_config | json | 时间窗口配置 |
| batch_size | int | 批次大小 |
| max_retry | int | 最大重试次数 |
| status | tinyint | 0停用，1启用 |
| last_run_time | datetime | 最近执行时间 |
| next_run_time | datetime | 下次执行时间 |
| create_time | datetime | 创建时间 |
| update_time | datetime | 更新时间 |

### 8.12 iot_platform_task_binding

定时任务与设备绑定关系。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint | 主键 |
| task_id | bigint | 任务 id |
| binding_id | bigint | 绑定 id |
| status | tinyint | 0停用，1启用 |

建议索引：

```text
uk_task_binding(task_id, binding_id)
```

### 8.13 iot_platform_push_record

推送记录，租户级 outbox。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint | 主键 |
| tenant_id | bigint | 租户 id |
| tenant_channel_id | bigint | 租户平台实例 id |
| flow_id | bigint | 流程 id |
| binding_id | bigint | 绑定 id |
| task_id | bigint | 定时任务 id，实时推送为空 |
| push_mode | varchar(16) | REALTIME、SCHEDULED、MANUAL |
| source_device_id | bigint | FastBee 设备 id |
| serial_number | varchar(64) | FastBee 设备编号 |
| source_ref_id | varchar(128) | 来源日志或历史数据 id |
| source_time | datetime | 数据时间 |
| time_window_start | datetime | 批量窗口开始 |
| time_window_end | datetime | 批量窗口结束 |
| request_payload | json | 待推送 payload |
| payload_hash | varchar(64) | payload 哈希 |
| idempotency_key | varchar(128) | 幂等 key |
| status | varchar(32) | PENDING、PROCESSING、SUCCESS、FAILED、RETRY_WAIT、SKIPPED、CANCELLED |
| retry_count | int | 已重试次数 |
| max_retry | int | 最大重试次数 |
| next_retry_time | datetime | 下次重试时间 |
| last_error | varchar(1000) | 最近错误 |
| locked_by | varchar(64) | worker 锁 |
| locked_time | datetime | 锁定时间 |
| success_time | datetime | 成功时间 |
| create_time | datetime | 创建时间 |
| update_time | datetime | 更新时间 |

建议索引：

```text
uk_idempotency(idempotency_key)
idx_record_poll(status, next_retry_time)
idx_record_device(tenant_channel_id, serial_number, source_time)
idx_record_binding(binding_id, source_time)
```

### 8.14 iot_platform_push_attempt

推送尝试日志。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint | 主键 |
| tenant_id | bigint | 租户 id |
| record_id | bigint | 推送记录 id |
| attempt_no | int | 第几次尝试 |
| request_url | varchar(1024) | 请求地址 |
| request_headers | json | 请求头，敏感信息脱敏 |
| request_payload | json | 请求体 |
| response_status | int | HTTP 状态码 |
| response_body | mediumtext | 响应内容 |
| success | tinyint | 是否成功 |
| error_msg | varchar(1000) | 错误信息 |
| duration_ms | int | 耗时 |
| create_time | datetime | 创建时间 |

建议索引：

```text
idx_attempt_record(record_id, attempt_no)
idx_attempt_tenant(tenant_id, create_time)
```

## 9. 技术实现建议

### 9.1 模块与包

后端先放在现有 IoT 服务和 open-api 中：

```text
fastbee-open-api/src/main/java/com/fastbee/controller/platform
fastbee-service/fastbee-iot-service/src/main/java/com/fastbee/iot/platform
fastbee-service/fastbee-iot-service/src/main/resources/mapper/iot/platform
```

前端目录：

```text
yack-web/src/views/iot/platformConnect
yack-web/src/api/iot/platformConnect.js
```

权限前缀建议使用 `iot:platformConnect`，避免和现有第三方登录 `iot:platform` 混淆。

### 9.2 核心接口

```java
public interface PlatformAdapter {
    String adapterCode();
    void beforeExecute(PlatformContext context);
    void ensureResources(PlatformContext context);
    Object buildPayload(PlatformContext context);
    PushResult push(PlatformContext context, Object payload);
}
```

```java
public interface PlatformFlowExecutor {
    PushResult execute(Long tenantChannelId, Long flowId, PlatformReport report, Long bindingId);
}
```

```java
public interface PlatformPushRecordService {
    void createRealtimeRecords(PlatformReport report);
    void createScheduledRecords(Long taskId, Date beginTime, Date endTime);
    void retry(Long recordId, boolean force);
    void retryBatch(List<Long> recordIds, boolean force);
}
```

### 9.3 实时推送接入点

设备上报原流程保持不变，在设备数据入库或规则处理附近增加平台推送事件：

```text
设备数据解析
  -> 原有设备日志/历史数据处理
  -> 构造 PlatformReport
  -> PlatformPushRecordService.createRealtimeRecords(report)
  -> 匹配 tenant_id + device_id 的启用绑定
  -> 生成 PENDING 推送记录
  -> worker 异步执行流程
```

如果短期不改主链路，也可先通过现有规则引擎脚本触发平台推送服务，作为过渡方案。

### 9.4 定时推送

优先复用 Quartz/sys_job：

```text
Quartz 触发
  -> 读取 iot_platform_push_task
  -> 根据 window_type 计算时间窗口
  -> 查询任务关联绑定
  -> 调用现有历史数据服务按设备取数
  -> 构造 PlatformReport
  -> 批量生成推送记录
  -> worker 执行流程
```

不建议第一阶段新增独立调度框架。

### 9.5 worker 处理

worker 轮询：

```text
status in (PENDING, RETRY_WAIT)
and next_retry_time <= now
```

抢占记录时使用数据库乐观更新，避免多实例重复消费：

```sql
UPDATE iot_platform_push_record
SET status = 'PROCESSING', locked_by = ?, locked_time = NOW()
WHERE id = ?
  AND status IN ('PENDING', 'RETRY_WAIT')
```

处理结果：成功写 `SUCCESS`，可重试失败写 `RETRY_WAIT`，超过次数写 `FAILED`，业务跳过写 `SKIPPED`。

## 10. 幂等与重推

### 10.1 推送记录幂等

实时数据优先使用原始日志 id：

```text
tenantChannelId + flowId + bindingId + pushMode + sourceRefId + payloadHash
```

没有 `sourceRefId` 时使用：

```text
tenantChannelId + flowId + bindingId + pushMode + sourceTime + payloadHash
```

定时窗口使用：

```text
tenantChannelId + flowId + bindingId + windowStart + windowEnd + sourceTime + payloadHash
```

`idempotency_key` 必须唯一。

### 10.2 外部资源幂等

资源创建前先查 `iot_platform_resource_mapping`。

DCP 设备级资源必须按 `tenantChannelId + bindingId + serialNumber + resourceType` 唯一。

```text
查 mapping
  -> 存在则复用
  -> 不存在则加 Redis 锁
  -> 再查一次
  -> 调第三方创建接口或适配器方法
  -> 保存 mapping
```

DCP 锁 key：

```text
platform:dcp:resource:{tenantId}:{tenantChannelId}:{serialNumber}
```

### 10.3 手动重推

- 失败记录重推：原记录状态重置为 `PENDING`，保留历史 attempt。
- 成功记录强制重推：新建 `MANUAL` 记录，幂等 key 追加手动批次号。
- 按设备时间范围补推：查询历史数据后生成新的 `MANUAL` 推送记录。

## 11. 权限建议

权限前缀：`iot:platformConnect`。

```text
iot:platformConnect:template:list/query/add/edit/remove
iot:platformConnect:api:list/add/edit/remove
iot:platformConnect:flow:list/add/edit/remove
iot:platformConnect:tenantChannel:list/query/add/edit/remove
iot:platformConnect:binding:list/query/add/edit/unbind/initResource
iot:platformConnect:task:list/add/edit/remove
iot:platformConnect:record:list/query/retry
```

平台模板、接口、流程建议仅平台管理员可维护；租户管理员主要维护租户接入、设备绑定、推送任务和推送记录。

## 12. 实施计划

### 阶段一：平台模板与租户接入骨架

- 新增平台模板、接口、字段、流程、流程步骤表。
- 新增租户平台实例表。
- 建立 DCP 平台模板和 DCP 基础流程。
- 实现租户级授权配置和默认用户/项目映射。

### 阶段二：设备绑定与 DCP 资源映射

- 新增设备绑定、字段映射、资源映射页面和接口。
- 实现 DCP 一设备一测点、一设备一 DCP 设备资源建模。
- 实现 DCP token、userId、projectId、pointId、dcpDeviceId、sensor/module/virtual 资源初始化。

### 阶段三：推送执行与审计

- 新增推送记录和推送尝试日志。
- 实现实时推送记录生成。
- 实现 worker、重试、幂等和手动重推。
- 支持雨量计实时推送闭环。

### 阶段四：补齐 DCP 设备类型与定时补偿

- 倾角 payload 组包。
- 静力水准 sensorData 配置和组包。
- 轴力计 payload 组包。
- 雨量递增校验和 `SKIPPED` 状态。
- 接入 Quartz/sys_job 定时推送和按时间范围补推。

### 阶段五：通用平台增强

- 通用 HTTP 平台模板。
- 接口调试。
- 模板导入导出。
- MQTT/DB 适配器按需扩展。
- 日志归档和敏感信息脱敏策略。

## 13. 风险与约束

- 平台模板是共享基础能力，租户授权、项目、设备绑定、推送记录必须按 `tenant_id` 隔离。
- DCP 一测点一设备是核心建模约束，不能把测点设计成产品级或平台级共享资源。
- 实时推送必须异步，不影响设备上报吞吐。
- token、密码、请求头等敏感信息需要加密保存和脱敏展示。
- 推送日志增长较快，需要后续增加归档或清理策略。
- 字段映射表达式必须受限，不能执行任意代码。
- 定时补推要限制窗口、批次大小和并发数，避免压垮第三方平台。
- 雨量累计值不递增时应跳过并记录原因，不应无限重试。

## 14. 结论

平台对接应定位为可复用的 iPaaS/Connector 能力，而不是单个平台的硬编码适配。

推荐模型：

```text
平台模板（共享）
  -> 接口配置（共享）
  -> 流程编排（共享）
  -> 适配器（共享）
  -> 租户平台实例（租户级）
  -> 用户/项目/资源映射（租户级）
  -> 设备绑定和字段映射（租户级）
  -> 推送任务、推送记录、推送日志（租户级）
```

DCP 是第一批落地模板和适配器，必须保留“一测点一设备”的资源约束；其他租户复用 DCP 平台模板后，只需配置自己的 DCP 账号、用户、项目、设备绑定、字段映射和推送策略。