order · 订单/支付

import { OrderDomain } from '@hfyidu/api/order'

订单/支付领域负责商品列表拉取、权益商品拉取、下单、订单查询、微信小程序虚拟支付及其支付成功回调，服务前缀 order。

用例总览

用例	说明	请求方式
`OrderDomain.cases.products`	获取商品列表	`GET order/products`
`OrderDomain.cases.benefits`	获取权益（免广告）商品列表	`GET order/equity`
`OrderDomain.cases.query`	查询订单支付状态	`GET order/query`
`OrderDomain.cases.wxVirtualPay`	微信小程序虚拟支付下单	`POST order/VirtualPayOrder`
`OrderDomain.cases.wxVirtualPaySuccess`	微信小程序虚拟支付成功回调	`POST order/VirtualPayOrderSuccess`
`OrderDomain.cases.create`	创建订单（通用下单）	`POST order`

products 与 benefits 两个用例继承自 ModuleUseCase（区别于 query/wxVirtualPay/wxVirtualPaySuccess/create 所继承的 BaseUseCase），但两者都是一次性请求，调用方式与响应结构（{ data, updatedAt }）与普通 BaseUseCase 用例完全一致，不涉及分页状态，本领域下没有继承 PaginatorUseCase 的用例。

`products` · 获取商品列表

const { data } = await OrderDomain.cases.products.run({
  page_type: PayPageType.VIDEO.value,
})

console.log(data) // OrderProductsDto[]

请求参数 `OrderProductsQueryParams`

字段	类型	必填	说明
`page_type`	`PayPageType['value']`（即 `number`）	是	当前发起下单的页面场景
`class_code`	`string`	否	商品分类编码，用于筛选指定分类下的商品
`length_category`	`NovelType['value']`（即 `number`）	否	小说篇幅分类，仅在 `page_type` 为阅读页场景时生效

响应 `OrderProductsDto[]`

OrderProductsDto

字段	类型	后台原始字段	说明
`id`	`number \| string`	`id`	商品 ID，必填
`productType`	`ProductType`	`product_type`	商品大类，默认 `ProductType.coins`
`type`	`ProductType`	`product_type`	与 `productType` 同源，默认 `ProductType.coins`
`class`	`string`	`class_code`	商品细分类编码（字符串形式），默认 `''`
`productClass`	`ProductClass`	`class_code`	商品细分类，默认 `ProductClass.COINS`
`vipDays`	`number`	`get_member_days`	兑换的会员天数，默认 `0`
`coins`	`number`	`get_coin`	兑换的币数量，默认 `0`
`coupons`	`number`	`give_num`	额外赠送的券数量，默认 `0`
`name`	`string`	`product_name`	商品名称，默认 `''`
`describe`	`string`	`product_describe`	商品描述，默认 `''`
`price`	`string`	`price`	商品价格（字符串形式），默认 `'0.00'`
`pivot`	`OrderProductsStyleDto`	—	商品展示样式配置，默认新建一个 `OrderProductsStyleDto` 实例
`wxGoodsKey`	`string`	`virtually_good_id`	微信虚拟支付商品 Key，默认 `''`
`wxGoodsId`	`number`	`virtually_id`	微信虚拟支付商品 ID，默认 `0`
`wxGoodsIcon`	`string`	`virtually_item_url`	微信虚拟支付商品图标地址，默认 `''`
`templateId`	`number`	`template_id`	模板 ID，默认 `0`
`templateNumber`	`number`	`template_number`	模板编号，默认 `0`
`__tagInfo`	`OrderProductsTagInfoDto`	—	角标标签信息，默认新建一个 `OrderProductsTagInfoDto` 实例
`customStyle`	`Record<string, any>`	—	非后台字段，由实例方法 `convert()` 在本地计算填充，用于自定义展示样式

OrderProductsDto 还额外提供若干便捷计算属性（非后台原始字段）：bgStyle/textStyle（读取 pivot.style 的展示样式）、tagInfo（角标信息，优先取 pivot.style.tagInfo，否则回退 __tagInfo.tagInfo）、isVip/groupKey/obtain/give/desc（基于 productType 派生的业务文案）、mpLayout（组装出小程序展示所需的 MpLayoutProps 结构）。

