Onboarding 配置 运营配置 · 用户视角 · 技术方案

保存0

发布0

下线0

ID	Campaign 名称	业务方	src	CTA 业务编码	更新时间	操作

共 0 条

📌 开发对照说明

ID：由后端在 campaign 第一次保存时自动生成（建议格式 ob_ + 12 位短哈希），前端展示为只读字段。
状态机：保存(saved) → 点击「发布」 → 发布(published) → 点击「下线」 → 下线(offline) → 点击「重新发布」 → 发布(published)。
src：字符串标识，由用户自由输入（如 global_ads_sourcing），不再是枚举。
CTA 业务编码：由 CTA 列表中的 bizValue 承载，用于 CTA 行为与列表展示；技术模型不再保留顶层 plugin 字段。
编辑已发布配置：需弹二次确认（"修改后会下线当前线上版本"）。确认后：① 该配置自动从 published 流转到 saved；② 列表线上版本同步消失；③ 用户继续在编辑弹窗中改动并保存。
下线状态保护：下线后不允许编辑、不允许删除，只能预览或重新发布。
预览：三种状态都可预览，弹出 onboarding 真实形态（图 + 标题 + 正文 + CTA），无须保存即可查看效果。
视角切换：顶部 tab 可切到「用户视角」，看到 onboarding 弹窗在 Accio Work 应用内的真实呈现，便于运营 / 设计 / 开发对齐落地效果。

状态 / 操作	预览	编辑	发布	下线	重新发布	删除
保存	✓	✓	✓	—	—	✓
发布	✓	✓ （二次确认）	—	✓	—	—
下线	✓	—	—	—	✓	—

Accio Work

插件

发现并安装插件，扩展你的工作能力。

跨境电商

Alibaba
.com

国际站生意助手

为阿里巴巴国际站跨境商家提供从选品、发品...

Startup Competition

CO
CREATE
PITCH

CoCreate Pitch Assistant

The official AI Assistant for CoCreate Pitch 20...

图片预览区

Onboarding 标题

Onboarding 正文…

👤 用户视角说明

该视图仅用于 预览 / 验收 / 走查，不会触发任何线上行为。
右上角 campaign 下拉可切换不同配置（已合并 saved / published / offline 三态），方便对比文案与图片效果。
关闭弹窗后可点击 「重新触发」 重新弹出，便于反复检查。
实际线上触发时机：用户首次进入指定 src 的页面 → 加载该 src 对应的 published 配置 → 弹窗展示 → 用户点击 CTA 或 ✕ 后写入"已展示"状态，下次不再弹出。

Onboarding 接口技术方案

收拢页面原型与接口契约：管理端按 5 个 CRUD 接口设计，用户侧 active 查询仅 src 必传。

1. 前端 UI 层 TS 类型

为提升扩展性，配置模型只保留 id、name、owner、src 四个核心字段；展示内容统一进入 content[]，每组内容内包含自己的 ctaList[]，不再保留顶层 plugin 字段。

export type OnboardingStatus = 'saved' | 'published' | 'offline';
export type BizType = 'plugin' | 'skill' | 'link';
export type CtaButtonType = 'primary' | 'default';

export interface ContentItem {
  image: string;
  title: string;
  content: string;
  ctaList: CtaConfig[];
  extra?: Record<string, unknown>;
}

export interface CtaConfig {
  btnType: CtaButtonType;
  btnText: string;
  bizType: BizType;
  bizValue: string;
  bizParams: string;
  sort: number;
}

export interface OnboardingCampaign {
  id: string;
  name: string;
  owner: string;
  src: string;
  content: ContentItem[];
}

export interface OnboardingCampaignRecord extends OnboardingCampaign {
  status: OnboardingStatus;
  createdAt: string;
  updatedAt: string;
  publishedAt: string | null;
  offlineAt: string | null;
}

export interface SaveOnboardingCampaignRequest {
  name: string;
  owner: string;
  src: string;
  content: ContentItem[];
}

