主用例说明：插件能力注册与暴露

背景概述

PowerX 平台鼓励生态伙伴通过插件扩展行业能力，但若缺乏标准化的能力注册与暴露流程，往往会出现能力命名混乱、权限不可控、宿主无法统一编排等问题。本主用例围绕“插件能力注册与暴露”，梳理从能力建模、权限审核、对外交付到生命周期维护的全流程，确保能力以安全、可治理的方式被宿主和其他插件消费。

目标与价值

• 结构化能力目录：沉淀统一的能力模型与元数据，便于检索、对齐命名与治理策略。
• 安全可控的暴露链路：在对外开放前完成权限、数据、合规校验，避免越权调用。
• 多通道消费体验：支持宿主工作流、API、Webhook、GraphQL/SDK 等多种方式消费插件能力。
• 可观测的能力生命周期：能力变更、下线均可追踪并通知订阅方，降低业务影响。

参与角色

• 插件开发者 / Vendor：登记能力元数据、编写说明文档与测试、提交审核。
• 平台能力注册服务：提供能力模型、审核流程、暴露配置与订阅通知。
• 安全与合规团队：对敏感数据、权限范围、合规条款进行审批。
• 宿主产品经理 / 业务管理员：选择需要接入的能力，配置消费方式与授权范围。
• 其他插件 / 第三方集成者：通过 API / SDK 调用已暴露的能力。

主场景 User Story

作为 插件开发者，我希望 在平台中注册并安全暴露插件能力，从而 让宿主与第三方能够标准化发现、调用并追踪这些能力的使用情况。

子场景详解

子场景 A：能力建模与注册提交流程

• 角色与触发：插件开发者完成能力开发后，准备在平台注册能力。
• 主要流程：
  1. 开发者在插件控制台选择“能力注册”，填写能力名称、描述、使用场景、输入输出 Schema、授权范围等元数据。
  2. 上传示例请求/响应、错误码定义以及体验 Demo 链接。
  3. 系统执行自动校验（命名规范、字段冲突、Schema 合法性）并给出修订建议。
  4. 注册申请进入待审核状态，系统生成唯一能力 ID 并记录版本。
• 成功标准：元数据填写完整且通过自动校验；能力 ID 唯一；申请状态在 5 分钟内可见。
• 异常与风控：发现命名冲突或字段冲突时阻断提交；对标记为“高敏数据”的能力要求强制附加数据脱敏方案。
• 指标建议：一次通过率、平均补充时长、能力命名冲突率。

子场景 B：多角色审核与合规把关

• 角色与触发：注册申请提交后，平台需要完成安全、权限、合规的多级审核。
• 主要流程：
  1. 能力注册服务根据能力标签自动分配审核人（安全、合规、运营）。
  2. 审核人在线检查数据分类、权限矩阵、调用频率限制与依赖情况。
  3. 如需整改，系统退回给开发者并附带修改建议；支持评论与附件补充。
  4. 审核通过后标记为“可暴露”，触发通知宿主管理员。
• 成功标准：审核 SLA 可配置（默认 2 个工作日内）；日志记录完整；高敏能力需双人复核。
• 异常与风控：审核超时自动升级；对拒绝理由进行结构化记录；防止未经审核的能力通过 API 暴露。
• 指标建议：审核通过率、平均审核时长、高敏能力复核覆盖率。

子场景 C：能力暴露与消费配置

• 角色与触发：审核通过的能力需要配置对外暴露方式并提供消费入口。
• 主要流程：
  1. 宿主管理员在能力目录中勾选需要暴露的能力，配置调用方式（REST API、GraphQL、Webhook、宿主工作流节点、SDK 模块等）。
  2. 为不同租户或项目分配授权范围与额度（QPS、调用次数、数据范围）。
  3. 平台生成文档、示例代码、Postman 集合等交付物，并同步到开发者门户。
  4. 订阅方可通过 API Gateway / 工作流引擎等渠道测试并启用能力。
• 成功标准：暴露配置可在 3 分钟内生效；文档自动同步；权限与额度与 IAM/RBAC 对齐。
• 异常与风控：额度超限自动熔断并发送告警；未授权租户调用时阻断并记录；Webhook 目标异常时支持重试策略。
• 指标建议：能力启用率、调用成功率、熔断次数、文档访问量。

子场景 D：能力变更、下线与订阅通知

• 角色与触发：能力上线后发生变更或计划下线，需要通知所有订阅方并保障过渡期。
• 主要流程：
  1. 开发者在能力管理面板发起变更（新增字段、参数调整、下线计划等）。
  2. 系统生成版本差异对比，提示影响范围并要求评估迁移方案。
  3. 对订阅方推送通知（邮件、站内消息、Webhook），提供灰度策略与兼容期限。
  4. 到期后自动下线旧版本，保留审计记录与回滚入口。