OrderProductsStyleDto

字段	类型	说明
`style`	`OrderProductsStylePivotDto`	具体样式字段，默认新建一个 `OrderProductsStylePivotDto` 实例

OrderProductsStylePivotDto

字段	类型	后台原始字段	说明
`tagText`	`string \| null`	`tag`	角标文案，默认 `null`
`tagBgColor`	`string \| null`	`tag_bg_color`	角标背景色，默认 `null`
`tagTextColor`	`string \| null`	`tag_color`	角标文字颜色，默认 `null`
`tagIcon`	`string \| null`	`tag_icon`	角标图标地址，默认 `null`
`productBgColor`	`string \| null`	`product_bg_color`	商品卡片背景色，默认 `null`
`productBgImg`	`string \| null`	`product_bg_img`	商品卡片背景图，默认 `null`
`productPriceColor`	`string \| null`	`product_price_color`	商品价格文字颜色，默认 `null`

提供计算属性 bgStyle/textStyle（拼接内联样式字符串）与 tagInfo（组装为 OrderProductTagProps 结构，仅当 tagText 存在时返回，否则为 null）。

OrderProductsTagInfoDto

字段	类型	后台原始字段	说明
`bgColor`	`string \| null`	`bg_color`	角标背景色，默认 `null`
`color`	`string \| null`	`color`	角标文字颜色，默认 `null`
`icon`	`string \| null`	`icon`	角标图标地址，默认 `null`
`tag`	`string \| null`	`tag`	角标文案，默认 `null`
`sort`	`number`	`sort`	排序值，默认 `0`

提供计算属性 tagInfo：仅当 tag 存在时组装为 OrderProductTagProps 结构，否则为 null。

`benefits` · 获取权益商品列表

const { data } = await OrderDomain.cases.benefits.run({
  page_type: PayPageType.READER.value,
})

console.log(data) // OrderBenefitsDto[]

请求参数 `OrderBenefitsQueryParams`

字段	类型	必填	说明
`page_type`	`PayPageType['value']`（即 `number`）	是	当前发起下单的页面场景

响应 `OrderBenefitsDto[]`

OrderBenefitsDto

字段	类型	后台原始字段	说明
`id`	`number \| string`	`id`	权益商品 ID，必填
`type`	`number`	`product_type`	商品类型原始数值（对应 `ProductType` 枚举 `value`，未做类型转换）
`code`	`string`	`class_code`	权益分类编码，默认 `''`
`days`	`number`	`num`	权益使用天数，默认 `0`
`price`	`string`	`price`	商品价格（字符串形式），默认 `'0.00'`
`name`	`string`	`product_name`	商品名称，默认 `''`
`describe`	`string`	`product_describe`	商品描述，默认 `''`
`sort`	`number`	`sort`	排序值，默认 `0`
`createdAt`	`string`	`created_at`	创建时间，默认 `'2099-12-31'`
`pivot`	`OrderProductsStyleDto`	—	商品展示样式配置，默认新建一个 `OrderProductsStyleDto` 实例（与 `products` 用例共用同一 DTO）
`__tagInfo`	`OrderProductsTagInfoDto`	—	角标标签信息，默认新建一个 `OrderProductsTagInfoDto` 实例（与 `products` 用例共用同一 DTO）

同样提供便捷计算属性：bgStyle/textStyle/tagInfo（含义与 OrderProductsDto 一致）、desc（当 type 等于 ProductType.benefit.value 时返回“免广告权益”，否则返回“不能适用与免除广告”）。

`query` · 查询订单支付状态

const { data } = await OrderDomain.cases.query.run({
  order_no: '202601010000001',
})

console.log(data) // OrderQueryDto

请求参数 `OrderQueryQueryParams`

字段	类型	必填	说明
`order_no`	`string`	是	待查询的订单号

响应 `OrderQueryDto`（不可变，`@Freeze`）

