主用例说明：插件发布与上架

背景概述

插件在完成开发与调试后，需要经过测试验证、合规审核与多租户部署，才能向企业内部或 Marketplace 用户提供服务。发布链路往往涉及多环境迁移、离线与在线双通道、CI/CD 自动化、灰度监控以及第三方审核等环节。一旦缺乏标准化流程，容易出现版本漂移、合规隐患或上线失败。本主用例聚焦“插件发布与上架”，梳理从测试租户验证、离线包导入、流水线持续发布到 Marketplace 审核上架的关键步骤，确保插件能够安全、高效、可追溯地进入生产环境并触达目标用户。

目标与价值

• 标准化发布路径：定义从测试、预生产到正式租户的规范流程，降低环境不一致风险。
• 多通道交付保障：同时支持在线推送与离线包导入，满足弱网或隔离环境需求。
• 持续交付与合规：将质量门禁、签名校验、审批流程嵌入 CI/CD，实现可追踪发布。
• 运营可观测性：灰度期间采集指标，确保问题可快速定位并回滚。
• 生态扩展：完成 Marketplace 审核与上架，使插件可被更多租户发现与安装。

参与角色

• 插件开发者：提交发布版本、维护版本说明与变更日志。
• 测试工程师 / QA：在测试租户执行回归验证并确认质量门禁通过。
• 发布经理 / 运维工程师：审批发布请求、监控灰度指标并执行回滚策略。
• 企业管理员：在隔离网络环境中执行离线导入或为生产租户启用新版本。
• Marketplace 审核员：校验合规性、元数据与商业信息后安排上架。
• CI/CD 平台与自动化服务：执行构建、签名、部署与指标采集任务。

相关基础能力

• PowerXPlugin 仓（PLG）：提供插件 SDK、接口与脚手架，是开发与构建的主仓库。
• CLI 工具链：px-plugin 用于构建、打包与发布；px-admin 配置测试或生产租户；px-market 对接 Marketplace 审核与上架。
• 宿主系统：PowerX Web Admin 支持插件安装与调试，PowerX Backend 管理插件生命周期与运行态。

主场景 User Story

作为 发布经理，我希望 在确保质量与合规的前提下，将插件版本快速发布到生产租户并同步至 Marketplace，从而 让目标用户及时获得新能力且上线过程可追踪、可回滚。

子场景详解

子场景 A：测试租户验证与发布审批

• 角色与触发：开发者完成功能后提交发布申请，需要在测试租户验证并通过审批。
• 主要流程：
  1. 开发者通过 powerx publish create 上传构建产物与版本说明，指定测试租户。
  2. CI/CD 平台自动部署至测试租户，执行回归测试与安全扫描。
  3. QA 审核测试报告，发布经理核对变更内容并审批上线窗口。
  4. 审批通过后，系统生成生产发布计划并锁定版本标签。
• 成功标准：测试覆盖率 ≥ 90%；安全扫描无高危；审批流在 24 小时内完成；发布计划包含回滚方案与联系人。
• 异常与风控：测试失败自动阻断流程；审批超时触发提醒；防止未登记的变更直接跳过测试环境。
• 指标建议：测试通过率、审批耗时、阻断次数。

子场景 B：离线包导入隔离环境

• 角色与触发：企业管理员在无外网或受限网络环境中需上线插件。
• 主要流程：
  1. 发布经理在 CI/CD 中生成离线包（含签名、依赖、校验文件），并上传到内网分发库。
  2. 企业管理员下载离线包，通过 powerx plugin import --offline 命令导入目标租户。
  3. 系统校验签名、版本兼容性与许可证状态，解压并部署插件。
  4. 管理员在控制台执行健康检查，确认服务可用后正式启用。
• 成功标准：离线包校验通过；部署耗时 < 10 分钟；健康检查全部通过；审计日志记录导入人、时间与版本号。
• 异常与风控：签名不匹配立即阻断并告警；依赖缺失需提示补齐；导入失败自动回滚并恢复旧版本。
• 指标建议：离线导入成功率、审计日志完整度、回滚次数。

子场景 C：CI/CD 自动发布至生产租户并执行灰度

• 角色与触发：批准的版本需在生产环境分批上线并监控关键指标。
• 主要流程：
  1. CI/CD 管道根据发布计划执行构建、单元测试、制品签名与版本打包。
  2. 系统将插件推送至生产租户的灰度分组（例如 10% 用户），同步启动指标采集。
  3. 发布经理与运维工程师监控性能、错误率、用户反馈，并在窗口期内决策扩容或回滚。
  4. 灰度稳定后自动扩大覆盖范围至 100%，更新变更日志并通知相关用户。
• 成功标准：灰度期间核心指标偏差 < 5%；错误率无显著上升；回滚策略经过演练；全量发布后 SLA 满足要求。
• 异常与风控：灰度异常自动触发回滚；推送失败重试三次后转人工；全量前需再次确认依赖与许可证状态。
• 指标建议：灰度时长、指标偏差、回滚触发率。

