fusion-help-docs

Fusion 帮助文档

通过 fhelp CLI 编写、整理并发布帮助文档（文章、发行说明、常见问题解答）。

适用场景

• 为 Fusion 应用编写帮助文章
• 创建／更新发行说明
• 设置文档文件夹结构和配置
• 为帮助系统整理 Markdown
• 将文档发布／同步到 Fusion 环境
• 添加常见问题解答条目
• 设置 CI/CD 流水线以自动发布

不适用场景

• 修改 fusion-help-cli 源码（tooling/fusion-help-cli/）
• 更改 Fusion.Services.Help 后端 API
• 与 Fusion Help 无关的常规 Markdown 编辑
• 非文档类任务

必需输入

创建前请收集：

输入项	必填	说明
应用密钥	是	Fusion 应用密钥（例如 my-app、resource-allocation-landingpage）。用户必须是该应用的管理员。
内容类型	是	articles、release-notes 或 faqs
文档根路径	是	团队存放文档的位置（例如 docs/help/）
目标环境	发布时必填	ci、fqa、tr 或 fprd

如果应用密钥未知，请检查应用管理页面：

• CI：https://fusion.ci.fusion-dev.net/apps/app-admin
• Production：https://fusion.equinor.com/apps/app-admin

查看“Admins”部分 — 必须列为管理员才能发布。

操作说明

1. 设置文档文件夹结构

创建文件夹布局：

docs/
  help/
    articles/                    # Markdown article files
      images/                    # Article images (PNG format)
    release-notes/               # Markdown release note files
      images/                    # Release note images (PNG format)
    faqs/                        # Optional: markdown FAQ body overrides
    help-articles.json           # Article config
    help-release-notes.json      # Release notes config (if using release notes)

文件夹和配置名称可以灵活设置 — 但必须与传给 fhelp 的名称一致。

2. 创建文章配置文件

创建 help-articles.json（告知 CLI 要同步哪些文章）：

{
  "articles": [
    {
      "slug": "my-app-getting-started",        // Must match the .md filename (without extension)
      "title": "Getting Started",               // Display title in Fusion Help
      "appKey": "my-app",                       // Your Fusion app key
      "sortOrder": 1.0,                         // Controls display order (lower = first)
      "summary": "Learn how to get started.",   // Short description shown in article list
      "tags": ["getting-started", "onboarding"],// Searchable tags
      "relevantApps": []                        // Optional: other app keys where this shows
    }
  ]
}

配置字段参考

字段	必填	类型	说明
slug	是	string	唯一标识符。必须与文章根文件夹中的 {slug}.md 文件名一致。使用 kebab-case。
title	是	string	在 Fusion Help 中显示的易读标题。
appKey	是	string	该文章所属的 Fusion 应用密钥。你必须是该应用的管理员。
sortOrder	否	number	控制显示顺序。数值越小，越靠前显示。默认值各不相同。使用小数（1.0、1.1、2.0）可灵活排序。
summary	是	string	在文章列表中显示的简短说明。
tags	否	string[]	用于分类的可搜索标签。
relevantApps	否	string[]	该文章还应显示在哪些其他应用中。

3. 编写文章内容

在文章根文件夹中创建 Markdown 文件。文件名（不含 .md）必须与配置中的 slug 一致。

文章编写指南：

• 面向 Fusion 应用的最终用户编写
• 使用 ##、### 进行结构划分 — 避免使用 #（标题取自配置）
• 将图片放在 images/ 中；使用 ![Alt text](images/my-screenshot.png) 引用
• CLI 会自动上传图片并将路径改写为 CDN 路径
• 图片必须为 PNG 格式（CLI 限制）
• 每篇文章只讨论一个主题
• 按标题链接相关文章（平台会处理深层链接）

文章示例（docs/help/articles/my-app-getting-started.md）：

## Overview

This guide walks you through the basics of using My App.

## Prerequisites

Before you begin, make sure you have:
- Access to the Fusion portal
- The correct role assigned to your user

## Step 1: Navigate to the app

Open Fusion and search for "My App" in the app launcher.

![App launcher](images/app-launcher.png)

## Step 2: Create your first item

Click the **New** button in the toolbar to create your first item.

## Need help?

Contact the team on Teams or check the FAQ section.

4. 创建发行说明配置文件（可选）

如果团队会发布发行说明，请创建 help-release-notes.json：

{
  "releaseNotes": [
    {
      "slug": "my-app-v2-release",              // Must match the .md filename
      "title": "Version 2.0 Release",           // Display title
      "appKey": "my-app",                       // Your Fusion app key
      "publishedDate": "2026-03-14T00:00:00Z",  // Publication date (ISO 8601)
      "tags": ["release", "v2"],                // Searchable tags
      "relevantApps": []                        // Optional: other app keys
    }
  ]
}

发行说明配置字段参考

字段	必填	类型	说明
slug	是	string	唯一标识符。必须与发行说明根文件夹中的 {slug}.md 文件名一致。
title	是	string	发行说明标题。
appKey	是	string	Fusion 应用密钥。你必须是管理员。
publishedDate	是	ISO 8601 date	发行说明的发布日期。
tags	否	string[]	可搜索标签。
relevantApps	否	string[]	其他应用密钥。

