按场景接入

Use Cases

我要完成一个业务任务，应该看哪些文档？

这页按真实接入任务组织入口。新同事不需要先理解所有包，只要找到当前任务，再按顺序阅读对应组件、数据结构、事件和前置条件。

工程前置条件业务组件数据结构

场景总览

我要做什么	先看	再看	需要注意
使用按钮、弹窗、输入框	基础 UI	@mbjia/ui	适合低业务依赖页面。
选择素材或管理素材	素材管理弹窗	素材选择弹窗、数据结构	需要 @mbjia/manager 和素材接口权限。
上传图片、视频、文件夹	全局上传	上传数据、@mbjia/upload-manager	需要 SharedWorker、OSS token、素材创建接口。
做 AI 搜索	AI 搜索	服务接口、事件协议	输入组件是富文本标签输入，不是普通 Input。
做支付、会员、点数拦截	支付与权益	业务 Hooks、服务接口	需要用户信息、权益接口、订单状态接口。
做视频拆条或抓取	媒体流程	服务接口、事件协议	通常由流程组件统一编排，不建议散用弹窗。
做脚本选择或 AI 生成脚本	媒体流程	AI 搜索	涉及脚本素材模型和 ScriptInfo。
用 Hooks 复用逻辑	Hooks 总览	状态类、异步类、DOM 类	业务 Hooks 不建议脱离模板加业务环境。
调接口	服务接口	公共数据结构	统一响应结构和取消请求能力在服务接口页。
用工具函数处理文件/URL	@mbjia/utils	上传数据	工具函数较多，按场景查表。
做编辑器底层能力	编辑器包	现有编辑器页面源码	这是高级 SDK，不建议新页面直接从这里开始。

场景一：接入素材选择

确认业务依赖

先读 工程前置条件，确认登录态、接口域名、Less、CSS Modules、styled-components 和 AntD 样式。

选择组件

需要完整素材管理弹窗时用 AssetManagementModal；只需要素材/音乐选择弹窗时看 AssetModal / MusicModal。

准备数据结构

素材类型、素材模型、目录模型和搜索参数统一看 公共数据结构。

最小路径：

import { AssetManagementModal } from '@mbjia/components'
import { MbjiaApiManager } from '@mbjia/manager'

const apiManager = new MbjiaApiManager()

<AssetManagementModal
  open={open}
  mode="select"
  baseApiManager={apiManager}
  onClose={() => setOpen(false)}
  onConfirm={(assets) => console.log(assets)}
/>

场景二：接入全局上传

选择文件/文件夹→校验格式和大小→OSS 上传→创建素材并刷新列表

阅读顺序：

步骤	文档	看什么
1	全局上传	组件用法、事件、失败弹窗、目录上传结构。
2	上传数据	SXMeta、上传选项、OSS 返回结构。
3	@mbjia/upload-manager	SharedWorker、Uppy 事件、IndexedDBStore。
4	工程前置条件	SharedWorker 路径和构建配置。

场景三：接入 AI 搜索

<AiSearch
  afterOptions={afterOptions}
  SearchPlaceHolder="输入画面描述、字幕或标签"
  eventBus={eventBus}
  onSearch={(params) => {
    console.log(params.searchType, params.searchRange, params.searchValue)
  }}
/>

查阅点：

文档	内容
AI 搜索	AiSearch、InputTextAndTags、AICreateScript。
事件协议	AiSearch:searchActive、global:searchAll、aiSearch:restAllData 等事件。
服务接口	AI 搜索任务创建、提交和轮询接口。

场景四：接入权益拦截

权益相关组件通常不应该散落在页面里临时拼装，优先复用流程组件。

用户行为	推荐入口	说明
下载或发布前确认次数	支付与权益	DownloadConfirmModal、PublishConfirmModal。
点数不足	支付与权益	NotEnoughVideoPointsMemo、PurchasePointsMemo 等。
通用权益不足	支付与权益	GeneralInterestsModalMemo。
业务 Hook 处理权益错误	业务 Hooks	usePromiseErrorHandler、useVerifySubscription。

场景五：接入视频处理

任务	推荐组件	文档
视频下载流程	MbjiaDownloadFlow	媒体流程
镜头拆分	MediaSplittingFlow	媒体流程
视频抓取	VideoCaptureFlow	媒体流程
分段时间轴	SegmentedProgressBar	媒体流程
视频裁剪	VideoClipper	媒体流程

场景六：维护或新增组件文档

新增组件后按这个顺序处理：

1. 确认是否从包入口导出。
2. 在对应模块页补使用示例、Props、回调、数据结构、事件和注意事项。
3. 如果是核心流程，补效果预览或流程预览。
4. 执行 pnpm docs:check。
5. 执行 pnpm docs:build。

维护规范见 文档维护。