PowerX 文档中心

简体中文

English

简体中文

English

Appearance

主用例说明：PowerX Web / MiniApp 业务插件前端交互 ​

背景概述 ​

PowerX 面向企业提供“插件即应用”的能力，越来越多 Vendor 选择在宿主 Web Admin 或 MiniApp 中直接提供面向业务人员的交互界面。与传统后端接口类插件不同，业务插件需要在宿主页面内嵌运行，与宿主共享导航、主题、权限和数据上下文，并在多租户环境下保持安全隔离。若缺乏统一的前端嵌入规范，容易出现视觉割裂、权限越界、状态不同步与性能不可控等问题。本主用例聚焦“宿主 ↔ 插件”在前端层面的嵌入、通信、治理闭环，确保业务插件能在 PowerX 生态中提供一致、可靠且可运维的用户体验。

目标与价值 ​

  • 一致的体验：通过统一的 UI 套件、主题和交互规范，避免嵌入式插件出现视觉割裂或交互逻辑冲突。
  • 安全的上下文传递：在多租户场景下，确保权限、租户、会话等上下文信息准确注入并可追踪。
  • 高可用与可观测：提供性能监控、错误上报、降级兜底策略，保障插件前端异常时仍能快速恢复。
  • 灵活的业务定制：支持租户按角色配置入口、参数和灰度策略，满足差异化业务需求。
  • 可协同的生态：与插件生命周期、权限治理、工作流编排等能力联动，实现端到端的插件运营闭环。

参与角色 ​

  • 业务终端用户：在 Web Admin 或 MiniApp 中使用插件界面完成业务操作。
  • 租户管理员/运营人员：配置插件入口、默认参数、灰度策略，监控使用情况。
  • 插件 Vendor 前端开发者：实现插件界面、与宿主 SDK 对接、处理消息与状态。
  • 宿主前端平台团队：提供嵌入容器、UI 套件、事件总线、异常兜底能力。
  • 安全与合规团队：审核插件的权限使用、前端数据访问和日志采集策略。
  • 运维 / SRE 团队：监控插件前端性能指标、异常告警与降级策略执行。

主场景 User Story ​

作为 PowerX 租户的业务运营人员，我希望 在 Web Admin 中打开业务插件时能够获得与宿主一致的界面风格、可靠的权限控制与实时的数据同步，从而 在多插件协同的环境下稳定完成关键业务流程，不必担心信息割裂或安全风险。

子场景详解 ​

子场景 A：嵌入初始化与安全握手 ​

  • 角色与触发：用户从宿主导航点击某业务插件入口，需要在宿主页面内加载插件前端。
  • 主要流程：
    1. 宿主根据租户、角色、灰度策略判定可访问性，并生成一次性会话 Token。
    2. 插件通过 iframe / Web Component 被注入到宿主容器中，监听 postMessage 或 SDK 初始化事件。
    3. 双方完成签名校验、版本协商、能力清单同步，约定通信通道与心跳策略。
    4. 初始化完成后宿主发送用户上下文、默认参数，插件返回就绪状态与首屏渲染事件。
  • 成功标准：握手耗时小于 1 秒；上下文注入完整可审计；插件未注册能力无法被调用。
  • 异常与风控：握手失败需显示兜底页面并上报；Token 过期需重新申请；不可信来源被立即阻断。
  • 指标建议：初始化成功率、平均握手时延、非法请求拦截次数。

子场景 B：主题样式与国际化对齐 ​

  • 角色与触发：租户启用自定义主题或不同语言，需要插件界面同步更新。
  • 主要流程：
    1. 宿主向插件注入主题变量（颜色、字体、组件尺寸）与 I18N 资源包。
    2. 插件基于宿主提供的 UI SDK 或 Design Token 渲染界面，并监听主题切换事件。
    3. 当用户切换暗色模式、语言或无障碍设置时，宿主广播变更，插件即时响应。
    4. 插件可声明额外的动态样式需求，由宿主审核后在容器内生效。
  • 成功标准：主题切换 200ms 内完成；国际化文案与宿主一致；无未授权样式污染宿主页面。
  • 异常与风控：插件未响应主题事件时自动回退默认样式；额外样式注入需 CSP 审核；I18N 缺失时回退为宿主默认语言。
  • 指标建议：主题同步成功率、无障碍对齐通过率、样式冲突告警次数。