• 成功标准：订阅方通知覆盖率 100%；灰度期内允许双版本并行；下线后调用自动阻断。
• 异常与风控：订阅方未确认时升级提醒；重要能力需平台审批；下线失败时触发回滚。
• 指标建议：通知触达率、迁移完成率、灰度期内故障率。

功能边界 & 非目标场景

• 不涉及插件内部的业务逻辑实现与单元测试，此部分由“插件开发与调试”主用例覆盖。
• 不处理 Marketplace 上架与交易流程，请参考“插件发布与上架”主用例。
• 不涉及宿主自身的 API Gateway 运维细节，相关内容归属“系统监控与告警”。
• 对于跨租户的业务编排策略需结合“多租户与组织管理”主用例，只在此引用结果。

依赖与接口

• 能力注册服务 API：提交/更新能力元数据、查询审核状态、生成能力 ID。
• 审批与合规系统：承载多级审核流程、SLA 监控与通知。
• API Gateway / GraphQL 层：配置能力暴露、认证授权、流控与熔断。
• 文档与开发者门户：自动生成文档、示例代码、SDK 包。
• 通知中心：向订阅方推送变更、下线与额度告警。
• 计量与计费服务（可选）：为能力调用提供计量、计费、对账能力。

验收要点

1. 能力元数据模板满足命名规范、Schema 校验，提交后可追溯版本变更历史。
2. 审核流程可配置角色、SLA 与升级策略，拒绝原因与整改记录可导出。
3. 暴露配置支持多种调用通道与租户级授权，额度控制可实时生效。
4. 能力变更/下线需有完整的通知、灰度与回滚机制，并记录审计日志。
5. 文档、SDK 等交付物在能力上线后自动生成并可供订阅方下载。

场景级测试用例示例

测试准备：在沙箱租户 sandbox-tenant-b 中安装 powerx-insight-plugin@1.0.0，预置能力注册模板与审批流程；配置 API Gateway 沙箱环境；准备两个测试租户 tenant-alpha、tenant-beta 分别模拟启用与未授权状态。

用例 A-1：能力注册成功（正向）

• 前置条件：能力模板校验规则已启用。
• 操作步骤：
  1. 开发者在控制台提交能力“Insight.Report.Export”，填写完整元数据。
  2. 上传示例请求/响应与错误码表。
• 预期结果：
  • 系统校验通过并生成能力 ID cap-001，状态为“待审核”。
  • 审计日志记录提交人、时间、字段校验结果。

用例 A-2：命名冲突阻断（逆向）

• 前置条件：已有能力使用相同名称。
• 操作步骤：
  1. 使用重复名称提交注册请求。
• 预期结果：
  • 系统阻断提交并返回“能力名称已被占用”提示。
  • 指向冲突能力 ID，建议修改命名或申请合并。

用例 B-1：高敏能力双人复核（正向）

• 前置条件：能力标记涉及 PII 数据。
• 操作步骤：
  1. 审核人 A 完成安全检查并通过。
  2. 审核人 B（合规）在 2 小时内完成复核。
• 预期结果：
  • 审核状态变为“可暴露”，通知宿主管理员。
  • 审核日志显示双人复核记录与 SLA 时长。

用例 B-2：审核超时升级（逆向）

• 前置条件：未在 SLA 内完成审核。
• 操作步骤：
  1. 人为延迟审核超过 2 个工作日。
• 预期结果：
  • 系统自动升级到主管并发送提醒邮件/站内信。
  • 能力状态保持“待审核”，并记录升级动作。

用例 C-1：REST API 暴露验证（正向）

• 前置条件：审核通过的能力配置 REST API 暴露，并授权 tenant-alpha。
• 操作步骤：
  1. 宿主管理员在能力目录中启用 REST 通道并配置 QPS=50。
  2. 使用 API Key 从 tenant-alpha 发起请求。
• 预期结果：
  • 请求返回 200，包含预期数据。
  • 监控面板显示调用成功记录，QPS 配额剩余正确。

用例 C-2：未授权调用阻断（逆向）

• 前置条件：tenant-beta 未被授权。
• 操作步骤：
  1. 使用 tenant-beta 的凭证调用同一 API。
• 预期结果：
  • 返回 403，提示“未授权访问”。
  • 审计日志记录阻断事件与调用方信息。

用例 D-1：能力变更通知生效（正向）

• 前置条件：已有订阅方 tenant-alpha。
• 操作步骤：
  1. 开发者提交能力 V2 变更（新增字段）。
  2. 系统设置灰度期 14 天，并推送通知。
• 预期结果：
  • 订阅方收到邮件与站内消息，附带迁移指南。
  • 灰度期内 V1/V2 双版本可调用，调用日志区分版本。

用例 D-2：下线失败回滚（逆向）

• 前置条件：计划在灰度结束后下线 V1，但检测到仍有调用。
• 操作步骤：
  1. 到期后执行下线任务。
• 预期结果：
  • 系统检测仍有调用并自动暂停下线，发出“需确认迁移完成”的告警。
  • 管理员可在确认后重新发起下线操作，过程留痕。