字段	类型	后台原始字段	说明
`id`	`number \| string`	`id`	订单主键 ID，必填
`uid`	`number \| string`	`uid`	下单用户 ID，无装饰器、无默认值
`orderNo`	`string`	`order_no`	订单号，默认 `''`
`spreadId`	`number \| string`	`spread_id`	推广 ID，默认 `0`
`orderStatus`	`OrderStatus`	`pay_status`	订单支付状态，默认 `OrderStatus.UNPAID`
`payType`	`PayType`	`pay_type`	支付方式，默认 `PayType.MH_WX`
`productType`	`ProductType`	`product_type`	商品大类，默认 `ProductType.coins`
`sourceType`	`PaySourceType`	`source_term`	支付来源场景，默认 `PaySourceType.THEATRE`

request_params/order_query_query_params.ts 中还额外导出了一个非请求体类型 OrderQueryCallbackParams（{ payCompleted: boolean; productType: ProductType }），随该领域一并对外暴露，供业务代码约定“支付结果回调”场景下的参数结构使用，不对应任何后台接口。

`wxVirtualPay` · 微信小程序虚拟支付下单

const { data } = await OrderDomain.cases.wxVirtualPay.run({
  code: 'wx_login_code_xxx',
  product_id: 1001,
})

console.log(data) // OrderWxVirtualPayDto

请求参数 `OrderWxVirtualPayBodyParams`

字段	类型	必填	说明
`code`	`string`	否	微信登录票据
`product_id`	`number`	是	商品 ID
`product_type`	`ProductGroup['value']`（即 `number`）	否	商品前端分组（`coins`/`vip`）
`theatre_id`	`number \| string`	否	短剧 ID
`theatre_title`	`string`	否	短剧标题
`theatre_collect_id`	`number \| string`	否	短剧合集 ID
`theatre_collect_number`	`number \| string`	否	短剧合集编号
`source_term`	`PaySourceType['value']`（即 `number`）	否	支付来源场景
`book_name`	`string`	否	小说名称
`book_id`	`number`	否	小说 ID
`book_chapter_id`	`number \| string`	否	小说章节 ID
`book_chapter_number`	`number \| string`	否	小说章节编号
`template_id`	`number`	否	模板 ID
`template_number`	`number`	否	模板编号
`pay_type`	`number`	否	支付方式（对应 `PayType` 枚举 `value`）

响应 `OrderWxVirtualPayDto`

字段	类型	说明
`id`	`string`	微信虚拟支付下单成功后返回的支付标识，用于拉起微信小程序虚拟支付，必填

`wxVirtualPaySuccess` · 微信小程序虚拟支付成功回调

const { data } = await OrderDomain.cases.wxVirtualPaySuccess.run({
  orderId: '202601010000001',
})

console.log(data) // OrderWxVirtualPaySuccessDto

请求参数 `OrderWxVirtualPaySuccessBodyParams`

字段	类型	必填	说明
`orderId`	`string \| number`	是	待确认的订单 ID

响应 `OrderWxVirtualPaySuccessDto`

字段	类型	后台原始字段	说明
`orderStatus`	`OrderStatus`	`pay_status`	订单支付状态，默认 `OrderStatus.UNPAID`
`orderNo`	`string`	`order_no`	订单号，默认 `''`
`payTime`	`number`	`pay_time`	支付完成时间戳，默认 `0`
`transactionNo`	`string`	`transaction_no`	微信支付交易流水号，默认 `''`

`create` · 创建订单

const { data } = await OrderDomain.cases.create.run({
  product_id: 1001,
  source_term: PaySourceType.THEATRE.value,
  theatre_id: 2001,
})

console.log(data) // OrderCreateDto

请求参数 `OrderCreateBodyParams`

字段	类型	必填	说明
`code`	`string`	否	微信登录票据，微信虚拟支付场景下必填
`product_id`	`number`	是	商品 ID
`product_type`	`ProductGroup['value']`（即 `number`）	否	商品前端分组（`coins`/`vip`）
`theatre_id`	`number \| string`	否	短剧 ID
`theatre_title`	`string`	否	短剧标题
`theatre_collect_id`	`number \| string`	否	短剧合集 ID
`theatre_collect_number`	`number \| string`	否	短剧合集编号
`source_term`	`PaySourceType['value']`（即 `number`）	否	支付来源场景
`book_name`	`string`	否	小说名称
`book_id`	`number`	否	小说 ID
`book_chapter_id`	`number \| string`	否	小说章节 ID
`book_chapter_number`	`number \| string`	否	小说章节编号
`template_id`	`number`	否	模板 ID
`template_number`	`number`	否	模板编号
`pay_type`	`number`	否	支付方式（对应 `PayType` 枚举 `value`）
`returnUrl`	`string`	否	支付完成后的跳转地址
`returnFormat`	`string`	否	米花支付宝 H5 / 微信 H5 下单时指定返回格式，支持 `DEEPLINK`/`URL`（对应 `PayReturnFormatType`，默认为 `URL`）

