system · 应用配置

import { SystemDomain } from '@hfyidu/api/system';

系统领域负责应用全局配置（应用信息、支付渠道配置）、底部导航栏（Tabbar）拉取、文件上传，以及应用运行错误上报，服务前缀 system。

用例总览

用例	说明	请求方式
SystemDomain.cases.appSetting	获取应用设置	GET system/appSetting
SystemDomain.cases.appTabbar	获取应用底部导航栏	GET system/appTabbar
SystemDomain.cases.report	上报应用运行错误	POST system/reportAppLog
SystemDomain.cases.upload	上传文件或图片	POST system/upload（uni.uploadFile）

appSetting · 获取应用设置

const { data } = await SystemDomain.cases.appSetting.run();

console.log(data); // SystemAppSettingDto

请求参数 SystemAppSettingQueryParams

该用例的请求参数类型固定为 null，即不需要任何查询参数，调用时可不传参数（或传 null）。

响应 SystemAppSettingDto

SystemAppSettingDto（不可变，@Freeze）

字段	类型	后台原始字段	说明
appKey	string	app_key	应用 Key，默认 ''
appName	string	app_name	应用名称，默认 ''
appPackageName	string	app_package	应用包名，默认 ''
appVersionName	string	app_version	应用版本号，默认 '1.0.0'
appType	AppType	app_type	应用类型，默认 AppType.QA
appId	string	mini_app_id	小程序 AppId，默认 ''
appSecret	string	mini_app_secret	小程序 AppSecret，默认 ''
config	SystemAppSettingConfigDto	—	应用扩展配置，默认新建一个 SystemAppSettingConfigDto 实例
domains	string	call_domain	请求域名列表的 JSON 字符串，默认 ''
requestDomains	any（getter）	—	对 domains 做 JSON.parse 后的运行时求值属性，非后台原始字段

SystemAppSettingConfigDto（不可变，@Freeze）

字段	类型	后台原始字段	说明
appName	string	name	应用展示名称，默认 ''
customerUrl	string	customer_url	客服链接，默认 ''
customerDouyin	string	customer_dy	抖音客服号，默认 '0'
customerWechat	string | null	customer_wechat	微信客服号，默认 null
customerQQ	string | null	customer_qq	QQ 客服号，默认 null
customerPhone	string | null	customer_phone	客服电话，默认 null
payOriginalType	number	pay_original_type	原生支付类型标识，默认 1
workingTime	string	working_time	客服工作时间，默认 ''
workType	string	work_type	工作类型，默认 ''
arpu	number	ad_close_arpu	关闭广告的 ARPU 阈值，默认 0
payType	SystemAppSettingConfigPayTypeDto[]	quickappAssignPay	快应用指定支付渠道列表，默认 []
mpPayType	SystemAppSettingConfigMpPayTypeDto[]	wechatMiniAssignPay	微信小程序指定支付渠道列表，默认 []
wechatOaPayType	SystemAppSettingConfigWechatOaPayTypeDto[]	wechatOaAssignPay	微信公众号指定支付渠道列表，默认 []
h5PayList	SystemAppSettingConfigH5PayListDto[]	h5AssignPay	H5 指定支付渠道列表，默认 []
servicesImage	string	services_image	客服图片，默认 ''
readListAdGaps	number	ad_section_num	小说滑动翻页时插入广告的段数，默认 10
readAdGaps	number	pre_read_ad_gaps	预留可配置字段：阅读间隔广告段数，默认 3
readAdCount	number	pre_read_ad_count	预留可配置字段：阅读广告次数，默认 0
adDwellTime	number	pre_ad_dwell_time	广告停留时间（秒），默认 3
payChannel	string	pay_channel	支付渠道标识，默认 'mhpay'

以下 4 个支付渠道子 DTO（payType / mpPayType / wechatOaPayType / h5PayList）字段结构完全一致，仅默认值不同，统一说明如下。其中 payType 字段与 payProvider 字段均引用 @hfyidu/api/order 领域（PayType、PayProvider）导出的枚举类型，非 system 领域自有类型，具体成员定义请查阅 order 领域文档。

SystemAppSettingConfigPayTypeDto（不可变，@Freeze，对应 quickappAssignPay）

字段	类型	后台原始字段	说明
type	number	assign_pay	指定支付类型数值，默认 1
payType	PayType	assign_pay	指定支付类型枚举，默认 PayType.MH_WX
provider	string	platform	支付平台代码，默认 'other'
payProvider	PayProvider	platform	支付平台枚举，默认 PayProvider.unknown
status	number	—	状态标记，默认 0

SystemAppSettingConfigMpPayTypeDto（不可变，@Freeze，对应 wechatMiniAssignPay）

字段	类型	后台原始字段	说明
type	number	assign_pay	指定支付类型数值，默认 1
payType	PayType	assign_pay	指定支付类型枚举，默认 PayType.MH_MP
provider	string	platform	支付平台代码，默认 'mhpay'
payProvider	PayProvider	platform	支付平台枚举，默认 PayProvider.mhpay
status	number	—	状态标记，默认 0

