主用例说明：插件间通信

背景概述

在 PowerX 生态中，插件不仅与宿主交互，还需要与其他插件协同完成业务闭环，例如数据同步、事件联动、跨模块自动化。 缺乏标准化的通信机制会导致协议不一致、租户数据越权、链路难以追踪以及问题定位困难。本主用例聚焦“插件间通信”场景， 阐明如何在受治理的基础设施上实现插件之间的事件、消息与数据交换，使跨团队开发的插件能够可靠协作。

目标与价值

• 统一通信协议：提供事件、消息与 API 网关的统一抽象，减少多种协议互转带来的复杂度。
• 租户级隔离：确保跨插件通信严格遵守租户与权限边界，防止数据泄露或串租。
• 高可靠低延迟：建设高可用消息通道、重放与补偿机制，保障联动链路的稳定性。
• 可观测与可审计：提供 trace、metrics、audit 统一视角，定位跨插件链路的性能与异常。

参与角色

• 事件总线 / 消息路由服务：承载插件间的事件分发、Topic 隔离、权限校验与重试队列。
• 通信编排服务（Integration Hub）：管理订阅关系、Schema、转换规则与回放策略。
• 插件 A / B 运行时：发布或消费消息、事件、数据流，并执行业务逻辑。
• 租户与权限服务：判定跨插件通信是否符合租户授权与最小权限策略。
• SRE / 运维人员：监控插件链路指标、处理死信队列并调优容量。

主场景 User Story

作为 平台集成架构师，我希望 插件间能通过受控的事件与消息通道完成双向通信，从而 在保持安全与可观测的前提下实现跨插件业务协同。

子场景详解

子场景 A：通信通道注册与拓扑编排

• 角色与触发：插件团队申请订阅其他插件暴露的 Topic 或数据流。
• 主要流程：
  1. 插件在 Integration Hub 登记通信需求，选择事件类型、Topic、租户范围。
  2. 平台根据 Schema 兼容性与租户策略进行审批，生成连接配置。
  3. Hub 创建或绑定专属 Topic / 队列，并下发访问凭证。
  4. 插件按照配置接入通道并执行联调。
• 成功标准：Topic/队列命名统一；Schema 校验通过；拓扑图可视化。
• 异常与风控：Schema 不兼容时阻断并提供转换建议；订阅数量超限触发配额预警；未经审批的直连请求一律拒绝。
• 指标建议：注册审批时长、Schema 校验失败率、Topic 利用率。

子场景 B：事件联动与幂等治理

• 角色与触发：插件 A 发布事件，插件 B 需要稳定消费并执行动作。
• 主要流程：
  1. 插件 A 按约定 Schema 发布事件并附带租户、Trace ID。
  2. 事件总线执行鉴权、幂等 ID 校验与持久化。
  3. 插件 B 通过消费组拉取事件并记录偏移量。
  4. 插件 B 完成业务处理后反馈处理状态（成功 / 失败 / 重试）。
• 成功标准：事件至少一次送达，重复消费被幂等逻辑过滤，处理成功率 ≥99%。
• 异常与风控：消费超时进入重试；连续失败事件进入死信队列；幂等冲突触发审计告警。
• 指标建议：事件吞吐、重复消费率、死信队列长度、端到端延迟。

子场景 C：共享 Topic 的访问控制

• 角色与触发：多个业务插件需要共享同一 Topic 进行数据同步。
• 主要流程：
  1. Integration Hub 为共享 Topic 配置租户隔离策略与访问 ACL。
  2. 插件接入时使用 SASL/OAuth2 等凭证完成鉴权。
  3. 平台根据租户策略对消息进行过滤或脱敏。
  4. 消费端根据标签决定处理或丢弃非授权消息。
• 成功标准：未授权插件无法消费；敏感字段按策略脱敏；Topic 利用率受控。
• 异常与风控：访问失败返回 403 并记录；脱敏策略缺失时阻断投递；Topic 消费积压触发扩容策略。
• 指标建议：ACL 拒绝次数、脱敏命中率、共享 Topic 吞吐量。

子场景 D：数据流插件到分析插件的链路监控

• 角色与触发：数据流插件清洗数据后需要推送至报表插件进行实时分析。
• 主要流程：
  1. 数据流插件将结果写入实时流或批处理通道，附带 Schema 版本。
  2. 报表插件读取数据并进行格式转换或聚合。
  3. Integration Hub 记录链路 trace 并生成 SLA 指标仪表盘。
  4. 当分析插件返回异常结果时，触发回滚或补偿任务。