响应 `OrderCreateDto`

不同支付渠道只会返回其中一部分字段，业务代码应结合实际使用的 PayType/PayProvider 只读取对应分组的字段。

公共参数

字段	类型	说明
`signType`	`string \| null`	支付签名类型，默认 `null`

微信小程序支付数据

字段	类型	说明
`nonceStr`	`string \| null`	随机字符串，默认 `null`
`paySign`	`string`	支付签名，默认 `''`
`package`	`string \| null`	统一下单接口返回的 `prepay_id` 参数值，默认 `null`
`timeStamp`	`string \| null`	时间戳，默认 `null`

微信米大师虚拟支付数据

字段	类型	说明
`mode`	`string`	支付模式，默认 `'short_series_goods'`
`paySig`	`string`	支付签名，默认 `''`
`signData`	`OrderCreateWxvirtualSignDataDto`	参与签名的原始数据，默认新建一个 `OrderCreateWxvirtualSignDataDto` 实例
`signature`	`string`	最终签名值，默认 `''`

米花微信小程序半屏支付返回参数

字段	类型	说明
`miniProgramOrgId`	`string`	半屏支付机构 ID，默认 `''`
`miniProgramPath`	`string`	半屏支付跳转路径，默认 `''`
`prePayTn`	`string`	预支付交易号，默认 `''`
`uniqueOrderNo`	`string`	唯一订单号，默认 `''`

非收银台支付数据

字段	类型	说明
`orderId`	`string \| null`	订单 ID，默认 `null`
`payUrl`	`string \| null`	支付跳转链接，默认 `null`
`mhPayInfo`	`string \| null`	米花支付信息（JSON 字符串），后台原始字段为 `payInfo`，默认 `null`，可通过计算属性 `formatMhPayInfo` 解析为对象
`referer`	`string \| null`	来源页地址，默认 `null`

拉取 vivo 收银台所需的支付数据

字段	类型	说明
`appId`	`string`	vivo 收银台 `appId`，默认 `''`
`bizContent`	`string`	vivo 收银台业务参数，默认 `''`
`method`	`string`	vivo 收银台接口方法名，默认 `''`
`sign`	`string`	vivo 收银台签名，默认 `''`
`timestamp`	`string`	vivo 收银台时间戳，默认 `''`
`version`	`string`	vivo 收银台接口版本，默认 `''`

拉取 oppo 收银台所需的支付数据

字段	类型	说明
`attach`	`string`	oppo 收银台附加参数，默认 `''`
`detailCode`	`string`	oppo 收银台明细编码，默认 `''`
`prePayToken`	`string`	oppo 收银台预支付 token，默认 `''`

掌中付微信半屏支付

字段	类型	说明
`appid`	`string`	掌中付微信半屏支付 `appid`，默认 `''`
`appletInfo`	`string`	半屏支付小程序信息（JSON 字符串），默认 `''`，可通过计算属性 `formatZzfPayInfo` 解析为对象
`charset`	`string`	字符集，默认 `''`
`mchId`	`string`	商户号，默认 `''`
`money`	`number`	支付金额，默认 `1`
`outTradeNo`	`string`	商户订单号，默认 `''`
`zzfPayInfo`	`string`	掌中付支付信息，后台原始字段为 `pay_info`，默认 `''`
`pdorderid`	`string`	掌中付订单 ID，默认 `''`

OrderCreateWxvirtualSignDataDto

字段顺序敏感

该 DTO 的字段声明顺序必须与后台返回的字段顺序保持一致，否则微信支付签名会校验失败，新增/调整字段时务必谨慎。