export type OnboardingUpdateOperation = 'save' | 'publish' | 'offline';

export interface UpdateOnboardingCampaignRequest {
  operation: OnboardingUpdateOperation;
  campaign?: SaveOnboardingCampaignRequest; // operation=save 时必传
}

export interface PageResult<T> {
  pageNo: number;
  pageSize: number;
  total: number;
  list: T[];
}

export interface ApiResult<T> {
  success: boolean;
  code: string;
  message: string;
  data: T;
}

2. 管理端接口

管理端接口收敛为 5 个：增、删、改、查详情、查列表。编辑保存态、编辑已发布、发布、下线、重新发布都走同一个“改”接口。

2.1 接口总览

场景	方法	路径	入参	返回值
列表查询	`GET`	`/api/admin/onboarding-campaigns`	`status`、`keyword`、`pageNo`、`pageSize`	`ApiResult<PageResult<OnboardingCampaignRecord>>`
详情查询	`GET`	`/api/admin/onboarding-campaigns/{id}`	`id`	`ApiResult<OnboardingCampaignRecord>`
创建配置	`POST`	`/api/admin/onboarding-campaigns`	`SaveOnboardingCampaignRequest`	`ApiResult<OnboardingCampaignRecord>`
更新配置 / 状态操作	`PUT`	`/api/admin/onboarding-campaigns/{id}`	`id` + `UpdateOnboardingCampaignRequest`	`ApiResult<OnboardingCampaignRecord>`
删除	`DELETE`	`/api/admin/onboarding-campaigns/{id}`	`id`	`ApiResult<boolean>`

2.2 列表查询

GET/api/admin/onboarding-campaigns

参数	类型	必填	说明
`status`	`saved \| published \| offline`	是	当前 tab 状态。
`keyword`	`string`	否	搜索 Campaign 名称 / src / 业务方；CTA 业务编码可由服务端在 `ctaList.bizValue` 中匹配。
`pageNo`	`number`	是	页码，从 1 开始。
`pageSize`	`10 \| 20 \| 50`	是	每页条数。

GET /api/admin/onboarding-campaigns?status=saved&keyword=supplier&pageNo=1&pageSize=10

{
  "success": true,
  "code": "SUCCESS",
  "message": "OK",
  "data": {
    "pageNo": 1,
    "pageSize": 10,
    "total": 1,
    "list": [
      {
        "id": "ob_2k9f3z2a8b3c",
        "name": "新用户首次进入引导",
        "owner": "Growth 团队",
        "src": "global_ads_sourcing",
        "content": [
          {
            "image": "https://img.alicdn.com/imgextra/i1/O1CN01foyLx61dsmzKu0tdk_!!6000000003792.png",
            "title": "发现优质供应商，从这里开始",
            "content": "Accio 帮你筛选经过验证的供应商，节省你的时间。点击下方按钮开启第一次智能搜索。",
            "ctaList": [
              {
                "btnType": "primary",
                "btnText": "安装并使用",
                "bizType": "plugin",
                "bizValue": "supplier_sourcing",
                "bizParams": "",
                "sort": 1
              }
            ],
            "extra": {}
          }
        ],
        "status": "saved",
        "createdAt": "2026-05-09 14:22:00",
        "updatedAt": "2026-05-09 14:22:00",
        "publishedAt": null,
        "offlineAt": null
      }
    ]
  }
}

2.3 详情查询

GET/api/admin/onboarding-campaigns/{id}

GET /api/admin/onboarding-campaigns/ob_2k9f3z2a8b3c

