用途
Fusion Help Integration 用于把 Fusion Help Center 接入应用页面，使用户可以通过 PageLayout 上的帮助按钮打开上下文相关的帮助文章。
适用场景
- 为页面添加帮助按钮
- 在页面组件中接入 useHelpCenter
- 创建或更新帮助文章常量文件
- 连接 PageLayout 与 Fusion Help Center
- 给某个应用添加帮助支持
- 从页面打开指定的帮助文章
以下场景不适用：撰写 Markdown 帮助文章（应使用 fusion-help-docs）；直接调用 Help 服务的 REST API（应使用 fusion-help-api）；修改 @fra/ui 共享组件（PageLayout、PageHeader、FusionHelpButton）；非 Fusion 框架应用或该 monorepo 之外的应用。
所需输入
在开始改动前需收集：
| 输入 | 是否必需 | 默认值 | 说明 |
|---|---|---|---|
| App name | 是 | — | apps/ 下的应用目录名，例如 fra-app-management |
| Target pages | 是 | — | 要接入的页面，或填 "all" 表示所有使用 PageLayout 的页面 |
| Article slugs | 是 | 自动推导 | 每个页面的 slug 字符串。若未提供，按 {app-name}-{page-kebab} 推导 |
| Include release notes | 否 | true | 是否同时向 PageLayout 传入 openReleaseNotes |
| Constants file location | 否 | src/constants/helpArticles.ts | FUSION_HELP_ARTICLES 对象的路径 |
如果 slug 为自动推导，必须在应用前与用户确认——slug 必须与通过 fhelp 发布的文章一致。
使用方式
-
检查现有帮助集成：在目标应用中搜索 helpArticles.ts、fusionHelpArticles.ts 以及 useHelpCenter 的 import。若已有部分集成，应在其基础上扩展而非重复添加。
-
确定 slug 约定：若应用已有包含 slug 的常量文件，沿用其命名模式；若没有，则使用 {app-name}-{page-kebab} 约定。参考约定示例：fra-access-manager 使用 {app-name}-{page-kebab}（如 fra-access-manager-access-groups）；fra-app-management 使用无前缀页面名（overview、requests）；personnel-allocation 使用 {app-name}-{page-kebab}（如 personnel-allocation-overview）。新应用优先使用带前缀的约定，以避免跨应用的 slug 冲突。
-
创建或更新常量文件：创建 src/constants/helpArticles.ts（或应用选定位置），内容形如：
export const FUSION_HELP_ARTICLES = { PAGE_NAME: '{app-name}-{page-kebab}', };
键为与页面概念匹配的 SCREAMING_SNAKE_CASE，值为 kebab-case 的 slug 字符串。完整的规范模式可参见 references/wiring-pattern.md。
-
接入每个目标页面：对每个使用 PageLayout 的页面组件：
a. 添加 import（顺序为外部依赖、@fra/、@/ 别名、相对路径）：
import { useHelpCenter } from '@equinor/fusion-framework-react-app/help-center'; import { PageLayout } from '@fra/ui'; import { FUSION_HELP_ARTICLES } from '@/constants/helpArticles';
b. 在组件体内解构 hook：
const { openArticle, openReleaseNotes } = useHelpCenter();
若不需要 release notes，则只解构 { openArticle }。
c. 向 PageLayout 传 props：
<PageLayout title="Page Title" openHelpArticle={() => openArticle(FUSION_HELP_ARTICLES.PAGE_NAME)} openReleaseNotes={openReleaseNotes}
注意：openHelpArticle 必须是回调包装 () => openArticle(slug)，不能直接引用，因为 openArticle 需要 slug 参数。
-
验证集成：运行 TypeScript 检查 pnpm --filter {app-name} exec tsc --noEmit；运行 lint 检查 pnpm --filter {app-name} exec eslint src/；进行视觉检查，确认页面头部显示 info-circle（ⓘ）图标，点击后可打开 Fusion Help 侧边面板。
-
与已发布内容交叉核对：FUSION_HELP_ARTICLES 中的每个 slug 都必须对应一篇已发布文章。若文章不存在：指向 fusion-help-docs 进行撰写；常量中的 slug 必须与 help-articles.json 中的 slug 字段完全一致；文章通过 fhelp 按环境发布。
预期输出
- 创建或更新包含文章 slug 映射的常量文件
- 目标页面完成 useHelpCenter + PageLayout props 接入
- TypeScript 编译通过
- 列出需要对应帮助文章的 slug 清单（用于交接给 fusion-help-docs）
安全与约束
- 未经确认不得臆造 slug 名称——slug 必须与已发布文章一致
- 不得修改 @fra/ui 组件——PageLayout、PageHeader、FusionHelpButton 已支持 help props
- 不得新增依赖——@equinor/fusion-framework-react-app 已在每个应用中
- 遵循应用的 import 别名约定——大多数应用使用 @/* → src/*
- 尊重现有代码风格——类型专用 import 使用 type，保持 import 分组顺序
- 不要重复接入帮助逻辑——若页面已有 useHelpCenter，应扩展而非重复添加
- 应用前确认自动推导的 slug——错误的 slug 会静默失败（不显示文章）
限制
关于收费、价格、平台与效果等信息，资料中暂未提供。