字段	类型	说明
`offerId`	`string`	应用宝 Offer ID，默认 `''`
`buyQuantity`	`number`	购买数量，默认 `1`
`env`	`number`	环境标识，默认 `0`
`currencyType`	`string`	货币类型，默认 `'CNY'`
`platform`	`string`	平台标识，默认 `'android'`
`outTradeNo`	`string`	商户订单号，默认 `''`
`attach`	`string`	附加数据（JSON 字符串），默认 `'[]'`
`productId`	`string`	米大师虚拟支付商品 ID，默认 `''`
`goodsPrice`	`number`	商品价格，默认 `0`

枚举

`OrderStatus` 订单状态

枚举成员	value	code	说明
`CANCELED`	0	`canceled`	取消支付
`UNPAID`	1	`unPaid`	未支付
`PAID`	2	`paid`	已支付
`PENDING_REFUND`	3	`pendingRefund`	未退款
`REFUND`	4	`refund`	已退款
`FAILED_REFUND`	5	`failedRefund`	退款失败
`CONFIRMING`	100	`confirming`	确认中
`ERROR`	-1	`error`	未知错误

`PayType` 支付方式

枚举成员	value	code	说明
`MH_WX`	1	`mh_wx`	米花微信 H5
`MH_ZFB`	2	`mh_zfb`	米花支付宝 APP
`WX`	3	`wx`	微信原生
`ZFB`	4	`zfb`	支付宝原生
`H5_WX`	5	`h5wx`	微信 H5 原生
`KS`	6	`ks`	快手担保支付
`WX_VIRTUAL`	7	`wx_virtual`	微信小程序虚拟支付原生
`MH_MP`	8	`mh_mp`	米花微信小程序
`DY`	9	`douyin`	抖音通用交易
`DY_DIAMOND`	10	`douyin_diamond`	抖音钻石支付
`H5_ZFB`	11	`h5zfb`	米花支付宝 H5
`MH_JSAPI`	12	`mh_jsapi`	米花微信 jsapi
`JSAPI`	13	`jsapi`	微信 jsapi 原生
`VIVO`	20	`vivo`	VIVO 钱包支付
`OPPO`	21	`oppo`	OPPO 钱包支付
`HUAWEI`	22	`huawei`	华为支付
`XIAOMI`	23	`xiaomi`	小米支付
`HONOR`	24	`honor`	荣耀支付
`YEE_H5_WX`	30	`yee_h5_wx`	易宝微信 H5 支付
`YEE_JSAPI`	31	`yee_jsapi`	易宝微信 jsapi
`YEE_MP_WX`	32	`yee_mp_wx`	易宝微信小程序支付
`ZZF_JSAPI`	50	`zhang_jsapi`	掌中付微信 jsapi
`ZZF_MP`	51	`zhang_wx_embedding`	掌中付微信小程序半屏支付
`ZZF_WX`	52	`zhang_wx_mini`	掌中付微信小程序支付
`ZZF_H5_WX`	53	`zhang_wx_h5`	掌中付微信 H5 支付
`ZZF_ZFB`	54	`zhang_alipay`	掌中付支付宝 APP 支付
`ZZF_ZFB_H5`	55	`zhang_alipay_h5`	掌中付支付宝 H5 支付
`WX_KF`	60	`wx_kf`	微信客服消息支付

`PaySourceType` 支付来源场景

枚举成员	value	code	说明
`DEFAULT`	0	`default`	默认
`THEATRE`	1	`theatre`	短剧
`NOVEL`	2	`novel`	书城

`ProductType` 商品大类

枚举成员	value	code	说明
`coins`	1	`coins`	币产品类
`vip`	2	`vip`	会员产品类
`unlock`	3	`unlock`	批量解锁类
`benefit`	99	`benefit`	权益产品类

`ProductClass` 商品细分类

枚举成员	value	code	说明
`WEEK_VIP`	4	`week_vip`	周会员
`QUARTER_VIP`	5	`quarter_vip`	季度会员
`MONTH_VIP`	6	`month_vip`	月会员
`HALF_YEAR_VIP`	7	`half_year_vip`	半年会员
`YEAR_VIP`	8	`year_vip`	年会员
`SINGLE_VIDEO`	9	`single_video`	解锁全集
`COINS`	10	`coins`	充值币
`TWO_MONTH_VIP`	11	`two_month_vip`	两月会员
`DAY_VIP`	12	`day_vip`	天会员
`TWO_DAYS_VIP`	13	`two_days_vip`	两天会员
`HALF_MONTH_VIP`	14	`half_mouth_vip`	半月会员
`BENEFITS`	99	`benefits`	免广告权益

