fusion-help-integration

Fusion Help 集成

将 Fusion Help Center 接入应用页面，让用户可以通过 PageLayout 的帮助按钮打开上下文相关的帮助文章。

适用场景

• 为页面添加帮助按钮
• 将 useHelpCenter 接入页面组件
• 创建或更新帮助文章常量文件
• 将 PageLayout 连接到 Fusion Help Center
• 页面使用 PageLayout，但未设置 openHelpArticle
• 为应用添加帮助支持
• 从页面打开特定帮助文章

不适用场景

• 编写 Markdown 帮助文章 → fusion-help-docs
• 直接调用 Help 服务的 REST API → fusion-help-api
• 修改 @fra/ui 共享组件（PageLayout、PageHeader、FusionHelpButton）
• 非 Fusion 框架应用或本单体仓库之外的应用

必需输入

开始修改前，请收集以下信息：

输入项	必需	默认值	说明
应用名称	是	—	apps/ 下的应用目录名称（例如，fra-app-management）
目标页面	是	—	要接入的页面，或指定 "all" 以覆盖所有使用 PageLayout 的页面
文章 slug	是	自动推导	每个页面对应的 slug 字符串。如果未提供，则按 {app-name}-{page-kebab} 推导
包含发行说明	否	true	是否同时向 PageLayout 传入 openReleaseNotes
常量文件位置	否	src/constants/helpArticles.ts	FUSION_HELP_ARTICLES 对象的路径

如果自动推导文章 slug，应用前请与用户确认——slug 必须与通过 fhelp 发布的文章一致。

操作说明

1. 检查现有帮助集成

在目标应用中搜索现有的帮助接入代码：

apps/{app-name}/src/**/helpArticles.ts
apps/{app-name}/src/**/fusionHelpArticles.ts

同时搜索 useHelpCenter 导入语句。如果应用已有部分集成，应在其基础上扩展，而不是重复添加。

2. 确定 slug 规则

检查应用是否已有包含 slug 的常量文件：

• 已有 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 冲突。

3. 创建或更新常量文件

创建 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。

4. 接入每个目标页面

对于每个使用 PageLayout 的页面组件：

a. 添加导入语句（先导入外部模块，再导入 @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();

如果不需要发行说明，只解构 { openArticle }。

c. 向 PageLayout 传入属性：

<PageLayout
    title="Page Title"
    openHelpArticle={() => openArticle(FUSION_HELP_ARTICLES.PAGE_NAME)}
    openReleaseNotes={openReleaseNotes}
>

重要：openHelpArticle 必须是回调包装函数 () => openArticle(slug)，而不能直接引用函数——openArticle 需要传入 slug 参数。

5. 验证集成

完成接入后：

1. 运行 TypeScript 检查：pnpm --filter {app-name} exec tsc --noEmit
2. 检查 lint：pnpm --filter {app-name} exec eslint src/
3. 视觉检查：页面标题栏应显示信息圆圈（ⓘ）图标。点击后会打开 Fusion Help 侧边面板。

6. 与已发布内容交叉核对

FUSION_HELP_ARTICLES 中的每个 slug 都必须对应一篇已发布的文章。如果文章不存在：

• 指向 fusion-help-docs 以便编写文章
• 常量中的 slug 必须与 help-articles.json 中的 slug 字段完全一致
• 文章通过 fhelp 按环境发布

预期输出

• 创建或更新常量文件，写入文章 slug 映射
• 目标页面已接入 useHelpCenter + PageLayout 属性
• TypeScript 编译通过
• 需要相应帮助文章的 slug 列表（交接给 fusion-help-docs）

安全与约束

• 未经确认，绝不臆造 slug 名称——slug 必须与已发布的文章匹配
• 不要修改 @fra/ui 组件——PageLayout、PageHeader 和 FusionHelpButton 已支持帮助属性
• 不要添加新依赖——每个应用都已包含 @equinor/fusion-framework-react-app
• 遵循应用的导入别名约定——大多数应用使用 @/* → src/*
• 遵循现有代码风格——仅类型导入使用 type，并保持导入分组顺序
• 不要重复接入帮助功能——如果页面已使用 useHelpCenter，请扩展现有接入，而不是重新添加
• 应用自动推导的 slug 前先确认——slug 错误会静默失败（不会显示文章）