{
  "success": true,
  "code": "SUCCESS",
  "message": "OK",
  "data": {
    "id": "ob_2k9f3z2a8b3c",
    "name": "新用户首次进入引导",
    "owner": "Growth 团队",
    "src": "global_ads_sourcing",
    "content": [
      {
        "image": "https://img.alicdn.com/imgextra/i1/O1CN01foyLx61dsmzKu0tdk_!!6000000003792.png",
        "title": "发现优质供应商，从这里开始",
        "content": "Accio 帮你筛选经过验证的供应商，节省你的时间。点击下方按钮开启第一次智能搜索。",
        "ctaList": [
          {
            "btnType": "primary",
            "btnText": "安装并使用",
            "bizType": "plugin",
            "bizValue": "supplier_sourcing",
            "bizParams": "",
            "sort": 1
          },
          {
            "btnType": "default",
            "btnText": "了解更多",
            "bizType": "link",
            "bizValue": "https://www.accio.com/help/supplier-sourcing",
            "bizParams": "utm_source=onboarding",
            "sort": 2
          }
        ],
        "extra": {}
      }
    ],
    "status": "saved",
    "createdAt": "2026-05-09 14:22:00",
    "updatedAt": "2026-05-09 14:22:00",
    "publishedAt": null,
    "offlineAt": null
  }
}

2.4 创建配置

POST/api/admin/onboarding-campaigns

字段	类型	必填	规则 / 说明
`name`	`string`	是	1-60 字符，Campaign 名称。
`owner`	`string`	是	1-40 字符，业务方。
`src`	`string`	是	来源场景，不是枚举；创建接口必须校验全局唯一。
`content`	`ContentItem[]`	是	展示内容数组，单项内保持 `image`、`title`、`content` 平铺字段，并包含该内容对应的 `ctaList`。

{
  "name": "新用户首次进入引导",
  "owner": "Growth 团队",
  "src": "global_ads_sourcing",
  "content": [
    {
      "image": "https://img.alicdn.com/imgextra/i1/O1CN01foyLx61dsmzKu0tdk_!!6000000003792.png",
      "title": "发现优质供应商，从这里开始",
      "content": "Accio 帮你筛选经过验证的供应商，节省你的时间。点击下方按钮开启第一次智能搜索。",
      "ctaList": [
        {
          "btnType": "primary",
          "btnText": "安装并使用",
          "bizType": "plugin",
          "bizValue": "supplier_sourcing",
          "bizParams": "",
          "sort": 1
        }
      ],
      "extra": {}
    }
  ]
}

2.5 更新配置 / 状态操作

PUT/api/admin/onboarding-campaigns/{id}

该接口统一承载“编辑保存态、编辑已发布、发布、重新发布、下线”。发布时后端需校验：同一 src 只能存在一条 published 配置。

operation	业务含义	允许状态	目标状态	campaign 是否必传
`save`	编辑保存态配置	`saved`	`saved`	是
`save`	编辑已发布配置	`published`	`saved`	是
`publish`	发布	`saved`	`published`	否
`publish`	重新发布	`offline`	`published`	否
`offline`	下线	`published`	`offline`	否

{
  "operation": "save",
  "campaign": {
    "name": "新用户首次进入引导",
    "owner": "Growth 团队",
    "src": "global_ads_sourcing",
    "content": [
      {
        "image": "https://img.alicdn.com/imgextra/i1/O1CN01foyLx61dsmzKu0tdk_!!6000000003792.png",
        "title": "发现优质供应商，从这里开始",
        "content": "Accio 帮你筛选经过验证的供应商，节省你的时间。点击下方按钮开启第一次智能搜索。",
        "ctaList": [
          {
            "btnType": "primary",
            "btnText": "安装并使用",
            "bizType": "plugin",
            "bizValue": "supplier_sourcing",
            "bizParams": "",
            "sort": 1
          }
        ],
        "extra": {}
      }
    ]
  }
}

{
  "operation": "publish"
}

2.6 删除配置

DELETE/api/admin/onboarding-campaigns/{id}

仅允许删除 saved 状态配置；published 需先下线或编辑回保存态，offline 不允许删除。

DELETE /api/admin/onboarding-campaigns/ob_2k9f3z2a8b3c

{
  "success": true,
  "code": "SUCCESS",
  "message": "OK",
  "data": true
}

3. 用户侧接口

用户侧只消费 published 配置。进入指定业务场景时只按 src 查询是否需要展示。

3.1 查询当前用户是否展示 Onboarding