`ProductGroup` 商品前端分组

枚举成员	value	code	说明
`COINS`	1	`coins`	币产品
`VIP`	2	`vip`	会员产品

该枚举用于前端本地分组展示，后台接口暂未直接返回对应字段，属于预留/备用枚举。

`PayPageType` 支付页面场景类型

枚举成员	value	code	说明
`UNKNOWN`	0	`unknown`	默认充值页
`VIDEO`	1	`video`	短剧播放页
`READER`	2	`reader`	小说阅读页

`NovelType` 小说篇幅分类

枚举成员	value	code	说明
`UNKNOWN`	0	`unknown`	不指定
`SHORT`	1	`short`	短篇小说
`MIDSHORT`	2	`middle-short`	中短篇小说
`MIDIUM`	3	`middle`	中篇小说
`MIDFULL`	4	`middle-full`	中长篇小说
`FULL`	5	`full`	长篇小说

`PayProvider` 支付服务商

枚举成员	value	code	说明
`mhpay`	1	`mhpay`	米花支付
`yeepay`	2	`yeepay`	易宝支付
`qingmpay`	3	`qingmpay`	掌中付
`wechatpay`	4	`wechatpay`	微信原生
`wxVirtualPay`	5	`wxVirtualPay`	微信小程序虚拟支付
`kfIssuePay`	6	`kfIssuePay`	微信小程序客服消息
`alipay`	7	`alipay`	支付宝原生
`unknown`	-1	`unknown`	未知

该枚举未在本领域任何请求参数/响应字段中直接引用，作为公共导出类型供业务代码自行归类判断支付渠道使用。

`PaySceneType` 支付发起端场景

枚举成员	value	code	说明
`UNKNOWN`	0	`unknown`	未知场景
`ANDROID`	1	`android`	安卓
`IOS`	2	`ios`	苹果

该枚举未在本领域任何请求参数/响应字段中直接引用，作为公共导出类型供业务代码自行判断发起支付的客户端场景使用，后续可能补充更多场景（如小程序、快应用、H5 等）。

`PayReturnFormatType` 支付跳转返回格式

枚举成员	value	code	说明
`DEEPLINK`	1	`DEEPLINK`	支付 scheme 唤起
`HTTPS`	2	`h5`	https 链接

对应 create 用例请求参数 returnFormat 字段的取值约定（该字段类型为 string，未直接使用枚举类型标注，此处枚举供参考取值）。

order · 订单/支付 ​

用例总览 ​

products · 获取商品列表 ​

请求参数 OrderProductsQueryParams ​

响应 OrderProductsDto[] ​

benefits · 获取权益商品列表 ​

请求参数 OrderBenefitsQueryParams ​

响应 OrderBenefitsDto[] ​

query · 查询订单支付状态 ​

请求参数 OrderQueryQueryParams ​

响应 OrderQueryDto（不可变，@Freeze） ​

wxVirtualPay · 微信小程序虚拟支付下单 ​

请求参数 OrderWxVirtualPayBodyParams ​

响应 OrderWxVirtualPayDto ​

wxVirtualPaySuccess · 微信小程序虚拟支付成功回调 ​

请求参数 OrderWxVirtualPaySuccessBodyParams ​

响应 OrderWxVirtualPaySuccessDto ​

create · 创建订单 ​

请求参数 OrderCreateBodyParams ​

响应 OrderCreateDto ​

枚举 ​

OrderStatus 订单状态 ​

PayType 支付方式 ​

PaySourceType 支付来源场景 ​

ProductType 商品大类 ​

ProductClass 商品细分类 ​

ProductGroup 商品前端分组 ​

PayPageType 支付页面场景类型 ​

NovelType 小说篇幅分类 ​

PayProvider 支付服务商 ​

PaySceneType 支付发起端场景 ​

PayReturnFormatType 支付跳转返回格式 ​