子场景 C：上下文状态同步与跨插件联动 ​

  • 角色与触发：用户在宿主或其他插件中选中资源，需要业务插件同步上下文并展示关联数据。
  • 主要流程：
    1. 宿主通过前端事件总线广播当前会话、选中客户、过滤条件等状态。
    2. 业务插件订阅相关事件，拉取必要数据并渲染界面，同时向宿主回传操作结果或草稿状态。
    3. 若用户在插件内更新数据，插件需调用宿主 SDK 写入共享缓存或触发后台 API。
    4. 其他订阅同类事件的插件或宿主模块可同步收到更新，实现跨插件联动。
  • 成功标准：状态延迟小于 300ms；跨插件数据一致；操作日志可追踪来源。
  • 异常与风控：事件丢失时支持重放；敏感数据需脱敏或最小化传输；写入失败提供重试与用户提示。
  • 指标建议：状态同步成功率、跨插件一致性告警数、重试成功率。

子场景 D：租户自定义配置与灰度发布 ​

  • 角色与触发：租户管理员希望针对特定角色或业务场景自定义插件入口、默认视图或参数。
  • 主要流程：
    1. 管理员在宿主配置中心为插件设置入口位置、默认筛选条件、初始表单字段等。
    2. 支持按租户、业务线、用户组配置差异化体验，并设置灰度比例与回滚策略。
    3. 发布后宿主将配置注入插件初始化参数，插件需读取并做版本兼容。
    4. 若灰度监控到异常，管理员可一键回滚到上一个稳定配置并通知相关用户。
  • 成功标准：配置发布即时生效；灰度监控指标可视；回滚 1 分钟内完成。
  • 异常与风控：配置冲突需提示并阻止发布；不兼容参数需插件返回错误码；灰度失败自动触发回滚流程。
  • 指标建议：灰度成功率、回滚次数、配置变更审计覆盖率。

子场景 E：前端性能监控与降级策略 ​

  • 角色与触发：插件前端出现性能下降或不可用，需要自动告警与降级。
  • 主要流程：
    1. 宿主在容器层注入性能监控 SDK，采集 FMP、API 耗时、错误日志等指标，并与插件侧数据汇合。
    2. 当指标超过阈值时触发告警，展示用户提示，并按策略降级为只读模式或宿主兜底页面。
    3. 降级期间继续采集数据，允许管理员手动恢复或通知 Vendor 修复。
    4. 事件结束后生成复盘报告，沉淀到运营与合规模板中。
  • 成功标准：告警检测及时率 ≥ 99%；降级过程不中断用户关键操作；恢复后状态不丢失。
  • 异常与风控：监控失效需冗余兜底；降级失败时强制关闭入口并提示用户；异常日志需符合隐私合规要求。
  • 指标建议：页面性能指标达标率、降级触发次数、恢复平均时长。

功能边界 & 非目标场景 ​

  • 本主用例不涉及插件后端 API 设计与数据存储策略，由插件生命周期和集成场景负责。
  • 不提供纯离线或原生 App 的嵌入方案，聚焦 Web Admin 与 MiniApp 的在线体验。
  • 不处理宿主导航或权限策略的定义，仅消费已有的 IAM 与菜单配置能力。
  • 不替代插件自身的业务逻辑实现，主要关注宿主与插件之间的前端契约与治理。

依赖与接口 ​

  • 宿主嵌入容器服务：提供 iframe/Web Component 容器、加载顺序、错误兜底能力。
  • 前端 SDK / Bridge：支持消息通信、上下文注入、事件订阅、API 调用代理。
  • IAM 与权限服务：提供用户身份、角色、租户、权限校验与会话 Token。
  • 配置与灰度服务：管理入口位置、参数模板、灰度策略与回滚历史。
  • 日志与监控服务：采集性能、错误、用户行为并对接告警平台。
  • 主题与国际化服务：提供 Design Token、组件库、I18N 资源。
  • 审计合规服务：记录敏感操作、配置变更、跨租户访问尝试。

