# 平台对接设计文档

## 1. 背景与目标

FastBee 需要将设备数据推送至第三方监测平台（当前为 DCP 结构监测 SaaS），并支持未来对接多个平台。不同平台的认证方式、接口路径、字段格式各不相同，需要一套可配置、可扩展的对接框架。

**设计原则：**
- 平台、接口、流程、设备绑定全部可视化配置，无需改代码即可对接新平台
- 严格区分三类执行模式，避免过度设计
- 字段映射通过 UI 关联选择，不手填字符串
- 推送全程有日志，可追溯

---

## 2. 三种执行模式

### 模式一：流程编排（多步串联）

**适用场景：** 多个接口必须按顺序调用，且上一步的返回值是下一步的入参。

| 流程 | 触发方式 | 步骤 | 频率 |
|---|---|---|---|
| 平台初始化 | 手动点击一次 | Token → userId → projectId | 一次性 |
| 设备入网 | 手动点击（每设备） | 创建测点 → 绑定传感器 → 获得 DCP deviceId | 每设备一次 |

执行结果自动持久化：userId/projectId 写入 `platform_instance.extra_config`，DCP deviceId 回填到 `platform_device_mapping`。

### 模式二：直接调用（实时推送）

**适用场景：** 设备上报数据时，按字段映射转换后调用单个推送接口。

流程：设备上报 → 字段映射转换 → 直接 HTTP 调用推送接口 → 写推送日志

**不走流程引擎**，最短路径，不引入额外开销。

### 模式三：Token 自动刷新（横切关注点）

每次 HTTP 调用前自动检查 `token_expires_at`，提前 5 分钟视为过期，过期则先调用认证接口刷新 Token，对业务逻辑完全透明。

---

## 3. 数据库设计（6 张表）

### 3.1 `platform_instance` — 平台实体