GET/api/onboarding/campaign/active

参数	类型	必填	说明
`src`	`string`	是	当前页面或入口来源。

GET /api/onboarding/campaign/active?src=global_ads_sourcing

export interface UserOnboardingResponse {
  shouldShow: boolean;
  exposureKey: string | null;
  campaign: OnboardingCampaignRecord | null;
}

{
  "success": true,
  "code": "SUCCESS",
  "message": "OK",
  "data": {
    "shouldShow": true,
    "exposureKey": "u_10001:ob_2k9f3z2a8b3c",
    "campaign": {
      "id": "ob_2k9f3z2a8b3c",
      "name": "新用户首次进入引导",
      "owner": "Growth 团队",
      "src": "global_ads_sourcing",
      "content": [
        {
          "image": "https://img.alicdn.com/imgextra/i1/O1CN01foyLx61dsmzKu0tdk_!!6000000003792.png",
          "title": "发现优质供应商，从这里开始",
          "content": "Accio 帮你筛选经过验证的供应商，节省你的时间。点击下方按钮开启第一次智能搜索。",
          "ctaList": [
            {
              "btnType": "primary",
              "btnText": "安装并使用",
              "bizType": "plugin",
              "bizValue": "supplier_sourcing",
              "bizParams": "",
              "sort": 1
            }
          ],
          "extra": {}
        }
      ],
      "status": "published",
      "createdAt": "2026-05-09 14:22:00",
      "updatedAt": "2026-05-11 11:40:00",
      "publishedAt": "2026-05-11 11:40:00",
      "offlineAt": null
    }
  }
}

{
  "success": true,
  "code": "SUCCESS",
  "message": "OK",
  "data": {
    "shouldShow": false,
    "exposureKey": null,
    "campaign": null
  }
}

3.2 上报曝光 / 关闭 / CTA 点击

POST/api/onboarding/exposures

export type OnboardingExposureAction = 'show' | 'close' | 'cta_click';

export interface OnboardingExposureRequest {
  campaignId: string;
  exposureKey: string;
  src: string;
  action: OnboardingExposureAction;
  ctaType?: CtaButtonType;
  clientTime: string;
}

{
  "campaignId": "ob_2k9f3z2a8b3c",
  "exposureKey": "u_10001:ob_2k9f3z2a8b3c",
  "src": "global_ads_sourcing",
  "action": "cta_click",
  "ctaType": "primary",
  "clientTime": "2026-05-11 11:42:00"
}

{
  "success": true,
  "code": "SUCCESS",
  "message": "OK",
  "data": true
}

4. 返回码约定

code	场景	前端处理
`SUCCESS`	请求成功	正常渲染或刷新列表。
`INVALID_PARAM`	字段为空、长度超限、枚举非法、URL 非法	提示具体字段错误。
`SRC_ALREADY_EXISTS`	创建或保存时 `src` 已存在	将 src 输入框标红，并提示更换唯一 src。
`CAMPAIGN_NOT_FOUND`	配置不存在	提示后刷新列表。
`STATUS_NOT_ALLOWED`	当前状态不允许该操作	提示状态已变化并刷新列表。
`PUBLISHED_SCENE_CONFLICT`	同一 `src` 已存在 published 配置	提示先下线冲突配置。

已保存

Onboarding 配置管理

📌 开发对照说明

插件

跨境电商

国际站生意助手

Startup Competition

CoCreate Pitch Assistant

Onboarding 标题

👤 用户视角说明

Onboarding 接口技术方案

1. 前端 UI 层 TS 类型

2. 管理端接口

2.1 接口总览

2.2 列表查询

2.3 详情查询

2.4 创建配置

2.5 更新配置 / 状态操作

2.6 删除配置

3. 用户侧接口

3.1 查询当前用户是否展示 Onboarding

3.2 上报曝光 / 关闭 / CTA 点击

4. 返回码约定

添加 Onboarding 配置

基础信息

Onboarding 内容

Onboarding 预览

Onboarding 标题

确认操作