From a439081ed1c4f87437c790a96e2e519205a6743e Mon Sep 17 00:00:00 2001 From: zhugongping Date: Sat, 30 May 2026 12:57:08 +0800 Subject: [PATCH] =?UTF-8?q?20260529:=E5=B9=B3=E5=8F=B0=E5=AF=B9=E6=8E=A5?= =?UTF-8?q?=E5=88=9D=E7=89=88=E5=AE=9E=E7=8E=B02?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/settings.local.json | 5 +- .../06-platform-integration-design.md | 206 +++++++----------- 2 files changed, 77 insertions(+), 134 deletions(-) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 9a8e9dae..3bac7b62 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -2,7 +2,10 @@ "permissions": { "allow": [ "Bash(python3 -c \"import pdfplumber; pdf = pdfplumber.open\\('D:/SoftProject/Java/fastbee/docs/platform/DCP接口文档\\(轴力计\\).pdf'\\); [print\\(p.extract_text\\(\\)\\) for p in pdf.pages[:15]]; pdf.close\\(\\)\")", - "Bash(mvn compile *)" + "Bash(mvn compile *)", + "mcp__filesystem__list_directory", + "Bash(mysql:*)", + "Bash(ls -d /Users/admin/IdeaProjects/fastbee/fastbee-service/fastbee-iot-service/src/main/java/com/fastbee/iot/*/)" ] } } diff --git a/docs/knowledge-base/06-platform-integration-design.md b/docs/knowledge-base/06-platform-integration-design.md index 56e2ab13..47276e07 100644 --- a/docs/knowledge-base/06-platform-integration-design.md +++ b/docs/knowledge-base/06-platform-integration-design.md @@ -211,27 +211,30 @@ Quartz / 手动触发 ## 6. 前端功能设计 -一级菜单：**平台对接**。 - -建议菜单： +一级菜单：**平台对接**，只有 3 个子菜单。 ```text 平台对接 - 平台模板 - 接口配置 - 流程编排 - 租户接入 - 资源映射 - 设备绑定 - 数据交换任务 - 数据交换记录 + 平台管理 ← 平台模板 + 接口 + 流程 + 租户接入，全部内嵌 + 设备接入 ← 设备绑定 + 字段映射 + 交换任务，向导式操作 + 交换记录 ← 数据交换记录 + 尝试日志 + 重试 ``` -### 6.1 平台模板 +资源映射不单独作为菜单，在设备接入页面的绑定详情中内嵌查看。 -平台模板是系统级可复用配置。 +### 6.1 平台管理 -主要字段： +平台管理页面采用左右布局：左侧是平台列表，右侧是选中平台的详情，通过 Tab 切换。 + +**左侧：平台列表** + +- 展示所有平台模板（DCP、通用 HTTP 等）。 +- 每行显示平台名称、类型、适配器、启用状态。 +- 支持新增平台模板。 + +**右侧 Tab 1：基本信息** + +平台模板主要字段： | 字段 | 说明 | | ------ | ----------------------------------------- | @@ -244,84 +247,39 @@ Quartz / 手动触发 | 默认请求配置 | 超时、重试、Content-Type 等。 | | 启用状态 | 启用、停用。 | -### 6.2 接口配置 +**右侧 Tab 2：接口列表** -接口配置属于平台模板，可被所有租户复用。 +接口属于平台模板，在此 Tab 内直接管理，不单独作为菜单。 -接口类型： +接口按类型分组展示，点击接口行展开查看/编辑接口字段： -| 类型 | 说明 | -| --------------- | ----------------------- | -| TOKEN | 获取或刷新 token。 | -| QUERY | 查询第三方基础数据，如用户、项目、设备、数据。 | -| RECEIVE | FastBee 接收入口定义。 | -| RESOURCE_CREATE | 创建外部资源，如测点、设备、传感器。 | -| RESOURCE_BIND | 绑定外部资源。 | -| PUSH | 推送设备数据。 | -| CALLBACK | 回调第三方处理结果，可选。 | +| 分组 | 接口类型 | 说明 | +| ------ | ------------------------------------- | ----------------------- | +| 认证接口 | TOKEN | 获取或刷新 token。 | +| 公共接口 | QUERY、RESOURCE_CREATE、RESOURCE_BIND | 查询用户/项目、创建/绑定资源等。 | +| 设备接口 | PUSH、CALLBACK | 按设备类型分组的数据推送接口。 | +| 接收入口 | RECEIVE | FastBee 被动接收第三方数据的入口定义。 | -配置项： +每个接口展开后显示：请求方法、URL 模板、Header/Query/Body 模板、成功条件、响应变量提取规则、重试策略，以及该接口的 REQUEST/RESPONSE 字段列表（可增删改）。 -- 请求方法：GET、POST、PUT、DELETE。 -- URL 模板：支持 `${变量}`。 -- Header、Query、Body 模板。 -- Content-Type。 -- 成功条件：HTTP 状态码、响应 JSONPath。 -- 响应变量提取：例如 `$.id -> pointId`。 -- 超时和重试策略。 -- RECEIVE 接口还需要配置入口路径、鉴权方式、签名规则、幂等 key 提取规则。 +接口字段用于设备接入时的字段映射，字段路径使用 JSONPath 或表单字段名。 -### 6.3 接口字段 +**右侧 Tab 3：流程配置** -接口字段用于页面展示和字段映射。 +流程属于平台模板，在此 Tab 内管理。 -| 字段 | 说明 | -| ---- | ----------------------------------- | -| 接口 | 所属接口。 | -| 方向 | REQUEST、RESPONSE。 | -| 字段路径 | JSONPath 或表单字段名。 | -| 字段名称 | 展示名称。 | -| 数据类型 | string、number、boolean、array、object。 | -| 是否必填 | 是否必填。 | -| 默认值 | 默认值。 | -| 示例值 | 示例值。 | +流程列表按类型展示（OUTBOUND_PUSH、INBOUND_PULL、INBOUND_RECEIVE、RESOURCE_SYNC），点击流程行展开步骤列表，支持拖拽排序步骤。 -### 6.4 流程编排 +步骤类型：API（引用接口）、ADAPTER（适配器方法）、CONDITION（条件判断）、TRANSFORM（数据转换）、SINK（写入业务落点）。 -流程属于平台模板，用于将多个接口和适配器方法组成可复用业务流程。 +**右侧 Tab 4：租户接入** -流程类型： - -| flow_type | 说明 | -| --------------- | --------------------- | -| OUTBOUND_PUSH | FastBee 推送数据到第三方。 | -| INBOUND_PULL | FastBee 从第三方拉取并消费数据。 | -| INBOUND_RECEIVE | FastBee 接收第三方提交并消费数据。 | -| RESOURCE_SYNC | 同步第三方用户、项目、设备、测点等资源。 | -| CALLBACK | 回调第三方处理结果，可选。 | - -流程步骤类型： - -| step_type | 说明 | -| --------- | ---------------- | -| API | 调用平台接口配置。 | -| ADAPTER | 调用专用适配器方法。 | -| CONDITION | 条件判断。 | -| TRANSFORM | 数据转换。 | -| SINK | 写入 FastBee 业务落点。 | - -流程模板可以被多个租户复用；步骤执行时使用当前租户的授权配置、项目映射、设备绑定、资源映射和字段映射。 - -### 6.5 租户接入 - -租户接入表示某个租户启用某个平台模板。 +租户接入表示当前租户启用该平台模板，在此 Tab 内配置，不单独作为菜单。 主要字段： | 字段 | 说明 | | ------- | -------------------------------- | -| 租户 | 当前租户。 | -| 平台模板 | 选择 DCP 等平台模板。 | | 实例名称 | 租户内展示名。 | | baseUrl | 可覆盖模板默认地址。 | | 授权配置 | 租户自己的账号、clientId、secret、token 等。 | @@ -330,90 +288,72 @@ Quartz / 手动触发 | 接收安全配置 | webhook token、签名密钥、IP 白名单等。 | | 启用状态 | 启用、停用。 | -租户接入配置完成后，该租户才能建立资源映射、设备绑定、交换任务和接收入口。 +租户接入配置完成后，才能在设备接入页面选择该平台实例。 -### 6.6 资源映射 +### 6.2 设备接入 -资源映射是平台对接的核心边界之一，表示 FastBee 本地对象和第三方对象的对应关系。 +设备接入页面是租户操作的核心入口，采用列表 + 抽屉向导的方式。 -常见资源类型： +**列表视图** -| resource_type | 说明 | -| ------------- | -------- | -| USER | 第三方用户。 | -| PROJECT | 第三方项目。 | -| DEVICE | 第三方设备。 | -| POINT | 第三方测点。 | -| SENSOR | 第三方传感器。 | -| MODULE | 第三方模块。 | -| VIRTUAL | 第三方虚拟资源。 | -| CUSTOM | 其他平台资源。 | +展示当前租户所有设备绑定，列显示：平台实例、设备类型、FastBee 设备名/编号、交换模式、状态、最近成功时间。 -资源映射必须带 `tenant_id` 和 `tenant_channel_id`。除平台模板定义外，第三方资源 id 不允许全局共享。 +支持按平台实例、设备类型、状态筛选。 -### 6.7 设备绑定 +操作列：编辑映射、启用/停用、初始化资源、查看资源映射、查看交换记录、解绑。 -设备绑定是租户级配置。 +**新增绑定：向导式抽屉（3步）** -绑定内容： +**第 1 步：选择平台与设备类型** -```text -租户平台实例 + FastBee 设备 + 平台流程 + 第三方用户/项目/资源 + 字段映射 + 交换模式 -``` +- 下拉选择平台实例（从当前租户已启用的租户接入中加载，不是写死的枚举）。 +- 选择平台实例后，动态加载该平台模板下的设备接口分组，作为设备类型选项（例如 DCP 加载后显示：雨量计、倾角仪、静力水准、轴力计）。 +- 设备类型对应平台模板中的 PUSH 接口分组，由平台模板定义，不在前端硬编码。 -绑定页面左侧使用现有 FastBee 产品、设备、物模型；右侧使用平台模板的接口字段和租户的第三方用户/项目/资源。 +**第 2 步：选择 FastBee 设备** -绑定支持：新增、修改、启用、停用、解绑、初始化资源、查看资源映射、查看交换记录。 +- 选择产品（下拉）。 +- 选择设备（从该产品下的设备列表选，支持搜索设备名/编号）。 +- 展示设备基本信息和物模型字段列表（供下一步参考）。 +- 可选：填写绑定级第三方用户 id、项目 id（留空则使用租户接入的默认值）。 -DCP 绑定规则： +**第 3 步：字段映射** -```text -FastBee 一个设备 = DCP 一个测点 = DCP 一个设备资源 -``` +左右分栏： -DCP 的 `pointId`、`dcpDeviceId`、sensor/module/virtual 等必须按租户设备绑定保存，不能平台级共享。 +- 左侧：FastBee 物模型字段列表（identifier、字段名、数据类型），以及系统字段（serialNumber、deviceName、reportTime）。 +- 右侧：第 1 步选定的设备接口的 REQUEST 字段列表（字段路径、字段名、是否必填）。 +- 中间：映射关系，每行对应一个目标字段，来源可选：物模型字段、系统字段、常量、资源映射（pointId 等）、JSONPath 表达式。 +- 支持从平台模板复制默认映射（如果平台模板预置了默认映射规则）。 -### 6.8 字段映射 +字段映射同时支持 OUTBOUND（FastBee → 第三方）和 INBOUND（第三方 → FastBee），通过方向 Tab 切换。 -字段映射按设备绑定维护，也可以支持从平台模板复制默认映射。 +**绑定详情：资源映射内嵌** -映射来源： +点击列表行的"查看资源映射"，在侧边抽屉中展示该绑定下的资源映射记录（USER、PROJECT、POINT、DEVICE、SENSOR 等），不单独作为菜单。 -| source_type | 说明 | -| ----------- | ------------------------------------------- | -| THING_MODEL | 物模型字段，例如 rainfall。 | -| SYSTEM | 系统字段，例如 serialNumber、deviceName、reportTime。 | -| CONSTANT | 常量。 | -| RESOURCE | 外部资源映射，例如 pointId、dcpDeviceId。 | -| JSONPATH | 从 rawPayload 或第三方响应中取值。 | -| EXPRESSION | 受限表达式，后续增强。 | +**交换任务** -字段映射同时服务 OUTBOUND 和 INBOUND： +在设备接入列表页顶部提供"交换任务"入口（或作为 Tab），管理当前租户的定时推送、主动拉取、资源同步任务。 -- OUTBOUND：FastBee 内部字段映射到第三方字段。 -- INBOUND：第三方字段映射到 FastBee 标准消息或业务落点字段。 +任务配置：选择平台实例、选择流程、设置 Cron 表达式、时间窗口类型、批次大小、最大重试次数。 -表达式必须受限，不能执行任意代码。 +任务与绑定的关联在任务详情中配置（选择哪些设备绑定参与该任务）。 -### 6.9 数据交换任务与记录 +### 6.3 交换记录 -数据交换任务是租户级配置。 +交换记录是运维监控视图，展示所有数据交换的执行状态。 -任务类型： +筛选条件：平台实例、方向（OUTBOUND_PUSH/INBOUND_PULL/INBOUND_RECEIVE）、设备编号、状态、时间范围。 -| task_type | 说明 | -| ------------- | ----------------------- | -| OUTBOUND_PUSH | 定时推送或补推 FastBee 数据到第三方。 | -| INBOUND_PULL | 定时拉取第三方数据并消费。 | -| RESOURCE_SYNC | 定时同步第三方用户、项目、设备、测点等资源。 | +列表列：方向、平台实例、设备名/编号、数据时间、状态、重试次数、最近错误、创建时间。 -INBOUND_RECEIVE 一般不依赖定时任务，而是通过接收入口触发；如果接收后异步处理，也会生成交换记录。 +操作： -数据交换记录展示业务层面的交换状态： - -- 按租户、平台、方向、流程、设备、状态、时间筛选。 -- 查看原始输入、标准消息、最终 payload、幂等 key、请求响应、错误信息。 -- 失败重试、批量重试、成功记录强制重放。 +- 点击行展开查看：原始输入、标准消息、最终 payload、幂等 key、请求响应详情、错误信息。 +- 失败记录：单条重试、批量重试。 +- 成功记录：强制重放（新建 REPLAY 记录，幂等 key 追加批次号）。 +- 点击"尝试日志"查看每次请求的 URL、请求头（脱敏）、请求体、响应状态、响应内容、耗时。 ## 7. 标准数据模型