```sql
CREATE TABLE `platform_instance` (
  `id`               bigint       NOT NULL AUTO_INCREMENT,
  `name`             varchar(100) NOT NULL COMMENT '平台名称，如 DCP结构监测',
  `code`             varchar(50)  NOT NULL UNIQUE COMMENT '平台唯一标识，如 dcp',
  `base_url`         varchar(255) NOT NULL COMMENT '基础URL',
  `auth_type`        tinyint      NOT NULL DEFAULT 1 COMMENT '认证类型(1=密码Token,2=ApiKey,3=OAuth2)',
  `auth_config`      json         DEFAULT NULL COMMENT '认证凭证JSON {userName,password,clientId,scope}',
  `extra_config`     json         DEFAULT NULL COMMENT '初始化后保存的平台数据 {userId,projectId,...}',
  `access_token`     varchar(2000) DEFAULT NULL COMMENT '当前有效Token',
  `token_expires_at` datetime     DEFAULT NULL COMMENT 'Token过期时间',
  `init_status`      tinyint      NOT NULL DEFAULT 0 COMMENT '初始化状态(0=未初始化,1=已初始化)',
  `enable`           char(1)      NOT NULL DEFAULT '1',
  `tenant_id`        bigint       DEFAULT NULL,
  `remark`           varchar(500) DEFAULT NULL,
  `create_by`        varchar(64)  DEFAULT '',
  `create_time`      datetime     DEFAULT CURRENT_TIMESTAMP,
  `update_by`        varchar(64)  DEFAULT '',
  `update_time`      datetime     DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`)
) COMMENT='第三方平台实体';
```

### 3.2 `platform_interface` — 接口定义

```sql
CREATE TABLE `platform_interface` (
  `id`              bigint       NOT NULL AUTO_INCREMENT,
  `platform_id`     bigint       NOT NULL COMMENT '所属平台',
  `name`            varchar(100) NOT NULL COMMENT '接口名称',
  `code`            varchar(100) NOT NULL COMMENT '接口标识',
  `method`          varchar(10)  NOT NULL COMMENT 'HTTP方法',
  `path`            varchar(255) NOT NULL COMMENT '接口路径，支持路径变量 {userId}',
  `content_type`    varchar(100) DEFAULT 'application/json',
  `request_schema`  json         DEFAULT NULL COMMENT '入参字段定义',
  `response_schema` json         DEFAULT NULL COMMENT '出参字段定义',
  `sort_order`      int          DEFAULT 0,
  `remark`          varchar(500) DEFAULT NULL,
  `create_by`       varchar(64)  DEFAULT '',
  `create_time`     datetime     DEFAULT CURRENT_TIMESTAMP,
  `update_by`       varchar(64)  DEFAULT '',
  `update_time`     datetime     DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_platform_id` (`platform_id`)
) COMMENT='平台接口定义';
```

**`request_schema` 字段 source 枚举：**
- `fixed` — 固定值（value 字段）
- `auth` — 从 `auth_config` 取（field 字段指定 key）
- `extra` — 从 `extra_config` 取（初始化后保存的 userId/projectId 等）
- `context` — 从流程上下文取（contextKey 指定，如 `step1.access_token`）
- `device` — 从设备绑定关系取（如 `platform_device_id`）
- `thingsModel` — 从设备物模型实时值取（identifier 字段）

### 3.3 `platform_flow` — 流程定义

```sql
CREATE TABLE `platform_flow` (
  `id`           bigint       NOT NULL AUTO_INCREMENT,
  `platform_id`  bigint       NOT NULL,
  `name`         varchar(100) NOT NULL,
  `code`         varchar(100) NOT NULL,
  `flow_type`    tinyint      NOT NULL COMMENT '流程类型(1=平台初始化,2=设备入网,3=Token刷新)',
  `sensor_type`  varchar(50)  DEFAULT NULL COMMENT '传感器类型，flow_type=2时有效',
  `enable`       char(1)      NOT NULL DEFAULT '1',
  `remark`       varchar(500) DEFAULT NULL,
  `create_by`    varchar(64)  DEFAULT '',
  `create_time`  datetime     DEFAULT CURRENT_TIMESTAMP,
  `update_by`    varchar(64)  DEFAULT '',
  `update_time`  datetime     DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_platform_type` (`platform_id`, `flow_type`)
) COMMENT='平台对接流程';
```

**flow_type 说明：**
- `1` 平台初始化：手动触发，获取 userId/projectId 等基础数据
- `2` 设备入网：手动触发，创建测点+绑定传感器，获得 DCP deviceId
- `3` Token 刷新：系统自动触发，不在 UI 中手动执行

### 3.4 `platform_flow_step` — 流程步骤

```sql
CREATE TABLE `platform_flow_step` (
  `id`            bigint NOT NULL AUTO_INCREMENT,
  `flow_id`       bigint NOT NULL,
  `step_order`    int    NOT NULL DEFAULT 1 COMMENT '执行顺序，从1开始',
  `interface_id`  bigint NOT NULL COMMENT '关联接口',
  `param_mapping` json   DEFAULT NULL COMMENT '入参来源覆盖配置',
  `result_key`    varchar(100) DEFAULT NULL COMMENT '出参写入上下文的key，如 step1',
  `result_save`   json   DEFAULT NULL COMMENT '需持久化的出参字段 [{field,saveTo}]',
  `remark`        varchar(255) DEFAULT NULL,
  PRIMARY KEY (`id`),
  KEY `idx_flow_id` (`flow_id`)
) COMMENT='流程步骤';
```

**`result_save` 示例：** 初始化流程 Step2 获取 userId 后自动保存
```json
[
  {"field": "id", "saveTo": "extra_config.userId"}
]
```

### 3.5 `platform_device_mapping` — 设备绑定

```sql
CREATE TABLE `platform_device_mapping` (
  `id`                  bigint       NOT NULL AUTO_INCREMENT,
  `platform_id`         bigint       NOT NULL,
  `device_id`           bigint       NOT NULL COMMENT 'FastBee设备ID',
  `serial_number`       varchar(64)  NOT NULL COMMENT 'FastBee设备序列号',
  `platform_device_id`  varchar(100) DEFAULT NULL COMMENT 'DCP侧deviceId，入网后自动回填',
  `platform_point_id`   varchar(100) DEFAULT NULL COMMENT 'DCP侧pointId',
  `sensor_type`         varchar(50)  NOT NULL COMMENT '传感器类型: inclino/stress/hyeto/static_level',
  `field_mapping`       json         DEFAULT NULL COMMENT '字段映射 [{identifier,platformField,transform}]',
  `net_status`          tinyint      NOT NULL DEFAULT 0 COMMENT '入网状态(0=未入网,1=已入网)',
  `enable`              char(1)      NOT NULL DEFAULT '1',
  `remark`              varchar(255) DEFAULT NULL,
  `create_by`           varchar(64)  DEFAULT '',
  `create_time`         datetime     DEFAULT CURRENT_TIMESTAMP,
  `update_by`           varchar(64)  DEFAULT '',
  `update_time`         datetime     DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_serial` (`serial_number`),
  KEY `idx_platform_device` (`platform_id`, `device_id`)
) COMMENT='平台设备绑定关系';
```

### 3.6 `platform_push_log` — 推送日志

```sql
CREATE TABLE `platform_push_log` (
  `id`               bigint        NOT NULL AUTO_INCREMENT,
  `platform_id`      bigint        NOT NULL,
  `flow_id`          bigint        DEFAULT NULL,
  `step_order`       int           DEFAULT NULL,
  `device_id`        bigint        DEFAULT NULL,
  `serial_number`    varchar(64)   DEFAULT NULL,
  `interface_code`   varchar(100)  DEFAULT NULL,
  `request_url`      varchar(500)  DEFAULT NULL,
  `request_body`     mediumtext    DEFAULT NULL,
  `response_code`    int           DEFAULT NULL,
  `response_body`    mediumtext    DEFAULT NULL,
  `status`           tinyint       NOT NULL DEFAULT 0 COMMENT '0=进行中,1=成功,2=失败',
  `error_msg`        varchar(1000) DEFAULT NULL,
  `idempotency_key`  varchar(100)  DEFAULT NULL COMMENT '幂等键',
  `retry_count`      int           NOT NULL DEFAULT 0,
  `cost_ms`          int           DEFAULT NULL,
  `create_time`      datetime      DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_platform_status` (`platform_id`, `status`),
  KEY `idx_device_time`     (`device_id`, `create_time`)
) COMMENT='平台推送日志';
```

---

## 4. 后端代码结构

```
fastbee-service/fastbee-iot-service/
└── com.fastbee.iot.platform/
    ├── domain/                          # 6个实体类
    ├── mapper/                          # MyBatis-Plus Mapper
    ├── service/
    │   ├── IPlatformInstanceService
    │   ├── IPlatformFlowService         # 含手动触发、流程执行
    │   ├── IPlatformDeviceMappingService
    │   ├── IPlatformPushLogService
    │   └── impl/
    ├── flow/
    │   ├── PlatformFlowExecutor         # 核心流程执行引擎
    │   └── FlowContext                  # 步骤间传递的上下文
    ├── adapter/
    │   ├── AbstractPlatformAdapter      # Token管理、HTTP调用、日志
    │   └── dcp/
    │       ├── DcpPlatformAdapter       # DCP实现
    │       └── strategy/
    │           ├── DcpSensorStrategy    # 接口
    │           ├── InclinoStrategy      # 倾角
    │           ├── StressStrategy       # 轴力计（递增约束）
    │           ├── HyetoStrategy        # 雨量计（递增约束）
    │           └── StaticLevelStrategy  # 静力水准
    └── trigger/
        ├── DeviceReportTrigger          # 挂接 RuleProcess event=1
        └── ScheduledPushJob             # Quartz 定时批量推送