• 成功标准：链路延迟 <5s（实时）或 <15min（批处理）；Trace 可关联整个处理链；异常数据可回放。
• 异常与风控：Schema 版本不兼容时触发灰度回滚；聚合失败进入补偿任务；链路延迟超阈值触发告警。
• 指标建议：端到端延迟、回放次数、补偿任务成功率。

功能边界 & 非目标场景

• 不覆盖插件对宿主的直接调用，请参考“宿主调用插件”与“插件调用宿主”主用例。
• 不讨论插件对外部第三方系统的集成方案，相关内容属于外部集成指南。
• 不涉及插件内部业务逻辑和数据建模，仅关注通信层治理与平台能力。

依赖与接口

• Integration Hub / EventBus API：提供 Topic 管理、Schema 校验、消费组配置与监控接口。
• 租户策略服务：提供租户授权、ACL、字段级脱敏策略。
• 插件 SDK / 连接器：支持 gRPC、WebSocket、Kafka、MCP 等协议的标准封装。
• 监控与审计平台：提供链路追踪、指标告警、日志审计与回放工具。

验收要点

1. 插件间通信需通过官方通道登记与审批，自动生成拓扑与配置文档。
2. 事件与消息链路具备租户隔离、鉴权与幂等控制，未经授权的访问会被阻断并告警。
3. 共享 Topic 支持字段脱敏、过滤与配额管理，防止串租与资源滥用。
4. 构建端到端可观测体系，包含 Trace、Metrics、日志与死信回放能力。
5. 提供沙箱演练脚本与测试工具，支持事件重放、延迟注入、故障模拟等场景。

场景级测试用例示例

测试准备：在沙箱中部署 etl-cleaner@1.4.0（插件 A）与 insight-reporter@2.1.0（插件 B）， 通过 Integration Hub 注册 Topic tenant-enterprise.analytics.stream，配置授权租户 tenant-enterprise， 启用 Schema 校验与死信队列 dlq.analytics。

用例 A-1：通道注册成功（正向）

• 前置条件：插件提交的 Schema 与租户策略均通过审批。
• 操作步骤：
  1. 在 Hub 中提交订阅申请并等待审批完成。
  2. 按照下发配置接入 Topic 并发送测试消息。
• 预期结果：
  • 消息成功送达，Topic 可在拓扑图中显示新的订阅关系。
  • Audit 日志记录审批流程与配置详情。

用例 A-2：Schema 校验失败（逆向）

• 前置条件：插件上传的 Schema 缺少必填字段。
• 操作步骤：
  1. 再次提交订阅申请。
• 预期结果：
  • Hub 返回 422 错误并指出缺失字段。
  • 审批被拒，未生成任何 Topic 凭证。

用例 B-1：事件消费幂等（正向）

• 前置条件：插件 B 启用幂等键 event_id。
• 操作步骤：
  1. 插件 A 连续发送两次相同的事件 ID。
• 预期结果：
  • 插件 B 仅执行一次业务逻辑，第二次记录为重复并忽略。
  • 监控面板显示重复过滤次数。

用例 B-2：死信队列回放（逆向）

• 前置条件：模拟插件 B 连续 3 次处理失败。
• 操作步骤：
  1. 触发错误事件并观察进入死信队列。
  2. 在 Hub 中执行死信回放。
• 预期结果：
  • 死信队列生成对应记录，回放后事件重新投递并成功处理。
  • 运维面板记录回放操作与结果。

用例 C-1：共享 Topic 权限控制（逆向）

• 前置条件：未授权插件 unauthorized-bot 尝试订阅同一 Topic。
• 操作步骤：
  1. 使用错误凭证连接 Topic。
• 预期结果：
  • 连接被拒绝并返回 403，审计触发告警。
  • Topic 不产生未授权消费记录。

用例 D-1：端到端链路监控（正向）

• 前置条件：链路监控已开启。
• 操作步骤：
  1. 插件 A 推送 100 条数据，插件 B 执行分析。
• 预期结果：
  • 仪表盘展示端到端延迟、吞吐与成功率。
  • Trace 链路可追踪每条消息从发布到消费的全过程。

用例 D-2：延迟注入告警（逆向）

• 前置条件：在沙箱中注入 10s 延迟。
• 操作步骤：
  1. 再次触发数据流。
• 预期结果：
  • 延迟超过阈值后触发告警并记录根因分析。
  • 插件自动切换为批处理模式或触发补偿任务。