SystemAppSettingConfigWechatOaPayTypeDto（不可变，@Freeze，对应 wechatOaAssignPay）

字段	类型	后台原始字段	说明
type	number	assign_pay	指定支付类型数值，默认 1
payType	PayType	assign_pay	指定支付类型枚举，默认 PayType.MH_JSAPI
provider	string	platform	支付平台代码，默认 'mhpay'
payProvider	PayProvider	platform	支付平台枚举，默认 PayProvider.mhpay
status	number	—	状态标记，默认 0

SystemAppSettingConfigH5PayListDto（不可变，@Freeze，对应 h5AssignPay）

字段	类型	后台原始字段	说明
type	number	assign_pay	指定支付类型数值，默认 1
payType	PayType	assign_pay	指定支付类型枚举，默认 PayType.MH_WX
provider	string	platform	支付平台代码，默认 'mhpay'
payProvider	PayProvider	platform	支付平台枚举，默认 PayProvider.mhpay
status	number	—	状态标记，默认 0

appTabbar · 获取应用底部导航栏

const { data } = await SystemDomain.cases.appTabbar.run({
  provider_code: 'wxapp',
});

console.log(data); // SystemAppTabbarDto[]

请求参数 SystemAppTabbarQueryParams

字段	类型	必填	说明
provider_code	string	否	广告/渠道平台代码

响应 SystemAppTabbarDto[]

SystemAppTabbarDto（支持 @List，即 SystemAppTabbarDto.toList 批量转换）

字段	类型	后台原始字段	说明
name	string	pagePath	导航项标识（与 pagePath 同源），默认 ''
title	string	text	导航项标题（与 text 同源），默认 ''
icon	string	—	图标，默认 ''
iconPath	string	—	未选中态图标路径，默认 ''
selectedIconPath	string	—	选中态图标路径，默认 ''
pagePath	string	—	页面路径，默认 ''
text	string	—	文案，默认 ''
pageParams	string	—	页面参数（JSON 字符串），默认 '{}'
render	boolean	—	是否渲染，运行时状态字段，默认 false
active	boolean	—	是否激活，运行时状态字段，默认 false
sort	number	—	排序值，默认 0
value	number	sort	与 sort 同源的唯一标识值，默认 0

report · 上报应用运行错误

await SystemDomain.cases.report.run({
  title: '页面渲染异常',
  content: { stack: 'Error: xxx' },
  level: 'error',
});

请求参数 SystemReportBodyParams

字段	类型	必填	说明
title	any	否	上报标题
content	any	否	上报内容详情
level	'warn' | 'error'	是	上报级别

响应

无格式化 DTO，直接透传后台原始返回（any）。

upload · 上传文件

该用例通过 uni-app 的 uni.uploadFile 发起 multipart/form-data 文件上传，而不是普通的 httpApi.request。上传请求会自动复用 httpApi 的请求地址和鉴权请求头。

const { data } = await SystemDomain.cases.upload.run({
  file: tempFilePath,
  onProgress(progress) {
    console.log(`上传进度：${progress}%`);
  },
});

console.log(data?.url); // 服务端返回的远程文件地址

请求参数 SystemUploadBodyParams

字段	类型	必填	说明
file	string	是	uni-app 选择文件后返回的本地临时路径，传给 uni.uploadFile.filePath
name	string	否	服务端接收文件的字段名，默认 'file'
onProgress	(progress: number) => void	否	上传进度回调，progress 取值范围为 0-100

响应 SystemUploadDto

字段	类型	后台原始字段	说明
url	string	url	上传成功后的远程文件地址，必填

上传错误处理

HTTP 状态码不是 200、响应无法解析，或后台业务码不是成功状态时，run() 返回的 Promise 会被拒绝。建议在业务侧使用 try/catch 处理失败状态。上传进度由底层 UploadTask.onProgressUpdate 回传。

使用案例：wd-upload 多图逐张上传

下面的案例提炼自 playground 的个人档案页面。它通过 wd-upload 选择和预览多张图片，再由 SystemDomain.cases.upload 逐张上传：

• 排队期间显示“待上传”，当前任务显示进度；
• 每张图片上传完成后才开始下一张，避免并发上传；
• file.url 保留本地临时地址，保证即时展示和预览；
• 服务端返回的持久化地址保存在自定义属性 file.remote；
• 所有任务结束后统一提示成功和失败数量。

先创建可复用的上传工厂：

import type { UploadFileItem, UploadMethod } from '@wot-ui/ui/components/wd-upload/types';
import { SystemDomain } from '@hfyidu/api/system';
import { ref } from 'vue';

type ImageFile = UploadFileItem & {
  remote?: string;
};