fastbee-open-api/
└── com.fastbee.controller.platform/
    ├── PlatformInstanceController       # /platform/instance
    ├── PlatformInterfaceController      # /platform/interface
    ├── PlatformFlowController           # /platform/flow（含手动触发）
    ├── PlatformDeviceMappingController  # /platform/device-mapping（含入网）
    └── PlatformPushLogController        # /platform/push-log
```

---

## 5. 核心逻辑

### 5.1 流程执行引擎（PlatformFlowExecutor）

```
FlowContext ctx = new FlowContext(platformInstance, deviceMapping?)

for each step (ordered by step_order):
  1. 按 request_schema + param_mapping 解析入参
     - fixed: 直接取 value
     - auth:  从 auth_config JSON 取
     - extra: 从 extra_config JSON 取（userId/projectId）
     - context: 从 ctx.get(contextKey) 取（上一步出参）
     - device: 从 deviceMapping 取（platform_device_id 等）
  2. 替换 path 变量，如 /project/by-user-id/{userId}
  3. 检查 Token，过期则先刷新
  4. HttpClientFactory.instance(config).executeAsString()
  5. 将出参写入 ctx（key = step.resultKey）
  6. 按 result_save 将指定字段持久化到 platform_instance 或 platform_device_mapping
  7. 异步写 platform_push_log
```

### 5.2 Token 自动刷新（AbstractPlatformAdapter）

```
before any HTTP call:
  if token is null OR now > token_expires_at - 5min:
    find flow where flow_type=3 for this platform
    execute flow → get new access_token + expires_in
    update platform_instance.access_token + token_expires_at
  inject "Authorization: Bearer {token}" into request headers
```

### 5.3 实时推送（DeviceReportTrigger）

```
// 挂接在 RuleProcess.processRuleScript() 调用方之后，异步执行
List<PlatformDeviceMapping> mappings = findBySerialNumber(serialNumber)
for each mapping where enable=1 and net_status=1:
  adapter = getAdapter(mapping.platformId)   // 按 platform.code 路由
  adapter.pushData(mapping, payload)
  // pushData 内部：字段映射转换 → Token检查 → HTTP调用 → 写日志