验收要点 ​

  1. 业务插件必须通过宿主提供的 SDK 完成初始化握手，未经授权的插件被拦截并记录审计。
  2. 插件界面需在主题、语言、无障碍设置变更时 200ms 内响应，与宿主保持一致。
  3. 插件对宿主广播的上下文事件需在 300ms 内处理，状态变更支持回放与追踪。
  4. 租户级配置与灰度发布需具备完整的版本管理、审计与一键回滚能力。
  5. 前端性能监控指标需接入统一平台，出现异常时自动触发降级与通知流程。
  6. 整体链路需输出安全与合规日志，包括权限校验、数据访问、降级操作等关键行为。

场景级测试用例示例 ​

测试准备：搭建 Web 宿主沙箱 web-admin-stg 与 MiniApp 沙箱 miniapp-stg，启用嵌入容器 embed-shell、前端 Bridge px-bridge, 配置服务 config-hub, 主题服务 theme-center, 监控服务 telemetry-hub, 审计服务 audit-trail。创建租户 tenant-x, 角色 ops-admin, sales-user, 用户 user-lucy（运营）、user-ken（销售）、user-emma（安全）、user-li（Vendor 开发）。部署业务插件 trade-insight，版本 1.4.0。

用例 A-1：嵌入初始化成功（正向） ​

  • 前置条件：user-lucy 具备访问 trade-insight 插件的权限。
  • 操作步骤：
    1. 在 Web Admin 菜单点击“交易洞察插件”。
    2. 观察加载流程。
  • 预期结果：
    • 1 秒内完成握手，插件收到租户与角色上下文。
    • 首屏渲染成功，审计日志记录初始化事件。
    • px-bridge 控制台显示插件能力清单注册成功。

用例 A-2：Token 过期失败（逆向） ​

  • 前置条件：人为缩短 embed-shell Token 过期时间。
  • 操作步骤：
    1. 保持页面 5 分钟不操作后刷新插件。
  • 预期结果：
    • 插件收到 Token 失效事件并请求重新授权。
    • 宿主弹出重新登录提示，拒绝访问时展示兜底页面。
    • 审计日志记录拒绝原因，通知安全人员。

用例 B-1：主题切换同步（正向） ​

  • 前置条件：启用暗色主题与英文语言包。
  • 操作步骤：
    1. user-ken 在宿主右上角切换暗色模式并选择 English。
  • 预期结果：
    • 插件 200ms 内完成暗色主题切换，文案全部显示英文。
    • 主题事件被记录到 telemetry-hub，无样式冲突告警。

用例 C-1：跨插件状态同步（正向） ​

  • 前置条件：另一个插件 customer-360 已打开，并选中客户 ID cust-888。
  • 操作步骤：
    1. user-ken 在 customer-360 中切换客户。
    2. 观察 trade-insight 响应。
  • 预期结果：
    • trade-insight 300ms 内刷新数据，显示与客户相关的交易图表。
    • 状态变更写入审计并在事件总线上留存。

用例 D-1：灰度发布与回滚（正向） ​

  • 前置条件：管理员在 config-hub 中创建新配置，灰度 30% 销售用户。
  • 操作步骤：
    1. 发布配置后观察灰度用户体验。
    2. 触发回滚。
  • 预期结果：
    • 灰度用户看到新增“高级过滤”入口，其他用户保持旧版本。
    • 回滚 1 分钟内完成，入口恢复旧状态。
    • 审计记录灰度发布与回滚动作。

用例 E-1：性能告警降级（逆向） ​

  • 前置条件：模拟插件接口延迟 > 5 秒。
  • 操作步骤：
    1. 执行触发慢接口的操作。
  • 预期结果：
    • telemetry-hub 触发告警并通知 user-emma。
    • 插件自动降级为只读模式，并显示“服务繁忙请稍后”。
    • 恢复后可手动解除降级，期间操作日志完整。

用例 E-2：MiniApp 兜底体验（逆向） ​

  • 前置条件：MiniApp 网络不稳定，导致插件资源加载失败。
  • 操作步骤：
    1. user-ken 在 MiniApp 打开 trade-insight。
  • 预期结果：
    • 宿主检测到资源加载失败，展示兜底引导并提供“稍后重试”按钮。
    • 错误信息上报到监控平台并关联网络指标。
    • 兜底页面提供业务热线或转人工入口，保障用户体验。

基于 Apache 2.0 许可发布