主用例说明：插件调用宿主

背景概述

在 PowerX 插件生态中，插件既提供独立能力，也需要调用宿主平台的数据、流程与安全能力，例如拉取租户配置、写入业务事件或触发工作流。 如果缺乏标准化的调用治理，常见风险包括鉴权绕过、接口耦合、租户隔离失效以及调用失败后的缺乏补偿。本主用例聚焦“插件调用宿主” 的端到端路径，明确插件如何通过受控的通道访问宿主服务，确保跨团队开发的插件能够安全、可观测、可扩展地复用平台能力。

目标与价值

• 统一调用通道：提供 SDK / API Gateway 规范，降低插件调用宿主接口的碎片化实现。
• 租户安全隔离：保证插件在调用宿主时仅能访问授权租户的数据域，并支持最小权限控制。
• 稳定可观测：建设调用指标、日志追踪与故障告警能力，便于定位问题与快速恢复。
• 弹性与扩展：支持同步与异步场景、批量写入与长连接通知，满足多样化业务需求。

参与角色

• 插件运行时（Runtime / Agent）：发起对宿主的 API 或事件调用，负责处理重试与回退。
• 宿主开放平台 Gateway：统一暴露宿主 API、进行鉴权、限流、协议转换和审计。
• 租户策略 / IAM 服务：判定插件所属租户的访问范围与权限。
• 宿主业务服务 / 数据服务：提供被调用的业务接口、配置中心、事件总线等能力。
• SRE / 平台运维：监控调用链路、排查异常并维护 SLA。

主场景 User Story

作为 PowerX 插件开发者，我希望 插件能够通过规范化的接口安全地调用宿主服务，从而 复用平台能力并为客户交付稳定可靠的扩展功能。

子场景详解

子场景 A：调用通道注册与鉴权

• 角色与触发：插件上线后需调用宿主提供的 API / Event 接口。
• 主要流程：
  1. 插件在开放平台登记调用意图，生成 client_id、密钥或签名证书。
  2. 插件运行时通过 SDK 获取短期访问令牌（OAuth2 Client Credentials / JWT）。
  3. 调用请求经过 Gateway 执行身份校验、租户授权与限流策略。
  4. Gateway 记录审计日志并将请求转发至目标宿主服务。
• 成功标准：调用延迟稳定 <80ms；鉴权通过率 ≥99%；审计日志包含租户、插件、请求 ID。
• 异常与风控：密钥泄露需支持吊销与轮换；超出限流阈值时返回 429；未授权租户访问返回 403 并告警。
• 指标建议：认证失败率、限流触发次数、令牌刷新成功率。

子场景 B：上下文传递与数据治理

• 角色与触发：插件在调用宿主时需要携带租户、用户及会话上下文。
• 主要流程：
  1. 插件在调用前从宿主下发的上下文缓存中读取租户 ID、用户角色、链路追踪 ID。
  2. 调用中通过标准 Header（如 x-tenant-id、x-trace-id）或签名 Payload 传递。
  3. 宿主服务依据上下文进行字段级访问控制与脱敏处理。
  4. 调用完成后插件根据宿主返回的审计信息更新本地状态。
• 成功标准：上下文字段完整无丢失；敏感字段访问均受策略控制；数据读写遵守最小权限。
• 异常与风控：上下文校验失败返回 400 并提示重新同步；脱敏策略缺失触发审计告警；跨租户数据访问一律阻断。
• 指标建议：上下文校验失败次数、跨租户拒绝数、字段脱敏命中率。

子场景 C：调用韧性与回退策略

• 角色与触发：宿主接口出现超时、限流或内部错误。
• 主要流程：
  1. 插件根据接口 SLA 设置超时阈值与断路策略。
  2. 当调用失败时，插件按指数退避策略自动重试并记录指标。
  3. 重试仍失败时触发降级逻辑（缓存响应、延迟队列补偿或人工任务）。
  4. 插件将失败事件上报监控平台，SRE 根据告警处理。
• 成功标准：自动重试成功率 ≥85%；熔断触发后可在设定窗口自动恢复；降级流程可追踪。
• 异常与风控：防止无限重试造成雪崩；降级响应需标记为非正式结果；监控告警需关联租户与插件维度。
• 指标建议：平均响应时间、重试次数、熔断触发量、MTTR。

子场景 D：异步事件与回调处理

• 角色与触发：插件需向宿主事件总线推送消息或订阅宿主回调。
• 主要流程：
  1. 插件将事件发布至宿主 EventBus / Webhook，附带签名与租户上下文。
  2. 宿主对事件进行幂等校验、持久化与投递。
  3. 对于宿主发出的回调，插件通过回调端点接收并确认处理。
  4. 失败事件进入重试队列或死信队列，供运维排查。