子场景 D：Marketplace 审核与上架

• 角色与触发：Vendor 希望在 Marketplace 提供插件，需要提交审核材料。
• 主要流程：
  1. Vendor 在发布控制台填写定价、功能亮点、截图、支持政策等元数据，提交上架请求。
  2. Marketplace 审核员校验合规性、签名与安全测试报告，必要时要求补充材料。
  3. 审核通过后，系统同步插件元数据到 Marketplace 列表，并设置可见范围与推广标签。
  4. 上架后生成运营报表，通知订阅租户并支持试用/购买流程。
• 成功标准：资料完整、签名验证通过；审核 SLA ≤ 3 个工作日；Marketplace 列表信息准确并可搜索到；订阅流程打通。
• 异常与风控：发现合规风险时拒绝并记录原因；签名或安全报告失效需重新提交；上架后监控下载量与退订率。
• 指标建议：审核通过率、上架耗时、Marketplace 转化率。

子场景 E：开发者本地调试链路

• 角色与触发：插件开发者完成新功能，需要在不依赖 Marketplace 的情况下验证构建结果并快速迭代。
• 主要流程：
  1. 在 PowerXPlugin 仓执行 px-plugin build 或 px-plugin dev 生成输出目录（如 dist/）。
  2. 打开 PowerX Web Admin，在插件管理区选择“从本地目录安装”并指向构建产物。
  3. PowerX Backend 完成插件安装与激活，写入本地插件仓库。
  4. 开发者在 Admin 界面验证 UI、接口与权限配置，按需热更新代码并重复构建。
• 成功标准：插件可在本地租户加载并响应交互；构建产物与源码同步更新；调试日志可追踪。
• 异常与风控：构建失败阻断安装；Backend 激活失败时需回滚到上一次成功版本；权限配置缺失时提示最小权限模板。
• 指标建议：单次迭代耗时、中断安装次数、调试期间错误日志量。

子场景 F：离线包上传至 Marketplace

• 角色与触发：供应商或企业管理员在离线或弱网环境下准备插件，需要通过离线包送审与上架。
• 主要流程：
  1. 开发者使用 px-plugin pack 生成 .pxp 包，并包含签名、依赖与版本说明。
  2. 管理员在 px-market 控制台选择“离线上传”，提交离线包与元数据。
  3. Marketplace 校验包体签名、兼容矩阵及许可证信息，注册版本记录。
  4. 审核通过后，发布经理将包体同步到目标内网分发库，供租户管理员导入。
• 成功标准：签名与兼容校验全部通过；Marketplace 记录完整版本信息；包体在目标环境可下载。
• 异常与风控：签名不一致立即拒绝并提示重新打包；依赖缺失时要求补齐并重新上传；上传失败保留审计日志供复核。
• 指标建议：离线包校验成功率、审核耗时、版本补件次数。

子场景 G：在线发布与 Marketplace 上架

• 角色与触发：Vendor 希望直接在 Marketplace 发布插件，面向多租户或公共市场用户。
• 主要流程：
  1. 开发者执行 px-plugin publish 或在 PowerXPlugin 管理界面提交版本，并补充更新日志、定价与支持策略。
  2. px-market 接收制品并触发 Marketplace 审核流程，验证合规、签名与安全扫描。
  3. 审核通过后，系统将插件上架至 Marketplace，通知订阅租户并允许试用或购买。
  4. 后续版本更新沿用相同流程，可触发自动通知与版本比对。
• 成功标准：审核 SLA ≤ 2 个工作日；Marketplace 列表可查询到最新版本；通知推送覆盖目标租户。
• 异常与风控：审核驳回需记录原因并回传至 px-plugin; 签名或扫描异常阻断上架；版本冲突时保留旧版本并提示升级策略。
• 指标建议：审核通过率、上线后下载/启用量、驳回原因分布。

功能边界 & 非目标场景

• 不涵盖插件源码开发、调试流程，参见“插件开发与调试”主用例。
• 插件运行时的动态启停与升级策略属于“插件安装与启停”主用例范围。
• Marketplace 的商业计费、分成结算在“插件上架与销售”或商业层用例中覆盖。
• 不处理宿主或其他插件对该插件的调用集成细节，相关内容见“插件通信与集成”系列用例。

依赖与接口

• PowerX CI/CD 平台：提供构建、测试、签名、发布流水线能力。
• 版本与制品仓库：存储构建产物、离线包与版本元数据。
• 身份与权限服务：确保发布审批、导入操作具备相应权限并记录审计。
• 监控与日志平台：在灰度与全量阶段采集指标、错误日志与用户反馈。
• Marketplace 管理系统：处理上架审核、元数据管理与运营报表。
• 许可证与合规服务：校验插件许可状态、合法性与合规要求。

工具协作闭环