export function useFileUpload() {
  const uploadUseCase = SystemDomain.cases.upload;
  const uploadFiles = ref<ImageFile[]>([]);
  const queuedIds = new Set<number>();
  let uploadQueue = Promise.resolve();
  let queueVersion = 0;

  function watchQueueFinished() {
    const currentVersion = ++queueVersion;
    const currentQueue = uploadQueue;

    void currentQueue.finally(() => {
      // 后续仍有任务加入时，旧的队尾监听不触发完成提示。
      if (currentVersion !== queueVersion || currentQueue !== uploadQueue) return;

      const successCount = uploadFiles.value.filter(file => file.status === 'success').length;
      const failCount = uploadFiles.value.filter(file => file.status === 'fail').length;

      uni.showToast({
        icon: failCount > 0 ? 'none' : 'success',
        title:
          failCount > 0 ? `上传完成：成功 ${successCount} 张，失败 ${failCount} 张` : `成功上传 ${successCount} 张图片`,
      });
    });
  }

  const customUpload: UploadMethod = (file, formData, options) => {
    // wd-upload 可能重复扫描 pending 文件，避免同一文件多次入队。
    if (queuedIds.has(file.uid)) {
      file.status = 'pending';
      return;
    }

    queuedIds.add(file.uid);
    file.status = 'pending';

    const upload = uploadQueue.then(async () => {
      file.status = 'loading';
      options.onProgress({ progress: 0, totalBytesSent: 0, totalBytesExpectedToSend: 0 }, file);

      try {
        const { data } = await uploadUseCase.run({
          file: file.url,
          onProgress(progress) {
            options.onProgress({ progress, totalBytesSent: 0, totalBytesExpectedToSend: 0 }, file);
          },
        });

        if (!data?.url) throw new Error('服务端未返回图片地址');

        // 本地 url 继续用于预览，远程地址单独保存。
        const imageFile = file as ImageFile;
        imageFile.remote = data.url;
        options.onSuccess({ data: JSON.stringify(data), statusCode: 200, header: {} }, file, formData);
      } catch (error) {
        const errMsg = error instanceof Error ? error.message : '图片上传失败';
        options.onError({ errMsg }, file, formData);
      } finally {
        queuedIds.delete(file.uid);
      }
    });

    // 当前任务成为新队尾，下一张图片等待它结束后再执行。
    uploadQueue = upload.catch(() => undefined);
    watchQueueFinished();
    return upload;
  };

  function getUploadStatusText(file: UploadFileItem) {
    if (file.status === 'loading') return `上传中 ${file.percent ?? 0}%`;
    if (file.status === 'success') return '上传完成';
    if (file.status === 'fail') return '上传失败';
    return '待上传';
  }

  return { customUpload, getUploadStatusText, uploadFiles };
}

在页面中绑定上传工厂：

<script setup lang="ts">
import { useFileUpload } from '@/composables/useFileUpload';

const { customUpload, getUploadStatusText, uploadFiles } = useFileUpload();
</script>

<template>
  <wd-upload
    v-model:file-list="uploadFiles"
    accept="image"
    image-mode="aspectFill"
    name="file"
    multiple
    :limit="9"
    :max-size="5 * 1024 * 1024"
    :upload-method="customUpload"
  >
    <template #preview-cover="{ file }">
      <view class="absolute inset-x-0 bottom-0 bg-black/55 py-1 text-center text-white">
        {{ getUploadStatusText(file) }}
      </view>
    </template>
  </wd-upload>
</template>

工厂必须在页面实例中调用

不要把 uploadFiles、uploadQueue 或去重集合声明成模块级单例。通过 useFileUpload() 为每个页面实例创建独立状态，页面销毁后再次进入时才不会继承上一次的上传列表。

枚举

AppType 应用类型

枚举成员	value	code	说明
H5	0	H5	网页端
WXGZH	1	WechatOa	微信公众号网页
WXAPP	2	WechatApp	微信小程序
QA	3	QuickApp	快应用
Android	4	Android	安卓 APP
IOS	5	IOS	苹果 APP
DouyinApp	6	DouyinApp	抖音小程序
KuaishouApp	7	KuaishouApp	快手小程序

TabbarItem 导航项类型

该类型定义在 enum/tabbar_type.ts 中，实际是一个纯 TypeScript 接口（interface），并非继承 BaseEnumeration 的业务枚举，这里为保持目录归属完整性一并收录。它描述了单个 Tabbar 导航项的完整字段形态，与 SystemAppTabbarDto 字段基本一一对应，可用于业务侧自定义 Tabbar 状态管理时的类型标注。

字段	类型	说明
name	string	导航项标识
value	number | null	排序/唯一标识值
active	boolean	是否激活
title	string	导航项标题
icon	string	图标
pagePath	string	页面路径
iconPath	string	未选中态图标路径
selectedIconPath	string	选中态图标路径
text	string	文案
sort	number	排序值
render	boolean	是否渲染