发行说明示例（docs/help/release-notes/my-app-v2-release.md）：

## What's new in Version 2.0

### New dashboard

We've completely redesigned the dashboard with new charts and filtering capabilities.

![New dashboard](images/new-dashboard.png)

### Performance improvements

- Page load times reduced by 40%
- Search results now appear in under 1 second

### Bug fixes

- Fixed an issue where filters would reset on navigation
- Corrected date formatting in the export feature

5. 安装并验证 CLI

从 Fusion Public feed 安装：

dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli

更新现有安装：

dotnet tool uninstall --global Fusion.Help.Cli
dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli

通过 Azure CLI 进行身份验证：

az login

CLI 使用 DefaultAzureCredentials，会自动获取 az login 会话。

6. 发布文档

同步文章：

fhelp article sync -f docs/help/help-articles.json -r docs/help/articles -e ci -v

同步发行说明：

fhelp releasenotes sync -f docs/help/help-release-notes.json -r docs/help/release-notes -e ci -v

命令标志：

标志	说明
-f、--file	JSON 配置文件的路径
-r、--root	包含 Markdown 文件的文件夹路径
-e、--env	目标环境：ci、fqa、tr、fprd
-t、--token	覆盖访问令牌（可选）
-v、--verbose	显示详细日志输出
--no-validation	跳过源系统检查——谨慎使用，可能覆盖通过 UI 创建的内容

环境晋级顺序： ci → fqa → fprd（除非测试基础设施，否则跳过 tr）。

先在 ci 中测试，再晋级到 fqa，然后到 fprd。

7. 设置 CI/CD 流水线（推荐）

通过 Azure DevOps 或 GitHub Actions 自动发布。

Azure DevOps 流水线示例：

parameters:
  - name: environment
    type: string
    default: ci
    values: [ci, fqa, fprd]
  - name: azureSubscription
    type: string

steps:
  - checkout: self

  - script: |
      dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli
    displayName: "Install fusion help CLI"

  - task: AzureCLI@2
    displayName: "Sync help articles"
    inputs:
      azureSubscription: ${{ parameters.azureSubscription }}
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        fhelp article sync `
          -f ./docs/help/help-articles.json `
          -r ./docs/help/articles `
          -e "${{ parameters.environment }}" `
          -v

  - task: AzureCLI@2
    displayName: "Sync release notes"
    inputs:
      azureSubscription: ${{ parameters.azureSubscription }}
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        fhelp releasenotes sync `
          -f ./docs/help/help-release-notes.json `
          -r ./docs/help/release-notes `
          -e "${{ parameters.environment }}" `
          -v

GitHub Actions 示例：

name: Sync Help Documentation

on:
  push:
    branches: [main]
    paths: ['docs/help/**']

jobs:
  sync-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Install fusion help CLI
        run: |
          dotnet tool install --global \
            --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" \
            Fusion.Help.Cli

      - name: Azure Login
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: '3aa4a235-b6e2-48d5-9195-7fcf05b459b0'
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: Sync articles
        run: |
          fhelp article sync \
            -f ./docs/help/help-articles.json \
            -r ./docs/help/articles \
            -e ci -v

8. 常见问题（补充）

常见问题使用基于 Excel 的工作流，并需要应用级访问权限。这是一个临时解决方案，最适合常见问题涉及多个应用的场景。

fhelp faq sync -f docs/help/faqs.xlsx -e ci -v

对于大多数团队，通过 https://fusion.equinor.com/apps/fusion-help-admin 上的 Fusion Help Admin UI 管理常见问题更简单。

预期输出

• 包含文章、图像和配置的 docs/help/ 文件夹
• 内容完整、格式正确的 Markdown 文章文件
• 有效的 help-articles.json（以及可选的 help-release-notes.json）
• 如何安装、验证并运行 fhelp
• CI/CD 流水线代码片段（可选）

故障排除

问题	原因	解决方案
DefaultAzureCredential failed to retrieve a token	未通过身份验证	运行 az login
403 Forbidden	不是该应用密钥的管理员	在应用管理页面检查管理员列表，或验证配置中的 appKey
未创建文章（已跳过）	根文件夹中没有匹配的 .md 文件	确保文件名与 slug 完全一致：{slug}.md
源系统不匹配警告	文章是通过 UI 创建的，CLI 不会覆盖	谨慎使用 --no-validation，或使用其他 slug
图片无法上传	格式错误	图片必须为 PNG 格式

安全与限制

• 未充分了解前，切勿使用 --no-validation——这可能覆盖通过 UI 创建的内容
• 发布到 fprd 前先在 ci 中测试
• sourceSystem 会自动设为 Fusion.Help.Cli；CLI 和 UI 文章的源系统不同，除非使用 --no-validation，否则不会冲突
• Slug 必须全局唯一——使用应用专属前缀（例如 my-app-getting-started）
• 切勿提交访问令牌——使用 az login 或流水线服务主体