• 成功标准：事件至少一次投递成功；回调确认时间 <3s；死信队列可查询。
• 异常与风控：重复事件需通过幂等 ID 去重；回调接口需校验签名；死信队列积压达到阈值触发扩容。
• 指标建议：事件吞吐量、死信率、回调成功率。

功能边界 & 非目标场景

• 不覆盖插件能力注册、审批流程，相关内容见“插件能力注册与暴露”主用例。
• 不讨论插件内部业务实现与调试方法，可参照“插件开发与调试”主用例。
• 宿主主动调用插件的链路属于“宿主调用插件”主用例，此处仅关注插件侧发起调用。
• 插件与第三方系统的直连集成不在本主用例范围，应参考外部系统集成指南。

依赖与接口

• 开放平台鉴权服务：提供 OAuth2 / JWT 签发、密钥轮换与令牌校验接口。
• 租户策略 / IAM API：返回租户授权范围、字段级权限、限流策略。
• 宿主业务服务 API：提供标准 REST/gRPC/MCP 接口与字段脱敏配置。
• 事件总线 / Webhook 管理中心：负责事件发布、订阅、重试与死信治理。
• 监控与日志平台：采集调用指标、追踪日志并触发告警。

验收要点

1. 插件可通过统一 SDK / Gateway 完成鉴权与调用，支持密钥轮换与令牌刷新。
2. 调用全链路具备租户级隔离与上下文传递，未授权访问被拦截并记录审计。
3. 建立完善的可观测与恢复机制，支持重试、熔断、降级及异常事件上报。
4. 支持同步与异步两类调用模式，异步事件具备幂等、死信处理与回调确认。
5. 提供沙箱环境与测试工具，便于插件开发者验证调用路径与安全策略。

场景级测试用例示例

测试准备：在沙箱环境部署插件 analytics-sync@3.0.0，配置开放平台凭据与租户 tenant-enterprise（授权）及 tenant-guest（未授权）。 启用宿主 API POST /api/v1/metrics/upload、事件总线 events://tenant/*，并在监控平台开启调用追踪。

用例 A-1：凭据鉴权成功（正向）

• 前置条件：插件正确配置 client_id 与密钥，可获取有效访问令牌。
• 操作步骤：
  1. 插件通过 SDK 获取访问令牌并调用上传接口。
• 预期结果：
  • 返回 200，响应体包含处理结果 ID。
  • 审计日志记录插件标识、租户、Trace ID。

用例 A-2：凭据过期（逆向）

• 前置条件：模拟令牌过期或密钥被吊销。
• 操作步骤：
  1. 插件携带过期令牌发起调用。
• 预期结果：
  • Gateway 返回 401 并提示刷新；监控触发安全告警。
  • 插件触发自动刷新逻辑并在 60s 内恢复成功调用。

用例 B-1：上下文缺失阻断（逆向）

• 前置条件：插件故意省略 x-tenant-id Header。
• 操作步骤：
  1. 再次调用宿主 API。
• 预期结果：
  • 宿主返回 400，提示缺少租户上下文。
  • 审计日志记录失败原因，开发者可定位问题。

用例 B-2：字段脱敏验证（正向）

• 前置条件：租户策略要求屏蔽 PII 字段。
• 操作步骤：
  1. 插件上传包含 PII 字段的数据集。
• 预期结果：
  • 宿主响应成功，但返回结果中的 PII 字段已脱敏。
  • 审计面板显示字段级策略命中一次。

用例 C-1：自动重试成功（正向）

• 前置条件：宿主 API 第一次调用返回 500，第二次恢复正常。
• 操作步骤：
  1. 触发接口调用并观察重试策略。
• 预期结果：
  • 插件在 300ms 后重试成功，记录一次重试事件。
  • 监控图表显示失败与成功请求的分布。

用例 C-2：熔断与降级（逆向）

• 前置条件：连续 5 次调用返回 503，熔断阈值设为 3 次失败/60s。
• 操作步骤：
  1. 连续触发失败调用。
• 预期结果：
  • 第 3 次后开启熔断，插件返回降级结果并提示稍后重试。
  • 熔断状态在 2 分钟内自动恢复，监控告警通知 SRE。

用例 D-1：事件发布成功（正向）

• 前置条件：插件具备事件发布权限，宿主 EventBus 正常运行。
• 操作步骤：
  1. 插件发布事件 events://tenant-enterprise/metrics.completed。
• 预期结果：
  • EventBus 返回确认 ID，宿主消费成功并回调通知。
  • Trace 链路可见发布与消费的完整流程。

用例 D-2：回调签名失败（逆向）

• 前置条件：回调端点故意使用错误签名密钥。
• 操作步骤：
  1. 宿主向插件回调处理结果。
• 预期结果：
  • 插件拒绝回调并记录告警，宿主重试至死信队列。
  • SRE 可在死信面板查看详细失败原因并发起人工补偿。