• px-plugin 负责构建、打包、发布与签名，是插件出包与上架入口。
• PowerX Web Admin 提供本地安装、调试与健康检查能力，支撑灰度验证。
• PowerX Backend 管理插件运行态、权限以及生命周期事件。
• px-market 与 Marketplace 平台承担审核、版本管理与分发统计，闭合上线到运营的链路。

验收要点

1. 发布流程需覆盖测试验证、审批、签名校验与回滚策略，全程可追踪并生成审计日志。
2. 支持在线推送与离线导入两种路径，确保在隔离环境中也能按标准发布。
3. 灰度阶段提供实时指标与告警，异常时可在 5 分钟内触发回滚并恢复旧版本。
4. Marketplace 上架流程需与发布记录关联，确保信息一致、签名有效且审核可追溯。

场景级测试用例示例

测试准备：配置 PowerX CI/CD 模板 plugin-release.yml，准备测试租户 tenant-test-01、生产租户 tenant-prod-01 与灰度分组 prod-canary；开通离线分发库访问；获取 Marketplace 审核账号；准备插件版本 v2.3.0 的签名证书与变更日志。

用例 A-1：测试租户自动化验证通过（正向）

• 前置条件：CI/CD 流水线绑定测试租户，质量门禁启用。
• 操作步骤：
  1. 执行 powerx publish create --target tenant-test-01 --version v2.3.0。
  2. 查看流水线执行记录，等待测试与安全扫描完成。
• 预期结果：
  • 流水线状态为成功，报告显示覆盖率 92%、无高危漏洞。
  • 发布审批页面显示待发布计划，包含回滚方案。
  • 审计日志记录提交人、版本号与测试摘要。

用例 A-2：测试失败阻断发布（逆向）

• 前置条件：单元测试存在失败用例。
• 操作步骤：
  1. 重复执行 powerx publish create 并触发流水线。
• 预期结果：
  • 流水线在“回归测试”阶段失败，自动标记为阻断。
  • 发布计划未生成，通知发送给开发者与 QA。
  • 审计日志记录失败原因与测试报告链接。

用例 B-1：离线包导入成功（正向）

• 前置条件：离线包 plugin-order-sync-v2.3.0.zip 已生成且签名有效。
• 操作步骤：
  1. 管理员执行 powerx plugin import --offline ./plugin-order-sync-v2.3.0.zip。
  2. 在控制台运行内置健康检查。
• 预期结果：
  • 命令输出“Signature verified. Deployment completed in 6m30s”。
  • 健康检查全部通过，插件状态为“Active”。
  • 审计日志包含导入人、时间与校验指纹。

用例 B-2：签名校验失败（逆向）

• 前置条件：使用过期签名证书生成的离线包。
• 操作步骤：
  1. 执行离线导入命令。
• 预期结果：
  • 系统提示“Signature expired or mismatched”，导入流程终止。
  • 旧版本保持运行，生成安全告警通知。
  • 审计日志记录失败原因与证书指纹。

用例 C-1：灰度发布指标达标（正向）

• 前置条件：灰度监控面板配置完成，回滚策略可执行。
• 操作步骤：
  1. 触发 powerx publish deploy --target tenant-prod-01 --strategy canary。
  2. 监控 prod-canary 指标 30 分钟并查看日志。
• 预期结果：
  • 核心 API 延迟与错误率在阈值内，灰度成功扩容至全量。
  • 系统推送变更通知给租户管理员。
  • 回滚按钮保持可用，记录“未触发回滚”。

用例 C-2：灰度异常自动回滚（逆向）

• 前置条件：模拟将错误率阈值上调为 10%，并注入异常流量。
• 操作步骤：
  1. 重复执行灰度发布命令并施加异常流量。
• 预期结果：
  • 监控检测到错误率 > 10%，自动触发回滚，恢复旧版本。
  • 发布任务状态显示“Rolled back”，并生成详细报告。
  • 通知发送至发布经理与运维团队，要求复盘。

用例 D-1：Marketplace 审核通过并上架（正向）

• 前置条件：上架资料完整，安全报告与签名有效。
• 操作步骤：
  1. Vendor 在 Marketplace 控制台提交上架申请，上传资料并绑定版本 v2.3.0。
  2. 审核员在后台核对资料并点击“通过”。
• 预期结果：
  • 审核状态更新为“Approved”，耗时 < 2 个工作日。
  • 插件显示在 Marketplace 列表，可搜索并预览详细信息。
  • 系统生成上架通知与初始下载量报表。

用例 D-2：合规审核驳回（逆向）

• 前置条件：缺少数据隐私合规声明。
• 操作步骤：
  1. Vendor 提交上架申请。
• 预期结果：
  • 审核状态更新为“Rejected”，备注要求补充合规声明。
  • 插件未在 Marketplace 上线，Vendor 收到整改通知。
  • 审计日志记录驳回原因与处理人。