```

### 5.4 DCP 传感器推送策略

| sensor_type | 推送接口 | 关键字段 | 特殊约束 |
|---|---|---|---|
| inclino | POST /api/app/inclino-data/many | xDeg, yDeg, temperature, epoch | 无 |
| stress | POST /api/app/stress-data/many | e, epoch | e 必须严格递增 |
| hyeto | POST /api/app/hyeto-data/many | value, epoch | value 必须严格递增 |
| static_level | POST /api/app/static-level-data/many | sensorData[{height,sensorId,epoch}] | 需两个 sensorId |

递增约束处理：推送前查询 `platform_push_log` 中上次成功推送的值，若当前值 ≤ 上次值则跳过并记录警告。

---

## 6. 前端页面（yack-web）

菜单：**系统管理 → 平台对接**

### 平台管理
- 列表：名称、标识、baseURL、Token状态（有效/过期/未认证）、初始化状态、启用
- 操作：新增/编辑、**初始化**（执行 flow_type=1 流程）、启用/禁用

### 流程编排
- 顶部选择平台，列表展示该平台所有流程
- 编辑页：步骤列表（可排序），每步选择接口 + 配置字段映射
  - 字段来源下拉：固定值 / 认证配置 / 上下文（下拉展示前序步骤出参）/ 平台已保存数据
- 操作：保存、**手动执行**（展示实时执行日志）

### 设备绑定
- 顶部选择平台，列表展示绑定关系
- 列表关联展示：设备名称（非ID）、入网状态标签
- 新增弹窗：
  - 设备搜索选择器（输入名称/序列号模糊搜索）
  - 传感器类型下拉
  - 字段映射：物模型字段下拉（自动加载该设备产品的物模型）+ DCP字段（根据传感器类型预填建议值）
- 操作：**入网**（执行 flow_type=2 流程，成功后自动回填 DCP deviceId）、启用/禁用

### 推送日志
- 筛选：平台、设备（搜索选择）、状态、时间范围
- 列表：时间、平台、设备名称、接口、状态标签、耗时
- 详情弹窗：请求URL/Body、响应码/Body（JSON格式化）、错误信息

---

## 7. DCP 内置初始化数据

系统内置 DCP 平台的接口定义和流程配置（SQL 初始化数据），用户只需填入账号密码即可使用。

**内置接口（6个）：**
1. `dcp_auth` — POST /connect/token
2. `dcp_get_user` — GET /api/app/user/user-id
3. `dcp_get_projects` — GET /api/app/project/by-user-id/{userId}
4. `dcp_create_point` — POST /api/app/point
5. `dcp_bind_inclino` — POST /api/app/inclino-sensor
6. `dcp_bind_stress` — POST /api/app/stress-sensor
7. `dcp_bind_hyeto` — POST /api/app/hyeto-sensor
8. `dcp_bind_static_level` — POST /api/app/static-level-device

**内置流程（5个）：**
1. `dcp_init`（flow_type=1）：Step1=dcp_auth → Step2=dcp_get_user → Step3=dcp_get_projects
2. `dcp_token_refresh`（flow_type=3）：Step1=dcp_auth
3. `dcp_onboard_inclino`（flow_type=2, sensor_type=inclino）：Step1=dcp_create_point → Step2=dcp_bind_inclino
4. `dcp_onboard_stress`（flow_type=2, sensor_type=stress）：Step1=dcp_create_point → Step2=dcp_bind_stress
5. `dcp_onboard_hyeto`（flow_type=2, sensor_type=hyeto）：Step1=dcp_create_point → Step2=dcp_bind_hyeto

---

## 8. 关键复用点

| 现有资产 | 位置 | 用途 |
|---|---|---|
| `HttpClientFactory` | `fastbee-plugs/fastbee-http` | 发起 HTTP 请求 |
| `HttpClientConfig` | `fastbee-plugs/fastbee-http` | 请求配置 DTO |
| `RuleProcess` | `fastbee-iot-service` | 设备上报触发挂接点（event=1） |
| `sys_job` / Quartz | `fastbee-plugs/quartz` | 定时批量推送 Job |
| `iot_device_log` | DB | 批量推送数据来源 |
| `iot_things_model` | DB | 设备绑定页面物模型字段下拉 |
| MyBatis-Plus ServiceImpl | 已有 | 所有 Service 基类 |